# Webill Green — User Manual Programme · Implementation Plan

Status: **PLANNED** — no milestone started. How the finished manual stays current is
defined in [EVOLUTION.md](EVOLUTION.md).

---

## 1. Mission and definition of done

Produce comprehensive, end-user documentation of the **entire** Webill Green
platform — every screen, every background process, every stage of the business
lifecycle from entity setup through strategy, nomination, market operations and
settlement — written in the voice and at the quality bar of the two existing
exemplars:

- [`docs/user-manual/USER-MANUAL.html`](USER-MANUAL.html) — *Strategy — User Manual* (trader,
  off-taker and IPP strategy books, BRP screens, demo walkthrough).
- The IPP volume — *IPP Allocation, Forecast & Availability*.

**Done means:**

1. A hub page plus eight themed volumes (§4), built from committed Markdown
   sources by one command (§9), visually consistent with the existing manuals.
2. Every route, LiveView, stateful component, Oban worker, AshOban trigger and
   long-running process is mapped to at least one manual section in
   [`COVERAGE.md`](COVERAGE.md) — the coverage contract (§8) — and that matrix is 100 %.
3. Concepts are explained problem-first before mechanics; every substantial
   mechanism carries a **data-driven worked example** whose numbers are
   re-derivable from the deterministic demo dataset (§6).
4. One master cross-referencing **glossary** (§7): every first-use term links to
   its definition; every definition links back to the section(s) that teach it.
5. Every chapter uses the house **figure library** (§5) — vivid, framework-free
   CSS/SVG illustrations, not walls of text.

---

## 2. What exists today (and what we inherit)

### 2.1 The exemplars — conventions we adopt wholesale

Both manuals are Pandoc-built single-page HTML sharing
[`docs/user-manual/USER-MANUAL.css`](USER-MANUAL.css) (dark shell, gold `#faa919` on ink
`#404068`, sticky collapsible TOC, paper reading column, print stylesheet).
Extracted conventions (to be codified in `STYLE.md` at M0):

- **Problem-first chapters**: each module opens with "the trader's/IPP's
  problem" before any UI. Numbered chapters `N. Title — em-dash subtitle`,
  numbered `N.M` subsections; anchors derive from headings.
- **Second person, plain speech**, short paragraphs; blockquote callouts for
  tips and warnings; tables only for enumerable facts.
- **Worked examples carry the arithmetic**: inputs table → step-by-step
  computation → conservation check (`Σ = 75 + 60 = 135 = G ✓`) → the roll-up
  table the user will see on screen, then "this is the pattern to expect on
  your own page".
- **Custom CSS figure families** (no charting library): `allocation-diagram`,
  `priority-prorata-diagram`, `rule-example-diagram`, `pricing-flow`,
  `run-chart-example` (inline SVG minicharts), `tab-sample` (annotated screen
  replicas with numbered red callouts). Mobile and print safe.
- **Standard closing chapters**: *The rhythms* (how the clock fits together),
  *Common questions*, *Glossary*, *Demo walkthrough / Reference card*.
- **Icon discipline** — the manual names badges/icons exactly as
  `StrategyComponents` renders them.

### 2.2 Known defects to repair in passing

- **No Markdown sources committed** for either manual — the HTML is the only
  artifact. M5 recovers sources (`pandoc` HTML→md + manual figure extraction) so
  both volumes join the normal build.
- The header logo `docs/assets/webill-site-logo.png` referenced by both manuals
  **does not exist in the repo** — both render a broken image. M0 restores it.
- Archive pointers that name files which are missing; the archive convention is formalised in EVOLUTION §10.

### 2.3 Source material inherited from the design-doc corpus

The `docs/` tree holds mature *developer* design docs. They are raw material,
**not** authority — the manual documents behaviour as built, verified against
code and the seeded dataset. High-value feeds (full mapping in §10):
settlement architecture + seven physical and four virtual worked examples,
per-deal-type PPA term-sheet specs and party-assignment matrices, the IPP
methodology trilogy, and the BRP
"day-in-the-life" narrative. Known-stale material (`docs/references/market/spot_mo.md` —
superseded per BACKLOG; `docs/references/entities/*.md`) must not be used without
re-verification.

