Feature/add working with text documentation

.cursor/agents/docs-reviewer.md

@@ -11,8 +11,9 @@ 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.
+3. **Links/media** — `url`/`section`/`figure`/`ref`/`ahref` paths likely valid. For new keys: confirm they were looked up in `data/urls.toml` and do not duplicate an existing target URL (flag invented “normalized” keys that point at the same page, heading, or external URL as an atypical key). Prefer heading keys when link text/context names a section — flag page-level keys used for section topics, and flag any `{{< url path="…" >}}#…` footer (expect a dedicated `urls.toml` key with the fragment in the value). Flag plain markdown external links `[…](https://…)` and bare `https://` / `http://` URLs — expect footer `[Label]: {{< url path="…" >}}` instead. For both `url` and `ref` footers: flag duplicate defs for the same target, and reference labels whose case does not match the definition (use `[Text][canonical]` instead). Flag inline same-page anchors `[…](#…)` — expect footer `[Label]: {{< ref "#slug" >}}` instead. Flag any `{{< ref "…" >}}` that is not a same-page `#slug` only (e.g. relative `.md` or `.md#fragment`) — expect `url` + `urls.toml` instead. Inside `alert`: expect `{{< ahref … >}}` only — flag reference-style / markdown links; flag alerts whose first body token is `ahref`.
+4. **Security** — no secrets, config, or ignored paths in the diff (except legitimate `data/urls.toml` key adds).
 5. **Consistency** — tone and structure match sibling pages.
+6. **Remarks / Known Limitations** — flag general remarks (expected behavior, null/empty handling, scope notes) placed under `### Known Limitations`; those belong as their own `###` headings under `## Remarks`. Flag clear constraints/gaps that lack a Known Limitations placement when the page uses that section. Flag Known Limitations content that uses nested headings (`####`) instead of a bullet list. Flag top-level `## Known Limitations` when siblings nest it under Remarks.
 
 Provide prioritized findings: must-fix vs nice-to-have.

.cursor/agents/docs-writer.md

@@ -10,5 +10,10 @@ 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.
+- Respect `.cursorignore`. For `url` keys: look up [`data/urls.toml`](../../data/urls.toml) and sibling pages first (internal `Cortex.*` and external namespaces such as `MSDocs.…`, `Postman.…`); edit `urls.toml` only when adding a truly new destination key; never add a second key that maps to the same full URL (path ± `#fragment` — page and heading are distinct). Never write plain markdown external links (`[text](https://…)`) or bare `https://` URLs — use `{{< url path="…" >}}` like any other link.
+- Prefer heading destinations: when prose targets a section on another page, use (or add) a `urls.toml` key whose value includes `#slug`. Never append `#…` after the `url` shortcode. Use a page-level key only for whole-page references.
+- Footer `url` defs: one per path; reuse that label via `[variant][canonical]` when wording or case differs; keep reference label case exact (avoids markdown warnings and duplicate shortcodes).
+- Same-page `ref` defs: `#slug` only (never relative `.md` / `.md#fragment` — those use `url` + a `urls.toml` key with any fragment in the value); one per `#slug`; same case rules as `url` — exact label match for `[Label][]`, otherwise `[variant][canonical]`; never inline `[text](#slug)`.
+- Inside `alert` callouts: links use `{{< ahref path="…" title="…" >}}` (same `urls.toml` keys as `url`); never reference-style `url`/`ref` or markdown links inside alerts. Never start the alert body with a link — lead with plain text or reword/omit the link.
+- Remarks vs Known Limitations: classify each item. General functional notes (null/empty handling, scope, expected behavior) get their own `###` heading under `## Remarks`. Real constraints/gaps go only under `### Known Limitations` as a bullet list (no nested headings). If classification is unclear, ask the user before writing or moving the item — do not guess into Known Limitations.
 - Keep diffs minimal and limited to requested versions.

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

@@ -8,5 +8,5 @@ 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).
+4. Look up keys in `data/urls.toml` (and sibling pages) before adding any — for this page’s `Cortex.*` key, any heading destinations (`#slug` in the `urls.toml` value), and any external destinations. Never use plain `[text](https://…)` links. Never append `#…` after `{{< url … >}}`. List files created/changed and any **new** `urls.toml` keys added (page-level plus fragment keys as needed; never a second key for the same full destination URL).
 5. Summarize nav impact (`weight`, parent section).

.cursor/commands/review-docs.md

@@ -9,6 +9,12 @@ Review current doc changes (branch diff or open files).
 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.
