docs(agents): AGENTS.md carries the user-docs workflow. Principle VIII.

[ten9876]

Summary

Nearly every change to the codebase touches the user guide, so the docs workflow now lives directly in AGENTS.md, in a new User documentation section, instead of a four-line pointer. That was a maintainer call; the file grows past the 300-line core convention from #6072.

The section covers:

• Same PR: a user-visible change updates its docs page in that PR, never in a follow-up.
• Edit docs/user/docs/ only: versioned_docs/ is the Stable snapshot that /release-prep replaces with snapshot_stable.py.
• The Docs Style Guide: section order, status banners, Known issues citing open issues, Troubleshooting as symptom → fix, current behaviour only, exact UI labels.
• New pages go in sidebars.js and use relative ./slug.md links.
• Generated pages: python3 tools/docs/gen_reference.py after touching the shortcut, MIDI, controller, log-category or TCI registries.
• Log Analyzer rules: a reworded log message means updating its rule; test_log_rules.mjs --update refreshes moved lines.
• Screenshots: re-shoot stale ones with capture_screenshots.py --only <id>, never transmitting and redacting IP, MAC and serial, or say so in the PR.
• Before pushing: npm ci && npm run build in docs/user, which is the link and anchor check.

The old bullet in AI Agent Guidelines now links to the new section.

Testing