---

## 3. Readers and seats

The manual serves eight seats. Volumes declare their primary seats up front;
the hub routes each reader to a suggested path.

| Seat | Logs into | Cares about |
| --- | --- | --- |
| **Trader** (desk) | Org app → Trader Pools → Strategy | pools, runs, simulations, nominations, BESS, risk, BRP bidding |
| **IPP operator** | Org app → IPP Sites → Strategy | hierarchy, monthly forecast, HAF/SCE, sales, allocations, settlement receipts |
| **Off-taker energy manager** | Org app → Off-taker Sites → Strategy | procurement, savings, coverage, bills vs statements |
| **Commercial / deal desk** | Org app → Proposals · Negotiations · Contracts | proposals, wizards, terms, signing, written agreements |
| **Eskom analyst** | Eskom app | tariffs, charges, rates, loss factors, UoS |
| **Municipal (Munix) officer** | Munix app | municipality config, municipal tariffs and wheeling charges |
| **Market/System Operator** | MO console · SO console | registrations, market rules, clearing, dispatch/curtailment |
| **Platform operator** | shell + any seat | `mix wb.setup`, profiles, Oban health, scenario lab, live sim |

Demo seats and credentials are defined by the consolidated setup
(all demo users share the documented password); the manual references them in every "follow along" callout.

---

## 4. Information architecture — hub + twenty-one volumes

One `index.html` hub (orientation, reader paths, master glossary, version
stamp) linking the published volumes. Single-page-per-volume keeps the
exemplars' travel-well property (searchable with ⌘F, printable, attachable).

**Canonical order (3.1.0+):** V0 Orientation → **V1 Rhythms** → V2 Entities →
V3 Strategy → V4 IPP → V5 Deals → V6 Settlement → V7 Market → V8–V10
(org / MO / SO seats) → V11 Market API → V12 Scenario Lab → V13 Billing →
V14 Analytics → **V15 Virtual Wheeling** → **V16 Regional Trading (SAPP)** →
**V17 Carbon** → **V18 Carbon Tax** → **V19 Operations** → **V20 TODOs**.

| Vol | Title (working) | Built file | Primary seats | Core sources in code |
| --- | --- | --- | --- | --- |
| V0 | Orientation & Core Concepts | `v0-orientation.html` | everyone | whole-system maps; SAPP / carbon / weather / full clock |
| V1 | The Four Rhythms | `v1-rhythms.html` | everyone | Oban cron + triggers; amalgamates V0 §6 / V3 §18 / V19 §3 |
| V2 | Entities & Setup | `v2-entities.html` | all org seats, Eskom, Munix | `WB.Org`, `WB.Wheeling.Entities`, `WB.Device`, `WB.Portfolio`, `WB.TS`, `WB.Tariff` |
| V3 | Strategy (retrofit of existing manual) | `v3-strategy.html` | trader, IPP, off-taker | `WB.Strategy.*` |
| V4 | IPP Allocation, Forecast & HAF (retrofit) | `v4-ipp.html` | IPP operator | `WB.Wheeling.Forecast.*`, hierarchy |
| V5 | The Deal Room — proposals to contracts | `v5-deals.html` | commercial desk | `WB.Wheeling.Contracts.*`, proposal/negotiation/contract LiveViews |
| V6 | Settlement — physical & virtual | `v6-settlement.html` | all commercial seats | `WB.Wheeling.Settlement.*` |
| V7 | Market Operations — BRP, MO & SO | `v7-market.html` | trader, MO, SO | `WB.Brp.*`, MO/SO consoles |
| V8 | Organization Market Bidding | `v8-org-bidding.html` | organisation bidder | Market (complete) · Bid Desk · Market Month · Accounts · Billing |
| V9 | Market Operator | `v9-market-operator.html` | MO | DAM / IDM handbook (`market-dam.md` §§1–11) · `/mo` console (§§12–26) |
| V10 | Systems Operator | `v10-systems-operator.html` | SO | Who the SO is · zones · notices / instructions · console |
| V11 | Market API | `v11-market-api.html` | integrators | `/api/v1`, `/internal`, OpenAPI |
| V12 | Scenario Lab | `v12-scenario-lab.html` | platform operator | `/org/sim`, `WB.Sim.Scenario`, `WB.Sim.Driver` |
| V13 | Billing | `v13-billing.html` | commercial / finance seats | reserved |
| V14 | Analytics | `v14-analytics.html` | analyst / operator seats | reserved |
| V15 | Virtual Wheeling | `v15-virtual-wheeling.html` | off-taker, Eskom, VW holder | VWA, 15-min allocation, consolidated refund |
| V16 | Regional Trading (SAPP) | `v16-regional-trading.html` | trader | `WB.Sapp`, FX register, Regional desk |
| V17 | Carbon | `v17-carbon.html` | sustainability / commercial | `WB.Carbon`, `WB.CarbonMarket`, CADT |
| V18 | Carbon Tax Compliance | `v18-carbon-tax.html` | emitter | `WB.CarbonTax` |
| V19 | Operations & Administration | `v19-operations.html` | Eskom, Munix, platform operator | Eskom/Munix apps, Oban catalog, `WB.Setup` |
| V20 | TODOs | `v20-todos.html` | docs programme | open items by owning volume |

