docs band migration: trim 42 files #307

New issue

Open

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

coilyco-ops commented

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

Member

This repo declares the small 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/: 20 files against a 20 cap - already under the cap, keep it there
42 files over a size cap - 24 docs/*.md prose, 11 content trees, not documentation, 7 co-located README.md and module docs

The work

Bring 42 files under 40 lines / 3,000 chars. Breakdown: 24 docs/*.md prose, 11 content trees, not documentation, 7 co-located README.md and module docs.
Hold on the 11 files in content trees until coilyco-flight-deck/agentic-os#1102 rules on whether a documentation cap should reach them at all. Everything else here can proceed now.

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.

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

This repo declares the **`small`** 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/`: 20 files against a 20 cap** - already under the cap, keep it there * **42 files over a size cap** - 24 `docs/*.md` prose, 11 content trees, not documentation, 7 co-located `README.md` and module docs ## The work 1. Bring 42 files under 40 lines / 3,000 chars. Breakdown: 24 `docs/*.md` prose, 11 content trees, not documentation, 7 co-located `README.md` and module docs. 2. **Hold on the 11 files in content trees** until coilyco-flight-deck/agentic-os#1102 rules on whether a documentation cap should reach them at all. Everything else here can proceed now. 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. 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:20 +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