chore(claude-md): update for post-flip MyST-as-primary state

The CLAUDE.md scaffolded by /init reflected the pre-MyST repo and was
never updated as the migration landed. Replaces it with a current
description of how the repo actually works:

- MD is the canonical source for migrated pages on all three release
  branches (current/circinus/sagitta) as of 2026-05-06. RST is the
  canonical source for pages that haven't been migrated yet.
- Documents the rare RST override mechanism: rst-<page>.rst plus
  docs/_rst_overrides.txt, scripts/swap_sources.py CLI flags. The
  override list is empty by default; the mechanism is a no-op.
- Editing rules: edit the .md for migrated pages, the .rst for
  non-migrated pages, write new pages as .md from the start. The
  md- prefix used during the migration is gone.

Also adds previously-missing sections: tests command, vale lint
command, branches/versions table with constellation→version mapping,
PR review flow with Copilot+CodeRabbit, worktree convention.

Generated by robots https://vyos.io

1 files changed, 128 insertions, 65 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 60f7d13f..2d553780 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,81 +1,147 @@
-# VyOS Documentation
+# CLAUDE.md
 
-RST documentation for VyOS, built with Sphinx and hosted on Read the Docs.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+VyOS user documentation, built with Sphinx and hosted on Read the Docs at https://docs.vyos.io. Sources are MyST Markdown (`.md`) for migrated pages and RST (`.rst`) for the rest. Both formats are first-class to Sphinx; MD is the canonical source for any page that has been migrated, and RST is the canonical source for pages that haven't.
+
+A small swap mechanism exists for the rare case where a maintainer needs to render the legacy RST version of a page that already has an MD primary — see `RST override mechanism` below. The override list is empty by default.
 
 ## Build
 
 ```bash
-# Docker (recommended)
+# Docker (recommended — bundles all deps incl. vale)
 docker build -t vyos/vyos-documentation docker
 docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
   -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
   vyos/vyos-documentation make html
 
-# Local
+# Live-reload server on port 8000
+docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs \
+  -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
+  vyos/vyos-documentation make livehtml
+
+# Local (Python 3, see requirements.txt for pinned versions)
 pip install -r requirements.txt
 cd docs && make html
 ```
 
-Output goes to `docs/_build/html/`.
+Output: `docs/_build/html/`.
 
-## RST Conventions
+## Tests
 
-### Heading Hierarchy
+```bash
+pytest tests/                      # all tests
+pytest tests/test_swap_sources.py  # single test file
+```
 
-```rst
-#####
-Title
-#####
+## Lint (vale)
 
-********
-Chapters
-********
+```bash
+docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
+  -e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) \
+  vyos/vyos-documentation vale .              # all files
+docker run ... vale path/to/page.rst          # single file
+```
+
+## Branches and versions
 
-Sections
-========
+One long-lived branch per VyOS release line. Branch names are constellations sorted by area:
 
-Subsections
------------
+| Branch | VyOS version |
+|--------|--------------|
+| `current` | rolling / 1.5+ (default branch — all new docs target this) |
+| `circinus` | 1.5.x |
+| `sagitta` | 1.4.x |
+| `equuleus` | 1.3.x (legacy) |
+| `crux` | 1.2.x (legacy) |
 
-Subsubsections
-^^^^^^^^^^^^^^
+PRs target `current`. After merge, request backports via Mergify comments on the PR:
 
-Paragraphs
-""""""""""
 ```
+@Mergifyio backport circinus
+@Mergifyio backport sagitta
+```
+
+Mergify is configured at the org level (no `.mergify.yml` in the repo). The PR template has a `## Backport` section to declare intent.
+
+## Architecture
+
+### Sphinx config (`docs/conf.py`)
 
