docs: declare a band, 4 oversized docs #118

New issue

Open

opened 2026-08-17 00:49:07 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-17 00:49:07 +00:00

Collaborator

Part of coilysiren/inbox#374. The cap landed in coilyco-flight-deck/agentic-os#1108.

What this repo needs

Declare a band. This repo declares none, so documentation-layout fails on that alone before any size question. A missing declaration is a hard failure rather than a silent default, because an undeclared repo and a chosen-small repo were previously the same file.

[tool.agentic-os.documentation-layout]
band = "small"

Declaring it is the decision about which band this repo is in, so pick deliberately rather than copying. Small is 40 lines / 3,000 chars / 20 docs. Large is 120 / 8,000 / 40.

4 docs over the per-file cap of 40 lines / 3,000 chars.
12 other Markdown files over the cap, outside docs/ and outside the skill roots.

What agentic-os learned migrating first

Merging costs lines rather than saving them, measured at 3.7 per fold: each adds a heading and its spacing. Budget a trimming pass rather than expecting consolidation to shrink the total.

Rephrasing prose to be tighter does not reduce line count, because reflowed text occupies the same rows. What works is deleting whole restatements, and folding a small trailing section into the paragraph above it, which drops a heading and a blank line without touching a word.

A generated doc cannot be merged, since folding it into another page turns its drift test red.

Acceptance

pre-commit run --all-files clean, with documentation-layout passing.
No live capability loses its reference material.

Part of coilysiren/inbox#374. The cap landed in coilyco-flight-deck/agentic-os#1108. ## What this repo needs 1. **Declare a band.** This repo declares none, so `documentation-layout` fails on that alone before any size question. A missing declaration is a hard failure rather than a silent default, because an undeclared repo and a chosen-small repo were previously the same file. ```toml [tool.agentic-os.documentation-layout] band = "small" ``` Declaring it **is** the decision about which band this repo is in, so pick deliberately rather than copying. Small is 40 lines / 3,000 chars / 20 docs. Large is 120 / 8,000 / 40. 2. **4 docs over the per-file cap** of 40 lines / 3,000 chars. 3. **12 other Markdown files over the cap**, outside `docs/` and outside the skill roots. ## What agentic-os learned migrating first **Merging costs lines rather than saving them**, measured at 3.7 per fold: each adds a heading and its spacing. Budget a trimming pass rather than expecting consolidation to shrink the total. **Rephrasing prose to be tighter does not reduce line count**, because reflowed text occupies the same rows. What works is deleting whole restatements, and folding a small trailing section into the paragraph above it, which drops a heading and a blank line without touching a word. **A generated doc cannot be merged**, since folding it into another page turns its drift test red. ## Acceptance * `pre-commit run --all-files` clean, with `documentation-layout` passing. * No live capability loses its reference material.

coilyco-ops commented

2026-08-17 01:12:20 +00:00

Author

Collaborator

Two corrections and a decision, all after this was filed.

Nothing is urgent. This repo pins v0.195.0, so the new caps do not apply here until that pin advances. aos-precommit-v0.24.0 carries them. The bump is the trigger, so the sequencing is migrate first then bump, or both in one change. Bumping first turns this repo's own commits red.

Skills are out of scope. documentation-layout was applying the band cap to SKILL.md and COMPOSED.md while check-skills allows 500 lines for the same file. Kai's call is to ignore skills, and the exemption is in coilyco-flight-deck/agentic-os#1110. Any skill-file count above is struck from the work.

The band is declared. Kai assigned it and it has landed, so that item above is done.

Epic: coilysiren/inbox#374.

Two corrections and a decision, all after this was filed. **Nothing is urgent.** This repo pins `v0.195.0`, so the new caps do not apply here until that pin advances. `aos-precommit-v0.24.0` carries them. The bump is the trigger, so the sequencing is migrate first then bump, or both in one change. Bumping first turns this repo's own commits red. **Skills are out of scope.** `documentation-layout` was applying the band cap to `SKILL.md` and `COMPOSED.md` while `check-skills` allows 500 lines for the same file. Kai's call is to ignore skills, and the exemption is in coilyco-flight-deck/agentic-os#1110. Any skill-file count above is struck from the work. **The band is declared.** Kai assigned it and it has landed, so that item above is done. Epic: coilysiren/inbox#374.

coilyco-ops commented

2026-08-17 01:59:10 +00:00

Author

Collaborator

docs/ is migrated and clean: FEATURES went from 122 lines to 35, and the references it carried became eight pages. 12 docs against a cap of 20. Landed on main.

Not done, and deliberately. Nine blog posts under src/pages/posts/ exceed the cap, the longest a 480-line published article. Those are writing, not documentation, and trimming them to satisfy a documentation rule would be destroying content.

That is a rule problem rather than a website problem, filed as coilyco-flight-deck/agentic-os#1111. This issue stays open until it is settled.

Epic: coilysiren/inbox#374.

`docs/` is migrated and clean: FEATURES went from 122 lines to 35, and the references it carried became eight pages. 12 docs against a cap of 20. Landed on `main`. **Not done, and deliberately.** Nine blog posts under `src/pages/posts/` exceed the cap, the longest a 480-line published article. Those are writing, not documentation, and trimming them to satisfy a documentation rule would be destroying content. That is a rule problem rather than a website problem, filed as coilyco-flight-deck/agentic-os#1111. This issue stays open until it is settled. Epic: coilysiren/inbox#374.