Free the docs budget by moving warp and aosguard pages into skill references #1397

Merged

coilyco-ops merged 1 commit from aos/claude/ee98-docsbudget into main

2026-08-29 10:27:07 +00:00

coilyco-ops commented

2026-08-29 10:25:40 +00:00

Owner

docs/ was at 39 of 40 with aterm.md at zero chars of headroom and five more pages within 20 chars. Five issues stall on that one wall: #1303, #1274, #1341, #1312, and #1119, whose 18 over-cap file headers carry ~155 lines the rule tells an author to move into docs/.

Merging pages does not solve it: the per-page cap is 120 lines and the merge candidates are ~100 lines each, so any merge overflows.

A skill's references/ takes no size cap (is_skill_reference) and no docs count (check_docs_count globs docs/*.md only). That is the escape check-skills already hands an author with an over-long SKILL.md, and seven skills here already use it.

docs/warp.md (87l) and docs/warp-host-setup.md (103l) to tooling-warp/references/
docs/aosguard.md (116l) to tooling-aosguard/references/

docs/ is now 36 of 40. Nothing was cut.

Two consequences worth naming:

.specgen/README.md was an outpost whose reciprocal target was docs/aosguard.md. With that target out of docs/ the outpost shape no longer applies, so it becomes a homestead naming the skill.
Code comments pointed at docs/warp.md with a deep relative path that would have blown the 90-char comment cap, so they name the skill instead. warp/paths.go carried five pointers to the same page; four were redundant before this move and are gone.

Verified: full pre-commit suite green, 759 tests pass, every rewritten link resolves on disk.

Refs #1303

`docs/` was at **39 of 40** with `aterm.md` at **zero** chars of headroom and five more pages within 20 chars. Five issues stall on that one wall: #1303, #1274, #1341, #1312, and #1119, whose 18 over-cap file headers carry ~155 lines the rule tells an author to move into `docs/`. Merging pages does not solve it: the per-page cap is 120 lines and the merge candidates are ~100 lines each, so any merge overflows. A skill's `references/` takes no size cap (`is_skill_reference`) and no docs count (`check_docs_count` globs `docs/*.md` only). That is the escape `check-skills` already hands an author with an over-long SKILL.md, and seven skills here already use it. * `docs/warp.md` (87l) and `docs/warp-host-setup.md` (103l) to `tooling-warp/references/` * `docs/aosguard.md` (116l) to `tooling-aosguard/references/` **docs/ is now 36 of 40.** Nothing was cut. Two consequences worth naming: * `.specgen/README.md` was an outpost whose reciprocal target was `docs/aosguard.md`. With that target out of `docs/` the outpost shape no longer applies, so it becomes a homestead naming the skill. * Code comments pointed at `docs/warp.md` with a deep relative path that would have blown the 90-char comment cap, so they name the skill instead. `warp/paths.go` carried **five** pointers to the same page; four were redundant before this move and are gone. Verified: full pre-commit suite green, 759 tests pass, every rewritten link resolves on disk. Refs #1303

coilyco-ops added 1 commit

2026-08-29 10:25:40 +00:00

refactor(docs): move the warp and aosguard pages into skill references

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

Details

ci / gate (pull_request) Successful in 54s

Details

13224d1c54

docs/ was at 39 of 40 with aterm.md at zero chars of headroom, so five
issues (#1303, #1274, #1341, #1312, #1119) all stalled on the same wall
with nowhere to put a page. Merging pages does not help: the per-page cap
is 120 lines and the candidates are ~100 lines each.

A skill's references/ takes no size cap and no docs count, which is the
escape check-skills already hands an author. warp.md and warp-host-setup.md
belong to tooling-warp, aosguard.md to tooling-aosguard. Nothing is cut.

docs/ is now 36 of 40.

.specgen/README.md was an outpost pointing at docs/aosguard.md, so with
that target gone it becomes a homestead naming the skill instead. Code
comments now name the skill rather than a deep path, and paths.go loses
four repeats of one pointer it already carried.

Refs coilyco-flight-deck/agentic-os#1303

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