R77.B — Audit

Inventory of broken internal .md refs in the Colibri docs corpus and gaps in docs/_config.yml against the just-the-docs canonical reference config. Basis for the R77.B contract (Step 2) and packet (Step 3).

Scope

R77.B ships no src/ code. It is a docs-and-Pages-config task only. Two independent sub-goals:

  1. Fix broken internal .md refs that render as 404 on GitHub Pages (case-sensitivity hazards + stray docs/ prefixes).
  2. Harden docs/_config.yml with remote_theme version pin, explicit color_scheme, callouts: block, and mermaid: block.

Sub-goal 1 — Broken .md refs inventory

1.1. Hazard grep patterns used

Pattern Purpose Scope
]\(adr- (case-insensitive) Lowercase ADR filename in link target — hazardous on Pages (Linux case-sensitive FS) docs/**/*.md
]\(docs/ Stray docs/ prefix inside a doc already under docs/ — resolves to /AMS/docs/docs/... 404 docs/**/*.md
]\(ADR-00.\.md\) ADR ↔ ADR cross-refs — verify uppercase casing preserved docs/architecture/decisions/**/*.md

1.2. Exclusion zones

Per R77.B brief, historical artefacts under the following dirs are not fixed (they document past states and the broken-ref strings in them are analysis, not live links):

  • docs/audits/**/*.md — past-round audit artefacts
  • docs/packets/**/*.md — past-round execution plans
  • docs/verification/**/*.md — past-round test evidence

1.3. Broken refs found — LIVE docs (fix these)

File Line Current ref Issue Target fix
docs/architecture/decisions/ADR-004-tool-surface.md 99 ](adr-005-multi-model-defer.md) Lowercase filename → case-mismatch 404 on Pages ](ADR-005-multi-model-defer.md)
docs/world-schema.md 3 [`docs/colibri-system.md`](docs/colibri-system.md) Stray docs/ prefix → /AMS/docs/docs/colibri-system.md 404 on Pages [`docs/colibri-system.md`](colibri-system.md) (sibling relative; link text kept verbatim)

Total live broken refs: 2.

1.4. Grep evidence — ]\(adr- pattern

Hits scanned: 14 total.

  • 8 legitimate hits where link text contains “adr-“ (lowercase prefix like “adr-005” in prose) but the link target is correctly-cased — these are not broken and are not touched.
  • 4 hits in docs/architecture/decisions/{ADR-003, ADR-002, ADR-005, README, index}.md — all target files correctly cased (ADR-00N-*.md). Not broken.
  • 1 legitimate hit ADR-004-tool-surface.md:183 — this is the “Rejected options” table row referencing the adr-005 decision in prose; target casing is correct (long matching line, Grep truncated). Manual spot-check confirms.
  • 1 broken hit ADR-004-tool-surface.md:99 — lowercase target filename. Fix required.

1.5. Grep evidence — ]\(docs/ pattern

Hits scanned: 13 total.

  • 12 hits in docs/audits/r75-plan-red-audit.md + docs/packets/r75-plan-red-packet.md — excluded zone, historical artefacts.
  • 1 hit docs/world-schema.md:3 — live stray docs/ prefix in blockquote attribution. Fix required.

1.6. Grep evidence — ADR ↔ ADR cross-refs

Pattern ]\(ADR-00.\.md\) returned zero hits — meaning all ADR cross-refs use the full filename ADR-00N-<slug>.md (not the short ADR-00N.md form). Current cross-refs manually verified:

  • ADR-003-bft-library.md:115 → (ADR-002-vrf-implementation.md) ✓
  • ADR-002-vrf-implementation.md:99 → (ADR-003-bft-library.md) ✓
  • ADR-005-multi-model-defer.md:40, 150 → (ADR-004-tool-surface.md) ✓
  • docs/architecture/decisions/README.md:42-44 → (ADR-001-*.md), (ADR-002-*.md), (ADR-003-*.md) ✓
  • docs/architecture/decisions/index.md:17-22 → (ADR-001-*.md) through (ADR-006-*.md) ✓