### V0 — Orientation & Core Concepts (~11 chapters)

1. What wheeling is and why this platform exists (SA market primer: Eskom,
   municipalities, NERSA, SAWEM; the money and energy flows).
2. The cast — IPPs, off-takers, traders, BRPs, MO, SO — and the five apps
   (Org, Eskom, Munix, MO console, SO console). *Figure: market map.*
3. The object model in plain language: organizations → sites/pools → meters →
   readings → intervals; tariffs; proposals → PPAs (physical vs virtual);
   books → pools → runs; settlement periods → line items → statements;
   carbon, SAPP and weather objects. *Figure: entity map.*
4. The lifecycle spine: setup → deal → strategy → nomination → market day →
   settlement → statement. *Figure: end-to-end spine — reused as a locator
   ("you are here") at the top of every volume.*
5. Physical vs virtual wheeling — one concept chapter to disambiguate early.
6. The clock: **every configured cron run and trigger**, grouped. Deep dive →
   **V1 · The Four Rhythms**; ops cards → V19 §3.
   *Figure: 24-hour dial + month strip.*
7. How to read this manual: conventions, callouts, badges/icons, follow-along
   demo data, glossary linking.
8. Master glossary (the single source; §7).
9. Cross-border trading (SAPP) — toolkit, 09:30 CAT gate, currency, path.
10. Carbon — RECs, credits, venue, tax. Deep dive → V17 / V18.
11. Weather — forecast / committed / nowcast; 02:00 cycle and intraday drift.

### V1 — The Four Rhythms (~8 chapters)

Settlement chain (gold), strategy loop (purple), market day (blue) and IPP
programme (teal) — step-by-step process, worked examples and the master
timetable. Amalgamates the former V0 §6 / V3 §18 / V19 §3 deep dives.

### V2 — Entities & Setup (~10 chapters)

Signing in (app chooser, seats, sessions) · Organization configuration
(profile, B-BBEE, Eskom/municipal accreditations) · Off-taker sites (wizard,
categories, voltage, tariff preference, map/GPS municipality lookup) ·
Generator/IPP sites (technology, capacities, TOU split, transformer, COD, grid
connection) · Trader pools (rights, treatments, saleable MW/MWh) · Meters &
devices (registry, meter vs check meter, site accounts) · **Readings →
intervals pipeline** (Reading → WheelingConsumption → daily/monthly rollups;
the consumption explorer modal and read-coverage heatmap) · Tariffs &
reference data (tariff anatomy: seasons/TOU/blocks/rates; Eskom TLF/DLF/UoS
lookup tables) · Municipalities & Munix linkage · **Worked example: stand up
one IPP + one off-taker + one trader from a blank org**, mirroring the seeded
cast so every screenshot is reproducible.

