From 93a5bdc70468ff92196e00783e6871de1891282f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 13 May 2026 10:14:12 +0000
Subject: docs(agents): address Copilot review on stale RST-era conventions

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.
---
 AGENTS.md | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9fa05a59..32c5885d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -142,6 +142,11 @@ include logic but follow the host file's parser, so pick
 
 ### RST heading hierarchy
 
+Applies only to RST contexts — `_include/*.txt` snippets and
+`{eval-rst}` blocks inside MyST pages. Canonical pages are MyST and
+use ATX `#` / `##` / `###` etc. headings; this hierarchy does not
+apply to them.
+
 ```
 ##### Title (overline+underline, one per file)
 ***** Chapters
@@ -151,8 +156,9 @@ include logic but follow the host file's parser, so pick
 """"" Paragraphs
 ```
 
-The first heading in every RST file uses `#` overline+underline. Field
-lists (e.g., `:lastproofread:`) or labels may precede it.
+The first heading in every embedded RST snippet that introduces a
+title uses `#` overline+underline. Field lists (e.g.,
+`:lastproofread:`) or labels may precede it.
 
 ### Formatting
 
@@ -161,7 +167,9 @@ lists (e.g., `:lastproofread:`) or labels may precede it.
 - American English.
 - Indent with 2 spaces.
 - Blank lines around headings.
-- Inline code: use double backticks per RST convention.
+- Inline code: single backticks in MyST (the canonical form). Double
+  backticks only inside `{eval-rst}` blocks and `_include/*.txt`
+  snippets, per RST convention.
 
 ### IP addresses (linter-enforced)
 
@@ -177,10 +185,9 @@ Allowed MAC ranges: `00-53-00`–`00-53-FF` (unicast),
 
 **Requires `stop/start_vyoslinter` suppression:**
 
-% stop_vyoslinter
-- Real public IPs (e.g., `8.8.8.8` for DNS examples).
+- Real public IPs (e.g., a DNS server's address in a DNS forwarder
+  example, or an upstream peer's address in an EBGP example).
 - NAT64 well-known prefix `64:ff9b::/96`.
-% start_vyoslinter
 - Lines over 80 chars (URLs, certificate fingerprints).
 
 ### Linter suppression markers
@@ -216,9 +223,13 @@ surrounding directive (indented inside a block) or sit at column 0
 4. **Known issues** — problems and workarounds.
 5. **Debugging** — log collection, `show` commands, state indicators.
 
-### `.. TODO::` markers
+### `{todo}` markers
+
+In MyST pages, write TODO markers as `{todo}` fenced directives
+(triple-backtick or `:::` fenced blocks with `{todo}` as the info
+string). In RST contexts (`{eval-rst}` blocks, `_include/*.txt`
+snippets) use the RST form `.. TODO::`. Two valid uses:
 
-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
-- 
cgit v1.2.3