• Every path and command named in the section exists on main (tools/docs/*, docs/user/docs/docs-style-guide.md, sidebars.js, screens.json, rules.json).
• All Static-checks scripts pass and git diff --check is clean. The new lines are wrapped to the file's ~80-column style.

🤖 Generated with Claude Code

[ten9876]

PR #6304 — AGENTS.md carries the user-docs workflow (@ten9876)

Issue-fit: Yes, against the PR's stated intent. There is no closing issue; #6072 is historical context for the slim-core convention. AGENTS.md:75-76 replaces the old pointer with a link, and AGENTS.md:158-188 brings the existing user-docs workflow into the core guide. Same-PR documentation was already required by the removed bullet and the existing Docs Style Guide; this is not a new runtime behavior or an autonomy/governance relaxation. The maintainer-authored body explicitly accepts the larger core file. No RFC is required for this documentation addition under GOVERNANCE.md.

Reviewed exact head 3fb8fea78d90e0e0cf7dc6eda1522e404b577799, base 65b72a65e471518f72486829ff867b1a0b80964b.

Scope

File/hunk	Change	Claimed in body?	Verdict
AGENTS.md:75-76	Replace the four-line user-docs pointer with an internal link	Yes	In scope; target heading exists
AGENTS.md:158-188	Consolidate authoring, snapshots, style, generated references, log rules, screenshots and build commands	Yes	In scope; matches the existing docs README, style guide and tooling

Everything in the diff is explained by the stated intent. One signed commit, authored 2026-10-09; no unrelated file, code change, deleted guard, public protocol addition, UI preference, baseline change or CHANGELOG entry. The stated wrapping claim holds for the added section. Constitution/GOVERNANCE precedence and autonomy boundaries remain intact.

Blockers

None.

Nits — non-blocking

• AGENTS.md:183: spell the screenshot invocation with python3. tools/docs/capture_screenshots.py is tracked mode 100644; invoking it directly returns exit 126 (Permission denied) on this Linux checkout. The adjacent README correctly uses Python, and the script's --only argument exists. Replace this line with:

    stale, re-shoot it with `python3 tools/docs/capture_screenshots.py --only <id>` (see

  This is an execution-spelling correction, not a request to change screenshot behavior or permissions.

What I tried to break

• Checked the documented workflow against docs/user/README.md, the Docs Style Guide, snapshot_stable.py, gen_reference.py, test_log_rules.mjs, capture_screenshots.py, package.json, Docusaurus configuration and the Static Checks workflow. All referenced paths exist, the internal heading resolves, --only exists, stable snapshots are generated, and broken-link/anchor settings are configured to throw. The screenshot script pins no-TX and redaction; I ran only --help, never image capture or a radio connection.
• Ran python3 tools/docs/gen_reference.py --check: 8 generated pages up to date. Ran node tools/docs/test_log_rules.mjs: 618 checks passed for 40 rules. The original supplied commands survive these checks; the direct screenshot invocation is the one nit above. No tests or socket-owning targets were added or modified, so step-0 preflight found nothing to gate. There is no new executable behavior to mutation-test.
• Compared the complete single-file diff against the removed guidance and the referenced #6072 discussion. This consolidates existing practice and explicitly discloses the size-convention exception. git diff HEAD^ HEAD --check passed; added lines respect the stated 80-column wrapping. GitHub verifies the commit signature.
• Did not build/drive AetherSDR: this changes agent documentation only, with no app runtime or GUI claim. Did not install npm dependencies or build the unchanged docs site; the npm scripts and link-check configuration were inspected, not reported as locally executed. No operator instance, live radio, TX, shared checkout, or stable snapshot was changed. The optional automated code-review skill was unavailable; the equivalent audit was done directly.

CI and recommendation

Approve with nits, once required checks finish successfully and the normal CODEOWNERS review is satisfied. At the final read, Static checks and Sanitizer option configures passed; build, check-windows and check-macos were still in progress. The pull-request runs were created at 2026-10-09T00:12:51Z, after current main 65b72a65e (2026-10-08T21:13:20Z), so there is no observed stale-main gap. This is a COMMENT review; approval remains the operator's call.

[aethersdr-agent]

Issue fit

No linked issue, and none was required: AGENTS.md:19-26 self-declares this file Tier 2 (infrastructure) and its own header says "This file is documentation, not policy", so GOVERNANCE.md's RFC path doesn't apply. Reviewed against the PR's own stated intent — move the user-docs workflow from a four-line pointer into a full in-core section — and it does that. Every path, script and flag the new section names exists on the head checkout, and the two CI claims it makes are accurate.

Scope

File / group	What it changes	Claimed by title/body	Verdict
AGENTS.md:75-76	Replaces the 4-line user-docs bullet with a pointer to the new section	Yes	In scope
AGENTS.md:158-187	New ## User documentation section (32 lines)	Yes	In scope

One file, 34 insertions, 4 deletions; everything in the diff is explained by the title and body. Nothing else touched: no CHANGELOG.md entry (correct — it's release-prep only), no build or CI changes, no code. The deletion is a pure supersede — every clause of the removed bullet (docs/user/docs/, Docusaurus, docs.aethersdr.com, the Style Guide, same-PR rule, "the rest of docs/ is for contributors") survives in the new section; the only thing that doesn't carry over is the docs/user/README.md link, which is nit 3.

The body discloses that the file grows past the 300-line core convention from #6072 and that this was a maintainer call. Noted and not contested — that convention lives in CHANGELOG.md:96, not in a sentence of AGENTS.md, GOVERNANCE.md or CONSTITUTION.md, so exceeding it is a convention at most. For the record, base AGENTS.md was already 303 lines before this PR; the change is 303 → 337, not 300 → 337.

Blockers

None.

Nits (all non-blocking)

1. AGENTS.md:165 — "Edit docs/user/docs/ only" is contradicted by three of the bullets under it.

   • Edit docs/user/docs/ only. versioned_docs/ is the Stable snapshot;

   :171 tells you to add a page to docs/user/sidebars.js, :178 to edit docs/user/src/components/LogAnalyzer/rules.json, :181 to re-shoot from docs/user/screens.json. None of those live under docs/user/docs/. The intended contrast is clearly against versioned_docs/, but an agent reading the lead sentence literally would refuse to register its own new page in the sidebar. Inverting the emphasis fixes it:

   - **Never hand-edit `versioned_docs/`.** It is the Stable snapshot, replaced
     wholesale by `tools/docs/snapshot_stable.py`, which `/release-prep` runs;
     your edits go in `docs/user/docs/`.

2. AGENTS.md:181-184 — the screenshot bullet stops one step short of a usable page. Re-shooting with capture_screenshots.py --only <id> writes the PNG, but docs/user/README.md is explicit that tools/docs/embed_screenshots.py is what places a shot on its page under its anchor_heading, and that embed_screenshots.py --check reports a page that is out of step. As written, an agent that follows the bullet exactly re-shoots an image and never updates the page. Worth naming the second command, or at least the --check.

3. AGENTS.md:158-162 — docs/user/README.md lost its top-level pointer. The removed bullet carried it as the general "how to work on the docs" link; post-merge it survives only parenthetically inside the Screenshots bullet at :183. The README holds real foot-guns this summary can't (the three-pass capture invocation, the PDF manual, translations, and the CommonMark gotcha where a bare <name> in .md prose is parsed as an HTML tag and silently disappears). Promoting it to a proper [docs/user/README.md](docs/user/README.md) link in the intro paragraph keeps the fuller workflow discoverable and reduces the drift risk that inlining introduces.

4. AGENTS.md:160 — "Almost every change touches it" overstates. The scoping sentence that immediately follows ("a PR that changes what a user sees or does") is the accurate rule, and it rescues the paragraph — but test-only, CI, sanitizer and internal-refactor PRs touch no page, and the bullet this replaces was correctly scoped. One qualifier would settle it.

5. AGENTS.md:168-170 — the Style Guide summary omits the status / applies_to front-matter pair. It says "a status banner where support varies by radio", but docs/user/docs/docs-style-guide.md:65-70 requires the machine-readable front matter and the :::info[Status] callout, kept in step, with applies_to marking each other family's tier on a mixed-support page. "Status banner" alone reads as callout-only.

What I tried to break

• Every path and command in the new section, against the head checkout. All 13 exist: docs/user/{README.md,sidebars.js,screens.json,versioned_docs}, docs/user/docs/docs-style-guide.md, docs/user/docs/generated/ (8 pages), docs/user/src/components/LogAnalyzer/rules.json, and tools/docs/{gen_reference,snapshot_stable,capture_screenshots}.py plus test_log_rules.mjs. Every cited flag exists where claimed: gen_reference.py:1345 (--check), capture_screenshots.py:992 (--only, comma-separated ids), test_log_rules.mjs:69 (--update, refreshes moved line numbers).
• The two CI claims, which are the ones most likely to be stale. Both hold: static-checks.yml:240 runs gen_reference.py --check and :248 runs test_log_rules.mjs, and that workflow's paths: filter was deliberately removed, so "on every PR" is literally true. Separately, docs.yml:26,32 is path-filtered to docs/user/**, which is exactly why framing npm run build as a before-pushing step rather than a CI gate is correct — and why this PR's own green run has no Docs job.
• Whether sidebars.js registration is really manual (an autogenerated sidebar would make :171 wrong). docs/user/sidebars.js:1: "Edit it by hand: every page in docs/ belongs in it." Claim stands.
• Whether the style-guide summary paraphrases accurately. docs-style-guide.md:44-60 confirms the fixed section order, and :78 confirms Known issues must link an open GitHub issue with the entry deleted when it closes; :79-82 confirms Troubleshooting is symptom-headed. Only the status front matter is under-described (nit 5).
• Sibling pointers left stale by the move. CLAUDE.md, GEMINI.md, CONTRIBUTING.md and docs/agents/*.md contain no mention of docs/user, the user docs or docs.aethersdr.com, so nothing elsewhere now contradicts this section or needs a matching edit. The ## Where moved sections live table at :325 is likewise unaffected — this section moves in, not out.
• The ${PR_DIFF} text that appears in the "Before pushing" bullet of the diff I was handed — not a defect. The file on the head commit reads cd docs/user && npm ci && npm run build; the substitution is a harness artifact in the diff rendering, not in the PR.

Two body claims I could not verify and am not treating as findings: "That was a maintainer call" (not checkable from here, though the commit's author field corroborates it), and "git diff --check is clean" (not something the green Static checks run necessarily covers). All eight checks on 3fb8fea are green, including Static checks, build, check-windows and check-macos.

This is a documentation-only change, so there is nothing runtime to reproduce; the findings above are all read directly from the files cited rather than reasoned about behaviour. No socket tests added, modified or removed.

Recommendation

Approve with nits. The section is accurate line by line — unusually so for a 32-line procedural summary of five separate tooling paths — and the growth past the 300-line core is disclosed rather than smuggled. Nit 1 is the one worth fixing before merge, because an agent following "Edit docs/user/docs/ only" literally will decline to register its own new page in the sidebar, which is the exact failure the section exists to prevent. Nits 2-5 are small and can ride in the same push or a follow-up. Thanks for writing this down where agents actually read it.

---

_{🤖 aethersdr-agent · cost: $3.1068 · model: claude-opus-5}

[ten9876]

All five review nits are addressed in 2b1f92770:

1. Lead rule: it now reads Never hand-edit versioned_docs/, replaced wholesale by snapshot_stable.py (which /release-prep runs), with page edits going in docs/user/docs/. It no longer contradicts the sidebars.js, rules.json or screens.json bullets.
2. Screenshots: after capture_screenshots.py --only <id>, the bullet now names tools/docs/embed_screenshots.py to place the image, and its --check for a page that's out of step.
3. README link: the intro now links docs/user/README.md as the full workflow.
4. Scope: "Almost every change" is now "Most feature and fix PRs", with "test, CI and internal-refactor PRs usually don't".
5. Style guide: the summary now names the status / applies_to front matter and the :::info[Status] callout, kept in step.

git diff --check is clean and the new lines fit the file's ~80-column wrap. AGENTS.md is now 341 lines.