Feature/use cursor to investigate working with docs

.cursor/agents/docs-reviewer.md

@@ -0,0 +1,18 @@
+---
+name: docs-reviewer
+description: Reviewer for CORTEX documentation PRs — conventions, scope, security, and Hugo build risks.
+---
+
+# Docs reviewer
+
+Review documentation changes critically but constructively.
+
+Check:
+
+1. **Scope** — only intended version(s) and files touched.
+2. **Conventions** — frontmatter, `ctx`, shortcodes, shared sections.
+3. **Links/media** — `url`/`section`/`figure` paths likely valid; flag new `Cortex.*` keys.
+4. **Security** — no secrets, config, or ignored paths in the diff.
+5. **Consistency** — tone and structure match sibling pages.
+
+Provide prioritized findings: must-fix vs nice-to-have.

.cursor/agents/docs-writer.md

@@ -0,0 +1,14 @@
+---
+name: docs-writer
+description: Technical writer for CORTEX Product Portal Hugo/Docsy content. Use for drafting or restructuring customer-facing documentation.
+---
+
+# Docs writer
+
+You write and edit CORTEX product documentation in this Hugo/Docsy repo.
+
+- Follow [AGENTS.md](../../AGENTS.md) and [content/AGENTS.md](../../content/AGENTS.md).
+- Plan multi-page work before editing; prefer `_shared` over duplication.
+- Use project shortcodes; never hardcode branding where `{{% ctx %}}` is standard.
+- Respect `.cursorignore`; ask for `urls.toml` snippets when adding new `url` paths.
+- Keep diffs minimal and limited to requested versions.

.cursor/commands/new-doc-page.md

@@ -0,0 +1,12 @@
+---
+name: new-doc-page
+description: Create a new CORTEX documentation page from a sibling template in the requested version and section.
+---
+
+Create a new documentation page for CORTEX Product Portal.
+
+1. Confirm doc version (e.g. 2026.3) and target folder under `content/en/docs/{version}/`.
+2. Open the closest sibling `_index.md` or leaf `.md` and mirror structure.
+3. Apply the add-documentation-page skill workflow.
+4. List files created/changed and any `urls.toml` keys the user must add (do not read ignored data files).
+5. Summarize nav impact (`weight`, parent section).

.cursor/commands/review-docs.md

@@ -0,0 +1,14 @@
+---
+name: review-docs
+description: Review documentation changes for Hugo conventions, branding, links, and scope.
+---
+
+Review current doc changes (branch diff or open files).
+
+1. Frontmatter complete; CORTEX literal in title/linkTitle; `ctx` in body where expected.
+2. Shortcodes valid (`section` paths exist under `_shared`, `figure` paths under `content/static`).
+3. No edits to ignored paths or unrelated doc versions.
+4. Tone matches surrounding customer-facing procedural docs.
+5. List risks: missing `urls.toml` keys, cross-version drift, broken shared paths.
+
+Output: brief bullet list of issues and suggested fixes.

.cursor/rules/cortex-docs-repo.mdc

