vyos-documentation.git/AGENTS.md, branch rolling

docs(agents): doc-linter is in-repo, scoped to docs/ — fix stale references

2026-05-13T12:43:31+00:00

Two stale claims flagged by Copilot in PR #2014 (one comment marked the other as 'same issue earlier in the file'): - '## Lint' (L40-45): said 'vyoslinter (doc-linter.py from the vyos/.github repo, via the lint-doc.yml workflow) on changed files only'. The cross-repo dependency was dropped in 1bf386e — the linter is now scripts/doc-linter.py in this repo, invoked from .github/workflows/lint-doc.yml. - '## CI' (L290-292): same stale claim in bullet form. Also reflect 65a8e9f's scoping decision: the linter applies only to files under docs/. Repo-root meta files (README.md, AGENTS.md, .github/copilot-instructions.md) are explicitly out of scope, since they are project meta rather than published documentation and don't need to obey docs-publication conventions (80-char wrap, RFC IP rules, suppression markers). Mention that exclusion in the CI bullet so contributors know the linter won't catch issues there.

docs(agents): address Copilot review on stale RST-era conventions

2026-05-13T10:14:12+00:00

Four follow-up findings from Copilot on commit e8d7e43, all valid: - '### Formatting' bullet 'Inline code: use double backticks per RST convention' was carried over from the RST era. The .md sources are overwhelmingly single-backtick (~1900 single- vs ~80 double-backtick inline-code spans across docs/). Rewrite to 'single backticks in MyST (the canonical form). Double backticks only inside {eval-rst} blocks and _include/*.txt snippets, per RST convention.' - '### RST heading hierarchy' section read like a general authoring rule. Add a preface scoping it explicitly to RST contexts (_include/*.txt and {eval-rst} blocks) and noting that canonical MyST pages use ATX (# / ## / ...) headings. Reword the post-block prose to 'every embedded RST snippet that introduces a title' instead of 'every RST file'. - '### `.. TODO::` markers' heading and prose described the RST form only. The .md sources use `{todo}` fenced directives exclusively (6 triple-backtick + 1 colon-fenced occurrences across docs/, zero `.. TODO::` in .md). Rename the section to '`{todo}` markers', describe the MyST fenced form first, and mention the RST form only for RST contexts. - Drop the '% stop_vyoslinter' / '% start_vyoslinter' markers I added around the '8.8.8.8' DNS example bullet under '### IP addresses'. Replace the literal IP with a description-only example ('a DNS server's address in a DNS forwarder example, or an upstream peer's address in an EBGP example'). The bullet still illustrates the rule (real public IPs need suppression) without rendering bare '% stop_vyoslinter' lines in GitHub views. Local doc-linter still exits 0 on AGENTS.md and README.md.

docs(agents): reflect completed MyST migration + bulk hard-wrap to 80 chars

2026-05-13T10:08:16+00:00

The previous README refresh sweep landed before the doc-linter was extended to MyST in 7a3aa29, so AGENTS.md was never wrapped to the 80-char rule its own 'Source conventions' section documents, and the source-format claims drifted out of sync once the RST->MyST migration finished. Content fixes (the inconsistency Copilot flagged on PR #2014): - '## Project': drop the 'MyST Markdown for migrated pages and RST for pages that haven't been migrated yet' framing. State plainly that sources are MyST Markdown only, source_suffix is ['.md'], and the RST archive under docs/_rst_legacy/ is not editable. - '### Sphinx config': source_suffix entry updated from ['.rst', '.md'] to ['.md']. - '### Source files': drop the 'docs/.rst' non-migrated bullet (no such pages exist). Add a 'docs/_include/.txt' bullet noting that the shared snippets stay RST because cmdincludemd parses their content as RST. - '**Editing rules:**': collapse 'Migrated page' / 'Non-migrated page' into one 'Existing page' rule. Add a bullet pointing at the _include/*.txt -> RST exception. - '### Command directives': rewrite to lead with MyST fenced blocks (the canonical form) and only mention RST forms for {eval-rst} blocks and _include/*.txt snippets. Avoid using literal quad-backtick code-in-code samples that would otherwise open phantom fences in the source. Linter compliance: - Hard-wrap every paragraph and bullet outside fenced code blocks to <=80 chars (~30 pre-existing violations). - Wrap the long line about the docutils inline-markup link by dropping the link entirely; the rule 'use double backticks' is self-contained and AGENTS.md doesn't need the reference. - Restructure '### Bot review workflow' table: shorten the CodeRabbit row to 79 chars and move the 'auto-reviews are disabled' note to a paragraph below the table. - Wrap the '8.8.8.8' real-public-IP bullet under '### IP addresses' with '% stop_vyoslinter' / '% start_vyoslinter' markers. The surrounding section is literally documenting suppression markers, so the meta-example reads naturally. - The '### Configuration page structure' bullet referring to MD fence syntax was using quad-backtick code-in-code; rewritten to '`{cfgcmd}` fenced code blocks (in MD)' to avoid opening a phantom fence in the linter's view of the source.

docs: refresh Mergify backport guidance — single-line syntax + maintainer-only

2026-05-10T15:38:34+00:00

- Update example to the consolidated `@Mergifyio backport circinus sagitta` form (multiple branches in one command, space-separated). The one-branch-per-line form still works but is no longer required. - Document that only Maintainers team members can invoke @Mergifyio commands — Mergify silently drops commands from anyone outside the team, with no error reply. Useful failure mode to know about: if a backport does not trigger, check team membership first. 🤖 Generated by [robots](https://vyos.io)

docs: refresh README + sweep stale `current` refs in AGENTS.md

2026-05-10T15:06:54+00:00

- Rewrite README.md: drop Python 2 install dance, drop `sphinx-panels` (removed years ago), drop `sudo pip install` antipattern, replace with venv + requirements.txt path. Refresh the branch table to current naming, point contributors at AGENTS.md for the full guide. Refresh the docs status badge to reference `rolling` (was `latest`). - AGENTS.md: replace remaining `current` branch references with `rolling` in the branch table, the "PRs target …" line, and the RTD layout table Branch column. The default branch was renamed `current` → `rolling` on 2026-05-10 (commit 8dbf8b05 only swept CI). 🤖 Generated by [robots](https://vyos.io)

chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/

2026-05-10T14:19:31+00:00

The swap mechanism (RST-as-fallback for migrated MD pages) is dormant — docs/_rst_overrides.txt has been empty since the MyST flip trio (#1899/#1900/#1901) landed in May 2026. The mechanism's surface area (scripts/swap_sources.py, its 245-line test, RTD pre/post hooks, Makefile glue, conf.py dynamic loader) is dead weight, and the rst-*.rst shadows scattered across the source tree cause Context7's parser to misclassify the project as RST. Changes: - Move 253 rst-*.rst shadow files into docs/_rst_legacy/ preserving subdirectory structure. They remain in the repo for reference; Sphinx excludes the folder via exclude_patterns; Context7 excludes it via excludeFolders. - Strip swap_sources.py invocation from docs/Makefile (swap/restore targets, : swap deps, trap chains). - Strip jobs: pre_build/post_build block from .readthedocs.yml. - Strip rst-*.rst exclude entry and the _md_exclude.txt loader from docs/conf.py; replace with a single _rst_legacy exclude. - Delete scripts/swap_sources.py, tests/test_swap_sources.py, docs/_rst_overrides.txt. - Update context7.json: add docs/_rst_legacy to excludeFolders; fix stale "Branch current tracks…" rule to "Branch rolling tracks…" (default branch was renamed 2026-05-10). - Update AGENTS.md: drop the "RST override mechanism" section and the test-runner snippet for the deleted test; describe _rst_legacy as archive only. Verified: sphinx-build -b html with --keep-going produces identical warning set (68 unique), identical sitemap entry count (257), identical llms.txt entry count (22), zero rst-* URLs in any artifact. 🤖 Generated by [robots](https://vyos.io)

fix(agents-md): add language tag to Mergify command fenced block

2026-05-07T13:42:49+00:00

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

docs(agents-md): Mergify commands work in comments only, not PR body

2026-05-07T13:17:03+00:00

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

docs(agents-md): document bot review workflow (Copilot=draft, CodeRabbit=ready)

2026-05-07T13:16:06+00:00

Copilot review must only be triggered on draft PRs. CodeRabbit review must only be triggered on ready-for-review PRs. Auto-reviews are disabled on this repo so CodeRabbit requires manual trigger. 🤖 Generated by [robots](https://vyos.io)

general: T8595: switch CLAUDE.md to AGENTS.md (+ Copilot symlink)

2026-05-07T12:38:27+00:00