Split the oversized docs under the layout caps #99

Merged

coilysiren merged 1 commit from doc-layout-caps into main

2026-08-12 11:37:25 +00:00

coilyco-ops commented

2026-08-12 11:34:36 +00:00

Member

Closes #88.

Stacked on #98 (exception-taxonomy) because that PR edits docs/proxy.md and docs/FEATURES.md, both of which this restructures. Merge #98 first and this applies cleanly.

With this, both catalog exemption lists are gone — documentation-layout here, code-comments in #89 — so every tracked file in the repo is governed.

The citation surface was measured, not assumed

The issue's main risk is that three of these documents are cited by path from outside this repository, and the dead-cross-links hook cannot see those. So before splitting anything I enumerated every *.md#anchor reference in the repo. Exactly four exist, all into proxy.md:

proxy.md#validation (×3, from app/resilience.py comments)
proxy.md#trace-correlation-metadata
proxy.md#signoz-content-viewing-contract (from README.md, and per the issue from coilyco-bridge/deploy)
proxy.md#removed-the-self-verification-claim-check

All four headings are kept in proxy.md as redirect stubs naming the page that now holds the content, so any link written before this change still resolves. Everything else is cited by filename only — and every original filename survives as a parent index page. Verified with a script that resolves each cited anchor against the actual headings.

Shape of the split

Nine parents, split at boundaries the documents already had:

proxy.md (378L) needed the deepest split — request path, trace correlation, correlation fields, capture contract, SigNoz viewing, capture projections, validation, configuration, num_ctx derivation, operations
trajectory-contract-v1.md keeps its versioned filename with envelope, identity, taxonomy, model facts, and governance beneath it — the filename carries the version other services build against, so it does not move
architecture-v2.md, FEATURES.md, ROADMAP.md, litellm-parity.md, reliability_baseline.md, route-registry.md, trajectory-retention.md follow the same parent-plus-children pattern

Two passes were needed: several children were still over cap after the first split, so they split again at their H3 boundaries.

One thing the mechanical split got wrong

Documents that began at an H2 (architecture-v2.md starts at ## Charter) had no intro text, so the generated parent was a bare title plus a link list — technically compliant and useless to a reader. Each thin parent now has a short intro saying what it covers and where to start. architecture-v2.md says so explicitly, since AGENTS.md names it read-first.

Verification

All 56 docs within the 80-line and 4000-char caps, with both exemption lists removed
pre-commit run --all-files — every hook passes, including dead-cross-links and documentation-layout
All four cited anchors resolve, checked programmatically
pytest 283 passed · ruff · mypy clean

What I could not verify

coilyco-bridge/deploy cites proxy.md and its capture-contract section from outside this repo. The anchor is preserved, so those links should hold — but I could not check that repository from here. Worth a grep there before considering #88 fully closed out.

Closes #88. **Stacked on #98** (`exception-taxonomy`) because that PR edits `docs/proxy.md` and `docs/FEATURES.md`, both of which this restructures. Merge #98 first and this applies cleanly. With this, **both catalog exemption lists are gone** — `documentation-layout` here, `code-comments` in #89 — so every tracked file in the repo is governed. ## The citation surface was measured, not assumed The issue's main risk is that three of these documents are cited by path from outside this repository, and the `dead-cross-links` hook cannot see those. So before splitting anything I enumerated every `*.md#anchor` reference in the repo. **Exactly four exist, all into `proxy.md`:** - `proxy.md#validation` (×3, from `app/resilience.py` comments) - `proxy.md#trace-correlation-metadata` - `proxy.md#signoz-content-viewing-contract` (from `README.md`, and per the issue from `coilyco-bridge/deploy`) - `proxy.md#removed-the-self-verification-claim-check` All four headings are **kept in `proxy.md`** as redirect stubs naming the page that now holds the content, so any link written before this change still resolves. Everything else is cited by filename only — and **every original filename survives** as a parent index page. Verified with a script that resolves each cited anchor against the actual headings. ## Shape of the split Nine parents, split at boundaries the documents already had: - **`proxy.md`** (378L) needed the deepest split — request path, trace correlation, correlation fields, capture contract, SigNoz viewing, capture projections, validation, configuration, `num_ctx` derivation, operations - **`trajectory-contract-v1.md`** keeps its versioned filename with envelope, identity, taxonomy, model facts, and governance beneath it — the filename carries the version other services build against, so it does not move - **`architecture-v2.md`**, **`FEATURES.md`**, **`ROADMAP.md`**, **`litellm-parity.md`**, **`reliability_baseline.md`**, **`route-registry.md`**, **`trajectory-retention.md`** follow the same parent-plus-children pattern Two passes were needed: several children were still over cap after the first split, so they split again at their H3 boundaries. ## One thing the mechanical split got wrong Documents that began at an H2 (`architecture-v2.md` starts at `## Charter`) had **no intro text**, so the generated parent was a bare title plus a link list — technically compliant and useless to a reader. Each thin parent now has a short intro saying what it covers and where to start. `architecture-v2.md` says so explicitly, since `AGENTS.md` names it read-first. ## Verification - **All 56 docs within the 80-line and 4000-char caps**, with both exemption lists removed - `pre-commit run --all-files` — every hook passes, including `dead-cross-links` and `documentation-layout` - All four cited anchors resolve, checked programmatically - `pytest` 283 passed · `ruff` · `mypy` clean ## What I could not verify `coilyco-bridge/deploy` cites `proxy.md` and its capture-contract section from outside this repo. The anchor is preserved, so those links should hold — but I could not check that repository from here. Worth a grep there before considering #88 fully closed out.

coilyco-ops added 1 commit

2026-08-12 11:34:36 +00:00

Split the oversized docs under the layout caps

ci / smoke (pull_request) Successful in 7s

Details

ci / quality (pull_request) Successful in 23s

Details

3c44c04a1f

Removes the agent-proxy#88 exemption list from pyproject.toml. Both catalog
exemption lists are now gone: documentation-layout here and code-comments in
#89, so every tracked file is governed.

Nine documents were over the 80-line or 4000-char caps. Each keeps its original
filename as a parent index, because inbound links from other repositories cite
files rather than sections, and the content moves into child pages split at the
boundaries the documents already had.

The citation surface was measured before splitting rather than assumed. Only
four anchors are cited anywhere: proxy.md#validation, #trace-correlation-metadata,
#signoz-content-viewing-contract, and #removed-the-self-verification-claim-check.
All four headings are kept in proxy.md as redirect stubs naming the page that
now holds the content, so links written before this change still resolve. Every
other document is cited by filename only, and every filename survives.

proxy.md needed the deepest split at 378 lines: request path, trace
correlation, correlation fields, capture contract, SigNoz viewing, capture
projections, validation, configuration, num_ctx derivation, and operations. The
contract document keeps its versioned filename with envelope, identity,
taxonomy, model facts, and governance beneath it.

Documents that began at an H2 lost their framing when the first section moved,
so each thin parent gained a short intro explaining what it covers and where to
start. architecture-v2.md says so explicitly, since AGENTS.md names it
read-first.

closes #88

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-12 11:34:36 +00:00