coilyco-flight-deck/infrastructure

Watch

docs: 127 docs to 40, 1 oversized docs #856

New issue

Open

opened 2026-08-17 00:48:47 +00:00 by coilyco-ops · 4 comments

coilyco-ops commented

2026-08-17 00:48:47 +00:00

Member

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

What this repo needs

Merge 127 docs down to 40. docs/ currently holds 127 files against the large-band cap of 40, totalling 6489 lines. The ceiling at the cap is 4800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out.
1 doc over the per-file cap of 120 lines / 8,000 chars.
1 other Markdown file 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. **Merge 127 docs down to 40.** `docs/` currently holds 127 files against the large-band cap of 40, totalling 6489 lines. The ceiling at the cap is 4800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out. 2. **1 doc over the per-file cap** of 120 lines / 8,000 chars. 3. **1 other Markdown file 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:11:15 +00:00

Author

Member

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

Nothing is urgent. This repo pins aos-precommit-v0.18.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.

Epic: coilysiren/inbox#374.

Two corrections and a decision, all after this was filed. **Nothing is urgent.** This repo pins `aos-precommit-v0.18.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. Epic: coilysiren/inbox#374.

coilyco-ops commented

2026-08-17 03:30:18 +00:00

Author

Member

Measured against current main. Five violations: one doc count, and four inside exclusions this repo already declares.

The count

docs/ holds 127 files against the large band's 40-doc cap. Every one of them passes the per-file caps, so there is nothing to trim, only to consolidate.

The character budget is what decides the shape. 40 docs at 8,000 chars is a 320,000-char ceiling, and docs/ holds 388,046. Merging reduces the file count but not the total, so about 18% has to be removed, roughly 68,000 chars, at any packing.

At the current pin it is much worse: a doc is capped at 4,000 there, so 40 files hold 160,000 and the cut would be 59%. The merges cannot land before the pin advances, which is on coilysiren/inbox#374 alongside lore and agent-proxy.

I have not started, because deleting 68,000 chars of infrastructure documentation is a judgment about what the cluster still needs explained rather than a mechanical migration. 18% is a much gentler target than sirens-echo's 30%, so this one is genuinely reachable by consolidating and dropping point-in-time records that git already holds.

The four excluded ones

eco-server/, ansible/README.md, deploy/*/README.md, terraform/*/README.md, and docs/FEATURES.md are excluded in pyproject.toml. agentic-os#1108 made excludes stop reaching the size cap, so four of them now fail. For docs/FEATURES.md that revocation was deliberate and stated in the band doc. The rest are the same side effect that six repos now carry, and that question is open on the epic.

Nothing is enforced here until the pin advances.

Measured against current `main`. **Five violations: one doc count, and four inside exclusions this repo already declares.** ## The count `docs/` holds 127 files against the large band's 40-doc cap. Every one of them passes the per-file caps, so there is nothing to trim, only to consolidate. The character budget is what decides the shape. 40 docs at 8,000 chars is a **320,000-char** ceiling, and `docs/` holds **388,046**. Merging reduces the file count but not the total, so about **18% has to be removed**, roughly 68,000 chars, at any packing. At the current pin it is much worse: a doc is capped at 4,000 there, so 40 files hold 160,000 and the cut would be 59%. The merges cannot land before the pin advances, which is on coilysiren/inbox#374 alongside lore and agent-proxy. I have not started, because deleting 68,000 chars of infrastructure documentation is a judgment about what the cluster still needs explained rather than a mechanical migration. 18% is a much gentler target than sirens-echo's 30%, so this one is genuinely reachable by consolidating and dropping point-in-time records that git already holds. ## The four excluded ones `eco-server/`, `ansible/README.md`, `deploy/*/README.md`, `terraform/*/README.md`, and `docs/FEATURES.md` are excluded in `pyproject.toml`. agentic-os#1108 made `excludes` stop reaching the size cap, so four of them now fail. For `docs/FEATURES.md` that revocation was deliberate and stated in the band doc. The rest are the same side effect that six repos now carry, and that question is open on the epic. Nothing is enforced here until the pin advances.

coilyco-ops commented

2026-08-17 05:11:21 +00:00

Author

Member

Measured against current main: 127 docs, 6,489 lines, 388,046 chars. At large the ceilings are 40 docs, 4,800 lines, 320,000 chars, so 1,689 lines have to come out, 26%, whatever the packing.

I did the analysis and stopped before deleting. Here is what it found, because it changes the shape of the job.

Merging alone makes this worse, and I measured it

Only 108 lines across the whole tree are recoverable from folded ## See also blocks. Meanwhile 127 docs into 40 pages costs a heading and its spacing per source, roughly +174 lines. So consolidation is net negative on the binding constraint, which is the line cap rather than chars.

The good news: two families are self-identified history

k3s-deploy-notes-*, 21 docs and 1,052 lines. The index says it outright: this "is split into the topic files below to stay under the doc size cap." That is the exact pathology the count cap was written to reverse, so re-merging it is undoing an earlier workaround rather than losing anything. Two of those 21 are change-log and change-log-2, 97 lines of dated entries that git already holds better.

forgejo-deploy-plan-*, 10 docs and 349 lines. A completed plan with per-phase retrospectives, smoke results, and a rollback note, all stamped with execution dates. phase1-retro opens "Executed 2026-05-05. Phase 1 completed end-to-end." Current-state readers need the outcome and the three deviations it records, not the phase-by-phase log.

Collapsing both families the obvious way recovers about 330 lines and takes the doc count from 127 to roughly 100.

Where it still does not close

After that, a realistic family packing lands near 53 pages and 6,160 lines, against ceilings of 40 and 4,800. So roughly 1,400 more lines have to be deleted, and they are not in an obvious pile. They are spread across 38 ansible-* role docs, 14 other forgejo-* pages, and 28 ungrouped runbooks. FEATURES.md alone is 168 lines, already over the per-file cap.

That is a judgment about which runbooks for a live cluster are stale, and getting it wrong deletes the only written record of how something is wired. I am not going to make that call by bulk-trimming at the end of a long session.

What would unblock it, cheaply: name which of these are historical rather than current-state, and I will do the rest. My read of the candidates, from titles and openings only:

dev-base-ci-rollout-report, forgejo-deploy-plan-phase1-retro, forgejo-runners-ser8-publisher-migration, forgejo-oci-migration-run, k3s-deploy-notes-change-log and -2, k3s-deploy-notes-gha-workflow-deploy-diag, systemd-native-agent-retirement, agent-logs-postmortem, issue-corpus-rollout-runner, forgejo-deploy-plan-followups, flux-gitops-rollout.

That set is about 500 lines. Confirming it, plus the two family merges above, gets most of the way, and the remainder is ordinary tightening I can do without a decision from you.

Measured against current `main`: 127 docs, 6,489 lines, 388,046 chars. At large the ceilings are 40 docs, 4,800 lines, 320,000 chars, so **1,689 lines have to come out**, 26%, whatever the packing. I did the analysis and stopped before deleting. Here is what it found, because it changes the shape of the job. ## Merging alone makes this worse, and I measured it Only 108 lines across the whole tree are recoverable from folded `## See also` blocks. Meanwhile 127 docs into 40 pages costs a heading and its spacing per source, roughly +174 lines. So consolidation is net negative on the binding constraint, which is the line cap rather than chars. ## The good news: two families are self-identified history **`k3s-deploy-notes-*`, 21 docs and 1,052 lines.** The index says it outright: this "is split into the topic files below **to stay under the doc size cap**." That is the exact pathology the count cap was written to reverse, so re-merging it is undoing an earlier workaround rather than losing anything. Two of those 21 are `change-log` and `change-log-2`, 97 lines of dated entries that git already holds better. **`forgejo-deploy-plan-*`, 10 docs and 349 lines.** A completed plan with per-phase retrospectives, smoke results, and a rollback note, all stamped with execution dates. `phase1-retro` opens "Executed 2026-05-05. Phase 1 completed end-to-end." Current-state readers need the outcome and the three deviations it records, not the phase-by-phase log. Collapsing both families the obvious way recovers about 330 lines and takes the doc count from 127 to roughly 100. ## Where it still does not close After that, a realistic family packing lands near 53 pages and 6,160 lines, against ceilings of 40 and 4,800. So roughly **1,400 more lines have to be deleted**, and they are not in an obvious pile. They are spread across 38 `ansible-*` role docs, 14 other `forgejo-*` pages, and 28 ungrouped runbooks. `FEATURES.md` alone is 168 lines, already over the per-file cap. That is a judgment about which runbooks for a live cluster are stale, and getting it wrong deletes the only written record of how something is wired. I am not going to make that call by bulk-trimming at the end of a long session. **What would unblock it**, cheaply: name which of these are historical rather than current-state, and I will do the rest. My read of the candidates, from titles and openings only: * `dev-base-ci-rollout-report`, `forgejo-deploy-plan-phase1-retro`, `forgejo-runners-ser8-publisher-migration`, `forgejo-oci-migration-run`, `k3s-deploy-notes-change-log` and `-2`, `k3s-deploy-notes-gha-workflow-deploy-diag`, `systemd-native-agent-retirement`, `agent-logs-postmortem`, `issue-corpus-rollout-runner`, `forgejo-deploy-plan-followups`, `flux-gitops-rollout`. That set is about 500 lines. Confirming it, plus the two family merges above, gets most of the way, and the remainder is ordinary tightening I can do without a decision from you.

