The aterm documentation budget is exhausted: docs/aterm.md sits at 7994 of 8000 chars and docs/ is at the 40-doc cap #1341

New issue

Closed

opened 2026-08-28 17:44:06 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-28 17:44:06 +00:00

Owner

What happened

#1340 fixed a bug where closing an aterm app and reopening it never restarted the console process. The fix needed one sentence of prose in docs/aterm.md to explain the surprise, per the comment-the-surprise rule that sends explanation to docs and leaves a pointer in code.

There was no room for it. docs/aterm.md was at 7973 chars against the large band's 8000-char cap, so 27 chars of headroom for a fact that needed roughly 180. The obvious escape was a docs/aterm-bundles.md split, since the file covers two subsystems (the launcher and the macOS app bundles) and that is what pushed it to the cap. That escape is closed too: docs/*.md is at exactly 40 files against the large band's 40-doc count cap. check_documentation_layout.py states there is no per-file escape from a size or count cap, and both band caps are global across every repo consuming the catalog hook, so raising either for one file is not available.

The fix therefore landed by compressing prose Kai wrote, reclaiming about 150 chars across five sentences to buy room for one. Every fact was preserved and pre-commit run --all-files is green, but the file now sits at 7994 of 8000, with 6 chars of headroom.

Why this needs an issue rather than a note

The compression is not repeatable. The next agent that finds an aterm surprise worth documenting has six characters and no split available, and its only remaining moves are to delete a load-bearing paragraph or to skip the doc and leave a code pointer aimed at prose that does not exist. Neither is a decision an agent should make alone mid-bugfix, and neither is visible to anyone reading the file.

This is the same wall as agent-compose#371 (docs/ at the 40-doc cap with bundle-protocol.md at the 120-line cap), which suggests the constraint is structural across the estate rather than particular to aterm.

What a fix has to decide

Kai's call, not the next agent's, since each option trades a different thing:

