The FASE 3 /docs restructure moved files into 8 subfolders (architecture,
guides, reference, frameworks, routing, security, compression, ops) but left
several link categories with stale relative paths. The new check:doc-links
gate (FASE 8) surfaced these and produced this exhaustive fix sweep.
Categories repaired (counts before → after, total broken: 270 → 0):
i18n-relative (241 → 0): docs in subfolders now reference translations
under docs/i18n/<locale>/docs/<subfolder>/<FILE>.md (one extra "../"
plus the docs/<subfolder>/ segment). Affects ARCHITECTURE, FEATURES,
USER_GUIDE, TROUBLESHOOTING, UNINSTALL, VM_DEPLOYMENT_GUIDE,
API_REFERENCE, and the I18N.md self-reference table.
parent-relative (14 → 0): refs like ../CLAUDE.md, ../CONTRIBUTING.md,
../AGENTS.md, ../Tuto_Qdrant.md, ../open-sse/..., ../electron/...,
../src/... promoted from one to two parent hops (../ → ../../) to
reach repo root from docs/<subfolder>/.
screenshots (9 → 0): FEATURES.md PNG refs rewritten to ../screenshots/
(assets live at docs/screenshots/ unchanged).
missing-rfc (2 → 0): RFC-AUTO-ASSESSMENT.md was deleted earlier in the
overhaul; replaced refs in EVALS.md with pointers to the live
AUTO-COMBO.md scoring doc plus an in-prose mention of
src/domain/assessment/.
other (4 → 0): ENVIRONMENT.md → ../../.env.example,
SETUP_GUIDE.md → ../../{open-sse/mcp-server,src/lib/a2a}/README.md,
PROVIDER_REFERENCE.md → ../../src/shared/... and ../../open-sse/...,
VM_DEPLOYMENT_GUIDE.md omnirouteCloud reference replaced with a
pointer to in-repo TUNNELS_GUIDE.md (omnirouteCloud lives in a
separate companion repo).
Validation:
npm run check:doc-links → PASS (501 internal links, 0 broken)
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Every .md under docs/{architecture,guides,reference,frameworks,routing,
security,compression,ops,diagrams} plus docs/README.md now opens with:
---
title: "<inferred from first H1>"
version: 3.8.0
lastUpdated: 2026-05-13
---
46 files updated (no docs were skipped — none had pre-existing
frontmatter). [slug]/page.tsx already reads frontmatter.version and
frontmatter.lastUpdated via gray-matter and renders a "v3.8.0" pill
plus a "Last updated" caption, so the UI picks these up automatically.
Helper: scripts/docs/add-frontmatter.mjs — idempotent (skips files that
already start with `---`), falls back to a humanized basename when no
leading H1 exists. Excludes docs/i18n/, docs/screenshots/,
docs/superpowers/, docs/diagrams/exported/. Re-runnable safely.
Also regenerated src/app/docs/lib/docs-auto-generated.ts: 44 docs across
8 sections (Architecture / Guides / Reference / Frameworks / Routing /
Security / Compression / Ops), which now includes the 14 docs that were
missing from the v3.7 sidebar (Cloud Agents, Guardrails, Memory, Skills,
Webhooks, Evals, Authz, Agent Protocols, Repository Map, Provider
Reference, Reasoning Replay, Stealth Guide, Tunnels Guide, Electron
Guide).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Group docs into intent-based subfolders so the topic each file covers is visible
from the directory layout: architecture/, guides/, reference/, frameworks/,
routing/, security/, compression/, ops/. Adds an empty diagrams/ placeholder
(populated in FASE 4) and a navigable docs/README.md index. Files were moved
with git mv so history is preserved. Internal cross-doc links were rewritten
to point at the new subfolder paths.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
