File size: 4,497 Bytes
f1342ce | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 | # Docs index
<!-- doc-status -->
> ✅ **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](../REPO_STATUS.md) | ✅ | **What is built.** Canonical current state |
| [../DEV_PLAN.md](../DEV_PLAN.md) | ✅ | **What is in flight.** Sprint plan, task table, locked decisions |
| [../API_CONTRACT_BE_PYTHON.md](../API_CONTRACT_BE_PYTHON.md) | ✅ | **The contract of record** for the FE-facing surface |
| [../README.md](../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](knowledge/knowledge_pipeline_context.md) | 🔄 | You need the *why* — ownership split, settled decisions, what not to reopen |
| [knowledge/KNOWLEDGE_PIPELINE_TODO.md](knowledge/KNOWLEDGE_PIPELINE_TODO.md) | 🔄 | You want per-task status and owners. **Start here** |
| [knowledge/KNOWLEDGE_PIPELINE_CALIBRATION.md](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](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](../eval/knowledge/README.md)
---
## `plans/` — design plans
| Doc | Status | Note |
|---|---|---|
| [plans/SPINE_V2_PLAN.md](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](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](archive/API_ENDPOINTS_RESTRUCTURE.md) | [../API_CONTRACT_BE_PYTHON.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](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](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](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.
|