docs: repository maturity audit — report, security policy, diagrams, index cleanup

.github/workflows/ci.yml

@@ -299,7 +299,7 @@ jobs:
           NEXT_BUILD_CPUS: "4"
         run: npm run build
 
-      - name: Bundle budget (warn-only until a baseline is enforced)
+      - name: Bundle budget (enforced — fails on >tolerancePct gzip growth vs baseline)
         run: npm run check:bundle-budget
 
       - name: Deployment boot smoke

README.md

@@ -269,3 +269,15 @@ synthetic and must not be used as clinical guidance.
 by Git. The smaller `public/demo-documents/` set is tracked because the app uses
 it for demo-mode source and image rendering when live Supabase setup is
 unavailable.
+
+## Security
+
+Report vulnerabilities privately — see `SECURITY.md`. Do not open a public issue for
+a security problem. Threat models and the privacy assessment live under `docs/`
+(`rag-injection-threat-model.md`, `tenancy-defense-in-depth-review.md`,
+`privacy-impact-assessment.md`).
+
+## License
+
+Proprietary — all rights reserved. This repository is private and is not licensed for
+redistribution or reuse (`package.json` declares `"license": "UNLICENSED"`).

SECURITY.md

@@ -0,0 +1,60 @@
+# Security Policy
+
+Clinical KB (`psychiatry.tools`) is a private, single-maintainer clinical reference
+application that handles private guideline documents and grounded answer generation.
+Security reports are taken seriously and handled privately.
+
+## Reporting a vulnerability
+
+**Please do not open a public issue, pull request, or discussion for a security
+problem, and do not disclose it publicly before it is resolved.**
+
+Report privately using **GitHub Private Vulnerability Reporting** — the
+**"Report a vulnerability"** button under this repository's **Security** tab
+(`Security → Advisories → Report a vulnerability`). If that channel is unavailable to
+you, contact the maintainer (`@BigSimmo`) directly through GitHub.
+
+When reporting, please include:
+
+- A description of the issue and its impact.
+- Steps to reproduce (a minimal proof of concept is ideal).
+- Affected paths, routes, or components if known.
+- Any suggested remediation.
+
+You can expect an initial acknowledgement within a few days. Because this is a
+single-maintainer project, timelines are best-effort; please allow a reasonable
+period for a fix before any disclosure.
+
+## Supported versions
+
+The application is continuously deployed from `main`. Only the current `main` /
+production deployment is supported — there are no maintained release branches or
+backports. Fixes land on `main` and roll out via the standard deployment path
+(`docs/deployment-architecture.md`).
+
+## Scope
+
+In scope: the Next.js app tier, API routes, the ingestion worker, Supabase
+schema/RLS/RPCs, and the retrieval/answer pipeline in this repository.
+
+Out of scope: third-party managed services themselves (Supabase, OpenAI, Railway,
+GitHub) — report those to the respective vendor. Note this is a clinical **prototype**,
+not validated clinical decision support (see `README.md` → "Clinical Safety Status").
+
+## Handling sensitive findings
+
+- Never include real secrets, credentials, tokens, or patient-identifiable data in a
+  report. Reference the affected file/location and the class of exposure instead.
+- Do not run intrusive tests against the live `psychiatry.tools` deployment or the live
+  Supabase project. Prefer local/demo mode (`README.md` → Setup).
+
+## Related security documentation
+
+- `docs/rag-injection-threat-model.md` — prompt-injection threat model.
+- `docs/tenancy-defense-in-depth-review.md` — multi-tenant isolation review.
+- `docs/privacy-impact-assessment.md` — privacy impact assessment and launch blockers.
+- `docs/clinical-hazard-analysis.md` — clinical hazard register.
+- `docs/openai-cross-border-basis.md` — cross-border data-processing basis.
+
+Automated controls in CI: secret scanning (Gitleaks, `.github/workflows/secret-scan.yml`)
+and static analysis (Semgrep, `.github/workflows/sast.yml`).

docs/README.md

@@ -1,8 +1,9 @@
 # Clinical KB Documentation Index
 