### V3 — The Deal Room (~9 chapters)

Deal types & topologies (IO/IT/TO/TT × physical/virtual — *figure: 8-cell
matrix*) · Finding counterparties (market search from the three directories) ·
Proposals (create from search or promoted simulation; terms; the S/B/J/D
party-assignment model; expiry & renewal; PENDING → ACCEPTED/DECLINED/EXPIRED/
WITHDRAWN/SUPERSEDED — *figure: lifecycle rail*) · The negotiation wizards —
all 10 steps, physical then virtual, field by field with real values · Term
deep-dives (tariff & escalation, TOU multipliers, curtailment, spill/excess,
shortfall, banking, RECs/carbon, UoS & loss factors, volume swing/nomination
windows) · Signing (completeness gate, content hash, buyer/seller ceremony)
and activation (the daily `:activate` trigger) · Contracts screen & the
written agreement · **Worked example: IPP→Off-taker physical PPA from search
to ACTIVE, every screen** · **Worked example: a virtual CfD deal**.

### V4 — Settlement (~14 chapters)

What settlement does (periods, intervals, matching, conservation, double
entry) · The five-stage pipeline: Resolve → Match → Price → Adjust → Ledger
(*figure: pipeline spine; then one 20-minute interval traced end-to-end with
numbers*) · Where demand and supply numbers come from (metered → nomination →
contracted → provisional) · Losses & UoS (TLF/DLF, wheeling charges; worked
tables; the sample Eskom bill) · Shared meters (allocation sets, multi-buyer/
multi-seller splits, claim sets, cross-contract no-double-sell) · The
hierarchy waterfall inside settlement (bridge to V6) · Pricing & adjustments
(TOU, escalation, floors/caps; spill, shortfall, curtailment credits, banking
FIFO) · The ledger and Σ = 0 (*figure: ledger table with balancing entries*) ·
Statements (per-party filtered views, versioning, immutability, content hash)
· Chain reconciliation & trader P&L · Statuses & re-settlement (DRAFT →
PRELIMINARY → FINAL → DISPUTED/REVERSED; idempotent re-runs) · The settlement
UI (`ContractSettlementLive`: stat cards, three charts, ledger, energy
balance) · **Worked month, physical**: one seeded PPA settled end-to-end
· **Worked month, virtual**: CfD variants
(WER / no-WER / nomination-based).

### V5 — Strategy (retrofit)

The existing 24-chapter manual, source-recovered and integrated: hub links,
glossary merged into the master, spine locator added, stale references
refreshed. **Decision D4 (§11)**: its BRP chapters (15–18) move to V7 with
redirect stubs, leaving V5 purely book-level strategy.

### V6 — IPP Allocation, Forecast & HAF (retrofit)

The existing 9-chapter manual, same retrofit treatment. Gains cross-links into
V4 (settlement trace) and V3 (contracting guard) instead of restating them.

### V7 — Market Operations (~11 chapters)

SAWEM primer (BRP model, gates, D−1 rhythm) · Registration & compliance ·
The Bid Desk (net position, per-hour ladder, provenance, clip strip, DRAFT →
SUBMITTED — *worked bid day with numbers*) · Intraday & the IDM monitor ·
Imbalance (actual − scheduled, pricing, attribution drawer — *worked day*) ·
SO instructions (dispatch/curtailment/outage; acknowledging; effect on books)
· Reconciliation & disputes (MO settlement files, matching, dispute kanban) ·
Notices & market-rules versions · **Worked cycle: one delivery day across
BRP → MO → SO screens** (from `docs/references/market/brp/daily_trade.md`, re-verified
against code). MO / SO operator consoles now live in V9 / V10.

### V8 — Organization Market Bidding

How an organisation deals with the Market Operator and System Operator.
Five sidebar rooms: Market (complete — every tab, card, table, button),
Bid Desk / Market Month / Accounts written field-by-field; Billing
mapped tab by tab. Arithmetic for bids and imbalance remains V7;
billing documents remain V13.

