@nurix/etna 0.18.1 → 0.18.3

package/data/harness-index.json

@@ -1,12 +1,8 @@
 {
-    "fingerprint": "5749d4f02de6",
+    "fingerprint": "4bbc31742cc4",
     "harnesses": {
         "code": {
-            "plugin": "code-fable",
-            "description": "Nurix code-project harness"
-        },
-        "code-fable": {
-            "plugin": "code-fable",
+            "plugin": "code",
             "description": "Nurix code-project harness"
         },
         "discover": {

package/data/harnesses/code/CLAUDE.md

@@ -36,7 +36,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 | **Spec** | new feature work | `spec-mode` agent + `documentation` skill | Plan |
 | **Plan** | a spec is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
 
-On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `Status: Active`, extending it with how-it-works sections; then distil the plan's trail — if the memory inbox (`docs/memory/inbox/`) holds entries, run `distiller facts` (inbox→fact-cards), then `distiller docs` for the just-completed feature's doc drafts any pending deltas for approval (presented, never auto-written). The `boundary` skill gates every approved plan before coding — it reads the source the plan touches and reports what would break (see **Boundaries** below); on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine + contract changes → `docs/architecture/` / ADRs, backlog → `docs/history/`. Open questions block close.
+On **Completion**: freeze the plan (`Status: Complete`) and flip the feature spec to `Status: Active`, extending it with how-it-works sections; then distil the plan's trail — if the memory inbox (`docs/memory/inbox/`) holds entries, run `distiller facts` (inbox→fact-cards), then `distiller docs` for the just-completed feature's doc drafts any pending deltas for approval (presented, never auto-written). The `boundary` skill gates every approved plan before coding — it reads the source the plan touches and reports what would break (see **Boundaries** below); on brainstorm close, harvest by scope — module pillars → `docs/modules/{m}/pillars/`, cross-module doctrine + contract changes (the deployed-design SOT) → `docs/architecture/` with its decision record → `docs/history/adr/`, backlog → `docs/history/`. Open questions block close.
 
 ---
 

package/data/harnesses/code/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "code",
-  "name": "code-fable",
-  "version": "0.17.0",
+  "name": "code",
+  "version": "0.17.3",
   "epoch": 14,
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "3a6fb5194539"
+  "digest": "0c459bd1301c"
 }

package/data/harnesses/code/rules/nomenclature.md

@@ -28,3 +28,14 @@
 - snake_case : Used in File names, folder names. Examples: `user_service`, `api_utils`, `auth_middleware`, `data_models`
 - UPPER_SNAKE_CASE : Used in Constants, environment variables. Examples: `MAX_RETRY_COUNT`, `API_KEY`, `DEFAULT_TIMEOUT`, `COLOR_PRIMARY`
 - kebab-case : Used in URLs, CSS class names, HTML IDs. Examples: `nav-container`, `user-profile`, `button-primary`, `form-wrapper`
+
+## Database
+
+Naming for D1 tables, columns, indexes, and their Drizzle mirrors. (For column **types** — PK shape, timestamp columns — see the Cloudflare D1 Schema rule, not here; this section governs names only.)
+
+- **Tables** : snake_case. Entity / hub tables use the plural noun for the thing they hold. Examples: `users`, `apps`, `devices`, `services`.
+- **Junction (M:N) tables** : name a many-to-many join `<entityA>_<entityB>_map` — **always**, even when the join carries its own columns (a `role`, a secret, a status). The `_map` suffix is the signal that a row is a relationship, not an entity; extra attributes on the join do **not** earn it a standalone noun. Use the **singular** stem of each side, owning/anchor entity first (mirror the existing tables — `app_*`). Examples: `app_user_map` (apps ⨯ users), `app_device_map` (apps ⨯ devices), `app_service_map` (apps ⨯ services).
+  - ❌ Don't invent a "nice" noun for a junction — no `members`, `installs`, `memberships`, `enrolments`. A reviewer should read the table name and know both sides and that it's a join.
+- **Columns** : snake_case. Foreign keys are `<entity>_id` (`user_id`, `app_id`, `device_id`, `service_id`). Booleans follow the boolean rule (`is_*`/`has_*`); timestamps are `created_at` / `updated_at`.
+- **Indexes** : `<table>_<col(s)>_idx`; unique indexes `<table>_<col(s)>_unique`. The composite unique on a junction reads `<table>_<colA>_<colB>_unique` — e.g. `app_user_map_app_user_unique`, `app_device_map_device_app_unique`.
+- **Drizzle mirror** : the exported table object is the camelCase of the snake_case table name (`app_user_map` → `appUserMap`); column TS properties are the camelCase of the column (`created_at` → `createdAt`, `service_key` → `serviceKey`). The snake_case string passed to `sqliteTable("…")` and every index name must match `seed/init.sql` exactly (the G1 schema-parity boundary).

package/data/harnesses/code/skills/brainstorm/harvest.md

@@ -10,7 +10,7 @@ The harvest is a structured diff between the session pillars and the live docs,
 | --- | --- |
 | `thesis.md` narrative | `docs/history/plans/YYYY-MM-DD-{slug}.md` (Status: Draft, `documentation` skill §8 Plan template) |
 | `domain-model.md` | `docs/architecture/domain-model.md`; if it changes the IA or a cross-cutting contract, note the contract change there — the `boundary` skill will pick it up from source at the next plan check |
-| Decisions spanning 2+ modules | one ADR per cohesive theme → `docs/architecture/adr/ADR-NNN-{slug}.md`, authored to the **`documentation` skill §10 ADR template** (frontmatter `status:` is the lifecycle source of truth — no body Status line; required sections Decision/Context/Consequences); rejected alternatives → the ADR's **Options Considered** table |
+| Decisions spanning 2+ modules | one ADR per cohesive theme → `docs/history/adr/ADR-NNN-{slug}.md` (a historical decision record, not the deployed-design SOT in `docs/architecture/`), authored to the **`documentation` skill §10 ADR template** (frontmatter `status:` is the lifecycle source of truth — no body Status line; required sections Decision/Context/Consequences); rejected alternatives → the ADR's **Options Considered** table |
 | Module-local decisions / doctrine / glossary / rejected | `docs/modules/{m}/pillars/{decisions,doctrine,glossary,rejected}.md` |
 | Cross-module doctrine / glossary | `docs/architecture/domain-model.md` / `docs/architecture/glossary.md` |
 | `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |

package/data/harnesses/code/skills/documentation/SKILL.md

@@ -11,6 +11,8 @@ Document contracts and architecture, not implementation details. Show function s
 
 **No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (routing, memory files, frontmatter `depends_on`, cross-doc links) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
 
+**Present tense, current state only.** Active docs (everything outside `docs/history/`) describe the system _as it is now_ — what exists and how it works today. They never narrate how it got there: no migration/fold history, no dated "shipped/verified/built on YYYY-MM-DD" markers, no "ex-`@nurix/X`, folded 2026-06-12" provenance, no "was X → now Y" change journeys, no "removed/deleted in the <date> fold". The historical record — when and how things changed — lives **only** in `docs/history/` (changelog, plans, ADRs); `docs/memory/` is the agent's dated log and is likewise exempt. A doc may cite an ADR for the _why_ (the decision rationale), but must not narrate the _when/how it changed_. Routing/index docs point only to current authority docs — never to a historical plan or changelog as the "read first" source. When you find historical narration in an active doc, rewrite it to the present-tense fact and let `docs/history/` carry the story.
+
 ---
 
 ## Decision Tree

package/data/harnesses/code/skills/documentation/references/style-guide.md

@@ -220,6 +220,29 @@ Use for structured info:
 
 ---
 
+## Tense & History
+
+**Active docs describe the present, not the past.** Everything outside `docs/history/` states what the system _is_ and how it works _today_. It must not narrate how it got there. The historical record — the journey, the dates, the migrations — lives **only** in `docs/history/` (changelog, plans, ADRs). (`docs/memory/` is the agent's own dated log and is likewise exempt from this rule.)
+
+Strip this language from active docs:
+
+| ❌ Historical narration (belongs in `docs/history/`) | ✅ Present-tense fact (belongs in the active doc) |
+| --- | --- |
+| "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." |
+| "Built 2026-06-14; shipped + verified 2026-06-13." | "`agentSessionWorkflow` runs an outer turn loop over `runAgentLoop`." |
+| "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets `WorkflowDefinition`." |
+| "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "MCP client runtime, wired into `agentTriggerWorkflow`." |
+| "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/<current-SOT>.md`" |
+
+Rules:
+
+- **No dates in active docs** for when something shipped, was verified, folded, or was removed. A bare status marker (`✅ shipped`, `⏳ pending`) is fine; the _date_ it shipped is not.
+- **Cite the ADR for the _why_, never the _when_.** `Provenance: ADR-002` is good (it points to the decision rationale). "Decided in ADR-002 and shipped 2026-06-13" is not.
+- **Routing/index docs point only to current authority docs.** A row whose only "read first" target is a historical plan or changelog is a redirect-for-history — repoint it to the current SOT doc, or drop the row.
+- **When a doc changes because the system changed, the change-story goes in `docs/history/` (a changelog entry), and the active doc simply becomes correct in present tense.** Never leave the diff narrated in place.
+
+---
+
 ## Structure
 
 ### Headers

package/data/harnesses/code/skills/documentation/references/templates.md

@@ -600,7 +600,7 @@ path/to/another/file.js
 
 ## 9. Architecture Decision Record (ADR)
 
-Use for: capturing a single, point-in-time architectural decision with its context, alternatives considered, and consequences. Lives in `docs/architecture/adr/`.
+Use for: capturing a single, point-in-time architectural decision with its context, alternatives considered, and consequences. Lives in `docs/history/adr/` — an ADR is a **historical decision record**, not the deployed-design source of truth (which lives in `docs/architecture/`). When the design later changes, update `docs/architecture/` and write a new superseding ADR; never rewrite a shipped ADR.
 
 ### When to write an ADR
 

package/data/harnesses/discover/CLAUDE.md

@@ -1,8 +1,8 @@
 # Discover Harness — Orchestrator
 
-This is the **policy** half of the `discover` harness. The plugin ships the capabilities (11 dimension-collector agents + 4 mode rules + a `tradecraft` keyboard reference); this file drives them. Together they discover a product across every surface it exposes and assemble a structured, provenance-tracked corpus in the resolved corpus root (default `research/<target>/`).
+This is the **policy** half of the `discover` harness. The plugin ships the capabilities (11 dimension-collector agents + 5 mode rules + a `tradecraft` keyboard reference); this file drives them. Together they discover a product across every surface it exposes and assemble a structured, provenance-tracked corpus in the resolved corpus root (default `research/<target>/`).
 
-A run is four modes, in order: **Discovery → Ingestion → Evaluation → Self-correction.** The main session drives all four — Ingestion and Evaluation fan out parallel sub-agents (dispatch each via the Agent/Task tool with `model: opus`), and a sub-agent cannot spawn further sub-agents.
+A run is five modes, in order: **Discovery → Ingestion → Evaluation → Cartography → Self-correction.** The main session drives all five — Ingestion and Evaluation fan out parallel sub-agents (dispatch each via the Agent/Task tool with `model: opus`); Cartography re-enters the live product (the browser singleton) to walk + screenshot it and may fan out doc-drafting sub-agents; a sub-agent cannot spawn further sub-agents.
 
 ---
 
@@ -70,15 +70,28 @@ Reconcile the collected dimensions into four cross-dimension rollups under `rese
 
 ---
 
-## Mode 4 — Self-correction (the run corrects itself; the harness improves only on approval)
+## Mode 4 — Product Cartography & Coverage
 
-Mode 4 is a loop, not a one-shot. Follow `.claude/rules/self-correction.md` — it carries the **defect checklist** (A), the **measurement rubric** (B), and the **iterate-or-propose loop** (C). Three stages, driven by the **main session** (not a sub-agent):
+Make the product **legible as a product**. After Evaluation reconciles the dimensions, Cartography **re-enters the live product** (read-only nav, the browser singleton) and compiles the navigable **information architecture**, the primary **UX flows**, a **screenshot surface map**, and a **feature-coverage gate** — reconciling every _marketed / documented_ feature against **where it actually lives in the product** and **whether the run walked it**. This catches the blind spot the dimension collectors structurally miss: a feature **hyped on the website but buried three levels deep** — or marketed but **absent from this edition**. Follow `.claude/rules/cartography.md` (the spine: inputs · scorecard · orchestration · ethics), which routes to three artifact references — `cartography-ia.md` · `cartography-flows.md` · `cartography-coverage.md`. Four artifacts:
 
-1. **Inspect** the finished run (scope verdict, plan, every dimension `_summary.md`, the rollups) against the **built-in defect checklist** → a concrete list of _behavioral defects_ in the prior steps (mode · defect · severity · evidence anchor · within-run|harness-changing).
-2. **Measure** the run against the **rubric** → a `/100` score + vibe band. Always — every iteration, including the final one; the self-correcting step ALWAYS evaluates the current run.
+1. `evaluation/information-architecture.md` — nav tree + per-surface cards, each tagged with **depth** (D0 top-level … D3+ sub-panel) and **promoted | buried**.
+2. `evaluation/ux-flows.md` — the primary journeys as mermaid sequence diagrams, traced from the **observed `session` wire** (not source). A write/generate flow on a `write_side_observed: false` run is diagrammed **as inferred**, never observed.
+3. `evaluation/feature-coverage.md` — the **claimed-vs-located-vs-walked** matrix + the machine-readable **coverage scorecard** (`feature_location_rate`, `flow_coverage`, `screenshot_coverage`, `ia_nav_complete`) that Mode 5 scores against. A `claimed-but-not-located` feature is **never dropped** — it is dispositioned (deeper-than-looked → re-walk queue · edition/roadmap-gated → recorded gap · over-claim → an evaluation flag).
+4. `dimensions/session/captures/screens/` — one **redacted** screenshot per primary surface (+ `_index.md`); the textual surface-map is the fallback only when the runtime can't screenshot.
+
+Main-session-driven (it owns the browser); it **may** dispatch sub-agents (`model: opus`) to draft the three docs from captured material, but the **live walk + screenshots are main-session**. **Read-only / no-cost only** — locating a feature never triggers it; any write/generate stays behind the Pass-2 gate.
+
+---
+
+## Mode 5 — Self-correction (the run corrects itself; the harness improves only on approval)
+
+Mode 5 is a loop, not a one-shot. Follow `.claude/rules/self-correction.md` — it carries the **defect checklist** (A), the **measurement rubric** (B), and the **iterate-or-propose loop** (C). Three stages, driven by the **main session** (not a sub-agent):
+
+1. **Inspect** the finished run (scope verdict, plan, every dimension `_summary.md`, the rollups, **the Cartography IA / UX-flows / feature-coverage docs**) against the **built-in defect checklist** → a concrete list of _behavioral defects_ in the prior steps (mode · defect · severity · evidence anchor · within-run|harness-changing).
+2. **Measure** the run against the **rubric** → a `/100` score + vibe band — including the heavily-weighted **experiential / IA coverage** axis fed by the Cartography scorecard. Always — every iteration, including the final one; the self-correcting step ALWAYS evaluates the current run.
 3. **Iterate-or-propose**, splitting each defect by one test — _does the fix require editing a rule or an agent?_
-   - **No → within-run:** the main session **auto-iterates** (no approval), re-running the cheapest affected Mode 1–3 steps on THIS target and re-measuring each round. The loop is **capable of ≥5 iterations** and **stops on regression** (a clear score drop → revert to the best prior run), **convergence** (no within-run defects left), or the cap. **Read-only / no-cost only** — any fix needing a Pass-2 / credit-spend / state-change / credential action goes through the explicit-confirmation gate, never the auto-loop.
-   - **Yes → harness-changing:** accumulate into `research/<target>/04-self-correction-proposal.md` (the shape is in `self-correction.md`: run measurement · iteration ledger · defect list · within-run fixes applied · the approval-gated harness-change table).
+   - **No → within-run:** the main session **auto-iterates** (no approval), re-running the cheapest affected Mode 1–4 steps on THIS target and re-measuring each round — including **re-entering the live product (read-only nav) to walk the `located-but-not-walked` queue** and capture missed screenshots. The loop is **capable of ≥5 iterations** and **stops on regression** (a clear score drop → revert to the best prior run), **convergence** (no within-run defects left), or the cap. **Read-only / no-cost only** — any fix needing a Pass-2 / credit-spend / state-change / credential action goes through the explicit-confirmation gate, never the auto-loop.
+   - **Yes → harness-changing:** accumulate into `research/<target>/05-self-correction-proposal.md` (the shape is in `self-correction.md`: run measurement · iteration ledger · defect list · within-run fixes applied · the approval-gated harness-change table).
 
 **Approval gate (unchanged):** present the harness-change table + the iteration ledger and STOP — nothing in the harness is applied. The user accepts / rejects / defers per item. Then the **main session** (not a sub-agent) applies accepted items, flips each row to APPLIED, and logs the change. Promote only what the _next, different_ target would also hit; prefer additive edits; structural edits are flagged, never auto-applied. (For a batch, additionally roll up into a cross-target synthesis that promotes only patterns ≥2 _independent_ targets hit — a homogeneous batch's 6/6 is one vote, not six.)
 
@@ -104,9 +117,11 @@ Output lives under the **resolved corpus root** (default `research/`; chosen per
 ├── 00-scope-verdict.md            ← Discovery: accept/narrow/redirect/refuse
 ├── 00-recon-plan.md               ← Discovery: access_grade + scope + dimension plan
 ├── dimensions/<dim>/{_summary.md, raw/}   ← Ingestion (session & wire-capture also: captures/, curls.md)
-├── evaluation/{technology-architecture, product-features, data-model-api-surface, competitive-positioning}.md
+├── dimensions/session/captures/screens/   ← Cartography: redacted per-surface screenshots (+ _index.md)
+├── evaluation/{technology-architecture, product-features, data-model-api-surface, competitive-positioning}.md   ← Evaluation
+├── evaluation/{information-architecture, ux-flows, feature-coverage}.md   ← Cartography (Mode 4)
 ├── README.md                      ← Evaluation: run story + headline findings
-└── 04-self-correction-proposal.md ← Self-correction: proposed harness fixes (approval-gated)
+└── 05-self-correction-proposal.md ← Self-correction (Mode 5): proposed harness fixes (approval-gated)
 ```
 
 Cloned repos live in `source/<target>/`. Provenance is the "self-aware" layer: each collector records _how_ it was obtained; Evaluation weights claims by it. Detailed shapes live in the rules.

package/data/harnesses/discover/harness.json

@@ -1,12 +1,12 @@
 {
   "harness": "discover",
   "name": "discover",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "epoch": null,
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "ee7d550283ae"
+  "digest": "0f1520e846ae"
 }

package/data/harnesses/discover/rules/cartography-coverage.md

@@ -0,0 +1,94 @@
+# Cartography — Feature Coverage + Screenshots reference (Mode 4, artifact 3 of 3)
+
+The method + template for `evaluation/feature-coverage.md` (the **coverage gate**) and the screenshot
+contract for `dimensions/session/captures/screens/`. Spine in [`cartography.md`](cartography.md);
+siblings [`cartography-ia.md`](cartography-ia.md), [`cartography-flows.md`](cartography-flows.md).
+
+This is the reconciliation the dimension collectors don't do: take **every** feature the product
+_claims_ (website + docs + community/changelog), locate it in the actual product by **route + depth**
+(from `information-architecture.md`), and record whether the run **walked** it. It turns "we clipped the
+feature page" into "we know which features are real, where they live, and which we never actually saw."
+
+---
+
+## Assembling the claimed-feature catalog
+
+The rows of the matrix are the **union** of every feature claim across:
+
+- `dimensions/website/raw/features.md` (+ `editions-pricing.md` for edition-gated features),
+- `dimensions/docs/raw/*` (a documented capability is a claim),
+- `dimensions/community/raw/changelog-digest.md` (a shipped-changelog feature is a claim).
+
+De-duplicate to one row per distinct capability. Each row is then **located** (against the IA surface
+cards) and **walked** (did this run actually navigate/observe it).
+
+## The disposition taxonomy (a `claimed-but-not-located` row is NEVER blank)
+
+Every feature that is claimed but not located **must** be dispositioned into exactly one — each routes
+differently:
+
+| Disposition | Meaning | Routes to |
+| --- | --- | --- |
+| **deeper-than-looked** | it exists in this product; we just didn't navigate deep enough | the **re-walk queue** (Mode 5 walks it read-only) |
+| **edition/plan-gated** | not in this tenant's edition/plan (e.g. a trial) | a recorded gap — **not** re-walked (re-walking can't find what isn't shipped here) |
+| **roadmap-not-shipped** | marketed but not yet a shipped capability | a recorded gap |
+| **marketing over-claim** | the claim overstates what the product does | an `evaluation/product-features.md` **over-claim flag** |
+
+---
+
+## The output template — `evaluation/feature-coverage.md`
+
+```markdown
+# <Target> — Feature Coverage
+---
+coverage_scorecard:
+  features_claimed: <N>            # union of website + docs + changelog feature claims
+  features_located: <N>            # found in the live product (route known)
+  features_walked: <N>             # actually navigated / observed this run
+  feature_location_rate: <0-100>   # located ÷ claimed
+  flow_coverage: <0-100>           # primary journeys diagrammed ÷ journeys identified
+  ia_surfaces_mapped: <N>          # surface cards written in information-architecture.md
+  ia_nav_complete: <true|false>    # every top-level nav destination has a surface card
+  screenshot_coverage: <0-100>     # primary surfaces with a screenshot ÷ all primary surfaces
+---
+## Coverage matrix
+| Feature (claimed) | Source | Located? | Route · depth | Walked? | Edition-gated? | Confidence | Note |
+|---|---|---|---|---|---|---|---|
+| <feature> | website,docs | ✅ | #/…/x · D2 | ❌ not-walked | — | high | promoted on site, 2 levels deep, not exercised this run |
+| <feature> | website(AI) | ⚠ edition? | — | ❌ | maybe-not-in-trial | low | marketed flagship, not located in this tenant |
+## Located-but-not-walked   (the within-run re-walk queue — Mode 5 walks these read-only, no cost)
+## Claimed-but-not-located  (each row dispositioned per the taxonomy above — NEVER left blank)
+## Buried flagships          (marketing-promoted features sitting ≥D3 — the positioning-vs-product gap,
+                             drawn from information-architecture.md's promoted-vs-buried headline)
+## Unmarketed depth          (powerful surfaces the marketing never mentions — the inverse finding)
+```
+
+## How the scorecard is scored (the Mode-5 handoff)
+
+`cartography.md` describes _why_ the scorecard exists; here is _how each field is computed_, so Mode 5's
+experiential / IA coverage axis (`self-correction.md` rubric, axis 2, max 20) is reproducible:
+
+- `feature_location_rate` = `100 × features_located ÷ features_claimed`.
+- `flow_coverage` = `100 × (primary journeys diagrammed in ux-flows.md ÷ journeys identified)`.
+- `screenshot_coverage` = `100 × (primary surfaces with a screenshot ÷ all primary surfaces)`.
+- `ia_nav_complete` = every D0 nav destination has a surface card.
+
+Mode 5 axis 2 = `8 × location_rate/100 + 6 × flow_coverage/100 + 4 × screenshot_coverage/100 + 2 ×
+(ia_nav_complete ? 1 : cards÷destinations)`, **−2** per `claimed-but-not-located` row left
+un-dispositioned. The `located-but-not-walked` list is the re-walk queue Mode 5 iterates.
+
+---
+
+## Screenshots — `dimensions/session/captures/screens/`
+
+One annotated screenshot per **primary** surface (each D0 nav destination + each materially distinct
+detail / editor surface). **Redact visible PII before saving** (user names, emails, customer data,
+partner identifiers). Name `<nn>-<surface>.png`; write a one-line `screens/_index.md` mapping each file
+→ surface → route → depth.
+
+**Screenshots are the Mode-4 deliverable that the session playbook's textual surface-map only
+_substitutes_ for** (ingestion §9.5) — capture them live here; fall back to the textual map (and record
+the `screenshot_coverage` gap) only when the runtime genuinely cannot screenshot (no image tool, or the
+app never reaches page-idle because of a persistent connection). The screenshots live under the
+`session` dimension (it owns the browser captures); `information-architecture.md`'s surface cards
+reference them by path.

package/data/harnesses/discover/rules/cartography-flows.md

@@ -0,0 +1,99 @@
+# Cartography — UX Flows reference (Mode 4, artifact 2 of 3)
+
+The method + template for `evaluation/ux-flows.md`. Spine in [`cartography.md`](cartography.md); siblings
+[`cartography-ia.md`](cartography-ia.md), [`cartography-coverage.md`](cartography-coverage.md).
+
+The UX-flows doc captures the primary end-to-end journeys, each as a **mermaid sequence diagram**. This
+is the **black-box adaptation of a code-level workflow trace**: where a source tracer follows call
+chains, Cartography follows the **observed wire** — trigger (user action) → surface → the actual API
+calls captured in the `session` dimension → state transitions → terminal effect. **Diagram only what was
+observed**; mark any inferred hop explicitly.
+
+---
+
+## Participants (the black-box vocabulary)
+
+Map every actor in a captured flow to one of these participants (keep names identical across all
+diagrams — the same backend is the same participant everywhere):
+
+| Participant | What it is |
+| --- | --- |
+| `User` | the operator taking the action |
+| `SPA` | the client app (browser) |
+| `InternalAPI` | the app-own cookie/token API (the real transport — `/rest`, `/enrich`, `/graphql`, …) |
+| `PublicAPI` | the published developer/partner API — **only if the flow actually used it** |
+| `JobQueue` | an async batch / worker / job system (the work happens off-request) |
+| `Realtime` | a WS / SSE / long-poll channel |
+| `3rdParty` | a named external vendor (AI mesh, payments, CDP, email, telephony) |
+| `Store` | browser storage / client cache (Apollo, Redux-persist, IndexedDB) |
+
+---
+
+## Identifying the flows (from captured wire, not source)
+
+The entry points are the **captured journeys** in the `session` dimension — you already have the wire;
+this turns it into a journey. Per category, look for:
+
+- **Core action** — the primary write: the create / save / submit body + its server resolution
+  (`raw/write-flow.md`).
+- **Auth & session** — login → token/cookie → the authed read; the refresh path (`raw/auth-*.md`).
+- **Realtime** — the WS/SSE/long-poll lifecycle + the event catalog (or the **negative**: "dashboard is
+  REST-only" is a real flow finding, not a miss).
+- **Data pipeline** — import/export, ingest, sync, bulk/mass-action (often an async `JobQueue` flow).
+- **Configuration** — a model/setting change that ripples (e.g. add an attribute → completeness recompute).
+- **AI** — a generate/translate/agent call (`raw/*-wire.md`); note brokered-server-side vs client-direct.
+
+Trace each: trigger → which surface → the observed request(s) → branches (conflict/permission/feature
+flag → `alt`/`opt`) → loops (polling/retry/batch → `loop`) → the terminal effect (a persisted entity, a
+job id, a streamed result). Stop at the terminal write or external response.
+
+## Complexity (sets diagram detail)
+
+- **Steps** (distinct operations): 1–2 simple · 3–5 moderate · 6+ complex.
+- **Participants**: 2 simple · 3–4 moderate · 5+ complex.
+- **Branching** (`alt`/`opt`): 0 linear · 1–2 moderate · 3+ complex.
+- Async (polling / job / child workflow): +1 level.
+
+---
+
+## The output template — `evaluation/ux-flows.md`
+
+````markdown
+# <Target> — UX Flows
+## TL;DR                  (how the product gets work done: sync-REST vs async-job, where realtime lives,
+                           the approval/gate pattern, what's brokered server-side)
+## Flow index             (table: flow · category · trigger · participants · complexity)
+## <Category> flows       (Core action / Auth & session / Realtime / Data pipeline / Configuration / AI —
+                           skip empty categories)
+  ### <Flow name>
+  **Trigger · Surface · Observed?**  (observed-wire | partially-inferred)
+  ```mermaid
+  sequenceDiagram
+      participant User
+      participant SPA
+      participant InternalAPI
+      User->>SPA: <action>
+      SPA->>InternalAPI: <METHOD> <path>
+      InternalAPI-->>SPA: <status + shape>
+      SPA-->>User: <UI effect>
+  ```
+  **Notes:** (server-side resolution · the gate · the async hop · what was inferred vs observed)
+## Cross-dimension reconciliation  (the flow as the app runs it vs as the public API/docs describe it —
+                                    drift is a finding; published = fact, observed-drift = tentative)
+## Open questions
+````
+
+## Diagram rules (from the workflow-mapper discipline)
+
+1. **Arrows:** solid `->>` = request/call · dashed `-->>` = return/response. No dangling calls (every
+   request has a response or a noted fire-and-forget).
+2. **≤7 participants, ≤15 steps** per diagram. Past that, group with `rect` blocks / `Note over`, or
+   split into linked sub-diagrams.
+3. **`alt`** = a real workflow branch (conflict vs success), **`loop`** = poll / retry / batch (label
+   the condition), **`opt`** = a gated step (permission, feature flag) — not generic error handling.
+4. **Labels ≤8 words** — the action, not the implementation detail.
+5. **Consistent participant names** across every diagram.
+6. **The write-side rule (hard):** a flow that touches a **write / generate / launch** path on a
+   `write_side_observed: false` run is diagrammed **as inferred** (dashed arrows, an explicit
+   `Note over … : inferred (Pass-1 only)`), **never as observed** — this mirrors the evaluation
+   write-side cap, and drawing it solid is a Mode-5 Cartography defect.

package/data/harnesses/discover/rules/cartography-ia.md

@@ -0,0 +1,88 @@
+# Cartography — Information Architecture reference (Mode 4, artifact 1 of 3)
+
+The method + template for `evaluation/information-architecture.md`. Spine + inputs + orchestration are
+in [`cartography.md`](cartography.md); the other two artifacts in [`cartography-flows.md`](cartography-flows.md)
+and [`cartography-coverage.md`](cartography-coverage.md).
+
+The IA doc is the map of **how the product is organized for the operator**. Walk the live app
+(read-only, in-app nav — never a full reload mid-walk, ingestion §9.4); for every reachable surface
+record its **depth**, whether it is **promoted** or **buried**, its **operator capability**, its
+**route**, the **wire endpoints** it fires, and the **entities** it touches.
+
+---
+
+## The depth taxonomy (the load-bearing measure)
+
+A capability's _depth_ is the product's implicit priority signal — record it **numerically**:
+
+| Depth | Meaning | Example |
+| --- | --- | --- |
+| **D0** | a top-level nav destination (sidebar / top-bar item) | `Products`, `Settings` |
+| **D1** | a list / index under a D0 destination | the product grid; the attributes list |
+| **D2** | a detail / editor surface, or a tab within it | a product edit form; an attribute's config |
+| **D3+** | a sub-panel, modal, drawer, or nested tab | "Ask AI" panel; a variant-axis editor; a workflow-config sub-tab |
+
+**Promoted** = the capability is a D0/D1 first-class destination. **Buried** = it is only reachable at
+≥D2 (often D3+), behind a detail surface or a menu. Depth is what makes the two reconciliations below
+computable.
+
+---
+
+## The two reconciliations that matter
+
+1. **Positioning-vs-product (the buried flagship).** A feature the **marketing** promotes — a verb on
+   the homepage, a named hero capability — that lives at **≥D3** in the product is a real finding. Name
+   it; it feeds `feature-coverage.md`'s _buried flagships_ section. (A "Workflow engine" splashed on the
+   site but reached only via a product → menu → sub-tab is the canonical case.)
+2. **Unmarketed depth (the inverse).** A deep, powerful surface the marketing **never mentions** (a rich
+   admin/config/automation surface, a governance log, a bulk-action engine) is equally a finding — it
+   feeds `feature-coverage.md`'s _unmarketed depth_ section.
+
+Both are computed by comparing the **walked nav depth** (this doc) against the **claimed feature
+catalog** (`cartography-coverage.md`).
+
+---
+
+## Surface cards (the screen layer that realizes the entity spine)
+
+One card per **primary** surface (each D0 destination + each materially distinct D1 list and D2 detail
+surface). The card is the join between the IA and the data model:
+
+```markdown
+### <Surface name>   [route · depth Dn · promoted | buried]
+- **Capability:** what the operator can do here (read / create / edit / configure / run)
+- **Entities:**   the domain entities it surfaces (link → data-model-api-surface.md)
+- **Endpoints:**  the app-own wire calls it fires (link → _shared/api-path-catalog.md)
+- **Screenshot:** captures/screens/<nn>-<surface>.png   (or: gap — reason)
+```
+
+> **Cross-dimension reconciliation (a route that's in the bundle but not in the nav).** Diff the walked
+> nav against `deployed-client-bundle`'s `route-table.md`: a route present in the bundle but **never
+> reachable in the live nav** is a **dormant / unshipped surface** — a finding, not noise. (On a
+> server-rendered / RSC app, a bundle route count can overstate the client surface — fold that into the
+> note rather than reporting a phantom "unused routes" gap; ingestion §9.4 RSC check.)
+
+---
+
+## The output template — `evaluation/information-architecture.md`
+
+```markdown
+# <Target> — Information Architecture
+## TL;DR              (org-shape in 3–5 sentences: how many top-level destinations, what's promoted vs
+                       folded, the deepest important surface, the biggest positioning-vs-product gap)
+## Nav tree           (the full hierarchy as an indented tree or table: top-level → section → list →
+                       detail → sub-tab; tag each node with depth D0/D1/D2/… and [promoted]/[buried])
+## Surface cards      (one per primary surface — the card shape above)
+## Promoted vs buried  (the headline reconciliation: first-class destinations vs surfaces hidden N
+                        levels deep — name the surprises in BOTH directions: buried flagships AND
+                        unmarketed depth)
+## Admin / settings depth   (the configuration surfaces + how deep they sit)
+## Global affordances  (command palette, global search, create-anywhere, keyboard shortcuts — if present)
+## Cross-dimension reconciliation  (nav-as-walked vs the bundle route-table / docs IA — dormant/unshipped
+                                    routes are findings)
+## Open questions
+```
+
+> The IA doc **feeds** `feature-coverage.md`: every surface card's route + depth is what the coverage
+> matrix's `Located? · Route · depth` columns cite, and the promoted-vs-buried headline is what its
+> _buried flagships_ / _unmarketed depth_ sections draw from. Build the IA doc first, then coverage.

package/data/harnesses/discover/rules/cartography.md

@@ -0,0 +1,109 @@
+# 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).

package/data/harnesses/discover/rules/evaluation.md

@@ -2,6 +2,8 @@
 
 `evaluation` reads every `dimensions/<dim>/_summary.md` (its **provenance frontmatter** + Findings) and reconciles them into **cross-dimension** documents under `research/<target>/evaluation/`. The value is the reconciliation — cross-checking views into one coherent picture, **weighted by how each claim was obtained**, with disagreements flagged.
 
+> This file governs the **four reconciliation rollups** (technology-architecture, product-features, data-model-api-surface, competitive-positioning) + the README. The three **experiential** docs that also live under `evaluation/` — `information-architecture.md`, `ux-flows.md`, `feature-coverage.md` — are produced by **Mode 4 (Cartography)** and governed by `cartography.md`; Evaluation's rollups are their inputs (the entity spine → IA surface cards; the feature map → the coverage matrix), and Cartography's coverage scorecard feeds Mode 5's experiential-coverage axis.
+
 **Three rules for every evaluation doc:**
 
 1. **Anchor + tag every claim** with its dimension _and provenance_: `(api: raw/endpoint-catalog.md · openapi-verbatim · high)`. The method + confidence come verbatim from the source dimension's `_summary.md` frontmatter.
@@ -127,7 +129,7 @@
 
 ## Headline findings (5–10, each anchored+tagged)
 
-## How to navigate (00-scope-verdict.md, 00-recon-plan.md, dimensions/, evaluation/, 04-self-correction-proposal.md)
+## How to navigate (00-scope-verdict.md, 00-recon-plan.md, dimensions/, evaluation/ [4 reconciliation rollups + Cartography's information-architecture / ux-flows / feature-coverage], 05-self-correction-proposal.md)
 
 ## Lessons (candidate methodology learnings → feed self-correction)