+5. List risks: missing `urls.toml` keys, cross-version drift, broken shared paths. Check `data/urls.toml` for new keys that duplicate an existing target URL (internal or external; full URL including any `#fragment`).
+6. Link footers (`url` and `ref`): flag duplicate defs for the same target, and reference labels that do not match the definition label’s case (prefer one canonical def + `[Text][canonical]`).
+7. Heading links: when link text/context names a section, expect a `urls.toml` key whose value includes `#slug` — flag page-level keys used for section topics, and flag `{{< url path="…" >}}#…` footers (fragment belongs in `urls.toml`, not after the shortcode).
+8. Same-page links: flag inline `[…](#…)` anchors; expect footer `[Label]: {{< ref "#slug" >}}` plus reference-style body links with the same exact-case rules as `url`. Flag `{{< ref "…" >}}` that is not `#slug`-only (relative `.md` / `.md#fragment`) — expect `url` + `urls.toml`.
+9. External links: flag plain markdown `[…](https://…)` / `[…](http://…)` and bare URLs; expect `{{< url path="…" >}}` with a key looked up (or added) in `data/urls.toml`.
+10. Alerts: links inside must use `{{< ahref path="…" title="…" >}}` — flag reference-style `url`/`ref`, inline `[…](#…)`, or plain URLs inside alerts. Flag alerts whose first body token is a link (`ahref`); expect plain-text lead-in or reword/omit.
+11. Remarks / Known Limitations: flag general remarks (expected behavior, null/empty handling, scope notes) under `### Known Limitations` — expect their own `###` headings under `## Remarks`. Flag clear constraints dumped as plain remarks when siblings use Known Limitations. Flag Known Limitations that use nested headings (`####`) instead of a bullet list. Flag top-level `## Known Limitations` when siblings nest it under Remarks.
 
 Output: brief bullet list of issues and suggested fixes.

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

@@ -9,5 +9,138 @@ alwaysApply: false
 - 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.
