Merge pull request #1912 from vyos/chore/docs-claude-md-expand-sagitta

docs(claude-md): add LLM-facing files + RTD layout sections

1 files changed, 47 insertions, 0 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 99320758..f4759273 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -187,6 +187,53 @@ Two valid uses:
 
 A PR that both adds and removes TODOs is not contradictory; intent matters.
 
+## LLM-Facing Files (`llms.txt`, `llms-full.txt`)
+
+Both files are regenerated on every `html` and `readthedocs` builder run.
+The `dirhtml` builder is intentionally skipped — production publishes
+only via `html`/`readthedocs`, and we don't render `llms.txt` for builds
+we don't ship. Local `make dirhtml` is a developer convenience and
+won't emit `llms.txt`.
+
+Files are shipped at the docs root for each version
+(`https://docs.vyos.io/en/<version>/llms.txt`, `.../llms-full.txt`).
+
+- **`llms-full.txt`** — auto-generated by the `sphinx_llms_txt` extension from
+  the full corpus. No curation; configured by `llms_txt_file = False` (which
+  disables the extension's *index* output, not the full output).
+- **`llms.txt`** — curated overview rendered at build time from
+  `docs/_templates/llms.txt.j2`. URLs and the version line are interpolated
+  from `html_baseurl` and `release` so the file always matches the branch.
+  The render lives in `_write_llms_txt(app, exception)` in `docs/conf.py`,
+  wired via `app.connect('build-finished', ...)`.
+
+When adding new top-level sections to the docs, add a corresponding bullet in
+`docs/_templates/llms.txt.j2`. Branch-specific differences (e.g. sagitta has
+no `vpp/index.md` or `contributing/index.md`) live in that branch's copy of the template.
+
+## Read the Docs Layout
+
+RTD slugs as of 2026-05-04 (verified via API). Re-verify via the RTD
+Versions API (project `vyos`) and update the date stamp before editing this
+table.
+
+| Slug | Verbose | Branch | Role |
+|---|---|---|---|
+| `rolling` | current | `current` | canonical for rolling/next major |
+| `1.5` | circinus | `circinus` | canonical for current LTS |
+| `1.4` | sagitta | `sagitta` | canonical for previous LTS |
+| `1.3`, `1.2` | equuleus, crux | older | canonical for older releases |
+
+URL-level redirect aliases (resolve to the canonicals above):
+`/en/latest/* → /en/rolling/`, `/en/lts/* → /en/1.5/`,
+`/en/stable/* → /en/lts/`, `/en/circinus/* → /en/1.5/`,
+`/en/sagitta/* → /en/1.4/`, `/en/equuleus/* → /en/1.3/`,
+`/en/crux/* → /en/1.2/`.
+
+`html_baseurl` per branch must point at the canonical (numeric or `rolling`),
+not the alias, so `<link rel="canonical">` and the sitemap match what RTD
+serves and crawlers skip the redirect hop.
+
 ## CI
 
 - **vyoslinter** (`doc-linter.py` from the `vyos/.github` repo, run via `lint-doc.yml`) — line length and IP rules, on changed files only.