Summary
docs/user-guide/ grew organically into eight overlapping files with no index, mixed audiences, and PRP-referential framing. It has no single entry point and some of it has drifted from the code.
Add a navigable docs/manual/ organised into three tracks, and absorb the user-guide content into it.
Scope
Three tracks, matching the product's real audiences:
- Operator — concepts, installation, quickstart, seeding, running the stack, operations.
- Analyst — dashboard tour, forecasting, backtesting, champion selector, demand & planning, chat & knowledge. (A dashboard user who never opens a terminal is a real persona here.)
- Integrator — API reference, code architecture, data model, artifacts & registry, extending, CI & quality gates.
Plus shared references: configuration, troubleshooting, FAQ, glossary.
Conventions per chapter: a Purpose: / Intended reader: header pair, a "What you'll accomplish" section, dense cross-linking, and a "Next" pointer.
Evidence discipline: every stated number traces to app/core/config.py, a fixed constant, or an authoritative module. Runtime-dependent figures (durations, accuracy, which model wins) are explained rather than asserted.
Drift corrected along the way
docs/user-guide/feature-reference.md listed 7 model types; app/shared/model_taxonomy.py defines 11 (5 baseline, 4 tree, 2 additive).- It also described 7 data-platform tables; there are 10 (adds
exogenous_signal, replenishment_event, sales_returns).
Related: #376 tracks the same class of drift (stale slice count) in docs/_base/.
Disposition of docs/user-guide/
- Six guides become short redirect stubs pointing at their new chapters.
showcase-manual-demo-guide.md (reviewer QA procedure) and showcase-walkthrough.md (contains unshipped PRP-38..41 roadmap) are kept intact with a pointer banner — neither is user-manual content.
Validation
- Every internal link and anchor fragment in
docs/manual/ resolves.
- No chapter is orphaned from the index.
Summary
docs/user-guide/grew organically into eight overlapping files with no index, mixed audiences, and PRP-referential framing. It has no single entry point and some of it has drifted from the code.Add a navigable
docs/manual/organised into three tracks, and absorb the user-guide content into it.Scope
Three tracks, matching the product's real audiences:
Plus shared references: configuration, troubleshooting, FAQ, glossary.
Conventions per chapter: a
Purpose:/Intended reader:header pair, a "What you'll accomplish" section, dense cross-linking, and a "Next" pointer.Evidence discipline: every stated number traces to
app/core/config.py, a fixed constant, or an authoritative module. Runtime-dependent figures (durations, accuracy, which model wins) are explained rather than asserted.Drift corrected along the way
docs/user-guide/feature-reference.mdlisted 7 model types;app/shared/model_taxonomy.pydefines 11 (5 baseline, 4 tree, 2 additive).exogenous_signal,replenishment_event,sales_returns).Related: #376 tracks the same class of drift (stale slice count) in
docs/_base/.Disposition of docs/user-guide/
showcase-manual-demo-guide.md(reviewer QA procedure) andshowcase-walkthrough.md(contains unshipped PRP-38..41 roadmap) are kept intact with a pointer banner — neither is user-manual content.Validation
docs/manual/resolves.