Raise the large band's doc-count cap so a subsystem doc can split. Touches every catalog consumer.
Retire or merge a docs/*.md file in this repo to free a count slot, then split the bundles half of docs/aterm.md into its own page.
Accept the cap as working back-pressure and rule that aterm documentation is closed, so future surprises live only in code comments. This contradicts the comment-the-surprise routing and should be written down if chosen.
Give documentation-layout a per-file cap override with a recorded justification, the way agents_md_max_lines already works for AGENTS.md. Note the validator's own docstring currently rules this out on purpose, so this option is a deliberate reversal.

Resuming

The band caps and their rationale: docs/documentation-bands.md, docs/catalog-caps-reference.md.
The validator and its no-per-file-escape docstring: agentic_os/pre_commit/check_documentation_layout.py.
The per-repo override precedent: agents_md_max_lines / agents_md_max_chars and readme_max_lines / readme_max_chars under [tool.agentic-os.documentation-layout] in pyproject.toml.
The compression that bought room this time is the docs/aterm.md hunk of #1340, if it needs reverting alongside a real fix.

## What happened #1340 fixed a bug where closing an aterm app and reopening it never restarted the console process. The fix needed one sentence of prose in `docs/aterm.md` to explain the surprise, per the comment-the-surprise rule that sends explanation to docs and leaves a pointer in code. There was no room for it. `docs/aterm.md` was at 7973 chars against the large band's 8000-char cap, so 27 chars of headroom for a fact that needed roughly 180. The obvious escape was a `docs/aterm-bundles.md` split, since the file covers two subsystems (the launcher and the macOS app bundles) and that is what pushed it to the cap. That escape is closed too: `docs/*.md` is at exactly 40 files against the large band's 40-doc count cap. `check_documentation_layout.py` states there is no per-file escape from a size or count cap, and both band caps are global across every repo consuming the catalog hook, so raising either for one file is not available. The fix therefore landed by compressing prose Kai wrote, reclaiming about 150 chars across five sentences to buy room for one. Every fact was preserved and `pre-commit run --all-files` is green, but the file now sits at **7994 of 8000, with 6 chars of headroom**. ## Why this needs an issue rather than a note The compression is not repeatable. The next agent that finds an aterm surprise worth documenting has six characters and no split available, and its only remaining moves are to delete a load-bearing paragraph or to skip the doc and leave a code pointer aimed at prose that does not exist. Neither is a decision an agent should make alone mid-bugfix, and neither is visible to anyone reading the file. This is the same wall as agent-compose#371 (`docs/` at the 40-doc cap with `bundle-protocol.md` at the 120-line cap), which suggests the constraint is structural across the estate rather than particular to aterm. ## What a fix has to decide Kai's call, not the next agent's, since each option trades a different thing: * Raise the large band's doc-count cap so a subsystem doc can split. Touches every catalog consumer. * Retire or merge a `docs/*.md` file in this repo to free a count slot, then split the bundles half of `docs/aterm.md` into its own page. * Accept the cap as working back-pressure and rule that aterm documentation is closed, so future surprises live only in code comments. This contradicts the comment-the-surprise routing and should be written down if chosen. * Give `documentation-layout` a per-file cap override with a recorded justification, the way `agents_md_max_lines` already works for AGENTS.md. Note the validator's own docstring currently rules this out on purpose, so this option is a deliberate reversal. ## Resuming * The band caps and their rationale: `docs/documentation-bands.md`, `docs/catalog-caps-reference.md`. * The validator and its no-per-file-escape docstring: `agentic_os/pre_commit/check_documentation_layout.py`. * The per-repo override precedent: `agents_md_max_lines` / `agents_md_max_chars` and `readme_max_lines` / `readme_max_chars` under `[tool.agentic-os.documentation-layout]` in `pyproject.toml`. * The compression that bought room this time is the `docs/aterm.md` hunk of #1340, if it needs reverting alongside a real fix.

coilyco-ops commented

2026-08-28 17:50:18 +00:00

Author

Owner

Second instance, same evening, and this one lost a whole page rather than a sentence

#1342 adds per-role icons to aterm bundles, which needs about 2.6 KB of reasoning: where the art comes from, why it is drawn rather than generated from favorite_color, and what regenerating it involves. It hit the same wall from the other side.

docs/aterm.md was at 7973 of 8000 when I started, so the 27 chars this issue names. Adding two paragraphs took it to 9074.
The split escape was tried and refused exactly as documented. docs/aterm-icons.md came to 2625 chars and made docs/ 41 of 40, and the hook said so in the terms this issue quotes: "splitting one doc into two to clear the size cap trades one violation for another."

So the reasoning landed nowhere in this repository. It lives in the importing script's docstring in the private agentic-os-xxx repo, plus the commit message and the PR body. A reader of aterm/icons finds a one-line code comment and no explanation of why seven .icns are committed to a public repo.

What this adds to the diagnosis

This issue frames the cost as the next agent having six characters. The icons case shows the harder shape: a genuinely new subsystem cannot be documented at all, not compressed into an existing page, because the count cap forbids the page that would hold it.

It also lands somewhere worse than undocumented. The delivery decision here is a disclosure decision, art from a private repo committed to a public one, and that is exactly the kind of thing a reader should find in docs/ rather than in a commit message. The budget pushed a judgement call out of the documented surface.

Both instances are aterm, four hours apart, from two different sessions that did not know about each other. That is two independent hits on one subsystem, which supports this issue's own reading that the constraint is structural rather than particular.

One note on the options list

"Retire or merge a docs/*.md file to free a count slot" is the only option here an agent could take alone, and I did not take it: choosing which of Kai's forty pages dies is not a call to make mid-feature. Worth stating in the issue that this option is human-gated too, or the next agent will read it as available.

## Second instance, same evening, and this one lost a whole page rather than a sentence #1342 adds per-role icons to `aterm bundles`, which needs about 2.6 KB of reasoning: where the art comes from, why it is drawn rather than generated from `favorite_color`, and what regenerating it involves. It hit the same wall from the other side. * `docs/aterm.md` was at 7973 of 8000 when I started, so the 27 chars this issue names. Adding two paragraphs took it to 9074. * The split escape was tried and refused exactly as documented. `docs/aterm-icons.md` came to 2625 chars and made `docs/` 41 of 40, and the hook said so in the terms this issue quotes: "splitting one doc into two to clear the size cap trades one violation for another." So the reasoning landed nowhere in this repository. It lives in the importing script's docstring in the private `agentic-os-xxx` repo, plus the commit message and the PR body. A reader of `aterm/icons` finds a one-line code comment and no explanation of why seven `.icns` are committed to a public repo. ## What this adds to the diagnosis This issue frames the cost as the next agent having six characters. The icons case shows the harder shape: **a genuinely new subsystem cannot be documented at all**, not compressed into an existing page, because the count cap forbids the page that would hold it. It also lands somewhere worse than undocumented. The delivery decision here is a disclosure decision, art from a private repo committed to a public one, and that is exactly the kind of thing a reader should find in `docs/` rather than in a commit message. The budget pushed a judgement call out of the documented surface. Both instances are aterm, four hours apart, from two different sessions that did not know about each other. That is two independent hits on one subsystem, which supports this issue's own reading that the constraint is structural rather than particular. ## One note on the options list "Retire or merge a `docs/*.md` file to free a count slot" is the only option here an agent could take alone, and I did not take it: choosing which of Kai's forty pages dies is not a call to make mid-feature. Worth stating in the issue that this option is human-gated too, or the next agent will read it as available.

coilyco-ops referenced this issue from a commit

2026-08-28 19:56:27 +00:00

feat(aosguard): a guarded Netlify domain-alias surface, so the token stays inside

coilyco-ops referenced this issue

2026-08-28 19:56:50 +00:00

feat(aosguard): a guarded Netlify domain-alias surface, so the token stays inside #1355

coilyco-ops referenced this issue

2026-08-28 20:56:36 +00:00

feat(aterm): open the session window fullscreen rather than maximized #1356

coilyco-ops referenced this issue

2026-08-29 02:01:42 +00:00

feat(aterm): tag every role bundle so one Spotlight word finds the set #1371