docs band migration: merge 61 docs #1103

New issue

Closed

opened 2026-08-16 06:59:42 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-16 06:59:42 +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/: 101 files against a 40 cap - 61 to merge away
0 files over a size cap - none

The work

Merge docs/ from 101 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/`: 101 files against a 40 cap** - **61 to merge away** * **0 files over a size cap** - none ## The work 1. Merge `docs/` from 101 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:02 +00:00

coilyco-ops referenced this issue

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

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