docs: refresh README + AGENTS source-format claim for circinus

Adapted from PR #2014 on rolling, tailored to this branch's actual
state.

This branch (circinus, 1.5.x LTS) is mostly migrated to MyST
Markdown. 11 RST pages remain in the build alongside the .md set:

- docs/changelog/index.rst + docs/changelog/{1.2.1..1.2.6, 1.3,
  1.4, 1.5}.rst (auto-generated; stayed RST)
- docs/automation/terraform/terraformvyos.rst

source_suffix in docs/conf.py is `['.rst', '.md']` to cover both.

Changes:

- README.md: new `## Source format` section naming the legacy RST
  pages, pointing at the `_rst_legacy/` archive, and noting the
  MyST-fence form for VyOS command directives in .md pages. The
  `## Contributing` blurb drops the now-imprecise "MyST for migrated
  pages, RST for the rest" phrasing.
- AGENTS.md: `## Project` and `### Source files` sections updated
  to enumerate the 11 remaining RST pages explicitly so contributors
  know which files are still RST and which to write as MyST.

Linter origin claim ("doc-linter.py from the vyos/.github repo")
left intact — that script is NOT inlined on this branch (the inline
move on rolling at 2026-05-10 has not been backported to circinus).

🤖 Generated by [robots](https://vyos.io)

2 files changed, 31 insertions, 10 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 2d2b128d..540005e7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,9 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## 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 pages that haven't been migrated yet. Both formats are first-class to Sphinx.
+VyOS user documentation, built with Sphinx and hosted on Read the Docs at https://docs.vyos.io. This branch (`circinus`, 1.5.x LTS) is mostly migrated to MyST Markdown (`.md`). 11 legacy pages remain as RST and are built alongside the Markdown: the changelog set under `docs/changelog/*.rst` and `docs/automation/terraform/terraformvyos.rst`. `source_suffix` in `docs/conf.py` is `['.rst', '.md']`. Both formats are first-class to Sphinx.
 
-Pre-migration RST shadows of migrated pages are archived under `docs/_rst_legacy/` for reference only — they are excluded from the build and not consulted by Sphinx.
+Pre-migration RST shadows of converted pages are archived under `docs/_rst_legacy/` for reference only — they are excluded from the build, not consulted by Sphinx, and must not be edited.
 
 ## Build
 
@@ -75,13 +75,16 @@ Mergify is configured at the org level (no `.mergify.yml` in the repo). The PR t
 
 ### Source files
 
-- `docs/<subdir>/<page>.md` — canonical MD source for migrated pages.
-- `docs/<page>.rst` — canonical RST source for pages that have not been migrated yet (no `rst-` prefix, no MD sibling).
-- `docs/_rst_legacy/<subdir>/rst-<page>.rst` — archived pre-migration RST shadows. Excluded from the Sphinx build and from the Context7 index. Reference only.
+- `docs/<subdir>/<page>.md` — canonical MD source for migrated pages (most of the tree).
+- The 11 RST-only pages on this branch:
+  - `docs/changelog/index.rst` + `docs/changelog/{1.2.1,1.2.2,1.2.3,1.2.4,1.2.5,1.2.6,1.3,1.4,1.5}.rst` (the changelog set is auto-generated and stayed RST).
+  - `docs/automation/terraform/terraformvyos.rst`.
+- `docs/_include/<name>.txt` — shared RST snippets included into MyST pages via `cmdincludemd`. Their content is parsed as RST so the legacy templates keep working unchanged.
+- `docs/_rst_legacy/<subdir>/rst-<page>.rst` — archived pre-migration RST shadows of converted pages. Excluded from the Sphinx build and from the Context7 index. Reference only.
 
 **Editing rules:**
-- Migrated page (has `<page>.md`): edit the `.md`. Do not touch the archived shadow under `_rst_legacy/`.
-- Non-migrated page (RST-only): edit the `.rst`.
+- Existing migrated page (has `<page>.md`): edit the `.md`. Do not touch the archived shadow under `_rst_legacy/`.
+- One of the 11 remaining RST-only pages above: 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.
 
 ### Command directives
diff --git a/README.md b/README.md
index 290c6ce1..ab46133b 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,24 @@ https://docs.vyos.io.
 The earlier wiki for VyOS 1.1.x and pre-1.2.0 docs is preserved on the
 [Wayback Machine](https://web.archive.org/web/20200225171529/https://wiki.vyos.net/wiki/Main_Page).
 
+## Source format
+
+This branch (`circinus`, 1.5.x LTS) is mostly migrated to
+[MyST Markdown](https://myst-parser.readthedocs.io/) (`.md`). 11 legacy
+pages remain in RST and are picked up alongside the Markdown — the
+changelog set under `docs/changelog/*.rst` and
+`docs/automation/terraform/terraformvyos.rst`. `source_suffix` in
+`docs/conf.py` is `['.rst', '.md']` to cover both. The pre-migration
+RST shadows of converted pages are archived under `docs/_rst_legacy/`
+for reference; they are excluded from the build and must not be
+edited.
+
+VyOS-specific command directives (`cfgcmd`, `opcmd`, `cmdincludemd`)
+are written as MyST fenced blocks in `.md` pages
+(`myst_fence_as_directive` in `conf.py`) and as the RST forms
+`.. cfgcmd::` / `.. opcmd::` / `.. cmdinclude::` in the remaining
+`.rst` pages and in shared `_include/*.txt` snippets.
+
 ## Branches
 
 The documentation repository tracks the same branch convention as the VyOS
@@ -60,6 +78,6 @@ Output lands in `docs/_build/html/`.
 
 ## Contributing
 
-See [AGENTS.md](AGENTS.md) for the full contributor guide — source format
-conventions (MyST Markdown for migrated pages, RST for the rest), CLI
-directive syntax, IP-address rules, the linter, and the bot review workflow.
+See [AGENTS.md](AGENTS.md) for the full contributor guide — MyST
+conventions, CLI directive syntax, IP-address rules, linter
+suppression markers, and the Copilot / CodeRabbit bot workflow.