+
+## Reference-style `url` links
+
+Every navigable link—docs pages **and** third-party / external sites—uses a reference definition with `{{< url path="…" >}}`. Do **not** use plain markdown external links (`[text](https://…)`) or bare `https://…` / `http://…` URLs in body text.
+
+**Exception: links inside alerts** — use `{{< ahref path="…" title="…" >}}` (not reference-style `url`/`ref`). The first word of the alert body cannot be a link; lead with plain text or reword/omit the link. See [hugo-shortcodes.mdc](hugo-shortcodes.mdc) (Alerts and `ahref`).
+
+Keys live in [`data/urls.toml`](../../data/urls.toml): internal docs under `Cortex.*`, external destinations under other top-level namespaces (e.g. `MSDocs.…`, `GitHub.…`, `Postman.…`, `Wikipedia.…`, `W3.…`).
+
+### Prefer heading keys
+
+When link text or context targets a **specific section/topic** on another page, link to that heading—not the page top:
+
+1. Confirm the target heading and its Hugo anchor slug on the destination page.
+2. Look up [`data/urls.toml`](../../data/urls.toml) for a key whose URL is that page path **including** `#slug`.
+3. If none exists, add a sibling-style key under that page’s namespace with the fragment in the value (e.g. `ViewClusterHealth`, `AntivirusExclusions`). Page-without-fragment and `page#slug` are **different** destinations — a new fragment key is allowed and expected.
+4. Footer: `[Label]: {{< url path="Cortex.…HeadingKey" >}}` only. **Never** append `#…` after the shortcode (`}}#slug` is forbidden).
+5. Use a page-level key (`MainDoc` or equivalent, no fragment) only when the reference is to the page as a whole.
+
+### Choosing a `urls.toml` key
+
+1. **Reuse before invent** — Grep content for an existing `{{< url path="…" >}}` to the target; copy that key **exactly**.
+2. **Look up before add** — Search [`data/urls.toml`](../../data/urls.toml) for any key whose URL already targets that destination (same path ± trailing slash / `_index` for internal pages, **including exact `#fragment` when present**; exact `https://` / `http://` URL for external sites).
+3. **Never “normalize”** — Do not invent a parallel key that mirrors the folder tree (or a new external namespace) when an atypical key already points at the same URL (e.g. historical suffixes like `New`).
+4. **New destinations only** — Add a new `urls.toml` entry only when none maps there: new docs pages get a page-level `Cortex.*` key (sibling style); heading destinations get additional fragment keys as needed; for external URLs, match sibling namespace style in that section (`MSDocs.…`, `Postman.…`, etc.). Confirm no existing value already maps to that full URL (path ± fragment).
+
+### Page footers
+
+- **One definition per `urls.toml` path** on the page. Do not add a second `[OtherText]: {{< url path="same…" >}}` for the same path.
+- **Never** write `[Label]: {{< url path="…" >}}#slug` — put the fragment in `urls.toml` and use a normal `url` shortcode.
+- Prefer a stable canonical label (usually the See Also / page title / heading form, e.g. `items`, `Keys`, `Antivirus exclusions`).
+- Implicit `[Label][]` only when `Label` matches the definition label **exactly** (including case). Case mismatches warn in markdown tooling — do not rely on case-insensitive resolution.
+- When display text differs in wording **or** case, use `[variant text][canonical]` so the second bracket matches the definition label’s case exactly.
+
+```markdown
+<!-- Good: heading key when the topic is a section; page key for whole-page refs -->
+… see [Antivirus exclusions][] …
+… see [Prerequisites][] …
+… download [Postman][] …
+
+[Antivirus exclusions]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.AntivirusExclusions" >}}
+[Prerequisites]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.Prerequisites" >}}
+[Postman]: {{< url path="Postman.Downloads.MainDoc" >}}
+
+<!-- Bad: section topic → page key only; fragment after shortcode; plain/bare URLs; duplicate defs; case-mismatched implicit refs -->
+… [Postman](https://www.postman.com/downloads/) …
+… https://learn.microsoft.com/en-us/dotnet/ …
+[Antivirus exclusions]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.Prerequisites" >}}
+[Antivirus exclusions]: {{< url path="Cortex.GettingStarted.OnPremise.InstallInnovationOnly.SingleServerWithoutHA.Prerequisites" >}}#antivirus-exclusions
+[Items]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Items.MainDoc" >}}
+[item]: {{< url path="Cortex.Reference.Concepts.WorkingWith.Collections.Items.MainDoc" >}}
+```
+
+```toml
+# urls.toml — fragment is part of the value (never appended in the markdown footer)
+AntivirusExclusions = "/docs/getting-started/on-premise/install-innovation-only/single-server-without-ha/prerequisites#antivirus-exclusions"
+```
+
+## Same-page `ref` links
+
+Links to headings or fragments **on the current page** use reference definitions with Hugo’s built-in `{{< ref "#slug" >}}`, then the same in-body pattern as `url` links. Pattern: `content/en/docs/2026.3/Reference/Concepts/working-with/concurrency/semaphores/what-is-a-semaphore.md`.
+
+- **`ref` is `#slug` only.** Do not use `ref` with relative paths (`other-page.md`, `../foo.md#bar`, or `page.md#fragment`). Cross-page targets (including headings on other pages) and external sites use `{{< url path="…" >}}` with a `urls.toml` key that includes any `#fragment` — never append `#` after the shortcode.
+- **Never** write inline `[text](#slug)`. Always add a footer definition and reference it.
+- **One definition per anchor** on the page. Do not add a second `[OtherText]: {{< ref "#same-slug" >}}` for the same fragment.
+- Prefer a stable canonical label (usually the heading text form, e.g. `Queuing Semaphore`).
+- Implicit `[Label][]` only when `Label` matches the definition label **exactly** (including case). Case mismatches warn in markdown tooling — do not rely on case-insensitive resolution.
+- When display text differs in wording **or** case, use `[variant text][canonical]` so the second bracket matches the definition label’s case exactly.
+
+```markdown
+<!-- Good: one def per anchor; shared label when wording/case differs -->
+… [queue][Queuing Semaphore] or [not queue][Non-Queuing Semaphore] …
+… see [Queuing Semaphore][] …
+
+[Queuing Semaphore]: {{< ref "#queuing-semaphore" >}}
+[Non-Queuing Semaphore]: {{< ref "#non-queuing-semaphore" >}}
+
+<!-- Bad: inline same-page anchors; duplicate defs; case-mismatched implicit refs; relative ref paths -->
+… [Queuing Semaphore](#queuing-semaphore) …
+[queuing semaphore]: {{< ref "#queuing-semaphore" >}}
+[Queuing Semaphore]: {{< ref "#queuing-semaphore" >}}
+[value type]: {{< ref "what-is-a-data-type.md#value-types" >}}
+```
+
+## Remarks and Known Limitations
+
+When a page has a Remarks section, use this structure (match siblings such as `content/en/docs/2026.3/Reference/Blocks/Text/contains-text/contains-text-block.md`):
+
+```markdown
+## Remarks
+
+### <Topic heading for a general remark>
+…
+
+### <Another remark topic>
+…
+
+### Known Limitations
+
+- …
+- …
+```
+
+Classify each item before placing it:
+
+| Kind | Placement |
+| --- | --- |
+| **Limitation** — a real constraint, gap, or unsupported/edge-case behavior (often “cannot”, “only supports”, “not evaluated as equal”, “may be removed in future”) | Under `### Known Limitations` as a **bullet list**. Do **not** use `####` or other nested headings under Known Limitations |
+| **Remark** — general functional behavior, null/empty handling, inclusive indexes, scope notes, or other expected “how it works” clarifications | Own `###` heading under `## Remarks` — **not** under Known Limitations |
+| **Unclear** | **Ask the user** whether the item is a remark or a limitation before writing or moving it |
+
+Do not put general remarks under Known Limitations. Do not invent a top-level `## Known Limitations` when siblings use `### Known Limitations` under Remarks. Do not nest headings under Known Limitations.
+
+```markdown
+<!-- Good: remarks as own headings; limitations as a bullet list -->
+## Remarks
+
+### Null or empty Text
+
+If [Text][Text Property] is `null` or empty (i.e. `""`), … is set to `false`.
+
+### Known Limitations
+
+- If [Search Options]… is `SearchOptions.Regex` … some characters … may not evaluate as equal.
+
+<!-- Bad: expected behavior dumped under Known Limitations; nested headings for limitations -->
+## Remarks
+
+### Known Limitations
+
+#### Null or empty Text
+
+If [Text][Text Property] is `null` or empty, … is set to `false`.
+```