coilyco-ops commented

2026-08-17 05:43:45 +00:00

Author

Member

The lossless half is done and pushed to aos/claude/aw85-bands (3d19efd). Not on main, because it is not green yet.

What landed on the branch

127 docs to 38, against the large cap of 40. The count violation is gone, no prose was deleted, and dead-cross-links is clean with 78 files repointed, including Ansible task files and workflow YAML that referenced the old paths.

The merges undo splitting rather than inventing structure:

k3s-deploy-notes-*, 21 files to 4. Its own index says it "is split into the topic files below to stay under the doc size cap," so folding it back is reversing an earlier workaround. Now topology, manifests, registry, and workflows.
forgejo-deploy-plan-*, 10 files to 1. A completed plan with dated per-phase retrospectives, smoke results, and a rollback note. One record now.
ansible-*, 38 files to 6, grouped by what they configure: the overview and safety model, agent roles, host baseline, Homebrew, k3s and containers, and guardrails and platform.
The forgejo-* runner, lockdown, GitHub-bridge and package families, the Windows and model-runtime pages, the watchers, and systemd likewise.

What is left, and why I stopped there

45 violations, every one a per-file size cap on a merged page. 6,576 lines against a 4,800 ceiling, so about 27% still has to come out. That is the deletion half, and it is a judgment about which live-cluster runbooks are stale rather than mechanical work.