### V9 — Market Operator

DAM / IDM handbook from the Market Operator's chair (`market-dam.md`
§§1–11): one picture, seats, the clock, intake, the bid field-by-field,
prices, chalkboard, till, IDM. Then the current `/mo` console (moved
from former V7 §10): sidebar map (§12) and one chapter per room
(§13–§26).

### V10 — Systems Operator

What the System Operator is · Network zones (from former V7 §2) ·
Notices and SO instructions (from former V7 §7) · The SO console
(from former V7 §11).

### V11 — Market API

Every `/api/v1` and `/internal` operation from the live OpenAPI.

### V12 — Scenario Lab

`/org/sim` (dev/demo only): purpose, the three seeded scenarios, every
editor panel, Runs / Compare / day log / Teardown, the driver walk, and a
clone-and-run worked example.

### V13 — Billing

Reserved. Invoices, billing cycles, and charge statements.

### V14 — Analytics

Reserved. Dashboards, reports, and analytical views.

### V19 — Operations & Administration (~7 chapters)

The Eskom app (tariffs, charges, rates, loss factors) · The Munix app ·
**The background-process catalog** — every Oban cron entry, AshOban trigger,
GenServer and mix task: what it does, when it runs, what to watch, failure
modes (*figures: 24-hour dial, month strip, per-worker cards*) · Demo &
acceptance data — consolidated setup for operators (profiles, stages S00–S15,
copy-paste procedures, recovery) · Scenario Lab pointer to
V12 · Live simulation mode (S15 live meters) · Troubleshooting & FAQ.

### V20 — TODOs

Open documentation work, one chapter per owning product volume (V0–V19).

---

## 5. Visualization strategy — the figure library

All figures are **hand-crafted CSS/inline-SVG in the house style** — no
charting libraries, no Mermaid at runtime, no screenshots as primary figures
(they rot; see EVOLUTION §8). M0 consolidates the six existing figure families
plus the new ones below into `manual.css`, with a copy-paste catalog page
(`STYLE.md` appendix) so every author reuses rather than reinvents:

| Family | Use | Status |
| --- | --- | --- |
| `allocation-diagram` | supply→demand splits, segmented bars | exists |
| `priority-prorata-diagram` | tiered fills before pro-rata splits | exists |
| `rule-example-diagram` | time-lane scenario flows | exists |
| `pricing-flow` | flow + money-ledger strips | exists |
| `run-chart-example` | inline SVG mini charts (stacks, SoC, spill) | exists |
| `tab-sample` | annotated screen replicas with numbered callouts | exists |
| `entity-map` | object-model card diagrams with relationship arrows | **new (M0)** |
| `lifecycle-rail` | state machines (proposal, PPA, settlement, nomination, dispute) | **new (M0)** |
| `pipeline-spine` | staged pipelines & the end-to-end locator strip | **new (M0)** |
| `ledger-table` | double-entry tables with Σ = 0 footer proof | **new (M0)** |
| `clock-dial` | 24-h cron dial + month-of-jobs strip | **new (M0)** |
| `topology-map` | wheeling paths across Eskom/munix voltage tiers | **new (M0)** |

Rules: every figure has a `figcaption`, works at 680 px and in print, uses the
palette tokens from the CSS `:root`, and states the data it was drawn from.

---

## 6. Data-driven examples — one canonical dataset

Every worked example is anchored to the **consolidated setup** dataset:
`mix wb.setup --profile full_demo` (deterministic, default seed 42, stages
S00–S14).

- **Provenance stamp**: each example opens with a one-line stamp — profile,
  stage that seeded the data (e.g. S09 settlement matrix), seat to log in as,
  and click path. Numbers in the prose must be re-derivable from that dataset.
- **The narrative thread**: one seeded IPP → trader → off-taker chain is
  followed across volumes — set up in V2, contracted in V3, planned in V5,
  allocated/forecast in V6, taken to market in V7, settled in V4 — so a reader
  can trace a single kWh and a single rand end to end. Each volume's flagship
  example is a chapter of that thread.
