coilyco-gaming/eco-app

Watch

docs: 24 oversized docs #311

New issue

Open

opened 2026-08-17 00:48:56 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

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

Member

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

What this repo needs

24 docs over the per-file cap of 40 lines / 3,000 chars.
18 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. **24 docs over the per-file cap** of 40 lines / 3,000 chars. 2. **18 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:11:48 +00:00

Author

Member

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

Nothing is urgent. This repo pins v0.193.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 `v0.193.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 02:49:26 +00:00

Author

Member

Measured against current main with the post-#1108 validator: 80 violations, and every single one falls inside an exclusion this repo already declared.

docs/ - 47
investigation/ - 19
mods/ - 14

pyproject.toml excludes all three, with the reasoning inline: "investigation/ is a preserved chronological post-mortem (see AGENTS.md). docs/ holds long-form per-component FEATURES docs migrated from the four source repos, predating the size caps. mods/ subtrees carry their own README + mod.io listing copy as part of their distributed shape."

agentic-os#1108 made excludes stop reaching the size and count caps. For docs/FEATURES.md that revocation was deliberate and stated. Here it was a side effect, and the effect is total: this repo has no actionable migration work that is not "undo a decision recorded in pyproject.toml and AGENTS.md." Complying means deleting most of a preserved post-mortem and most of the per-component docs carried over from four source repos.

So I have changed nothing here, and this issue is blocked rather than open. eco-ops#78 hit the same wall for the same reason and names this repo as the precedent it followed. The general question is on coilysiren/inbox#374, and it wants one decision, not one per repo.

For what it is worth, the band and the caps themselves look right for this repo's root. It is the retroactive reach into deliberately-excluded legacy trees that does not.

Nothing is enforced here until the pin advances.

Measured against current `main` with the post-#1108 validator: **80 violations, and every single one falls inside an exclusion this repo already declared.** * `docs/` - 47 * `investigation/` - 19 * `mods/` - 14 `pyproject.toml` excludes all three, with the reasoning inline: "`investigation/` is a preserved chronological post-mortem (see AGENTS.md). `docs/` holds long-form per-component FEATURES docs migrated from the four source repos, predating the size caps. `mods/` subtrees carry their own README + mod.io listing copy as part of their distributed shape." agentic-os#1108 made `excludes` stop reaching the size and count caps. For `docs/FEATURES.md` that revocation was deliberate and stated. Here it was a side effect, and the effect is total: this repo has no actionable migration work that is not "undo a decision recorded in `pyproject.toml` and `AGENTS.md`." Complying means deleting most of a preserved post-mortem and most of the per-component docs carried over from four source repos. So I have changed nothing here, and this issue is blocked rather than open. eco-ops#78 hit the same wall for the same reason and names this repo as the precedent it followed. The general question is on coilysiren/inbox#374, and it wants one decision, not one per repo. For what it is worth, the band and the caps themselves look right for this repo's root. It is the retroactive reach into deliberately-excluded legacy trees that does not. Nothing is enforced here until the pin advances.

coilyco-ops commented

2026-08-17 05:37:46 +00:00

Author

Member

docs/ migrated to the small band and landed on main (3db0c2c). pre-commit run --all-files is clean.

Twenty docs from 1,818 lines and 165,629 chars to 746 and 34,126, against ceilings of 800 and 60,000. Every file is inside the 40-line and 3,000-char per-file caps.

This is a rewrite rather than a trim, because small was not reachable any other way. The two biggest single wins:

FEATURES.md was 46,730 chars, 78% of the entire char budget on its own, written as paragraph-length bullets. It is now the index a FEATURES is supposed to be, at 1,900.
dual-route-inventory.md was 15,619 chars that repeated "Registered in Wave N - Canonical REST path GET /preview/<tool>.json" twenty times. It now states the pattern once, names the Wave 1 exceptions that keep shorter paths, and lists the two tools awaiting prerequisites with the reason for each.

Every operative fact is kept: module paths, env vars and their defaults, data sources, computed outputs, and specifically the named gotchas, which are the load-bearing part of these docs. Numeric citizen ids and the /api/v1/citizens join. The undeclared extra tool column that shifts every later field. BoughtOrSold 32 and 33 being undecoded in the exporter. The cycle-boundary rule for prices. The three freshness ages and why they are never merged. The RCON enum boundary. The modded-export refusal list. What went is the extended rationale behind each choice, which git holds.

One thing worth recording

I first tried a mechanical compressor and reverted it. It produced docs that were the right size and actively wrong: it merged H1 titles into the following paragraph, and it truncated bullet lists so that a partial list read as complete. civics.md came out claiming one data source where there were three. That is worse documentation than either the long original or an honest short rewrite, so the 20 pages here are hand-written.

What remains

42 violations, every one inside investigation/, mods/, or the nested docs/datasets, docs/jobs, docs/mcp, and docs/replay subdirectories. All are inside the exclusions this repo already declares with its reasoning, so they are the agentic-os#1108 excludes question rather than migration work. That is still open on coilysiren/inbox#374.

`docs/` migrated to the small band and landed on `main` (`3db0c2c`). `pre-commit run --all-files` is clean. **Twenty docs from 1,818 lines and 165,629 chars to 746 and 34,126**, against ceilings of 800 and 60,000. Every file is inside the 40-line and 3,000-char per-file caps. This is a rewrite rather than a trim, because small was not reachable any other way. The two biggest single wins: * **`FEATURES.md`** was 46,730 chars, 78% of the entire char budget on its own, written as paragraph-length bullets. It is now the index a FEATURES is supposed to be, at 1,900. * **`dual-route-inventory.md`** was 15,619 chars that repeated "Registered in Wave N - Canonical REST path `GET /preview/<tool>.json`" twenty times. It now states the pattern once, names the Wave 1 exceptions that keep shorter paths, and lists the two tools awaiting prerequisites with the reason for each. Every operative fact is kept: module paths, env vars and their defaults, data sources, computed outputs, and specifically the named gotchas, which are the load-bearing part of these docs. Numeric citizen ids and the `/api/v1/citizens` join. The undeclared extra tool column that shifts every later field. `BoughtOrSold` 32 and 33 being undecoded in the exporter. The cycle-boundary rule for prices. The three freshness ages and why they are never merged. The RCON enum boundary. The modded-export refusal list. What went is the extended rationale behind each choice, which git holds. ## One thing worth recording I first tried a mechanical compressor and **reverted it**. It produced docs that were the right size and actively wrong: it merged H1 titles into the following paragraph, and it truncated bullet lists so that a partial list read as complete. `civics.md` came out claiming one data source where there were three. That is worse documentation than either the long original or an honest short rewrite, so the 20 pages here are hand-written. ## What remains 42 violations, every one inside `investigation/`, `mods/`, or the nested `docs/datasets`, `docs/jobs`, `docs/mcp`, and `docs/replay` subdirectories. All are inside the exclusions this repo already declares with its reasoning, so they are the agentic-os#1108 excludes question rather than migration work. That is still open on coilysiren/inbox#374.

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-gaming/eco-app#311

No description provided.

Rows
Columns