docs: file loose dated records and close the docs index gaps

[BigSimmo]

Summary

Repository organisation pass over the documentation surface and the orientation maps. No product code, no schema, no retrieval or ranking surface is touched — this is filing and indexing only.

• Filed five dated point-in-time docs into the directories that already exist for them.docs/README.md states the convention (dated records are historical; audits live in audit/, superseded material in archive/) but these five were still sitting loose at the docs/ top level:

  • audit-handover-2026-07-14.md, audit-remediation-plan-2026-07-14.md, design-audit-2026-07-17.md → docs/audit/
  • rag-scalability-wip-remediation-2026-07-17.md (self-labelled "Superseded historical record"), rag-scalability-wip-review-handover-2026-07-15.md → docs/archive/

  Relative links inside the moved files were re-anchored (](foo.md) → ](../foo.md)), and the two inbound references were updated in docs/operator-backlog.md and docs/archive/design-qa-2026-07-15.md. Verified content-identical apart from those link prefixes and Prettier's table reflow.

• Moved the root codex-cloud-review/ directory to docs/prompts/codex-cloud-review/. It held three verbatim Codex review prompt inputs, was absent from every layout map, and docs/prompts/ is already the home for review prompts. The .prettierignore and .cursorindexingignore entries were repointed to the new path so the files stay unformatted and unindexed as before.

• Closed the docs/README.md index gaps. Seventeen docs were unlisted, including search-chrome-behaviour.md — a load-bearing contract that AGENTS.md requires reading before touching search chrome. Added the maintained ones to their existing sections, the dated ones under point-in-time records, and added a subdirectory map covering rag-behaviour/, prompts/, codex/, evidence/, audit/, redesign/, superpowers/, and archive/, none of which were described.

• Documented the top-level directories the orientation maps omit. Root data/ is loaded at runtime by seven src/lib modules (differentials, forms, medications, services, specifiers) yet appeared in neither CLAUDE.md nor docs/codebase-index.md, and is easily confused with src/data/. Also documented mockups/, plugins/, eslint-rules/, .agents/, .claude/, and .githooks/.

• scripts/check-docs-links.mjs: added a VERBATIM_DIRS skip for codex-cloud-review/. Relocating that directory under docs/ brought it into the checker's default scan, where two of its internal references point at a path that never existed. Those files are retained byte-for-byte as provided, so the reference cannot be corrected; the checker already has this exact mechanism for archive/ and audit/, and --all still sweeps them.

Verification

• npm run docs:check-links — docs link check passed: 1368 repo path references resolve. (baseline before this branch: 1348 passing; the increase is the new index entries)

• npm run docs:check-scripts — docs script-ref check passed: 378 npm-run reference(s) resolve to real scripts.

• npm run docs:check-index — docs/codebase-index.md coverage OK: all 31 top-level modules/routes and all schema tables are indexed.

• npm run format:check (whole tree, since .prettierignore changed and that alters the verdict for files this diff never touched) — All matched files use Prettier code style!, exit 0.

• npm run verify:cheap — all 26 static gates and lint/typecheck passed; the unit suite reported Test Files 1 failed | 433 passed (434) / Tests 1 failed | 4562 passed | 3 skipped (4566), so the gate exited 1.

  The single failure is pre-existing and Windows-only, unrelated to this diff:

  FAIL |node| tests/repo-hygiene.test.ts > branch-review-ledger row parsing > rotates older rows into a quarterly archive while keeping newer live rows
  Expected: "docs/archive/branch-review-ledger-2026-q3.md"
  Received: "docs\archive\branch-review-ledger-2026-q3.md"
  

  scripts/branch-review-ledger.mjs:209 builds the archive path with path.join, which yields backslashes on Windows while the test asserts the POSIX form. Neither that script nor that test is in this diff, and CI runs Linux, so it is green there. Left alone deliberately — ledger tooling is its own change, not something to fold into a docs tidy.

The advisory deep sweep npm run docs:check-links -- --all reports 36 missing paths, up from 34. Both additions are the verbatim-input references described above; every other entry is pre-existing and points at source files that historical docs referenced when they were written (src/lib/rag.ts and similar). No missing path in this diff traces to a link that was re-anchored.

