Docs index
✅ LIVE — the map. Reorganised 2026-08-24. Every doc in this repo carries a status banner under its H1; read it before trusting the body.
Status legend: ✅ LIVE (canonical) · 🔄 LIVE PLAN (in flight) · 💡 PROPOSAL (not approved) · ⛔ ARCHIVED (superseded, kept for the record) · 📎 REFERENCE (another repo's, can drift)
Start here — repo root
The root deliberately holds only four docs. If you read nothing else, read the first three.
| Doc | Status | Is |
|---|---|---|
| ../REPO_STATUS.md | ✅ | What is built. Canonical current state |
| ../DEV_PLAN.md | ✅ | What is in flight. Sprint plan, task table, locked decisions |
| ../API_CONTRACT_BE_PYTHON.md | ✅ | The contract of record for the FE-facing surface |
| ../README.md | — | HuggingFace Space card. The YAML frontmatter is load-bearing for deployment — don't restructure it |
CLAUDE.md also sits in the root but is gitignored (local operating manual, not shipped).
Trust order when sources disagree: code > REPO_STATUS / DEV_PLAN > everything else.
knowledge/ — the knowledge-pipeline workstream
Client documents → candidate knowledge entries an expert reviews rather than authors. Two halves (parsing, Sofhia · extraction, Rifqi) meeting at one versioned artifact.
| Doc | Status | Read it when |
|---|---|---|
| knowledge/knowledge_pipeline_context.md | 🔄 | You need the why — ownership split, settled decisions, what not to reopen |
| knowledge/KNOWLEDGE_PIPELINE_TODO.md | 🔄 | You want per-task status and owners. Start here |
| knowledge/KNOWLEDGE_PIPELINE_CALIBRATION.md | 🔄 | Before changing any constant. Every tuned value with the reason it has that value |
| knowledge/KNOWLEDGE_PARSING_OUTPUT_CONTRACT.md | 🔄 | You're working either side of the seam |
Roll-up status: DEV_PLAN §0.8 · built state: REPO_STATUS §14 · eval harness: ../eval/knowledge/README.md
plans/ — design plans
| Doc | Status | Note |
|---|---|---|
| plans/SPINE_V2_PLAN.md | 🔄 | Approved 2026-07-13; W2+W1 shipped. W3 deferred — do not start. Holds the message_charts DDL (§4.4) |
| plans/DS_TOOLS_PLAN.md | 💡 | Design study only. Nothing was built from it; don't implement without sign-off |
archive/ — superseded, kept for the record
Nothing here is safe to implement from. Each says what replaced it.
| Doc | Superseded by |
|---|---|
| archive/API_ENDPOINTS_RESTRUCTURE.md | ../API_CONTRACT_BE_PYTHON.md. The frozen 2026-06-30 snapshot sent to Harry; says "observability" (now traceability) and cites the removed ENABLE_SLOW_PATH |
| archive/CODE_REVIEW_2026-07-23.md | DEV_PLAN §0.7 for live F-n status. The review body still explains why each fix exists |
| archive/PROJECT_BRD.md | REPO_STATUS (built state) + API_CONTRACT_BE_PYTHON (contract). Written against pr/4 |
reference/ — other repos
| Doc | Note |
|---|---|
| reference/API_CONTRACT_BE_GOLANG.md | The Go Orchestrator's contract. We don't edit that repo; this is a copy and can drift. Verify against the Go source before relying on it. Last synced 2026-07-01 |
Subsystem docs (live beside the code)
src/*/README.md — catalog · knowledge_parsing · query · retrieval · security.
eval/*/README.md — chat_sim · help · intent · knowledge · planner · readiness.
Eval READMEs are reliable; follow their run and commit conventions exactly. Subsystem READMEs can lag — code wins.
Conventions
- Every doc gets a status banner under its H1, marked
<!-- doc-status -->. New docs too. - Archive, don't delete. A deleted doc leaves a dead link and no explanation; an archived one says what replaced it. (Repo convention: deletion needs Rifqi's explicit sign-off.)
- Docs are part of the change — a behaviour, surface or schema change updates the affected doc in the same unit of work.