Documentation Organization Proposal¶

Phase 4 addendum — APPROVED and EXECUTED 2026-09-21 (moves in commit; see git history). Reorganizes the reader-facing doc-site around the three modeling purposes: analyze consequences, inform decisions, compete (market intelligence).

Principle¶

Documentation mirrors purpose. A reader arriving with a question should land in the section built for that question:

Reader question	Section
How do we model?	Methodology
If we do X, what happens?	Decisions (analyze)
What should X be?	Decisions (inform)
What do competitors/partners do, and what does it mean here?	Competitive
What do the BU models look like inside?	Models (reference)
What did we decide and why?	ADRs

Storage boundary (Sep 2026 ruling): the repo holds authored content only. Input documentation — source PDFs, partner workbooks (incl. the v12 xlsx itself), published benchmark reports, raw data files in any format — does not enter this repo's folder tree. Bloat and orphaned single-purpose files are the failure mode this prevents. Inputs live as collections in the COS object store (bucket oves-cos-bucket-1437812500, consistent with the OVES unified knowledge-SPOT pattern); this repo references them through a curated index in curation/ (extending the existing web-sources.yaml pattern) and accesses them via the COS MCP/file-index tooling.

Consequence: competitive/benchmarks/ as a folder of source documents is removed from this proposal. The repo keeps only the framework-cast analyses (original authored content); each analysis page links to its COS-indexed sources.

Proposed IA¶

docs/                                 # authored content ONLY
├── methodology/          # unchanged — framing, unitary core, BU interface, DS coupling
├── decisions/            # NEW — purpose 1 + 2
│   ├── pricing/          # pricing decision analyses (composite tariff scenarios, wedge splits)
│   ├── cost/             # cost-reduction consequence + target analyses
│   ├── capacity/         # expansion phase, fleet size, station count decisions
│   └── output-matrix/    # BU × market grid reports (Phase 5 output)
├── competitive/          # NEW — purpose 3 (analyses only; sources live in COS)
│   └── v12-mapping.md    # moved from methodology/ — first framework-cast intelligence artifact
├── markets/              # NEW — standalone market bundles (Kenya first: HTML + CSV)
├── models/               # unchanged — BU model reference (legacy pages cleaned per below)
├── reference/            # unchanged
├── adr/                  # unchanged
├── curation/             # curated indexes ONLY — pointers to COS collections + trusted sources
└── analysis/             # tooling/method reports (this proposal lives here)

COS object store (external):      # input documentation, any format
└── emob-inputs collection       # partner workbooks (v12 xlsx), benchmark PDFs, raw data files

Moves and changes¶

Item	From → To	Reason
v12-mapping.md	methodology/ → competitive/	it is market intelligence, not method
v12 xlsx (source workbook)	OneDrive/WXWork cache → COS emob-inputs collection	input doc, not repo content
output matrix reports (Phase 5)	— → decisions/output-matrix/	they are decision outputs
market bundles (Phase 6)	— → markets/	standalone per-market deliverables
benchmark source documents (Phase 5+)	— → COS emob-inputs collection	input docs never in repo
benchmark recast analyses (Phase 5+)	— → competitive/	authored content; links to COS sources

No methodology page moves — the methodology section stays the stable core.

Legacy cleanup (existing pages)¶

Item	Proposal
models/vrs.md (retired VOR alias)	redirect stub → models/rider.md, or delete with ADR note
models/fcs.md	rename to cns.md — FCS is a retired alias of CNS (Charging Network Services), registered BU in catalog
broken link to models/rider-swapping.md	fix or remove (pre-existing warning)
models/mob3-bridge.md	keep; review after catalog is final

Content type conventions (new)¶

A decision analysis page names: the decision, the options, the BU queries used (per BU object interface), the answer, and the profile(s) it ran on.
A benchmark recast page names: the source (COS object key + curation index entry), the original units/language, the framework-aligned translation, and the adopted/contrast/reject verdict per ADR 0002.
Every decision/benchmark page links back to the methodology section it relies on — no method duplicated.
Curation index format: curation/ holds machine-readable index files (YAML, extending web-sources.yaml): source name, COS object key or URL, format, topics, status (adopted / read-for-information), and the framework page that consumes it. The index is the repo's only knowledge of the inputs — the objects themselves never enter the tree.

Execution notes¶

All moves happen in one commit after approval; mkdocs nav updated in the same commit; KRR strict must pass before push.
URL redirects for moved pages (v12-mapping) handled by a stub page for one release cycle.