docs: migrate sirens-echo onto the large documentation band #896

Merged
coilysiren merged 31 commits from aos/claude/aw85-se-bands into main 2026-08-17 14:05:36 +00:00
Member

Closes the sirens-echo half of coilysiren/inbox#374.

164 docs -> 40, 10,409 -> 4,158 lines, every page inside the large band's per-file caps (120 lines / 8,000 chars). pre-commit run --all-files, go vet, and go test ./... are green.

The pin was the gate. sirens-echo sat on aos-precommit-v0.18.0, whose 80-line / 4,000-char cap forbids exactly the merges the 40-doc count cap requires, so the local band checks passed while the installed suite failed on the same files. Bumped to aos-precommit-v0.24.0.

The knob table moved out of docs/. It was 94 lines of one-row-per-number, which no prose budget survives sharing a page with. Per the band doctrine that the fix for a generated file over the cap is the generator, RenderKnobReference now emits two NAME=default pairs per line into agent/rendered/knobs.txt, beside the other rendered artifacts, and docs/sirens-echo-tuning.md is the human page that points at it. Its exclude in pyproject.toml is gone with it.

119 files were repointed at merged pages, including three tests that read a doc path (validatorlanguage_test.go, glyphdoc_test.go, composedprovenance_test.go) and two that assert on contents. The glyph table and its > 🔨 example footer are restored verbatim in sirens-echo-tool-markup.md, because glyphdoc_test.go parses them, and sirens-echo-rate.md still carries composed, stubbed, and agent-compose for the same reason.

Content was deleted, not compressed away. The band's own thesis in agentic-os names this repo as the proof that a per-doc size cap with no count cap grows a folder nobody can read: 156 docs, none over the old limit. So the deliberation went and the rules stayed. Every threshold, identifier, env var, issue reference, and load-bearing why survived: the \A\s*ORCHID\b anchor, the sub-100 microsecond gap that settled #258, the 74-93us window, PlaceholderComposed at 249 bytes against 53,133, the 898-spans-against-169-turns contamination, the eco-app.coilysiren.me first-label walk, the CGNAT-is-the-tailnet reason, and the data: wrapper that failed loudly one way and silently the other.

No mechanical compressor. An earlier one truncated bullet lists and merged headings into prose on eco-app, so every page here is hand-written.

Closes the sirens-echo half of coilysiren/inbox#374. **164 docs -> 40, 10,409 -> 4,158 lines**, every page inside the large band's per-file caps (120 lines / 8,000 chars). `pre-commit run --all-files`, `go vet`, and `go test ./...` are green. **The pin was the gate.** sirens-echo sat on `aos-precommit-v0.18.0`, whose 80-line / 4,000-char cap forbids exactly the merges the 40-doc count cap requires, so the local band checks passed while the installed suite failed on the same files. Bumped to `aos-precommit-v0.24.0`. **The knob table moved out of `docs/`.** It was 94 lines of one-row-per-number, which no prose budget survives sharing a page with. Per the band doctrine that the fix for a generated file over the cap is the generator, `RenderKnobReference` now emits two `NAME=default` pairs per line into `agent/rendered/knobs.txt`, beside the other rendered artifacts, and `docs/sirens-echo-tuning.md` is the human page that points at it. Its exclude in `pyproject.toml` is gone with it. **119 files were repointed** at merged pages, including three tests that read a doc path (`validatorlanguage_test.go`, `glyphdoc_test.go`, `composedprovenance_test.go`) and two that assert on contents. The glyph table and its `> 🔨` example footer are restored verbatim in `sirens-echo-tool-markup.md`, because `glyphdoc_test.go` parses them, and `sirens-echo-rate.md` still carries `composed`, `stubbed`, and `agent-compose` for the same reason. **Content was deleted, not compressed away.** The band's own thesis in agentic-os names this repo as the proof that a per-doc size cap with no count cap grows a folder nobody can read: 156 docs, none over the old limit. So the deliberation went and the rules stayed. Every threshold, identifier, env var, issue reference, and load-bearing why survived: the `\A\s*ORCHID\b` anchor, the sub-100 microsecond gap that settled #258, the 74-93us window, `PlaceholderComposed` at 249 bytes against 53,133, the 898-spans-against-169-turns contamination, the `eco-app.coilysiren.me` first-label walk, the CGNAT-is-the-tailnet reason, and the `data:` wrapper that failed loudly one way and silently the other. **No mechanical compressor.** An earlier one truncated bullet lists and merged headings into prose on eco-app, so every page here is hand-written.
Three of the forty target pages. 164 -> 153 docs so far.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Nine of forty target pages; 164 -> 140 docs.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
The generated knob table was 94 lines of one-row-per-number, which no prose
budget survives sharing a page with. Per the band doctrine, the fix for a
generated file over the cap is the generator: it now emits two pairs per line
into agent/rendered/knobs.txt, beside the other rendered artifacts, and
docs/sirens-echo-tuning.md is the human page that points at it.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
119 files, including three tests that read a doc path and two that assert on
its contents. The glyph table and its example footer are restored verbatim in
sirens-echo-tool-markup.md, because glyphdoc_test.go parses them.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
164 docs to 40, 10,409 lines to 4,436, both inside the large band's folder
budget. Per-file caps are the remaining pass.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
docs(bands): finish the large-band migration and bump the hook pin
All checks were successful
ci / test (pull_request) Successful in 55s
ci / publish-echo-image (pull_request) Has been skipped
ci / publish-observed (pull_request) Has been skipped
ci / image-build (pull_request) Successful in 27s
2f6751007c
164 docs to 40, 10,409 lines to 4,158, and every page inside the large band's
per-file caps of 120 lines and 8,000 chars. `pre-commit run --all-files`,
`go vet`, and `go test ./...` are all green.

The pin was the gate. sirens-echo sat on aos-precommit-v0.18.0, whose 80-line
cap forbids exactly the merges the 40-doc count cap requires, so the local
checks passed while the installed suite failed. Bumped to v0.24.0.

The generated knob table moved out of docs/ to agent/rendered/knobs.txt and
now emits two pairs per line instead of 94 table rows: per the band doctrine,
the fix for a generated file over the cap is the generator, and the table was
the one page no prose budget could share.

119 files were repointed at merged pages, including three tests that read a
doc path and two that assert on its contents. The glyph table and its example
footer are restored verbatim, because glyphdoc_test.go parses them.

Content was deleted, not compressed away. The band's own thesis names this
repo as the proof that a per-doc size cap with no count cap grows a folder
nobody can read, so the deliberation was cut and the rules, identifiers,
thresholds, and load-bearing whys were kept.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
coilyco-gaming/sirens-echo!896
No description provided.