-Curated map of everything under `docs/`. Categories distinguish **maintained**
-documents (keep these current when behavior changes) from **point-in-time
-records** (historical; do not update, supersede with a new dated doc instead).
+Curated map of the load-bearing docs under `docs/` (not an exhaustive listing of every
+file). Categories distinguish **maintained** documents (keep these current when behavior
+changes) from **point-in-time records** (historical; do not update, supersede with a new
+dated doc instead).
 
 Check that repo paths referenced from the maintained docs still resolve with:
 
@@ -27,6 +28,7 @@ npm run docs:check-links
 - [clinical-chat-ui-component-map.md](clinical-chat-ui-component-map.md) — chat UI component inventory
 - [clinical-badge-system-guide.md](clinical-badge-system-guide.md) — clinical badge semantics
 - [multi-user-auth-setup.md](multi-user-auth-setup.md) — auth, sessions, owner scoping
+- [pwa.md](pwa.md) — PWA install assets, privacy-first service worker, offline shell
 
 ## Operations runbooks
 
@@ -40,6 +42,9 @@ npm run docs:check-links
 - [database-drift-detection.md](database-drift-detection.md) — schema drift detection (`npm run check:drift`)
 - [supabase-migration-reconciliation.md](supabase-migration-reconciliation.md) — migration drift and repair policy
 - [observability-slos.md](observability-slos.md) — health probes, SLO counters, degraded modes
+- [openai-rag-operations.md](openai-rag-operations.md) — OpenAI/RAG provider operations and modes
+- [operator-backlog.md](operator-backlog.md) — pending operator debt backlog
+- [deploy-corrector-public-titles.md](deploy-corrector-public-titles.md) — public-title corrector deploy notes
 
 ## Governance, safety, privacy
 
@@ -50,10 +55,13 @@ npm run docs:check-links
 - [privacy-impact-assessment.md](privacy-impact-assessment.md) — PIA findings and launch blockers
 - [openai-cross-border-basis.md](openai-cross-border-basis.md) — cross-border data-processing basis
 - [production-readiness-checklist.md](production-readiness-checklist.md) — release readiness criteria
+- [samd-classification-medication-considerations.md](samd-classification-medication-considerations.md) — SaMD classification and medication considerations
 
 ## Process and review
 
 - [process-hardening.md](process-hardening.md) — verification gates, CI expectations, known debts
+- [testing.md](testing.md) — test execution, focused/live commands, Playwright ownership, flake policy
+- [productivity-workflows.md](productivity-workflows.md) — repo workflow planners (flightplan, triage, rag-lab, …)
 - [codex-review-protocol.md](codex-review-protocol.md) — shared review protocol for all review skills
 - [codex-prompt-playbook.md](codex-prompt-playbook.md) — copy/paste prompts for common repo work
 - [branch-cleanup-guide.md](branch-cleanup-guide.md) — branch hygiene workflow
@@ -75,10 +83,11 @@ Dated status reports, reviews, and operator decisions. They describe the repo
 as it was on that date; supersede with a new dated document rather than editing.
 
 - [audit/](audit/) — repo and UX/accessibility audits
+- [audit/2026-07-20-repository-maturity.md](audit/2026-07-20-repository-maturity.md) — full repository maturity, mapping, and organisation audit
 - [forward-codify-retrieval-rpcs-workorder.md](forward-codify-retrieval-rpcs-workorder.md) — completed retrieval RPC codification workorder
-- [project-alignment-cleanup.md](project-alignment-cleanup.md) — completed June 2026 repo-alignment record
+- [project-alignment-cleanup.md](archive/project-alignment-cleanup.md) — completed June 2026 repo-alignment record
 - [capacity-review.md](capacity-review.md), [scale-readiness-review.md](scale-readiness-review.md), [tenancy-defense-in-depth-review.md](tenancy-defense-in-depth-review.md)
-- `*-2026-*` findings and status docs, e.g. [chunking-ocr-reindex-lever-finding-2026-07-08.md](chunking-ocr-reindex-lever-finding-2026-07-08.md), [source-governance-status-2026-07-08.md](source-governance-status-2026-07-08.md), [source-governance-priorities-2026-07-02.md](source-governance-priorities-2026-07-02.md), [source-review-priority-2026-07-02.md](source-review-priority-2026-07-02.md), [operator-apply-july8-batch.md](operator-apply-july8-batch.md)
+- `*-2026-*` findings and status docs, e.g. [chunking-ocr-reindex-lever-finding-2026-07-08.md](chunking-ocr-reindex-lever-finding-2026-07-08.md), [source-governance-status-2026-07-08.md](archive/source-governance-status-2026-07-08.md), [source-governance-priorities-2026-07-02.md](archive/source-governance-priorities-2026-07-02.md), [source-review-priority-2026-07-02.md](source-review-priority-2026-07-02.md), [operator-apply-july8-batch.md](operator-apply-july8-batch.md)
 
 ## Archive
 