RAG impact: no retrieval behaviour change — no file under src/lib/rag/**, clinical-search, ranking-config, answer-ranking, the eval harness, or the golden fixture is touched; scripts/pr-policy.mjs classifies this diff as clinicalRisk: false, operationalRisk: false, and non-RAG-ranking.

Deliberately not in scope

Four more loose dated docs stay at the docs/ top level because moving them means editing source and migrations rather than docs: capacity-review.md (cited from scripts/soak-test.ts), tenancy-defense-in-depth-review.md (src/lib/owner-scope.ts, tests/owner-scope-guard.test.ts, two migrations, SECURITY.md), operator-apply-july8-batch.md (three migrations plus supabase/schema.sql), scale-readiness-review.md (one migration). forward-codify-retrieval-rpcs-workorder.md is indexed as completed but live is still ahead of the repo on those RPCs, so archiving it would be misleading.

No gate catches an undocumented repo-root directory — check-codebase-index-coverage.mjs covers routes, src/lib modules and schema tables only, which is exactly how root data/ stayed invisible in both orientation maps. Extending that checker is the durable fix and deserves its own PR rather than widening a blocking gate here.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Expanded the docs index with new architecture links, operations runbooks, a directory purpose map, and additional historical audit/ledger entries.
  • Added new Codex full-stack master review prompt materials, including a review-and-stress-test workflow and repository working agreement.
  • Published/updated detailed audit and handover documentation, and refreshed multiple intra-doc links for consistent navigation.

• Chores

  • Refined formatting and link-checker ignore/scan behavior for review prompt artifacts.
  • Updated repository layout and review-archive metadata to match the latest documented structure.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in:45 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8d6607a9-f14d-40d5-8873-e3dafef3c65c

📥 Commits

Reviewing files that changed from the base of the PR and between 880ac31 and 93741e1.

📒 Files selected for processing (2)

• docs/branch-review-ledger.md
• docs/outstanding-issues.md

📝 Walkthrough

Walkthrough

The PR adds Codex review prompt documentation, expands documentation indexes and repository maps, corrects relative links, adds audit and handover records, updates documentation link scanning, and reorganizes review ledger entries.

Changes

Documentation and review tooling

Layer / File(s)	Summary
Codex prompt corpus and preservation rules docs/prompts/codex-cloud-review/*, scripts/check-docs-links.mjs, .cursorindexingignore, .prettierignore	Adds three Codex review documents and preserves their verbatim paths from default formatting, indexing, and link scans.
Repository documentation indexes and operational catalogues CLAUDE.md, docs/README.md, docs/codebase-index.md, docs/operator-backlog.md, docs/outstanding-issues.md, docs/scripts-index.md	Expands repository maps, documentation indexes, script catalogues, operator references, and outstanding issue entries.
Audit artifacts and cross-references docs/archive/*, docs/audit/*	Adds RAG handover and design-audit reports and corrects relative links across audit and remediation documents.
Review ledger organization docs/branch-review-ledger.md	Adds one review record and relocates four existing CI hygiene records.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• BigSimmo/Database#584: Introduced the documentation link-checker behavior extended here.
• BigSimmo/Database#673: Added audit artifacts referenced by the updated operator backlog links.
• BigSimmo/Database#657: Also updates review records in docs/branch-review-ledger.md.

Suggested labels:codex

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main docs reorganization and index-gap cleanup.
Description check	✅ Passed	The description is detailed and covers summary and verification well; only the optional risk/rollout section is missing.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/archive/rag-scalability-wip-review-handover-2026-07-15.md`:
- Around line 275-276: Update the copy-paste prompt in the handover document to
reference the archived path
docs/archive/rag-scalability-wip-review-handover-2026-07-15.md instead of the
nonexistent docs/rag-scalability-wip-review-handover-2026-07-15.md, leaving the
Track A remediation instructions unchanged.
In `@docs/branch-review-ledger.md`:
- Line 148: Update the merge-readiness entry for commit
b660dbc5a10d7ca3da03541028017f0abc6b5bd3 so the outcome field contains a
concrete READY or NOT READY disposition followed by the relevant finding(s),
rather than only “findings,” while preserving the existing check details.

🪄 Autofix (Beta)

❌ Autofix failed (check again to retry)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bd385d3d-efb8-4401-8732-7819fdeea981

📥 Commits

Reviewing files that changed from the base of the PR and between 0310c6a and cb38354.

📒 Files selected for processing (17)

• .cursorindexingignore
• .prettierignore
• CLAUDE.md
• docs/README.md
• docs/archive/design-qa-2026-07-15.md
• docs/archive/rag-scalability-wip-remediation-2026-07-17.md
• docs/archive/rag-scalability-wip-review-handover-2026-07-15.md
• docs/audit/audit-handover-2026-07-14.md
• docs/audit/audit-remediation-plan-2026-07-14.md
• docs/audit/design-audit-2026-07-17.md
• docs/branch-review-ledger.md
• docs/codebase-index.md
• docs/operator-backlog.md
• docs/prompts/codex-cloud-review/1-codex-full-stack-master-review-prompt.md
• docs/prompts/codex-cloud-review/2-codex-full-stack-master-prompt-review-and-stress-test.md
• docs/prompts/codex-cloud-review/3-codex-agents-md-companion.md
• scripts/check-docs-links.mjs

[coderabbitai]

Caution

Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/archive/rag-scalability-wip-review-handover-2026-07-15.md`:
- Around line 275-276: Update the copy-paste prompt in the handover document to
reference the archived path
docs/archive/rag-scalability-wip-review-handover-2026-07-15.md instead of the
nonexistent docs/rag-scalability-wip-review-handover-2026-07-15.md, leaving the
Track A remediation instructions unchanged.
In `@docs/branch-review-ledger.md`:
- Line 148: Update the merge-readiness entry for commit
b660dbc5a10d7ca3da03541028017f0abc6b5bd3 so the outcome field contains a
concrete READY or NOT READY disposition followed by the relevant finding(s),
rather than only “findings,” while preserving the existing check details.

🪄 Autofix (Beta)

❌ Autofix failed (check again to retry)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bd385d3d-efb8-4401-8732-7819fdeea981

📥 Commits

Reviewing files that changed from the base of the PR and between 0310c6a and cb38354.

📒 Files selected for processing (17)

• .cursorindexingignore
• .prettierignore
• CLAUDE.md
• docs/README.md
• docs/archive/design-qa-2026-07-15.md
• docs/archive/rag-scalability-wip-remediation-2026-07-17.md
• docs/archive/rag-scalability-wip-review-handover-2026-07-15.md
• docs/audit/audit-handover-2026-07-14.md
• docs/audit/audit-remediation-plan-2026-07-14.md
• docs/audit/design-audit-2026-07-17.md
• docs/branch-review-ledger.md
• docs/codebase-index.md
• docs/operator-backlog.md
• docs/prompts/codex-cloud-review/1-codex-full-stack-master-review-prompt.md
• docs/prompts/codex-cloud-review/2-codex-full-stack-master-prompt-review-and-stress-test.md
• docs/prompts/codex-cloud-review/3-codex-agents-md-companion.md
• scripts/check-docs-links.mjs

🛑 Comments failed to post (1)

docs/archive/rag-scalability-wip-review-handover-2026-07-15.md (1)

275-276: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Fix the handover document path.

This file lives at docs/archive/rag-scalability-wip-review-handover-2026-07-15.md, but the copy-paste prompt points to docs/rag-scalability-wip-review-handover-2026-07-15.md. The next agent will be directed to a nonexistent path.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/archive/rag-scalability-wip-review-handover-2026-07-15.md` around lines
275 - 276, Update the copy-paste prompt in the handover document to reference
the archived path docs/archive/rag-scalability-wip-review-handover-2026-07-15.md
instead of the nonexistent
docs/rag-scalability-wip-review-handover-2026-07-15.md, leaving the Track A
remediation instructions unchanged.

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

Autofix skipped. No unresolved CodeRabbit review comments with fix instructions found.

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

❌ Cannot run autofix: This PR has merge conflicts.

Please resolve the conflicts with the base branch and try again.

Alternatively, use @coderabbitai resolve merge conflict to automatically resolve the conflicts.

[BigSimmo]

@Cursorsgent fix merge conflict

[BigSimmo]

@cursoragent fix merge conflict

[cursor]

Merge conflict on PR #1436 is resolved and pushed.

Conflict: only docs/scripts-index.md — this branch’s gate-set listing vs main’s Codex Cloud setup notes. Kept both.

Result:

• Merge commit: 229a71ff
• Branch is mergeable with origin/main (mergeable: MERGEABLE)
• docs:check-scripts and docs:check-links both passed

PR: #1436

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/outstanding-issues.md`:
- Around line 85-86: Update the outstanding-issues ledger markers near the
duplicate next-ID comments: assign unique IDs to the new issue rows below,
remove both existing 138 and 141 markers, and retain exactly one marker with
next ID 144 in docs/outstanding-issues.md.
- Around line 163-165: Resolve the duplicate ledger entries in
docs/outstanding-issues.md by determining whether rows `#135`–#137 are
replacements for the later copies or distinct issues. Remove the later duplicate
rows if they are replacements; otherwise renumber these three rows to `#141`–#143
and update the ledger marker to `#144`, preserving monotonic unique IDs.

🪄 Autofix (Beta)

❌ Autofix failed (check again to retry)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8ef90170-a638-40e7-a2c4-1a5de9f8b3eb

📥 Commits

Reviewing files that changed from the base of the PR and between cb38354 and 229a71f.

📒 Files selected for processing (5)

• CLAUDE.md
• docs/README.md
• docs/branch-review-ledger.md
• docs/outstanding-issues.md
• docs/scripts-index.md

🚧 Files skipped from review as they are similar to previous changes (3)

• CLAUDE.md
• docs/branch-review-ledger.md
• docs/README.md

[github-actions]

CI triage

CI failed on this PR. Automated classification of the 2 failed job(s):

• Static PR checks — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.
• PR required — needs investigation: inspect the failing step and uploaded diagnostics; rerun only after classifying the cause.

Compared with main CI run #6895 (cancelled).

Classification is evidence routing, not permission to ignore a failure. Exact quarantined Playwright identities remain governed by the flake ledger.

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

Autofix skipped. No unresolved CodeRabbit review comments with fix instructions found.

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

Autofix skipped. No unresolved CodeRabbit review comments with fix instructions found.

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

Autofix skipped. No unresolved CodeRabbit review comments with fix instructions found.

[BigSimmo]

@cursoragent resolve merge conflict

[cursor]

Merge conflict on PR #1436 is resolved and pushed.

Conflict: only docs/outstanding-issues.md (the issues:next-id marker), with an ID collision underneath:

• Kept main’s closed #140 and its #141 (clinical-accent tokens)
• Renumbered this branch’s colliding docs-index issue #141 → #144
• Set issues:next-id=145

Result: merge commit 93741e1d, mergeable: MERGEABLE, check:outstanding-issues and docs:check-links both green.

PR: #1436