docs: give CLAUDE.md a codebase orientation layer

[BigSimmo]

Summary

• CLAUDE.md was a bare @AGENTS.md import, so a Claude Code session loaded the full rule corpus with no orientation to the system those rules govern. Stack, layout, and the core data flows had to be rediscovered from docs/codebase-index.md every session.
• This keeps the @AGENTS.md import unchanged — no policy is moved, removed, or duplicated — and adds an orientation layer above it: what the product is, how the instruction files divide up, the rules most easily violated by accident, stack/runtime, repository layout, the answer and ingestion flows, the verification pyramid, the conventions the gates enforce, and the repo-specific skills/subagents.
• AGENTS.md remains the single source of truth for rules. CLAUDE.md points at it rather than restating it, and states explicitly that AGENTS.md wins on any disagreement, so the two cannot drift.
• docs/agents-guide.md — updated the one AI-tooling-map row that described CLAUDE.md as "a one-line @AGENTS.md import", which this change would otherwise leave stale.

Note on the deliberate design: the maturity audit records CLAUDE.md as a "non-dup import" on purpose, to stop five overlapping AI systems from drifting. That intent is preserved — the new content is orientation (structure, flows, commands), which is the layer AGENTS.md does not carry, and the file documents its own scope boundary so it does not grow into a second policy file.

CLAUDE.md sits outside the scan set for docs:check-links / docs:check-scripts (those cover README.md, AGENTS.md, and docs/**), so every repo path and npm script it references was verified by hand — all 15 script references and all module paths resolve.

Verification

• npm run verify:pr-local

Test Files  422 passed (422)
     Tests  4271 passed | 4 skipped (4275)
Skipping build: no build-affecting source, config, package, or container changes detected.
EXIT CODE: 0

Also run directly during iteration:

docs link check passed: 1312 repo path references resolve.
docs script-ref check passed: 386 npm-run reference(s) resolve to real scripts.
docs/codebase-index.md coverage OK: all 31 top-level modules/routes and all schema tables are indexed.
prettier --check CLAUDE.md docs/agents-guide.md → All matched files use Prettier code style!

UI verification not run: documentation-only change, no UI, routing, styling, browser, reduced-motion, or forced-colors behaviour touched.

npm run verify:release not run: no release or handoff-confidence claim is being made, and it is provider-backed.

Retrieval/answer evals not run: no retrieval, ranking, selection, chunking, scoring, source/citation rendering, or answer-contract code is touched. verify:pr-local independently classified this diff as docs-only and skipped offline RAG fixture validation on that basis.

Risk and rollout

• Risk: Very low. Documentation only — no source, config, test, schema, or dependency changes. The worst case is that a future edit lets the orientation text drift from the code it describes; the file mitigates that by pointing at docs/codebase-index.md for deep structure rather than duplicating it, and by stating its own scope boundary.
• Rollback: Revert this single commit. No migration, deployment, data, or runtime effect to unwind.
• Provider or production effects: None. No provider, network, or production system was contacted; every check run was local and offline.

Clinical Governance Preflight

Not applicable — this change touches no ingestion, answer generation, search/ranking, source rendering, document access, privacy, production env, or clinical output surface. Confirmed programmatically against scripts/pr-policy.mjs:

classifyPullRequestFiles(["CLAUDE.md", "docs/agents-guide.md"])
→ { clinicalRisk: false, operationalRisk: false, ragRanking: false, ui: false }

RAG impact: no retrieval behaviour change — documentation-only diff; no file under any RAG ranking surface is modified, and pr-policy classifies ragRanking: false.

Notes

• The Supabase project pin (Clinical KB Database / sjrfecxgysukkwxsowpy), the stale-ref warning, the provider-confirmation boundary, and the RAG-surface flagging rule are all summarised in the new "Highest-consequence rules" section as pointers into AGENTS.md, not as restatements that could diverge from it.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01PjFvJmVn1xb9QTtmuxcn7y

---

Generated by Claude Code

[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: 46 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: bd1feac2-d183-4b6b-aa2c-ebb5a779ee47

📥 Commits

Reviewing files that changed from the base of the PR and between 0adad0a and faca4f4.

📒 Files selected for processing (2)

• CLAUDE.md
• docs/agents-guide.md

---

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

[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 ↗︎.

[BigSimmo]

@cursoragent Inspect the PR and repository state, identify the root cause of every failing CI check, unresolved review comment, merge conflict, and related defect. Apply the smallest robust fix using existing project patterns and best practices, without unrelated changes. Run Bugbot and all relevant lint, type-check, test, build, and CI-equivalent commands, fix any issues found, then resolve only the review comments that are fully addressed. Summarise the root causes, changes made, validation results, and any remaining blockers.

[cursor]

PR #1379 is already merged and clean — nothing to fix.

Inspected PR #1379 after the @Cursoragent request. It was squash-merged into main as be83f5ce at 04:19:48Z, before this babysit finished.

Root causes / defects

Area	Result
Failing CI	None — PR required, Static PR, PR policy, Semgrep, Gitleaks, CircleCI all SUCCESS; scoped jobs correctly SKIPPED for docs-only
Merge conflicts	None
Review threads	0 unresolved (no reviews / inline comments)
Bugbot	0 findings (cursor[bot] had only the agent ack)
CodeRabbit	Rate-limited; no actionable findings

Changes made

No product/doc fixes. Appended a ledger closeout row and opened draft PR #1382 so this HEAD isn’t re-reviewed.

Validation

• Hosted: all required checks on docs: give CLAUDE.md a codebase orientation layer #1379 green
• Local: docs:check-links (1312 resolve), docs:check-scripts (386 resolve), Prettier pass
• npm run verify:pr-local → Test Files 422 passed (422) / Tests 4271 passed | 4 skipped (4275)
• Bugbot triage: no P0/P1/P2; only soft count approximations in CLAUDE.md (~160 / ~200), not defects

Remaining blockers

None for #1379 — it has already landed.

  

[BigSimmo]

@codex review PR

[BigSimmo]

@CodeRabbit review PR

[coderabbitai]

@BigSimmo I’ll review PR #1379.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

Reviewed commit: be83f5cebb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cursor]

Babysit closeout — no action required

Inspected PR #1379 after @Cursoragent request. Already squash-merged into main as be83f5ce (2026-07-29T04:19:48Z); head was faca4f47.

Findings

Area	Result
Failing CI	None — PR required, Static PR, PR policy, Semgrep, Gitleaks, CircleCI all SUCCESS; scoped jobs correctly SKIPPED for docs-only
Merge conflicts	None (merged)
Unresolved review threads	0 (no reviews, no inline comments)
Bugbot (cursor[bot] findings)	0 — only the agent ack comment; no Bugbot check-run findings
CodeRabbit	Rate-limited / no actionable findings on this head

Local validation (on origin/main)

• docs:check-links → docs link check passed: 1312 repo path references resolve.
• docs:check-scripts → docs script-ref check passed: 386 npm-run reference(s) resolve to real scripts.
• prettier --check CLAUDE.md docs/agents-guide.md → pass
• npm run verify:pr-local → Test Files 422 passed (422) / Tests 4271 passed | 4 skipped (4275); build skipped (docs-only)
• Bugbot triage subagent: no P0/P1/P2; soft count approximations in CLAUDE.md only (~160 scripts / ~200 lib modules) — not defects

Changes made

None — no failing checks, conflicts, or confirmed defects to fix.

Remaining blockers

None for this PR. It has already landed.