# Cartography Reference — Mode 4 spine (Information Architecture · UX Flows · Feature Coverage) The reference root for **Cartography** (`discover` harness, **Mode 4**). After Evaluation (Mode 3) reconciles the dimensions into the four rollups, Cartography makes the product **legible as a product**: it **re-enters the live product** (read-only nav) and compiles three experiential artifacts the dimension collectors structurally miss, then runs a **coverage gate** that reconciles every _marketed / documented_ feature against **where it actually lives in the product** and **whether the run walked it**. The blind spot it closes: a feature **hyped on the website but buried three levels deep** in the product — or marketed but **absent from this edition entirely**. Ingestion captures the _raw_ feature lists (`website`, `docs`, `community`) and the _entity spine + wire_ (`session`); none of those locate a feature in the nav, measure its depth, draw its journey, or save a screenshot. > **Why a distinct mode, not a phase of Evaluation.** Evaluation is **desk reconciliation** of > already-captured material. Cartography **re-enters the live product** to walk surfaces, measure nav > depth, and capture screenshots — work that needs the **browser singleton** (ingestion §7 rule 9) and > a marketed-feature checklist to drive it. It runs **after** Evaluation (so the entity spine + > claimed-feature catalog exist) and **before** Self-correction (Mode 5), so the **coverage scorecard** > it emits feeds the score and the within-run re-walk. --- ## The Cartography family (this spine + three artifact references) This file is the **spine** — the inputs, the orchestration, the scorecard handoff, the ethics, the degraded modes. Each of the three artifacts has its own focused reference; **read the matching one when building that artifact**: | Artifact (output) | Governing reference | One-line | | --- | --- | --- | | `evaluation/information-architecture.md` | [`cartography-ia.md`](cartography-ia.md) | nav tree + per-surface cards, tagged with **depth** + **promoted\|buried** | | `evaluation/ux-flows.md` | [`cartography-flows.md`](cartography-flows.md) | primary journeys as mermaid sequence diagrams, traced from the **observed wire** | | `evaluation/feature-coverage.md` + `dimensions/session/captures/screens/` | [`cartography-coverage.md`](cartography-coverage.md) | the **claimed-vs-located-vs-walked** matrix + the **coverage scorecard** + the screenshots | > **Degraded modes are recorded, never faked.** When `auth` is `none` / there is **no authenticated app > surface**, Cartography maps only the **public** surfaces (marketing IA + docs IA + the unauth app > shell from `deployed-client-bundle`) and records the authed-surface gap in the scorecard. When the > live runtime can't be screenshotted (no image tool, or the app never reaches page-idle because of a > persistent connection — ingestion §9.5), the **textual surface-map is the accepted fallback** and the > `screenshot_coverage` gap is recorded. Cartography never fabricates an IA it could not navigate. --- ## Inputs (read these first) - `evaluation/product-features.md` + `dimensions/website/raw/features.md` + `dimensions/docs/raw/*` — the **claimed feature catalog**: the checklist Cartography must locate. (Community/changelog feature claims fold in too.) → drives `cartography-coverage.md`. - `evaluation/data-model-api-surface.md` + `dimensions/session/raw/*` — the **entity spine** + the observed endpoints, so each surface card names the entities + wire calls it touches → drives `cartography-ia.md`; the captured wires (`raw/write-flow.md`, `raw/*-wire.md`, the auth fingerprint) are the source for `cartography-flows.md`. - `dimensions/session/captures/surface-map.md` + `dimensions/deployed-client-bundle/raw/route-table.md` — the **route / nav inventory** to walk (the coverage checklist of surfaces, ingestion §9.4). - `dimensions/session/_summary.md` `write_side_observed` / `pass2` flags — gate whether a write/generate flow can be diagrammed from **observation** or must be marked **inferred** (ingestion §9.2; `cartography-flows.md`). --- ## The coverage scorecard (the machine-readable handoff to Mode 5) The single load-bearing output of Cartography for the self-correcting loop. It is produced as the frontmatter of `feature-coverage.md` (schema + scoring in `cartography-coverage.md`) and read by **Self-correction (Mode 5)** two ways: 1. **Scores the experiential / IA coverage axis** (the heavily-weighted rubric axis) from `feature_location_rate`, `flow_coverage`, `screenshot_coverage`, `ia_nav_complete`. 2. **Drives the within-run re-walk** from the `located-but-not-walked` queue: Mode 5 re-enters the live product (read-only nav), walks the not-yet-walked surfaces, captures the missed screenshots, and locates any _deeper-than-looked_ marketed feature — then re-runs Mode 4 and re-scores. A `claimed-but-not-located` feature is **never silently dropped** — it is always dispositioned (_deeper-than-looked_ → the re-walk queue · _edition/plan-gated_ and _roadmap-not-shipped_ → a recorded gap, not re-walked · _marketing over-claim_ → an `evaluation/product-features.md` over-claim flag). --- ## How Mode 4 is driven By the **main session** — it owns the browser singleton (ingestion §7 rule 9), and Cartography re-enters the live product. Steps: 1. Read the inputs (the claimed-feature catalog, the entity spine, the route/nav inventory). 2. **Walk the live product read-only**, section by section, via in-app nav (never a full reload mid-walk, ingestion §9.4). Per surface: record depth + capability + route + the endpoints it fires + capture a screenshot. _(method per `cartography-ia.md`)_ 3. Compile `information-architecture.md` (`cartography-ia.md`). 4. Turn the captured `session` wires into the `ux-flows.md` sequence diagrams (`cartography-flows.md`). 5. Build the `feature-coverage.md` matrix + emit the **coverage scorecard** (`cartography-coverage.md`). The main session **MAY dispatch sub-agents** (`model: opus`) to _draft_ the three docs from already-captured material (overlapping reads, independent writes) — but the **live walk + screenshots are main-session only** (browser singleton). **Read-only / no-cost only:** locating a feature never requires triggering it — any write/generate/launch trigger stays behind the Pass-2 confirmation gate (ingestion §7 rule 4, §9.2), never fired to "see" a feature. **Absences are findings, never silent drops** — a claimed-but-not-located feature, an unmapped nav destination, and an undiagrammed primary flow are each recorded, and the scorecard makes the gaps machine-readable for Mode 5. --- ## How the modes use this family Mode 4 reads this spine for the inputs + orchestration + scorecard contract, then the three artifact references for each deliverable's method + template. Mode 5 reads the **scorecard** (here) + the **Cartography defect category** (`self-correction.md` stage A) to score the experiential axis and drive the within-run re-walk. Evaluation's rollups are Cartography's inputs (`evaluation.md`); Cartography's screenshots complete the session playbook's surface-map (ingestion §9.5).