docs band migration: trim 16 files #117

New issue

Open

opened 2026-08-16 07:00:00 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

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

Collaborator

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/: 5 files against a 20 cap - already under the cap, keep it there
16 files over a size cap - 12 content trees, not documentation, 4 docs/*.md prose

The work

Bring 16 files under 40 lines / 3,000 chars. Breakdown: 12 content trees, not documentation, 4 docs/*.md prose.
Hold on the 12 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.

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

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/`: 5 files against a 20 cap** - already under the cap, keep it there * **16 files over a size cap** - 12 content trees, not documentation, 4 `docs/*.md` prose ## The work 1. Bring 16 files under 40 lines / 3,000 chars. Breakdown: 12 content trees, not documentation, 4 `docs/*.md` prose. 2. **Hold on the 12 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. This repo's `pre-commit run --all-files` fails on pristine `main` for reasons unrelated to this work, so nothing can commit until website#116 clears. Start there. 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 referenced this issue from coilyco-flight-deck/agentic-os

2026-08-16 07:02:44 +00:00

coilysiren/* repos cannot carry the scoped label taxonomy #1106

coilyco-ops commented

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

Author

Collaborator

Unlabelled on purpose. The coilysiren namespace is a user account, not an org, so it cannot hold the scoped taxonomy, and repo-level label creation is policy-denied to prevent shadowing. Tracked at coilyco-flight-deck/agentic-os#1106. Triage this one by hand until that lands.

Unlabelled on purpose. The `coilysiren` namespace is a user account, not an org, so it cannot hold the scoped taxonomy, and repo-level label creation is policy-denied to prevent shadowing. Tracked at coilyco-flight-deck/agentic-os#1106. Triage this one by hand until that lands.

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