- **Follow-along callouts**: the exemplars' demo-walkthrough pattern
  (blockquote: seat, path, what you should see) is used per-chapter rather
  than only as a closing chapter.
- **Conservation proofs**: wherever energy or money is split, show the Σ check
  exactly as the IPP manual does.

---

## 7. Glossary & cross-referencing

- **One source of truth**: `GLOSSARY.md` — a table of `term · definition ·
  taught-in links`, merged at M1 from the two existing manuals' glossaries and
  grown by every milestone (a milestone gate item: new terms landed).
- The build inlines the glossary into the hub; each volume's build appends a
  "Terms used in this volume" index that links into the hub glossary.
- **Forward references**: first use of a term in each chapter links to its
  glossary anchor. **Back references**: each glossary entry ends with
  "Explained in → V4 §2.1" links.
- Anchor stability: heading-derived Pandoc ids; published chapter numbers are
  never reused (EVOLUTION §7).

---

## 8. The coverage contract — `COVERAGE.md`

Mirrors the consolidated setup's coverage catalog. Four living matrices,
initialised at M0 from the router, component tree and Oban config, each row
mapping to manual sections:

1. **Routes/LiveViews** (~44 LiveViews across `/`, `/org/**`, `/eskom/**`,
   `/munix/**`, `/mo`, `/so`, `/org/sim`) → volume §.
2. **Stateful components** (~21: wizards, detail modals, consumption explorer,
   signing, settlements modal…) → volume §.
3. **Background processes** — 15 Oban cron workers, non-cron workers
   (`StatementRunner`, `ForecastRunner`, `RunAllocation`, `IngestReadingWorker`,
   `BackfillMeterHistory`), 2 AshOban triggers (`PhysicalPpa :activate`,
   `Proposal :expire_stale`), GenServers (`Sim.LiveMeter.Simulator`,
   `Sim.Driver`), mix tasks (`wb.setup`, `wb.forecast_backfill`,
   `wb.replay_hierarchy_diff`) → V19 §3 plus the volume that owns the feature.
4. **Seats** (8) → recommended reading path on the hub.

A row may be marked `n/a` (dev-only routes) with a reason. M8's gate is
100 % of rows resolved.

---

## 9. Toolchain & repository layout

Pandoc (≥ 3.x, already the generator of both exemplars), framework-free HTML,
one command build. **Never edit built HTML** — the build stamps a
`<!-- GENERATED — edit docs/user-manual/src/ -->` banner.

```
docs/user-manual/
  PLAN.md  EVOLUTION.md  STYLE.md  COVERAGE.md  GLOSSARY.md  CHANGELOG.md
  build.sh                  # builds hub + all volumes; --volume vN for one
  manual.css                # grown from USER-MANUAL.css + figure families
  assets/                   # webill logo, shared images
  src/
    index.md                # hub
    v0-orientation/ 01-*.md …      # one file per chapter, numeric prefix
    v1-rhythms/ · v2-entities/ … v13-todos/
  index.html  v0-orientation.html … v20-todos.html   # committed artifacts
```

Committed artifacts keep the "attach/print/email" property of the exemplars.
`build.sh` also runs an internal link/anchor check (grep-based; no runtime
deps). After M5, `docs/user-manual/USER-MANUAL.html` and the old IPP manual
become meta-refresh redirect stubs to `v4`/`v5` (decision D3, §11).

---

## 10. Source-material map (corpus → chapters)

| Existing doc | Feeds | Caution |
| --- | --- | --- |
| `references/tariffs/wheeling_uos_lf.xlsx` | V2 §8, V4 §4 | — |
| `contract/physical/{IO,IT,TO,TT}/*.md`, `*party_assignment*.md`, `contract/virtual/*.md`, `additions/volume_swing_nomination.md` | V5 §§3–5 | — |
| `references/templates/written_contract*.md` | V5 §7 | check build state |
| `spot/brp/daily_trade.md`, `brp_mo_so.md`, `mo/so data catalogs` | V7 | `spot/spot_mo.md` **superseded** — do not use |
| `references/entities/munix.xlsx` | (background only) | municipality boundaries |

