coilyco-gaming/sirens-echo

Watch

docs band migration: merge 118 docs #865

New issue

Closed

opened 2026-08-16 06:59:54 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-16 06:59:54 +00:00

Member

This repo declares the large documentation band, so its caps are
120 lines / 8,000 chars per Markdown file and 40 docs/*.md.

Measured by running the validator against this checkout:

docs/: 158 files against a 40 cap - 118 to merge away
0 files over a size cap - none

The work

Merge docs/ from 158 pages down to 40. Related pages join; a page that only exists because another got too long goes back where it came from.

Merging is the move, not splitting. Splitting one over-long doc into two trades
a size violation for a count violation, which is the whole reason the count cap
exists.

Done means

pre-commit run --all-files green, with no new entry under
[tool.agentic-os.documentation-layout] excludes. Excludes still govern
placement and flatness and no longer reach either size cap or the count, so
adding one cannot close this issue. A generated file over the cap is a
generator emitting too much, and the fix is the generator.

Take as long as it needs. There is no partial-credit state to reach for.

The docs count cap is implemented and tested but not yet wired into the hook's
main() - it lands with agentic-os's own migration. So pre-commit will not
fail on the count today. Do the merging anyway: it goes red the moment that
one-line wiring commit lands.

Parent: coilyco-flight-deck/agentic-os#1102. Rationale and the measurements behind the numbers:
docs/documentation-bands.md.

This repo declares the **`large`** documentation band, so its caps are **120 lines / 8,000 chars** per Markdown file and **40 `docs/*.md`**. Measured by running the validator against this checkout: * **`docs/`: 158 files against a 40 cap** - **118 to merge away** * **0 files over a size cap** - none ## The work 1. Merge `docs/` from 158 pages down to 40. Related pages join; a page that only exists because another got too long goes back where it came from. Merging is the move, not splitting. Splitting one over-long doc into two trades a size violation for a count violation, which is the whole reason the count cap exists. ## Done means `pre-commit run --all-files` green, with no new entry under `[tool.agentic-os.documentation-layout] excludes`. Excludes still govern placement and flatness and no longer reach either size cap or the count, so adding one cannot close this issue. A generated file over the cap is a generator emitting too much, and the fix is the generator. Take as long as it needs. There is no partial-credit state to reach for. The docs count cap is implemented and tested but not yet wired into the hook's `main()` - it lands with agentic-os's own migration. So `pre-commit` will not fail on the count today. Do the merging anyway: it goes red the moment that one-line wiring commit lands. Parent: coilyco-flight-deck/agentic-os#1102. Rationale and the measurements behind the numbers: [docs/documentation-bands.md](https://forgejo.coilysiren.me/coilyco-flight-deck/agentic-os/src/branch/main/docs/documentation-bands.md).

coilyco-ops added the

labels

2026-08-16 07:01:28 +00:00

coilyco-ops referenced this issue from coilyco-flight-deck/agentic-os

2026-08-16 07:03:24 +00:00

docs band migration: 468 docs to merge, 531 files to trim, 24 repos #1102

coilyco-ops referenced this issue

2026-08-17 16:35:05 +00:00

docs: 158 docs to 40 #872

coilyco-ops added

priority

and removed

priority

labels

2026-08-17 16:39:23 +00:00

coilyco-ops commented

2026-08-17 18:26:08 +00:00

Author

Member

Done on main, and measured rather than assumed. Closing. Angie (ENG, claude seat), working the headless engineer queue.

The migration landed as PR 896, "docs: migrate sirens-echo onto the large documentation band", across a run of docs(bands) commits ending at 2f67510.

Measured against this checkout of `main`

files        40 / 40 cap
total lines  4,158 / 4,800 ceiling
total chars  303,513 / 320,000 ceiling
largest      FEATURES.md at 120 lines, sirens-echo-access.md at 8,000 chars

Both hooks pass by name, not just as part of a green run:

documentation layout.....................................................Passed
Markdown size caps.......................................................Passed

Done means, checked one at a time

pre-commit run --all-files green - yes, and just gate runs the same suite last.
No new entry under [tool.agentic-os.documentation-layout] excludes - the only entry is agent/bundles/**, which is just compose-bundles output, is gitignored, and predates this work. Confirmed through git log -p on pyproject.toml rather than by reading the current file.

The sequencing worked out

The earlier comments said the caps were not enforced here because the repo pinned aos-precommit-v0.18.0, and that migrating had to come before the bump. .pre-commit-config.yaml now pins aos-precommit-v0.24.0, so the caps are live and the tree is under them. Migrate-then-bump, in that order, as recommended.

One caveat for whoever edits `docs/` next

Every page is close to its ceiling and several sit exactly on it. Adding a paragraph now costs a trim somewhere on the same page. I hit that four times today across #873, #895, #651, and #855, and each cost real editing rather than a line of slack. That is the cap doing its job, and it is worth knowing before starting rather than halfway through.

Closing #872 alongside this as the duplicate it was triaged as.

**Done on `main`, and measured rather than assumed. Closing.** Angie (ENG, `claude` seat), working the headless engineer queue. The migration landed as PR 896, *"docs: migrate sirens-echo onto the large documentation band"*, across a run of `docs(bands)` commits ending at `2f67510`. ## Measured against this checkout of `main` ``` files 40 / 40 cap total lines 4,158 / 4,800 ceiling total chars 303,513 / 320,000 ceiling largest FEATURES.md at 120 lines, sirens-echo-access.md at 8,000 chars ``` Both hooks pass by name, not just as part of a green run: ``` documentation layout.....................................................Passed Markdown size caps.......................................................Passed ``` ## Done means, checked one at a time * **`pre-commit run --all-files` green** - yes, and `just gate` runs the same suite last. * **No new entry under `[tool.agentic-os.documentation-layout] excludes`** - the only entry is `agent/bundles/**`, which is `just compose-bundles` output, is gitignored, and predates this work. Confirmed through `git log -p` on `pyproject.toml` rather than by reading the current file. ## The sequencing worked out The earlier comments said the caps were not enforced here because the repo pinned `aos-precommit-v0.18.0`, and that migrating had to come before the bump. `.pre-commit-config.yaml` now pins **`aos-precommit-v0.24.0`**, so the caps are live and the tree is under them. Migrate-then-bump, in that order, as recommended. ## One caveat for whoever edits `docs/` next Every page is close to its ceiling and several sit exactly on it. Adding a paragraph now costs a trim somewhere on the same page. I hit that four times today across #873, #895, #651, and #855, and each cost real editing rather than a line of slack. That is the cap doing its job, and it is worth knowing before starting rather than halfway through. Closing #872 alongside this as the duplicate it was triaged as.

coilyco-ops closed this issue

2026-08-17 18:26:10 +00:00

coilyco-ops referenced this issue

2026-08-17 18:26:29 +00:00

docs: 158 docs to 40 #872

coilyco-ops referenced this issue

2026-08-17 19:19:28 +00:00

Give enabled / disabled features the config.go treatment: they all must go into 1 file, with a validator, and compile into a markdown doc #854