docs: merge 101 docs into 68, and measure why 40 is not reachable

coilyco-ops commented

2026-08-16 06:19:58 +00:00

Member

Migration for the docs-count cap on #1090. Branched off aos/claude/ym96-docs-bands, so merge that first.

What landed

101 docs to 68. Every doc inside the large band's 120-line and 8,000-char caps. Every hook green, including dead-cross-links across roughly 100 inbound references the merges had to repoint, in markdown and in three generator source files.

The skill-discipline handbook is the case #1090's own body cites, and its index said the quiet part out loud:

The handbook is split across topic files to stay under the documentation size cap.

That is the count cap's argument, written in the repo as a design note. Ten files became five.

The rest went the same way: five repo-map traces into one, three Forgejo Actions pages into two, six dev-base into three, eight native-session into four, fourteen aos-* into ten.

The cap is not reachable by merging, and here is the arithmetic

I did not get to 40, and I do not think more merging gets there.

Merging costs lines rather than saving them. 101 docs held 5,089 lines and 68 hold 5,210. Every fold adds a heading and its spacing, measured at 3.7 lines per merge over the 33 merges here. I had assumed the opposite going in, and the measurement is the reason this PR stops where it does.

So:

current            68 docs, 5,210 lines, all within caps
cap capacity       40 docs x 120 lines = 4,800 lines
deficit            410 lines
minimum docs       ceil(5210/120) = 44, at perfect packing with zero overhead

44 > 40 before any packing loss. The content does not fit under the cap at any arrangement.

It is worse in practice. Twelve docs are under 60 lines and can still pair freely. Every other doc has a median of 77, so two of them breach the 120-line cap on contact. Merging alone floors out around 62 docs.

Closing the last 28 means deleting roughly 500 lines, about 10% of the corpus. That is a content decision, not a layout one, and not mine to make unilaterally across 68 pages.

Three ways forward

Raise the large band. 44 docs is the floor at 120 lines; a cap of 55 leaves working room. The band pairs stay principled, the count moves.
Delete or archive. Some of this is historical rather than current: the security-boundary audits are dated incident records, and catalog-caps-reference.md is generated.
Move content out of docs/. The repo-map traces describe other repositories and arguably belong to them.

I lean 1, because the cap's stated purpose is stopping a folder nobody can read, and 68 coherent pages is not that. sirens-echo at 156 was.

check_docs_count stays unwired

Deliberately, and for #1090's own stated reason: this repo still fails it at 68, and wiring a check the owning repo fails bricks commits to the repo that owns the hook. It is one line, in whichever commit closes the gap above.

Verify

pre-commit run --all-files clean on this branch.

Migration for the docs-count cap on https://forgejo.coilysiren.me/coilyco-flight-deck/agentic-os/pulls/1090. Branched off `aos/claude/ym96-docs-bands`, so merge that first. ## What landed **101 docs to 68.** Every doc inside the large band's 120-line and 8,000-char caps. Every hook green, including `dead-cross-links` across roughly 100 inbound references the merges had to repoint, in markdown and in three generator source files. The `skill-discipline` handbook is the case #1090's own body cites, and its index said the quiet part out loud: > The handbook is split across topic files to stay under the documentation size cap. That is the count cap's argument, written in the repo as a design note. Ten files became five. The rest went the same way: five repo-map traces into one, three Forgejo Actions pages into two, six dev-base into three, eight native-session into four, fourteen `aos-*` into ten. ## The cap is not reachable by merging, and here is the arithmetic I did not get to 40, and I do not think more merging gets there. **Merging costs lines rather than saving them.** 101 docs held 5,089 lines and 68 hold 5,210. Every fold adds a heading and its spacing, measured at **3.7 lines per merge** over the 33 merges here. I had assumed the opposite going in, and the measurement is the reason this PR stops where it does. So: ``` current 68 docs, 5,210 lines, all within caps cap capacity 40 docs x 120 lines = 4,800 lines deficit 410 lines minimum docs ceil(5210/120) = 44, at perfect packing with zero overhead ``` **44 > 40 before any packing loss.** The content does not fit under the cap at any arrangement. It is worse in practice. Twelve docs are under 60 lines and can still pair freely. Every other doc has a median of 77, so **two of them breach the 120-line cap on contact**. Merging alone floors out around 62 docs. Closing the last 28 means deleting roughly **500 lines, about 10% of the corpus**. That is a content decision, not a layout one, and not mine to make unilaterally across 68 pages. ## Three ways forward 1. **Raise the large band.** 44 docs is the floor at 120 lines; a cap of 55 leaves working room. The band pairs stay principled, the count moves. 2. **Delete or archive.** Some of this is historical rather than current: the security-boundary audits are dated incident records, and `catalog-caps-reference.md` is generated. 3. **Move content out of `docs/`.** The repo-map traces describe other repositories and arguably belong to them. I lean 1, because the cap's stated purpose is stopping a folder nobody can read, and 68 coherent pages is not that. sirens-echo at 156 was. ## check_docs_count stays unwired Deliberately, and for #1090's own stated reason: this repo still fails it at 68, and wiring a check the owning repo fails bricks commits to the repo that owns the hook. It is one line, in whichever commit closes the gap above. ## Verify `pre-commit run --all-files` clean on this branch.

coilyco-ops added 1 commit

2026-08-16 06:19:58 +00:00

docs: merge 101 docs into 68, every one inside the band caps

ci / ward-doctor (pull_request) Successful in 13s

Details

ci / aos-cli-tests (pull_request) Successful in 18s

Details

ci / gate (pull_request) Successful in 1m7s

Details

dev-base-pr / build (pull_request) Successful in 12m31s

Details

40471adc5e

The docs-count cap this branch adds cannot be wired until this repository
passes it. This is the migration, and it stops short of the cap for a reason
the last section states.

101 docs became 68 by folding topical clusters into one page each. Every doc is
inside the large band's 120-line and 8,000-char caps, and every hook is green,
including dead-cross-links across the roughly 100 inbound references the merges
had to repoint.

The skill-discipline handbook is the clearest case and the one this branch's
own body cites. It was ten files, and its index said so in as many words:

  The handbook is split across topic files to stay under the documentation
  size cap.

That sentence is the count cap's whole argument, written down in the repo as a
design note. It is now five files: the handbook, its conventions, its hooks,
the authoring walkthrough, and the entry point.

The other clusters went the same way. Five repo-map traces became one page,
three Forgejo Actions pages became two, six dev-base pages became three, eight
native-session pages became four, fourteen aos-* pages became ten.

Merging costs lines rather than saving them. 101 docs held 5,089 lines and 68
hold 5,210, because every fold adds a heading and the spacing around it, about
3.7 lines per merge. That number matters for what comes next and is measured
here rather than assumed.

check_docs_count stays unwired. At 68 docs against a cap of 40 this repository
still fails it, and wiring a check the repository fails would brick commits to
the repository that owns the hook. The remaining distance is not more merging:
5,210 lines against a 40-doc cap of 120 lines is a 4,800-line ceiling, so the
content does not fit at any packing, and perfect packing would still need 44
docs. Twelve docs are under 60 lines and can still pair. Everything else has a
median of 77, so two of them breach the cap on contact.

Closing the last 28 docs means deleting roughly 500 lines, which is a content
decision rather than a layout one. Left for Kai on the tracking issue.

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-16 06:19:58 +00:00

coilyco-ops referenced this pull request

2026-08-16 06:20:18 +00:00

feat(docs): size bands with a docs-count cap, and no per-file escape #1090

coilyco-ops added 1 commit

2026-08-16 06:33:48 +00:00