Worth knowing before anyone reaches for a shortcut: I tried a mechanical compressor on eco-app earlier today and reverted it. It hit the size target and produced wrong documentation, merging H1 titles into prose and truncating bullet lists so a partial list read as complete. One page ended up claiming a single data source where there were three. The 20 pages I shipped for eco-app are hand-written instead, and infrastructure's 24 over-cap pages need the same treatment.

The twelve retirement candidates I listed in my previous comment are still the cheapest way to close most of the gap. Confirming that set would let me finish this without guessing at a cluster I cannot observe.

The lossless half is done and pushed to `aos/claude/aw85-bands` (`3d19efd`). Not on `main`, because it is not green yet. ## What landed on the branch **127 docs to 38**, against the large cap of 40. The count violation is gone, no prose was deleted, and `dead-cross-links` is clean with **78 files repointed**, including Ansible task files and workflow YAML that referenced the old paths. The merges undo splitting rather than inventing structure: * **`k3s-deploy-notes-*`, 21 files to 4.** Its own index says it "is split into the topic files below **to stay under the doc size cap**," so folding it back is reversing an earlier workaround. Now topology, manifests, registry, and workflows. * **`forgejo-deploy-plan-*`, 10 files to 1.** A completed plan with dated per-phase retrospectives, smoke results, and a rollback note. One record now. * **`ansible-*`, 38 files to 6**, grouped by what they configure: the overview and safety model, agent roles, host baseline, Homebrew, k3s and containers, and guardrails and platform. * The `forgejo-*` runner, lockdown, GitHub-bridge and package families, the Windows and model-runtime pages, the watchers, and systemd likewise. ## What is left, and why I stopped there 45 violations, every one a per-file size cap on a merged page. **6,576 lines against a 4,800 ceiling, so about 27% still has to come out.** That is the deletion half, and it is a judgment about which live-cluster runbooks are stale rather than mechanical work. Worth knowing before anyone reaches for a shortcut: I tried a mechanical compressor on eco-app earlier today and **reverted it**. It hit the size target and produced wrong documentation, merging H1 titles into prose and truncating bullet lists so a partial list read as complete. One page ended up claiming a single data source where there were three. The 20 pages I shipped for eco-app are hand-written instead, and infrastructure's 24 over-cap pages need the same treatment. The twelve retirement candidates I listed in my previous comment are still the cheapest way to close most of the gap. Confirming that set would let me finish this without guessing at a cluster I cannot observe.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-flight-deck/infrastructure#856

No description provided.

Rows
Columns