docs band migration: merge 22 docs, trim 36 files #1669

New issue

Open

opened 2026-08-16 06:59:49 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

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

Member

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

Measured by running the validator against this checkout:

docs/: 42 files against a 20 cap - 22 to merge away
36 files over a size cap - 32 docs/*.md prose, 2 .agents/skills/*/SKILL.md, 2 root-level Markdown

The work

Merge docs/ from 42 pages down to 20. Related pages join; a page that only exists because another got too long goes back where it came from.
Bring 36 files under 40 lines / 3,000 chars. Breakdown: 32 docs/*.md prose, 2 .agents/skills/*/SKILL.md, 2 root-level Markdown.

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.

This repo's pre-commit run --all-files fails on pristine main for reasons unrelated to this work, so nothing can commit until ward#1668 clears. Start there.

The large declaration is not in main yet (declaration blocked, ward#1668), so the hook currently measures this repo against small. Land the declaration first or the caps will read wrong.

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 **40 lines / 3,000 chars** per Markdown file and **20 `docs/*.md`**. Measured by running the validator against this checkout: * **`docs/`: 42 files against a 20 cap** - **22 to merge away** * **36 files over a size cap** - 32 `docs/*.md` prose, 2 `.agents/skills/*/SKILL.md`, 2 root-level Markdown ## The work 1. Merge `docs/` from 42 pages down to 20. Related pages join; a page that only exists because another got too long goes back where it came from. 2. Bring 36 files under 40 lines / 3,000 chars. Breakdown: 32 `docs/*.md` prose, 2 `.agents/skills/*/SKILL.md`, 2 root-level Markdown. 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. This repo's `pre-commit run --all-files` fails on pristine `main` for reasons unrelated to this work, so nothing can commit until ward#1668 clears. Start there. The `large` declaration is not in `main` yet (declaration blocked, ward#1668), so the hook currently measures this repo against `small`. Land the declaration first or the caps will read wrong. 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:17 +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