M2 — Link orphaned Scout docs & rebuild docs/README.md as a complete index #37578

Sub-issue of #37124. Scout half of the Rock — mirrors Jose's M2 (#37127).

Description

Make every doc in Fabrizzio's slice reachable, and rebuild docs/README.md into a real index. Jose's M2 (#37127) linked the backend orphans into CLAUDE.md's navigation; this is the other half — the remaining orphans plus the index that was supposed to catch them.

docs/README.md is not a docs index today: it carries 11 links and 10 of them are frontend. It reads as an index of docs/frontend/, so this is close to writing it from scratch for the other 40+ files.

Acceptance Criteria

• docs/testing/PERFORMANCE_TESTS.md (27 KB) linked — JMeter over test-jmeter/ plus the Kubernetes analytics suite; no overlap found, so this is a linking job
• docs/testing/API_TESTING.md (21 KB) linked — Postman (dotcms-postman/) and Karate (test-karate/); read in full, no overlap with REST_API_PATTERNS.md or INTEGRATION_TESTS.md, so this is a linking job, not M3's
• docs/core/SDK_BREAKING_CHANGE_CATEGORIES.md (13 KB) linked
• The four unowned orphans resolved per M0's ownership decision: docs/cli/CLI_OVERVIEW.md, docs/cli/CLI_BUILD_SYSTEM.md, docs/claude/GPG_COMMIT_SIGNING.md, docs/test-cases/README.md
• docs/integration/API_CONTRACTS.md linked into CLAUDE.md's navigation — already agreed as jointly owned in M4 — Backend gap backlog #37129, where the linking itself was left open as mechanical work
• docs/README.md rewritten as a complete index covering every file under docs/, grouped by area, each entry with a one-line description of when to load it
• Every new link verified to resolve (no typos in relative paths)
• Reachability check automated and committed — a script that walks the link graph from root CLAUDE.md and docs/README.md and fails on any unreachable .md under docs/, so the index can't silently rot again. This is what makes the Rock's third condition checkable instead of a one-time sweep.
• Reachability check green: zero orphans across docs/backend/, docs/testing/, docs/core/ and the rest of docs/

Additional Context

Baseline measured on main at dfbe40f: 52 .md files under docs/, 45 reachable, 7 orphaned. Zero orphans remain in docs/backend/ and docs/infrastructure/ — Jose's M2 closed those.

Correction

An earlier revision of this issue asserted that API_TESTING.md overlapped REST_API_PATTERNS.md and INTEGRATION_TESTS.md. That was inferred from the filename, not from reading the file — the same mistake M0's criteria warn against. Both orphans have since been read: API_TESTING.md covers Postman and Karate, PERFORMANCE_TESTS.md covers JMeter, and all three directories they document (dotcms-postman/, test-karate/, test-jmeter/) exist. Neither is a consolidation candidate. Their content still needs the M1 audit against real source, which is tracked there.

Priority

Medium

Done — #37709, merged Sep 25

docs/README.md is now a complete index of all 54 documents, grouped by area, each entry saying when to load it rather than what it contains. The gotchas that cost most when missed are surfaced in the index itself, before the file is opened: that an unregistered integration test is silently never run in CI, that the CLI compiles to a lower release than the core modules, that certain Vitest options were already measured and did not help.

All five remaining orphans linked — PERFORMANCE_TESTS.md, API_TESTING.md, SDK_BREAKING_CHANGE_CATEGORIES.md, GPG_COMMIT_SIGNING.md, test-cases/README.md — plus docs/integration/API_CONTRACTS.md with the joint-ownership note agreed in #37129, closing one of the two items that issue left open. Orphans across docs/: 7 at the start of this Rock, 0 now.

The unowned directories were resolved rather than deferred: docs/cli/ taken by Scout and audited in #37664 (which found the Java language level stated as 21 against a pom pinned to 11), docs/claude/ and docs/test-cases/ in #37721.

scripts/validate-docs-reachability.py walks the link graph from CLAUDE.md and the index and exits non-zero on anything unreachable. Review caught that the first revision claimed it fails while nothing ran it — so .github/workflows/cicd_pr_docs-reachability.yml now runs it on every PR touching docs/, CLAUDE.md or the script. It passed on its own PR in 7 seconds, and a doc added without a link makes it exit 1.

That last part is what makes this milestone durable rather than a sweep. The Rock's own ownership split missed 10 files because it was built from a hand-enumerated list; an index over everything plus a check that fails on omission is the structural answer.