docs: bring the docs tree into the large band #1673

Merged

coilysiren merged 1 commit from aos/claude/aw85-docs-bands into main

2026-08-17 02:15:16 +00:00

coilyco-ops commented

2026-08-17 01:55:50 +00:00

Member

Refs #1670, part of coilysiren/inbox#374.

The large band Kai assigned turned a 42-to-20 migration into two merges and one generated page.

The generated page

docs/agent-flags.md was 142 lines against the 120-line cap. It is generated with a drift test, so the fix is the generator: the emitter wrote a heading, a blank, and a bullet for each of 46 commands. It writes one row per command now, and the page is 53 lines with identical content. TestAgentFlagsMarkdownShape asserted the heading form and now asserts the row form.

Worth knowing: this repo's pyproject.toml excludes that file from documentation-layout, and under the band rule excludes no longer reaches a size cap. The exclude still governs placement so it is left alone, but it was not what kept this page legal.

The two merges

42 docs to 40, both pairs being one subject split in half:

container and container-substrate - the filesystem a run gets, and which part of it is authoritative writable work.
agent-dispatch-health and agent-dispatch-recovery - what a restarted broker reconciles, and what the health verb reports.

Nine files referencing the merged-away pages are repointed, four of them Go source comments that source-doc-refs would have caught.

Verification

documentation-layout from aos-precommit-v0.24.0 reports clean. go build clean, the flag-tree tests pass.

One pre-existing failure is untouched and not mine: code-comments flags cmd/ward/agent.go:1338, a file this branch does not modify.

Timing

ward pins ea1f4086, which predates the bands, so this lands ahead of the pin bump rather than in response to a red build.

Refs #1670, part of coilysiren/inbox#374. The large band Kai assigned turned a 42-to-20 migration into two merges and one generated page. ## The generated page `docs/agent-flags.md` was 142 lines against the 120-line cap. It is generated with a drift test, so the fix is the generator: the emitter wrote a heading, a blank, and a bullet for each of 46 commands. It writes one row per command now, and the page is **53 lines with identical content**. `TestAgentFlagsMarkdownShape` asserted the heading form and now asserts the row form. Worth knowing: this repo's `pyproject.toml` excludes that file from `documentation-layout`, and under the band rule `excludes` no longer reaches a size cap. The exclude still governs placement so it is left alone, but it was not what kept this page legal. ## The two merges 42 docs to 40, both pairs being one subject split in half: * `container` and `container-substrate` - the filesystem a run gets, and which part of it is authoritative writable work. * `agent-dispatch-health` and `agent-dispatch-recovery` - what a restarted broker reconciles, and what the health verb reports. Nine files referencing the merged-away pages are repointed, four of them Go source comments that `source-doc-refs` would have caught. ## Verification `documentation-layout` from `aos-precommit-v0.24.0` reports clean. `go build` clean, the flag-tree tests pass. One pre-existing failure is untouched and not mine: `code-comments` flags `cmd/ward/agent.go:1338`, a file this branch does not modify. ## Timing ward pins `ea1f4086`, which predates the bands, so this lands ahead of the pin bump rather than in response to a red build.

coilyco-ops added 1 commit

2026-08-17 01:55:50 +00:00

docs: bring the docs tree into the large band

test / test (pull_request) Successful in 47s

Details

893907cbf4

Kai put ward on the large band, which turned a 42-to-20 migration into two doc
merges and one generated page.

docs/agent-flags.md was 142 lines against the 120-line cap. It is generated,
with a drift test, so the fix is the generator rather than the file: the
markdown emitter wrote a heading, a blank, and a bullet for each of 46
commands. It writes one row per command now, and the page is 53 lines with the
same content. TestAgentFlagsMarkdownShape asserted the heading form, so it
asserts the row form instead.

The repo's pyproject excludes this file from documentation-layout, which no
longer reaches a size cap under the band rule. The exclude is left in place
since it still governs placement, but it is not what was keeping this page
legal.

Two merges take the count from 42 to 40. container and container-substrate are
the filesystem a run gets and which part of it is authoritative writable work.
agent-dispatch-health and agent-dispatch-recovery are what a restarted broker
reconciles and what the health verb reports. Nine files referencing the two
merged-away pages are repointed, including four Go source comments.

Part of coilysiren/inbox#374.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-17 01:55:50 +00:00