---

## 11. Decisions

| # | Decision | Rationale / alternative |
| --- | --- | --- |
| D1 | Author in Markdown, build with Pandoc, commit both source and HTML | fixes the no-source defect; keeps travel-well single pages. Alt (mdBook/ExDoc site) deferred — EVOLUTION §12 |
| D2 | Hub + 8 single-page volumes, not one mega-page | 369 KB (Strategy) is already at the ceiling; whole system would be ~5× |
| D3 | After retrofit, legacy manual paths become redirect stubs | preserves bookmarks; single publish location. Alt: rebuild in place — rejected, splits the toolchain |
| D4 | BRP chapters move from V4 to V7 | one home per topic; trader manual keeps a short bridge + links |
| D5 | Figures are CSS/SVG, screenshots secondary | exemplars' pattern; survives restyles; print-safe |
| D6 | Examples bind to `full_demo` seed-42 dataset only | reproducibility; the setup programme already guarantees determinism |
| D7 | Milestone files follow the IPP programme shape (Objective / Scope In-Out / Tasks / Verification Gate) | proven house pattern; gates keep "comprehensive" honest |

## 12. Risks & mitigations

| Risk | Mitigation |
| --- | --- |
| Docs drift as code moves | change-map + coverage gate (EVOLUTION §§2–3); verified-against stamps per chapter |
| Worked-example numbers go stale | provenance stamps + deterministic seed; re-derive on setup changes (EVOLUTION §4) |
| Writing volume (~150–200 k words incl. retrofits) | milestone pacing; per-volume gates; source-material map front-loads content |
| HTML edited directly again | generated banner + EVOLUTION rule §1; build overwrites |
| Duplication between V4/V5/V6 and V4 | D4 extraction; "one home per topic, bridges elsewhere" rule in STYLE.md |
| Dev design docs taken as truth | every adapted claim re-verified against code/tests; stale list in §10 |

## 13. Milestones

| # | Milestone | Delivers | Depends on |
| --- | --- | --- | --- |
| M0 | Toolchain, style & coverage foundations | build.sh, manual.css + figure library, STYLE.md, COVERAGE.md, hub skeleton, logo fix | — |
| M1 | V0 Orientation & master glossary | v0-orientation.html, GLOSSARY.md bootstrap | M0 |
| M2 | V2 Entities & Setup | v2-entities.html | M1 |
| M3 | V5 The Deal Room | v5-deals.html | M2 |
| M4 | V6 Settlement | v6-settlement.html | M3 |
| M5 | Retrofit: Strategy & IPP volumes | v4/v5 sources + HTML, redirect stubs, BRP extraction prep | M0 |
| M6 | V7 Market Operations | v7-market.html (incl. moved BRP chapters) | M1 + M5 |
| M7 | V19 Operations & Administration (shipped as V8, then V9, then V12, then V13) | v19-operations.html, background-process catalog | M1 |
| M8 | Cross-reference, coverage & hardening | 100 % coverage, glossary/link audits, print pass, publish | all |

Sequencing: M1→M4 are the narrative chain; M5 and M7 parallelise after their
dependencies; M6 needs M5's extraction. M8 is the programme gate.

## 14. Acceptance criteria (programme gate = M8 gate)

- `./build.sh` from a clean checkout produces hub + 14 volumes, zero broken
  internal links/anchors, zero missing assets.
- `COVERAGE.md`: 100 % of routes, components, and background processes mapped
  (or reasoned `n/a`).
- Glossary: no term used-but-undefined; no orphan definitions; all
  back-references resolve.
- Every worked example carries a provenance stamp and at least one per volume
  has been re-derived against a fresh `full_demo` run.
- Legacy manual URLs redirect; hub footer carries version + verified-against
  commit stamps.
- An end-to-end read of the narrative thread (V1→V3→V5→V6→V7→V4) by someone
  who did not write it, with findings triaged to zero blockers.