@@ -0,0 +1,15 @@
+---
+description: CORTEX Product Portal repo purpose, structure, and agent workflow
+alwaysApply: true
+---
+
+# CORTEX docs repository
+
+- Source for https://docs.wearecortex.com/ (Hugo + Docsy).
+- Versioned docs: `content/en/docs/{version}/` with `{version}/_shared/`.
+- Shortcodes: `layouts/shortcodes/` (`ctx`, `version`, `section`, `url`, `figure`, …).
+- Images: `content/static/{version}/images/`.
+
+Read [AGENTS.md](../../AGENTS.md) before large edits. Contributions: [CORTEX Support](https://support.wearecortex.com/) per README.
+
+Canonical page: `content/en/docs/2026.3/getting-started/on-premise/install-innovation-only/single-server-without-ha/architecture.md`

.cursor/rules/hugo-content-markdown.mdc

@@ -0,0 +1,13 @@
+---
+description: Hugo/Docsy markdown and frontmatter for CORTEX documentation
+globs: content/**/*.md
+alwaysApply: false
+---
+
+# Hugo content
+
+- Frontmatter: `title`, `linkTitle`, `description`, `weight`.
+- Literal CORTEX in `title`/`linkTitle`; `{{% ctx %}}` in body where siblings do.
+- Reuse `_shared` + `{{< section "/path.md" >}}` instead of copy-paste.
+- Internal links: `{{< url path="Cortex...." >}}` like neighboring pages.
+- Procedural tone; no drive-by edits across doc versions.

.cursor/rules/hugo-shortcodes.mdc

@@ -0,0 +1,20 @@
+---
+description: Custom Hugo shortcode usage and constraints
+globs: content/**/*.md, layouts/shortcodes/**
+alwaysApply: false
+---
+
+# Shortcodes
+
+Read `layouts/shortcodes/*.html` before changing usage.
+
+| Shortcode | Notes |
+| --- | --- |
+| `ctx` | Renders CORTEX; not in `title`/`linkTitle` |
+| `version` | Uses `{version}/_shared/currentVersion.md` |
+| `section` | Path under `{version}/_shared/`; must exist |
+| `url` | Keys from `urls.toml` (ignored — ask user for keys) |
+| `figure` | `src` under `/images/...`; file in `content/static/{version}/images/` |
+| `image` | `src` under `/images/...`; file in `content/static/{version}/images/` |
+
+Template edits affect all versions — scope testing accordingly.

.cursor/rules/security-cursorignore.mdc

@@ -0,0 +1,12 @@
+---
+description: Respect .cursorignore — no secrets, config, or data file access
+alwaysApply: true
+---
+
+# Security
+
+Follow [.cursorignore](../../.cursorignore).
+
+Do not read/commit: `config.*`, `data/**`, `urls.toml`, CI configs, `.env*`, certs/keys, `public/**`, `node_modules/**`, internal/draft content paths.
+
+If link keys are needed, copy from an existing page in the same section or ask the user.

.cursor/skills/add-documentation-page/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: add-documentation-page
+description: Add a new Hugo documentation page under a versioned CORTEX docs section. Use when creating topics, install steps, reference pages, or _index.md section roots.
+---
+
+# Add documentation page
+
+## When to use
+
+- New leaf page or section `_index.md` under `content/en/docs/{version}/`
+- User names a doc version (e.g. 2026.3) and section path
+
+## Steps
+
+1. Find a sibling page in the same folder; copy frontmatter shape (`title`, `linkTitle`, `description`, `weight`).
+2. Set `weight` relative to neighbors (lower = earlier in sidebar).
+3. Use literal CORTEX in `title`/`linkTitle`; `{{% ctx %}}` in body.
+4. For install/guide style, use `# {{% param title %}}` and match callouts (`pageinfo`, `alert`).
+5. Add next-step links with `{{< url path="Cortex...." >}}` — reuse keys from sibling pages.
+6. If content repeats across pages, add `{version}/_shared/...` and `{{< section "/path.md" >}}` instead.
+7. Do not edit other version trees unless requested.
+
+## Checklist
+
+- [ ] Frontmatter complete
+- [ ] Branding matches `ctx` convention
+- [ ] Links follow section `url` patterns
+- [ ] Scope limited to requested version

.cursor/skills/edit-versioned-images/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: edit-versioned-images
+description: Add or update versioned diagrams and screenshots under content/static. Use for figures, architecture diagrams, or draw.io editable assets.
+paths: content/static/**/*
+---
+
+# Versioned images
+
+## When to use
+
+- New/updated `{{< figure >}}` or diagram in docs
+- User mentions draw.io, editable folder, or architecture screenshots
+
+## Steps
+
+1. Confirm doc version → static folder `content/static/{version}/images/`.
+2. Editable diagrams: `images/editable/` (see `content/static/2026.3/images/_ReadMe.md`).
+3. Reference in markdown: `{{< figure src="/images/editable/....png" class="centre" title="..." >}}`.
+4. Ensure file exists on disk before referencing (figure shortcode checks `content/static/{version}/...`).
+5. For new versions, mirror structure from the latest version's `images/` tree when appropriate.
+
+## Screenshot conventions (from _ReadMe)
+
+- Service Fabric screenshots: 1500×700, device emulation, refresh off where noted.

.cursor/skills/shared-sections/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: shared-sections
+description: Create or edit reusable _shared markdown included via the section shortcode. Use for duplicated install, architecture, or upgrade steps within a doc version.
+paths: content/**/_shared/**/*.md
+---
+
+# Shared sections
+
+## When to use
+
+- Same paragraph/block appears on multiple pages in one version
+- User asks to DRY up install/architecture/upgrade content
+
+## Steps
+
+1. Locate `{version}/_shared/` (e.g. `content/en/docs/2026.3/_shared/`).
+2. Find existing fragment before creating a new file.
+3. Add or edit `.md` under `_shared/` with normal markdown (no page frontmatter required for fragments).
+4. Include from pages: `{{< section "/relative/path/from/_shared.md" >}}` (leading path as in `architecture.md`).
+5. Fix all includers if you rename or move a shared file.
+
+## Pitfalls
+
+- Path must resolve for the page's version or Hugo errors at build.
+- Shared files are per-version; syncing across 2026.3 / 2025.9 requires explicit user approval.

.cursorignore

@@ -0,0 +1,103 @@
+# ============================================
+# Hugo / Docsy Sensitive Data Protection
+# ============================================
+
+# Core secrets (keep from previous list)
+.env
+.env.*
+*.env
+*.secret
+*.secrets
+
+# Hugo config files (frequently contain URLs, tokens, etc.)
+config.toml
+config.yaml
+config.yml
+config.json
+
+# If you split config:
+config/**/production*
+config/**/prod*
+config/**/secrets*
+config/**/private*
+
+# Hugo module cache (can include fetched private modules)
+resources/_gen/**
+.hugo_build.lock
+
+# Content drafts / unpublished content
+content/**/drafts/**
+content/**/_drafts/**
+content/**/private/**
+content/**/internal/**
+
+# Frontmatter-heavy markdown (may contain PII / metadata leaks)
+# (Optional depending on your workflow)
+# content/**/*.md
+
+# Data files (VERY important in Hugo)
+data/**
+*.yaml
+*.yml
+*.json
+*.toml
+*.csv
+
+# Docsy-specific
+# Includes navigation and structure that may leak internal structure
+content/en/docs/internal/**
+content/en/docs/private/**
+content/en/docs/drafts/**
+
+# Static assets (can accidentally contain secrets)
+static/uploads/**
+static/private/**
+static/internal/**
+static/files/**
+static/data/**
+
+# Built output (can contain rendered secrets if misconfigured)
+public/**
+
+# Scripts / build tooling
+scripts/**
+tools/**
+
+# Node dependencies (Docsy commonly uses npm tooling)
+node_modules/**
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+
+# CI/CD configs (often contain refs to secrets)
+.github/workflows/**
+.gitlab-ci.yml
+.azure-pipelines.yml
+
+# Logs / temporary files
+*.log
+tmp/**
+.cache/**
+
+# ============================================
+# Global sensitive patterns
+# ============================================
+**/*password*
+**/*secret*
+**/*credential*
+**/*token*
+**/*apikey*
+**/*private*
+
+# Certificates & keys
+*.pem
+*.key
+*.crt
+*.p12
+*.pfx
+
+# Cloud credentials
+.aws/**
+.azure/**
+.gcp/**
+*service-account*.json

AGENTS.md

@@ -0,0 +1,59 @@
+# CORTEX Product Portal — Agent Instructions
+
+This repository is the source for the [CORTEX Product Portal](https://docs.wearecortex.com/) (Hugo + Docsy). Use these instructions when editing documentation, layouts, or static assets.
+
+## Repository purpose
+
+- **Site**: Public product documentation for the CORTEX automation platform.
+- **Stack**: Hugo static site with Docsy theme, custom shortcodes under `layouts/shortcodes/`, versioned content under `content/en/docs/`.
+- **Contributions**: Per [README.md](README.md), external contributions and feedback go through [CORTEX Support](https://support.wearecortex.com/). Do not assume undocumented publish or deploy steps.
+
+## How to work in this repo
+
+### Plan before large edits
+
+For multi-page or cross-version changes, outline affected paths first (which version folders, `_shared` snippets, `urls.toml` entries, images). Prefer small, reviewable diffs over sweeping rewrites.
+
+### Versioned documentation
+
+- Product docs live under `content/en/docs/{version}/` (e.g. `2026.3`, `2025.9`, `2024.9`).
+- Each version has a `_shared/` folder for reusable sections included via the `section` shortcode.
+- When changing behavior that applies to multiple releases, identify whether content is duplicated per version or centralized in `_shared` before editing.
+- Canonical example: `content/en/docs/2026.3/getting-started/on-premise/install-innovation-only/single-server-without-ha/architecture.md`
+
+### Branding and naming
+
+- In page **body** text, use `{{% ctx %}}` for the product name — do not hardcode "CORTEX" in prose when the shortcode applies.
+- In YAML **`title`** and **`linkTitle`**, use the literal name (e.g. `CORTEX`) — shortcodes are not used there.
+- Release label in prose: `{{< version >}}` (reads `{version}/_shared/currentVersion.md`).
+
+### Images and diagrams
+
+- Versioned assets: `content/static/{version}/images/` (`editable/` for draw.io).
+- Use `{{< figure src="/images/..." >}}`; see `layouts/shortcodes/figure.html`.
+- Diagram notes: `content/static/2026.3/images/_ReadMe.md`
+
+### Security and ignored paths
+
+Respect [.cursorignore](.cursorignore). Do not read or commit Hugo config, `data/**`, CI workflows, secrets, or internal/draft paths. If `urls.toml` is needed, ask the user for the relevant key or snippet.
+
+## Project agent assets
+
+| Asset | Location |
+| --- | --- |
+| Rules | `.cursor/rules/*.mdc` |
+| Skills | `.cursor/skills/*/SKILL.md` |
+| Commands | `.cursor/commands/*.md` |
+| Agents | `.cursor/agents/*.md` |
+
+## Quality bar
+
+- Procedural, customer-facing tone; preserve frontmatter (`title`, `linkTitle`, `description`, `weight`).
+- Prefer shortcodes over raw HTML; match `{{< url path="Cortex...." >}}` patterns in the same section.
+- Scope changes to the version(s) the user requested.
+
+## What not to do
+
+- Do not modify `public/`, `node_modules/`, or ignored config/data files.
+- Do not invent install commands or CI steps not documented in-repo.
+- Do not remove or weaken `.cursorignore` without explicit user approval.