All ADR cross-refs except the single R77.B target at ADR-004-tool-surface.md:99 use correct casing.

Sub-goal 2 — _config.yml hardening

2.1. Current docs/_config.yml inventory

Present keys (keep untouched):

  • title, description, baseurl, url
  • remote_theme (needs version pin)
  • plugins (4 plugins declared)
  • relative_links: (enabled, collections: true)
  • search_enabled: true, search: block (heading_level 3, previews 3, 5/10 before/after)
  • aux_links: (Repository → //github.com/LastEld/AMS)
  • footer_content (Apache 2.0 + Commons Clause)
  • nav_sort: case_insensitive
  • back_to_top: true, back_to_top_text
  • markdown: kramdown, highlighter: rouge, kramdown: block
  • exclude: list (6 entries)
  • defaults: block (layout: default)

2.2. Missing keys (add via R77.B)

Key Current Target Source
remote_theme just-the-docs/just-the-docs (unpinned) just-the-docs/just-the-docs@v0.12.0 Latest stable release tag (GitHub releases API, fetched 2026-04-19)
color_scheme absent light just-the-docs default made explicit; canonical value per _config.yml line 166 of just-the-docs main (comment: “only supports dark, light/nil, or a custom scheme”)
callouts: block absent 5 standard variants (highlight, important, new, note, warning) just-the-docs canonical _config.yml lines 168-183
mermaid: block absent version: "9.1.6" just-the-docs canonical _config.yml lines 97-103

2.3. Latest stable just-the-docs release

Fetched via gh api repos/just-the-docs/just-the-docs/releases/latest on 2026-04-19:

Tag Published Prerelease
v0.12.0 (LATEST STABLE) 2026-01-23 false
v0.11.2 2026-01-23 false
v0.11.1 2026-01-03 false
v0.11.0 2026-01-01 false
v0.10.2 2026-01-01 false

Decision: pin to v0.12.0 (current stable, six-week track record). Prompt suggestion of v0.10.1 was speculative — the actual current stable as of Apr 2026 is v0.12.0.

2.4. Keys that must NOT be touched

Per R77.B brief — these are already correct and are explicitly outside scope:

  • title, description, baseurl, url
  • plugins: (4 entries)
  • relative_links: block
  • search_enabled, search: block
  • aux_links: block
  • footer_content
  • nav_sort
  • back_to_top, back_to_top_text
  • markdown, highlighter, kramdown: block
  • exclude: list
  • defaults: block

Pages rendering expectation

After merge of R77.B:

  1. https://lasteld.github.io/AMS/architecture/decisions/adr-004-tool-surface.html — “ADR-005” link resolves to 200 instead of 404.
  2. https://lasteld.github.io/AMS/world-schema.html — “docs/colibri-system.md” link resolves to /AMS/colibri-system.html (200) instead of /AMS/docs/colibri-system.html (404).
  3. Theme renders from a pinned version (v0.12.0) — no silent breakage when just-the-docs main branch lands an unrelated change.
  4. Explicit color_scheme: light — preserves existing visual (was defaulting to light); protects against upstream default flip.
  5. Callouts block — unlocks just-the-docs {: .note }, {: .warning }, etc. syntax (not currently used in Colibri docs, but surface becomes available).
  6. Mermaid block — unlocks mermaid diagram rendering (not currently used, but surface becomes available).

Risks flagged

  • Theme pin semantics: remote_theme: owner/repo@tag — verified syntax in GitHub Pages docs (https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/adding-a-theme-to-your-github-pages-site-using-jekyll#adding-a-theme). Safe.
  • Callouts + mermaid blocks inert: adding them activates no existing content. Zero content-layer risk.
  • No src/ touched: R77.B is docs-only; test suite (1085/1085) should pass unchanged.

Files inventoried

Count Path
1 docs/_config.yml (target for sub-goal 2)
1 docs/architecture/decisions/ADR-004-tool-surface.md (target for sub-goal 1)
1 docs/world-schema.md (target for sub-goal 1)

Total files to edit in Step 4: 3.

Audit gate

Step 1 complete. Step 2 (contract) will specify the exact edits and invariants preserved.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.