# 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](../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 | | [knowledge/KNOWLEDGE_SURFACE_PLAN.md](knowledge/KNOWLEDGE_SURFACE_PLAN.md) | ๐Ÿ”„ | Persistence + endpoints: who owns what, phased tasks, blockers. Approved 2026-09-01 | | [knowledge/KNOWLEDGE_CONSUMPTION_PLAN.md](knowledge/KNOWLEDGE_CONSUMPTION_PLAN.md) | ๐Ÿ’ก | How agents READ the entries (N14). Which agent gets what, and why. **Proposal, nothing built** | | [knowledge/TABLE_BRANCH_PROPOSAL.md](knowledge/TABLE_BRANCH_PROPOSAL.md) | ๐Ÿ’ก | Step 8 โ€” the symptom x cause matrix a shop manual actually holds. Deterministic triples, LLM only to phrase. **Proposal, nothing built** | | [knowledge/TERM_HIERARCHY_PROPOSAL.md](knowledge/TERM_HIERARCHY_PROPOSAL.md) | ๐Ÿ’ก | Step 7 + R7 โ€” parent/child terms and cross-document identity, designed together. **Touches `entity_id`; read before building** | | [knowledge/KNOWLEDGE_DOMAIN_CONTEXT_V4.md](knowledge/KNOWLEDGE_DOMAIN_CONTEXT_V4.md) | ๐Ÿ’ก | What a *real* domain context is. v3's object is a document brief wearing the name. **Proposal, nothing built** | | [knowledge/KNOWLEDGE_PERSISTENCE_CONTRACT.md](knowledge/KNOWLEDGE_PERSISTENCE_CONTRACT.md) | ๐Ÿ’ก | The four-table DDL sent to Harry 2026-09-01. **Pending โ€” no ORM written against it yet** | | [knowledge/KNOWLEDGE_DOMAIN_CONTEXT_V3.md](knowledge/KNOWLEDGE_DOMAIN_CONTEXT_V3.md) | โœ… | `DomainContext` design reasoning. **Shipped in full 2026-09-02** โ€” the live shape is the output contract ยง8 | 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 | | [plans/PR0_PR1_TOOL_FIXES.md](plans/PR0_PR1_TOOL_FIXES.md) | ๐Ÿ”„ | Sofhia's six tool fixes. PR-0 merged; PR-1 open. Every claim re-verified against the code, and two of the review's findings narrowed | | [plans/PR2_EVALUATION.md](plans/PR2_EVALUATION.md) | ๐Ÿ”„ | **Read before PR-3.** Four layers, three of them free. Establishes that **14 of 14** tools have zero output-correctness coverage | | [plans/PR3_REPAIR_EDGE.md](plans/PR3_REPAIR_EDGE.md) | ๐Ÿ”„ | The feedback edge (trigger B, budget 1) **gated on measured hit-rate**, plus the determinism fixes that ship regardless | | [plans/PR23_PART2_PLANNER_EVAL.md](plans/PR23_PART2_PLANNER_EVAL.md) | ๐Ÿ”„ | **pr/23 part 2 (2026-09-23).** Planner, router and eval work re-checked against the code: measurement first, then router, retrieve-then-plan, planner structure. **Aโ€“E done 2026-09-23** (D4 reverted, F1 optional) | | [plans/UNSTRUCTURED_V2_PLAN.md](plans/UNSTRUCTURED_V2_PLAN.md) | ๐Ÿ”„ | **The demo track (2026-09-23).** Parsing v2 โ†’ embeddings, private images via 1h signed URLs, analysis-scoped retrieval, the mixed structured+unstructured path **without a new intent**. Pre-empts the prompt-architecture work | --- ## `tools/` โ€” the analytical-tools workstream The `analyze_*` tool surface: forecast, importance, anomaly, cluster, A/B testing, segmentation, pareto. Tools are **pure functions, no base class** โ€” the "framework" is `spec_builder` + `ml/executor` + the shared chart kit. | Doc | Status | Read it when | |---|---|---| | [tools/ANALYTICAL_TOOLS_CONVENTIONS.md](tools/ANALYTICAL_TOOLS_CONVENTIONS.md) | โœ… | **Before writing any tool.** The InputModel โ†’ ToolSpec flow, the auto-chart convention, `run_fit`, the three registrations, and the rules that aren't negotiable | Roll-up status: DEV_PLAN ยง0.9 ยท built state: REPO_STATUS ยง9 ยท chart envelope: [plans/SPINE_V2_PLAN.md](plans/SPINE_V2_PLAN.md) ยง4.2 --- ## `reviews/` โ€” point-in-time assessments Read-only reviews. Nothing in them is a decision; findings are cited by id elsewhere. | Doc | Status | Note | |---|---|---| | [reviews/AGENTIC_DESIGN_REVIEW_2026-09-18.md](reviews/AGENTIC_DESIGN_REVIEW_2026-09-18.md) | ๐Ÿ“Ž | The DS agent against the 2026 state of the art. Findings **D-1โ€ฆD-12**; the source of PR-0โ€ฆPR-3 | | [reviews/PROMPT_ARCHITECTURE_2026-09-22.md](reviews/PROMPT_ARCHITECTURE_2026-09-22.md) | ๐Ÿ“Ž | `planner.md` + `intent_router.md` measured against industry practice. Findings **P-1โ€ฆP-7 / R-1โ€ฆR-4**, candidates **C-1โ€ฆC-9** โ€” **paused behind the unstructured v2 demo work** (added 2026-09-23) | --- ## `testing/` โ€” what running the thing actually found End-to-end dry-runs of the `structured_flow` path against real sources. These runs are expensive (~170k-290k tokens each) and found twelve bugs that 881 passing unit tests did not, because each was an interaction between the model's choices and a real data shape. | Doc | Status | Read it when | |---|---|---| | [testing/AGENTIC_DRY_RUN_LOG.md](testing/AGENTIC_DRY_RUN_LOG.md) | ๐Ÿ“Ž | **Before running a dry-run** (it costs real money, and ยง6 halves it), and before assuming a green run means a working turn โ€” seven of the twelve bugs produced a confident WRONG answer rather than an error | Suites + shapes: `eval/chat_sim/run_chat.py` ยท per-run answers: `eval/chat_sim/results/` --- ## `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 ``. 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.