-The first heading in every RST file must use `#` overline+underline. Files may have field lists (e.g., `:lastproofread:`) or labels before the heading.
+- `source_suffix = ['.rst', '.md']` — both formats build into the same site.
+- MyST extensions: `colon_fence`, `deflist`, `fieldlist`, `substitution`.
+- `myst_fence_as_directive = ["cfgcmd", "opcmd", "cmdincludemd"]` — MyST fences with these names get parsed as if they were RST directives. This is how command pages stay format-portable.
+- Custom Sphinx extensions live in `docs/_ext/`:
+  - `vyos.py` — defines the `cfgcmd`, `opcmd`, `cmdinclude` directives that drive command coverage tracking.
+  - `testcoverage.py` — reads VyOS XML command definitions and exposes coverage stats.
+  - `releasenotes.py`, `autosectionlabel.py` — release-notes builder and label-prefix tweak.
 
-### Formatting Rules
+### RST override mechanism
 
-- 80 character line limit (except inside `.. code-block::`)
-- American English
-- Indent with 2 spaces
-- Leave a blank line before and after headers
-- Use double backticks for inline code: ``` ``command`` ```
-- Use `.. code-block:: none` for command/output blocks
+For pages that have been migrated from RST to MyST:
 
-### Address Space
+- `docs/<page>.md` — canonical MD source (primary).
+- `docs/rst-<page>.rst` — preserved RST sibling kept around as an override option, prefixed `rst-` so it doesn't collide with the MD. Excluded from the build by `exclude_patterns` in `conf.py`.
+- `docs/_rst_overrides.txt` — list of page stems that should render from `rst-<page>.rst` instead of `<page>.md`. Empty by default; pages listed here have their RST temporarily activated for the build.
+- `scripts/swap_sources.py` — CLI for `--swap` (apply overrides), `--restore`, `--dry-run`, `--status`. Build-time state lands in `docs/_build/_rst_override_state.json` and `docs/_build/_md_exclude.txt` (gitignored).
 
-See `docs/documentation.rst` for canonical rules. Per RFC 5737, RFC 3849, RFC 5389, and RFC 7042:
+For pages that have NOT been migrated:
 
-The linter enforces documentation-reserved addresses. Use only:
+- `docs/<page>.rst` — original RST, no `rst-` prefix, no MD sibling.
 
-- IPv4: `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`
-- IPv6: `2001:db8::/32`
-- ASN: `64496-64511` (16-bit), `65536-65551` (32-bit)
-- MAC: `00-53-00` to `00-53-FF` (unicast), `90-10-00` to `90-10-FF` (multicast)
+**Editing rules:**
+- Migrated page (has `<page>.md`): edit the `.md`. Don't touch `rst-<page>.rst` unless you're maintaining a parallel RST version that someone has flagged in `_rst_overrides.txt`.
+- Non-migrated page (RST-only): edit the `.rst`.
+- New page: write it as `.md` from the start. The `md-` prefix that earlier MyST migration commits used is gone — never add it.
 