design-qa.md → docs/archive/design-qa-2026-07-15.md

@@ -64,4 +64,4 @@ Blocker: an independent source visual target is required to certify concept fide
 
 ## Follow-up audit — 2026-07-17
 
-The exhaustive line-level design, accessibility, UX, interaction, and route-coverage follow-up is documented in [`docs/design-audit-2026-07-17.md`](docs/design-audit-2026-07-17.md). It preserves the fixes above, avoids duplicating this pass, and records the new P1/P2/P3 fixes plus the exact local verification limitations.
+The exhaustive line-level design, accessibility, UX, interaction, and route-coverage follow-up is documented in [`docs/design-audit-2026-07-17.md`](../design-audit-2026-07-17.md). It preserves the fixes above, avoids duplicating this pass, and records the new P1/P2/P3 fixes plus the exact local verification limitations.

docs/project-alignment-cleanup.md → docs/archive/project-alignment-cleanup.md

@@ -2,7 +2,7 @@
 
 **Status: complete (reconciled 2026-07-15).** This is a historical record of the June alignment pass,
 not an active cleanup backlog. Current dependency work is routed through the `dependency` shortcut;
-current operational work is tracked in [`operator-backlog.md`](operator-backlog.md).
+current operational work is tracked in [`operator-backlog.md`](../operator-backlog.md).
 
 ## Dependency decisions
 

docs/source-governance-status-2026-07-08.md → docs/archive/source-governance-status-2026-07-08.md

@@ -20,7 +20,7 @@ lack detectable local document-control endorsement).
 ## Three corrections to earlier framing
 
 1. **`document_status = "unknown"` triggers no governance warning.**
-   `sourceGovernanceWarnings` ([src/lib/source-governance.ts](../src/lib/source-governance.ts))
+   `sourceGovernanceWarnings` ([src/lib/source-governance.ts](../../src/lib/source-governance.ts))
    only warns on `outdated` (danger) and `review_due` (warning). "Unknown" is
    silent as a warning, though it renders as "Review status unknown" in the
    provenance line. So resolving unknown statuses improves the **displayed
@@ -35,7 +35,7 @@ lack detectable local document-control endorsement).
 3. **The `verification` metadata field is vestigial.** The consumed governance
    fields are `document_status`, `clinical_validation_status`,
    `clinical_validation_evidence`, and `extraction_quality` (the required set in
-   [scripts/audit-source-governance.ts](../scripts/audit-source-governance.ts)).
+   [scripts/audit-source-governance.ts](../../scripts/audit-source-governance.ts)).
    `verification` is not read by the warning logic; a null `verification` is not
    a governance gap.
 
@@ -60,7 +60,7 @@ lack detectable local document-control endorsement).
    (or re-derive from source).
 
    **Now automatic:** the cycle inference is folded into the canonical governance
-   backfill's `deriveMetadata` ([scripts/backfill-source-metadata.ts](../scripts/backfill-source-metadata.ts),
+   backfill's `deriveMetadata` ([scripts/backfill-source-metadata.ts](../../scripts/backfill-source-metadata.ts),
    `npm run backfill:source-metadata`), so any governance refresh derives
    cycle-based statuses for new docs without a separate pass. Date-less docs
    still resolve to `unknown` and **remain visible to users** — governance never
@@ -85,7 +85,7 @@ lack detectable local document-control endorsement).
 - **Full corpus re-index** — retrieval is lexical-fast-path dominant
   (`embedding_skipped_rate = 1.0`), recall metrics are at ceiling, and extraction
   is 100% good, so a re-index can only hold the line, not measurably improve.
-  See the shadow-harness design ([docs/reindex-shadow-harness-design.md](reindex-shadow-harness-design.md))
+  See the shadow-harness design ([docs/reindex-shadow-harness-design.md](../reindex-shadow-harness-design.md))
   — keep it as a dormant tripwire for future chunking changes, do not run now.
 
 ## How to re-measure