-
Notifications
You must be signed in to change notification settings - Fork 0
docs: refresh README, add docs index and link checker, fix stale paths #584
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| # 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). | ||
|
|
||
| Check that repo paths referenced from the maintained docs still resolve with: | ||
|
|
||
| ```bash | ||
| npm run docs:check-links | ||
| ``` | ||
|
|
||
| ## Start here | ||
|
|
||
| | Doc | What it is | | ||
| | -------------------------------------- | ------------------------------------------------------------------------------------------------------- | | ||
| | [codebase-index.md](codebase-index.md) | Structured architecture map: layout, module map, Supabase schema, scripts, domain concepts | | ||
| | [site-map.md](site-map.md) | **Generated** route map — regenerate with `npm run sitemap:update`, verify with `npm run sitemap:check` | | ||
| | [agents-guide.md](agents-guide.md) | Human onboarding pointer; authoritative agent rules live in the root `AGENTS.md` | | ||
|
|
||
| ## Architecture | ||
|
|
||
| - [frontend-architecture.md](frontend-architecture.md) — shell, routing, dashboard module structure | ||
| - [deployment-architecture.md](deployment-architecture.md) — app/worker/Supabase deployment topology | ||
| - [ingestion-state-machine.md](ingestion-state-machine.md) — ingestion job lifecycle and states | ||
| - [design-system.md](design-system.md) — tokens, primitives, styling conventions | ||
| - [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 | ||
|
|
||
| ## Operations runbooks | ||
|
|
||
| - [launch-operator-runbook.md](launch-operator-runbook.md) — launch/operational duties and SLO probes | ||
| - [reindex-runbook.md](reindex-runbook.md) — safe reindex and ingestion recovery | ||
| - [retrieval-quality-runbook.md](retrieval-quality-runbook.md) — RAG/retrieval eval gates and tuning | ||
| - [worker-deploy-runbook.md](worker-deploy-runbook.md) — worker build contract, run recipe, secrets | ||
| - [disaster-recovery-runbook.md](disaster-recovery-runbook.md) — backup/restore and recovery drills | ||
| - [auth-connection-cap-runbook.md](auth-connection-cap-runbook.md) — Supabase auth connection cap (operator) | ||
| - [staging-setup.md](staging-setup.md) — staging environment bootstrap | ||
| - [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 | ||
|
|
||
| ## Governance, safety, privacy | ||
|
|
||
| - [clinical-governance.md](clinical-governance.md) — deployment and source governance checklist | ||
| - [clinical-hazard-analysis.md](clinical-hazard-analysis.md) — clinical hazard register | ||
| - [rag-injection-threat-model.md](rag-injection-threat-model.md) — prompt-injection threat model | ||
| - [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 | ||
|
|
||
| ## Process and review | ||
|
|
||
| - [process-hardening.md](process-hardening.md) — verification gates, CI expectations, known debts | ||
| - [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 | ||
| - [branch-review-ledger.md](branch-review-ledger.md) — reviewed branch/SHA ledger (append after reviews) | ||
|
|
||
| ## Plans and workstreams (living) | ||
|
|
||
| - [search-rag-master-plan.md](search-rag-master-plan.md) / [search-rag-master-context.md](search-rag-master-context.md) — search/RAG roadmap and shared context | ||
| - [rag-hybrid-findings-and-todo.md](rag-hybrid-findings-and-todo.md) — hybrid retrieval findings backlog | ||
| - [reindex-shadow-harness-design.md](reindex-shadow-harness-design.md) — designed-only shadow reindex harness (driver not built) | ||
| - [forward-codify-retrieval-rpcs-workorder.md](forward-codify-retrieval-rpcs-workorder.md) — retrieval RPC codification workorder | ||
| - [ingestion-concurrency-fix-workorder.md](ingestion-concurrency-fix-workorder.md) — ingestion concurrency workorder | ||
| - [project-alignment-cleanup.md](project-alignment-cleanup.md) — repo alignment cleanup tracker | ||
| - [redesign/](redesign/) — premium redesign plans, decision log, token adoption | ||
| - [superpowers/](superpowers/) — agent-authored plans and specs | ||
|
|
||
| ## Point-in-time records (historical — do not update) | ||
|
|
||
| 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 | ||
| - [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) | ||
|
|
||
| ## Archive | ||
|
|
||
| - [archive/](archive/) — completed phase plans, superseded designs, and old | ||
| progress logs kept for provenance. Never treat archive content as current | ||
| guidance. | ||
|
|
||
| ## Maintenance rules | ||
|
|
||
| - Generated files (`site-map.md`) are updated only via their generator scripts. | ||
| - When adding a doc, add it to the matching section here; date the filename if | ||
| it is a point-in-time record. | ||
| - When a maintained doc is superseded, move it to `archive/` and update inbound | ||
| links (`npm run docs:check-links` finds broken ones). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,40 +1,33 @@ | ||
| # Agents Guide | ||
|
|
||
| ## Purpose | ||
|
|
||
| This repository contains the Clinical KB application. It is a Next.js + Supabase + OpenAI RAG knowledge base for medical guidelines. Agents working with this project should follow these guidelines. | ||
|
|
||
| ## Getting Started | ||
|
|
||
| - Use Node 24 and npm 11; the project uses Next.js v16. | ||
| - Copy `.env.example` to `.env.local` and populate secrets. **Never commit actual secrets**. | ||
| - Use `npm run ensure` to start or verify the local dev server. It selects a stable port automatically. | ||
| - Start the ingestion worker in a separate terminal using `npm run worker`. | ||
|
|
||
| ## Development Guidelines | ||
|
|
||
| - Avoid changing `.env.example` values other than adding placeholders. Do not commit `.env.local`. | ||
| - When adding environment variables, update the schema in `src/lib/env.ts` and document them in `.env.example`. | ||
| - Use TypeScript and follow existing code patterns; avoid introducing new dependencies unless necessary. | ||
| - Run `npm run lint` and `npm run typecheck` before committing. | ||
| - Use `npm run test` and `npm run test:e2e` to ensure critical flows remain stable. | ||
| - Keep Supabase service role keys on the server; never expose them to the client. | ||
|
|
||
| ## Routing & Architecture | ||
|
|
||
| - The app uses the Next.js App Router under `src/app`. | ||
| - API routes live under `src/app/api`. | ||
| - Client components are in `src/components`. | ||
| - Supabase integration code is in `src/lib/supabase`. | ||
|
|
||
| ## Performance & Safety | ||
|
|
||
| - Use `zod` for request and environment validation. | ||
| - Enforce permissions server-side; do not rely on client-side checks. | ||
| - Respect the existing rate-limiting and source-governance logic. | ||
| - When adding new API endpoints, provide appropriate error handling and status codes. | ||
|
|
||
| ## Documentation | ||
|
|
||
| - Keep the README up to date if you change setup, scripts, or environment variables. | ||
| - Add high-level architectural changes or decisions in `docs/`. | ||
| Short onboarding pointer. The authoritative, always-current rules for agents | ||
| working in this repository live in the root [`AGENTS.md`](../AGENTS.md) — | ||
| verification gates, provider confirmation boundaries, Supabase project safety, | ||
| review routing, and workflow shortcuts. This page only orients you; it does not | ||
| duplicate those rules, so it cannot drift from them. | ||
|
|
||
| ## Read in this order | ||
|
|
||
| 1. [`AGENTS.md`](../AGENTS.md) — agent rules, verification gates, shortcuts | ||
| (`upload`, `dependency`, `bug-hunter`), and safety boundaries. | ||
| 2. [`docs/codebase-index.md`](codebase-index.md) — architecture and module map. | ||
| 3. [`docs/README.md`](README.md) — index of all runbooks, governance docs, and | ||
| plans, with maintained vs historical classification. | ||
| 4. [`docs/site-map.md`](site-map.md) — generated route map. | ||
|
|
||
| ## Human quickstart | ||
|
|
||
| - Node 24.x / npm 11.x are hard requirements (`engine-strict`); the app is | ||
| Next.js 16 + Supabase + OpenAI. | ||
| - Copy `.env.example` to `.env.local` and fill in values (never commit | ||
| secrets). Without Supabase/OpenAI values the app runs in demo mode on a | ||
| synthetic corpus. | ||
| - `npm run ensure` starts or verifies the dev server on a stable | ||
| project-specific port (never assume `localhost:3000`). | ||
| - `npm run worker` runs the local ingestion worker in a second terminal. | ||
| - When adding environment variables, update the schema in `src/lib/env.ts` and | ||
| document them in `.env.example`. | ||
| - Before handing off changes: `npm run verify:cheap` first, then | ||
| `npm run verify:pr-local` when the change is PR-ready (see | ||
| [`docs/process-hardening.md`](process-hardening.md) for the full | ||
| verification pyramid). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.