-**Allowed without suppression:**
+Running `make html` runs the swap automatically (it's a no-op when the override list is empty, which is the default state).
+
+### Command directives
+
+`.. cfgcmd::`, `.. opcmd::`, and `.. cmdinclude::` are the VyOS-specific Sphinx directives. They are tracked for command coverage — do **not** convert them to plain `.. code-block::`. In MyST, the same directives are written as fenced blocks: ` ```{cfgcmd} set system ... ` (the `myst_fence_as_directive` config makes this work).
+
+## Source conventions
+
+### RST heading hierarchy
+
+```
+##### Title (overline+underline, one per file)
+***** Chapters
+===== Sections
+----- Subsections
+^^^^^ Subsubsections
+""""" Paragraphs
+```
+
+The first heading in every RST file uses `#` overline+underline. Field lists (e.g., `:lastproofread:`) or labels may precede it.
+
+### Formatting
+
+- 80-character line limit (exception: inside `.. code-block::` / fenced code blocks — `<pre>` preserves source verbatim).
+- American English.
+- Indent with 2 spaces.
+- Blank lines around headings.
+- Inline code: `` ``command`` ``.
+
+### IP addresses (linter-enforced)
+
+Allowed without suppression:
+- RFC 5737 IPv4 docs: `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`
+- RFC 3849 IPv6 docs: `2001:db8::/32`
 - RFC 1918 private ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
-- Link-local, loopback, and other non-public ranges
+- Loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16`), `0.0.0.0/0`
 
-**Requires `stop/start_vyoslinter`:**
-- Real public IPs when needed for authenticity (e.g., `8.8.8.8` in DNS examples)
-- NAT64 well-known prefix `64:ff9b::/96`
-- Long URLs or certificate fingerprints that exceed 80 chars
+Allowed ASN: `64496-64511` (16-bit), `65536-65551` (32-bit).
+Allowed MAC ranges: `00-53-00`–`00-53-FF` (unicast), `90-10-00`–`90-10-FF` (multicast).
 
-### Linter Suppression
+**Requires `stop/start_vyoslinter` suppression:**
+- Real public IPs (e.g., `8.8.8.8` for DNS examples).
+- NAT64 well-known prefix `64:ff9b::/96`.
+- Lines over 80 chars (URLs, certificate fingerprints).
+
+### Linter suppression markers
 
 ```rst
 .. stop_vyoslinter
@@ -87,32 +153,29 @@ The linter enforces documentation-reserved addresses. Use only:
 .. start_vyoslinter
 ```
 
-Place markers immediately before/after the block they suppress. Always re-enable with `start_vyoslinter`.
-
-### VyOS-Specific Directives
+In MyST `.md` files use the comment form: `% stop_vyoslinter` / `% start_vyoslinter`. In `.txt` template files (included via `{include}` or `cmdincludemd`) keep the RST form: `.. stop_vyoslinter` / `.. start_vyoslinter`.
 
-- `.. cfgcmd::` — configuration mode commands
-- `.. opcmd::` — operational mode commands
-- `.. cmdinclude::` — include command definitions from XML
+Markers must always come in pairs. Indentation may match the surrounding directive (indented inside a block) or sit at column 0 (top-level) — both are valid.
 
-### Page Structure
+### Configuration page structure
 
-Each configuration page should contain:
+1. **Theory** — what it is, when to use it, relevant RFCs.
+2. **Configuration** — all CLI options as `.. cfgcmd::` (RST) or ` ```{cfgcmd} ` (MD).
+3. **Examples** — practical configurations with topology diagrams.
+4. **Known issues** — problems and workarounds.
+5. **Debugging** — log collection, `show` commands, state indicators.
 
-1. **Theory** — what it is, when to use it, relevant RFCs
-2. **Configuration** — all CLI options with `.. cfgcmd::` directives
-3. **Examples** — practical configurations with topology diagrams
-4. **Known issues** — problems and workarounds
-5. **Debugging** — log collection, `show` commands, state indicators
+### `.. TODO::` markers
 
-## CI
+Two valid uses:
+1. **Tracking** marker on pages that still need `cfgcmd`/`opcmd` conversion — intentional.
+2. **Stale** marker on pages that already have full content — should be removed.
 
-- **Linter** (`doc-linter.py` from `vyos/.github`): checks line length and IP addresses on changed files only
-- **Sphinx build**: runs on Read the Docs for each PR
-- **CLA check**: contributors must sign the CLA
+A PR that both adds and removes TODOs is not contradictory; intent matters.
 
-## Git Workflow
+## CI
 
-- Base branch: `current`
-- Branch naming: `fix/docs-*`, `feat/docs-*`
-- PRs target `current` branch
+- **vyoslinter** (`doc-linter.py` from the `vyos/.github` repo, run via `lint-doc.yml`) — line length and IP rules, on changed files only.
+- **Sphinx build** — runs on Read the Docs for every PR; preview URL appears as a check.
+- **CLA check** — contributors must sign the VyOS CLA before merge.
+- **Conflict check** — fails the PR if it doesn't merge cleanly into base.