@nurix/etna 0.18.0 → 0.18.2

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

@@ -282,7 +282,7 @@ Append entries below, oldest at bottom. Format:
 Memory file initialized during documentation baseline.
 ```
 
-> The per-actor memory **inbox** (`docs/memory/inbox/`) is *not* a baseline scaffold — the `session-reflect` hook creates it mechanically on the first reflected session. See **§11 Memory inbox entry** for its format.
+> The per-actor memory **inbox** (`docs/memory/inbox/`) is _not_ a baseline scaffold — the `session-reflect` hook creates it mechanically on the first reflected session. See **§11 Memory inbox entry** for its format.
 
 ---
 
@@ -295,12 +295,12 @@ The four research-derived sections (**Affected Modules**, **Conventions to Follo
 ```yaml
 ---
 owns:
-  - src/feature-name/**     # projected at Draft, confirmed at Active
+  - src/feature-name/** # projected at Draft, confirmed at Active
 touches:
   - src/shared/state/feature.js
 depends_on:
   - docs/features/related-feature.md
-anchors:                    # optional — see §3 frontmatter reference
+anchors: # optional — see §3 frontmatter reference
   - "qmd query: wire envelope invariants"
 ---
 ```
@@ -428,7 +428,7 @@ model Resource {
 Sections fill in across the feature's lifecycle. No template swap — they accumulate in place.
 
 | When | Sections written | Source |
-|------|------------------|--------|
+| --- | --- | --- |
 | Status: Draft (design) | Goal, Goals & Non-Goals, Background, Approach, Open Questions, Risks | User interview |
 | Status: Draft (research) | Affected Modules, Conventions to Follow, Current Behavior, Ownership Conflicts | spec-mode agent |
 | Status: Draft → Active (implementation lands) | Architecture, Key Functions, State, Redux, Files; frontmatter `owns`/`touches` confirmed against real code | Main agent (from actual code) |
@@ -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
 
@@ -635,11 +635,11 @@ Three sections are required: **Decision**, **Context**, **Consequences**. Everyt
 ```markdown
 ---
 title: "ADR-NNN: Short title in sentence case"
-status: Accepted              # Proposed | Accepted | Deprecated | Superseded by ADR-NNN
+status: Accepted # Proposed | Accepted | Deprecated | Superseded by ADR-NNN
 date: YYYY-MM-DD
 decision-owner: Name
-reviewers: []                 # optional
-supersedes:                   # optional, e.g., ADR-005
+reviewers: [] # optional
+supersedes: # optional, e.g., ADR-005
 tags: [adr]
 ---
 
@@ -656,12 +656,15 @@ tags: [adr]
 ## Consequences
 
 **Positive:**
+
 - [What becomes easier]
 
 **Negative:**
+
 - [What becomes harder, what we accept reluctantly]
 
 **Risks:**
+
 - [Second-order effects you can already see, with mitigations if known]
 
 <!-- Optional sections below. Include only when warranted by the decision's weight. -->
@@ -672,10 +675,10 @@ tags: [adr]
 
 ## Options Considered
 
-| Option | Pros | Cons | Outcome |
-|---|---|---|---|
-| **Option A** | … | … | **CHOSEN** |
-| Option B | … | … | Eliminated — [reason] |
+| Option       | Pros | Cons | Outcome               |
+| ------------ | ---- | ---- | --------------------- |
+| **Option A** | …    | …    | **CHOSEN**            |
+| Option B     | …    | …    | Eliminated — [reason] |
 
 ## Deep Comparison
 
@@ -688,12 +691,12 @@ tags: [adr]
 ## Implementation Plan
 
 | Phase | Scope | Duration |
-|---|---|---|
-| 1 | … | … |
+| ----- | ----- | -------- |
+| 1     | …     | …        |
 
 ## Open Questions
 
-1. **[Question]** — *Default*: [stated default until resolved].
+1. **[Question]** — _Default_: [stated default until resolved].
 
 ## Acknowledgements
 
@@ -757,7 +760,7 @@ Skip any section that doesn't apply. Don't pad to fill the template.
 - **{Family 2}** — {what's in it.}
 - **{Family 3}** — {what's in it.}
 
-The full surface lives in [`{path/to/public-index}`]({path/to/public-index}).   ← optional pointer for libraries
+The full surface lives in [`{path/to/public-index}`]({path/to/public-index}). ← optional pointer for libraries
 
 ## Stack
 
@@ -767,32 +770,21 @@ The full surface lives in [`{path/to/public-index}`]({path/to/public-index}).
 
 ## Getting started
 
-\`\`\`bash
-{pm} install
-{pm} run dev       # what it does (port, URL)
-{pm} run build     # what it does
-{pm} run preview   # what it does (omit if not applicable)
-\`\`\`
+\`\`\`bash {pm} install {pm} run dev # what it does (port, URL) {pm} run build # what it does {pm} run preview # what it does (omit if not applicable) \`\`\`
 
 {Optional one-liner about first-run behavior — e.g., "Dev server lands on /playground."}
 
-## {Runtime entry point}   ← optional; e.g., "The playground", "CLI", "API endpoints"
+## {Runtime entry point} ← optional; e.g., "The playground", "CLI", "API endpoints"
 
 {Brief description of the dev/runtime surface.}
 
-| {Thing}              | {What it shows / does}     |
-| -------------------- | -------------------------- |
-| `{route or command}` | {description}              |
+| {Thing}              | {What it shows / does} |
+| -------------------- | ---------------------- |
+| `{route or command}` | {description}          |
 
 ## Layout
 
-\`\`\`
-src/
-├── {entry-file}         # {purpose}
-├── {folder}/            # {purpose}
-│   └── ...
-└── {folder}/            # {purpose}
-\`\`\`
+\`\`\` src/ ├── {entry-file} # {purpose} ├── {folder}/ # {purpose} │ └── ... └── {folder}/ # {purpose} \`\`\`
 
 ## Adding a {primary unit}
 
@@ -801,7 +793,7 @@ src/
 3. {Wire into the playground / example app / test harness so reviewers can see it render.}
 4. {Document any divergence from upstream in `docs/{...}`.}
 
-## Styling   ← optional; replace with whichever cross-cutting concern matters most
+## Styling ← optional; replace with whichever cross-cutting concern matters most
 
 {Configuration notes that affect every consumer — design tokens, conventions, opt-outs.}
 

package/data/harnesses/code/skills/workflow-mapper/SKILL.md

@@ -45,6 +45,7 @@ Search patterns (adapt to framework):
 For each route, record: `{ method, path, handler_function, file }`.
 
 Filter out trivial CRUD (single DB call + response). Keep routes that:
+
 - Call `startWorkflow`, `addJob`, `enqueue`, `emit`, `publish` (async dispatch)
 - Call 2+ service functions sequentially
 - Have transaction blocks (`$transaction`, `BEGIN`, `withTransaction`)
@@ -66,6 +67,7 @@ Search patterns:
 ```
 
 For Temporal specifically, also check:
+
 - `temporal/config/workflowModules.js` — workflow registry with queues and dependencies
 - `temporal/config/activityModules.js` — activity aggregation
 
@@ -82,6 +84,7 @@ Search patterns:
 ```
 
 Focus on actions that:
+
 - POST/PUT/PATCH/DELETE to backend (not just GETs)
 - Dispatch multiple Redux actions in sequence
 - Start polling loops (`setInterval`, recursive `setTimeout`, retry patterns)
@@ -138,7 +141,7 @@ For each discovered entry point, trace the full execution path. Use one sub-agen
 Map code actors to diagram participants using this hierarchy:
 
 | Code Pattern | Participant Name |
-|---|---|
+| --- | --- |
 | React component, hook, event handler | `User` + `Frontend` |
 | Express/API route handler | `API` |
 | Temporal workflow | `Temporal` |
@@ -175,7 +178,7 @@ Not every API route is a "workflow". Classify and filter.
 ### Workflow Categories
 
 | Category | Criteria | Include? |
-|---|---|---|
+| --- | --- | --- |
 | **Orchestration** | Multi-step, multi-service, async handoffs (save, publish, deploy) | Always |
 | **Auth & Session** | Login, logout, token refresh, SSO flows | Always |
 | **Real-time** | WebSocket connections, live updates, presence | Always |
@@ -206,9 +209,7 @@ Simple workflows get a compact diagram. Complex workflows get full detail with a
 ````markdown
 ### {Workflow Name}
 
-**Trigger:** {What initiates this — button click, API call, cron schedule, event}
-**Participants:** {List of systems involved}
-**Key files:** {3-5 most important files in the chain}
+**Trigger:** {What initiates this — button click, API call, cron schedule, event} **Participants:** {List of systems involved} **Key files:** {3-5 most important files in the chain}
 
 ```mermaid
 sequenceDiagram
@@ -226,6 +227,7 @@ sequenceDiagram
 ```
 
 **Notes:**
+
 - {Important implementation detail not visible in diagram}
 - {Performance consideration, timeout, retry policy}
 - {Known edge cases or failure modes}
@@ -265,11 +267,11 @@ sequenceDiagram
 
 Write to the user-specified path, or default to `docs/architecture/workflows.md`. Before writing output files, ensure the target directory exists. Create it with `mkdir -p` if needed.
 
-````markdown
+```markdown
 ---
-generated: {YYYY-MM-DD}
-scope: {full | feature-name}
-workflows_found: {count}
+generated: { YYYY-MM-DD }
+scope: { full | feature-name }
+workflows_found: { count }
 ---
 
 # Codebase Workflows
@@ -279,7 +281,7 @@ Auto-generated workflow map. Traces execution paths from user action to terminal
 ## Table of Contents
 
 | Workflow | Category | Trigger | Participants | Complexity |
-|---|---|---|---|---|
+| --- | --- | --- | --- | --- |
 | [{Name}](#{anchor}) | {Category} | {Trigger} | {Count} | {Simple/Moderate/Complex} |
 
 ---
@@ -287,6 +289,7 @@ Auto-generated workflow map. Traces execution paths from user action to terminal
 ## Orchestration Workflows
 
 ### {Workflow Name}
+
 {Diagram + metadata as defined in Phase 4}
 
 ---
@@ -294,6 +297,7 @@ Auto-generated workflow map. Traces execution paths from user action to terminal
 ## Authentication & Session Workflows
 
 ### {Workflow Name}
+
 {...}
 
 ---
@@ -301,6 +305,7 @@ Auto-generated workflow map. Traces execution paths from user action to terminal
 ## Real-time Workflows
 
 ### {Workflow Name}
+
 {...}
 
 ---
@@ -308,6 +313,7 @@ Auto-generated workflow map. Traces execution paths from user action to terminal
 ## Event-driven Workflows
 
 ### {Workflow Name}
+
 {...}
 
 ---
@@ -315,6 +321,7 @@ Auto-generated workflow map. Traces execution paths from user action to terminal
 ## Scheduled Workflows
 
 ### {Workflow Name}
+
 {...}
 
 ---
@@ -322,8 +329,9 @@ Auto-generated workflow map. Traces execution paths from user action to terminal
 ## Data Pipeline Workflows
 
 ### {Workflow Name}
+
 {...}
-````
+```
 
 ### Section Ordering
 
@@ -347,6 +355,7 @@ Launch 5 parallel sub-agents for Phase 1 (one per technique). Collect results, d
 ### Targeted Discovery
 
 User specifies a feature name. Skip broad Phase 1 scan. Instead:
+
 1. Find the feature's directory/files (grep for feature name in routes, components, workflows)
 2. Trace from those entry points only
 3. Output a single-feature workflow document
@@ -362,56 +371,68 @@ Read the existing workflow map file. For each workflow listed, check if the key
 ### Payload Storage Detection
 
 Look for patterns where large payloads are stored separately and referenced by ID:
+
 ```
 storePayload|savePayload|workflow_payload|jobData
 → then: retrievePayload|fetchPayload|getPayload (in the worker/activity)
 ```
+
 Note this in the diagram as a "Store payload → reference by ID" pattern.
 
 ### Optimistic Locking Detection
 
 Look for version comparison patterns:
+
 ```
 version.*!==|version.*conflict|StaleObjectError|OptimisticLock
 if.*serverVersion.*localVersion|if.*version.*mismatch
 ```
+
 These indicate conflict branching that should appear as `alt` blocks.
 
 ### Polling Loop Detection
 
 Look for patterns where the frontend waits for async completion:
+
 ```
 setInterval|setTimeout.*recursive|poll|retry.*status
 GET.*status\?.*workflowId|GET.*status\?.*jobId
 ```
+
 Note the polling interval and timeout in the diagram.
 
 ### Child Workflow / Sub-job Detection
 
 Look for spawned sub-processes:
+
 ```
 startChild\(|spawnChild|fork\(|.add\(.*queue
 Promise\.all.*map.*startWorkflow
 ```
+
 These should appear as nested sequences or separate linked diagrams.
 
 ### Transaction Boundary Detection
 
 Look for explicit transaction markers:
+
 ```
 \$transaction|\$executeRaw|BEGIN|COMMIT|ROLLBACK
 withTransaction|runInTransaction|atomic
 ```
+
 Group operations within a transaction using `rect` blocks in the diagram.
 
 ### Rate Limiting & Middleware Detection
 
 Look for middleware applied to route groups:
+
 ```
 rateLimit|rateLimiter|throttle
 authenticate|authorize|requireAuth|requireRole
 validate|validateBody|validateParams
 ```
+
 Note these as guards in the diagram using `opt` blocks or notes.
 
 ---

package/data/harnesses/code/skills/workflow-mapper/references/patterns.md

@@ -9,7 +9,7 @@ Concrete grep/glob patterns for each discovery technique. Agents should adapt th
 Identify the tech stack to select the right patterns:
 
 | Check | Pattern | Means |
-|---|---|---|
+| --- | --- | --- |
 | `package.json` contains `express` | `"express"` | Express backend |
 | `package.json` contains `@temporalio` | `"@temporalio"` | Temporal workflows |
 | `package.json` contains `bullmq` | `"bullmq"` | BullMQ job queues |

package/data/harnesses/discover/CLAUDE.md

@@ -1,46 +1,38 @@
 # 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.
 
 ---
 
 ## Access is a capability vector (the front gate)
 
-A target's access is four orthogonal axes, each `{value, confidence, evidence}` — and the vector
-decides which dimensions are reachable and which extraction method each uses:
+A target's access is four orthogonal axes, each `{value, confidence, evidence}` — and the vector decides which dimensions are reachable and which extraction method each uses:
 
 | Axis | Values | Unlocks | Case |
-|------|--------|---------|------|
+| --- | --- | --- | --- |
 | **source** | full · partial · none | codebase, packages | open-source repo |
 | **runtime** | reachable · gated · none | deployed-client-bundle, api, infra-backend-fingerprint, wire-capture | deployed, no source |
 | **auth** | have-login · none | session | logged-in SaaS |
 | **presence** | rich · thin · none | docs, website, community | — |
 
-Targets light several axes at once. The full model + grade→method mapping is in
-`.claude/rules/discovery.md`.
+Targets light several axes at once. The full model + grade→method mapping is in `.claude/rules/discovery.md`.
 
 ---
 
 ## The eleven dimensions → agents
 
-| Dimension / agent | | Dimension / agent |
-|---|--|---|
-| `codebase` | | `session` ⚠ |
-| `docs` | | `deployed-client-bundle` |
-| `packages` | | `infra-backend-fingerprint` |
-| `api` (+MCP) | | `wire-capture` ⚠ |
-| `website` | | `distribution-artifacts` |
-| `community` | | |
+| Dimension / agent |     | Dimension / agent           |
+| ----------------- | --- | --------------------------- |
+| `codebase`        |     | `session` ⚠                 |
+| `docs`            |     | `deployed-client-bundle`    |
+| `packages`        |     | `infra-backend-fingerprint` |
+| `api` (+MCP)      |     | `wire-capture` ⚠            |
+| `website`         |     | `distribution-artifacts`    |
+| `community`       |     |                             |
 
-Agent name = dimension name. ⚠ = gated (needs user authorization before dispatch). The catalog —
-detection signals + strategy + per-dimension artifacts — is in `.claude/rules/discovery.md`.
+Agent name = dimension name. ⚠ = gated (needs user authorization before dispatch). The catalog — detection signals + strategy + per-dimension artifacts — is in `.claude/rules/discovery.md`.
 
 ---
 
@@ -48,116 +40,70 @@ detection signals + strategy + per-dimension artifacts — is in `.claude/rules/
 
 Cheap, read-only. Scope the target, grade its access, detect which dimensions it exposes.
 
-**0. Resolve the corpus root** — the folder this run writes into. The harness chooses it *intelligently* rather than hardcoding one: default `research/` at the repo root, but if the project already holds a discovery corpus (any folder with a prior run's `*/00-scope-verdict.md`) under another name (`recon/`, `discovery/`, `teardowns/`, `analysis/`, …) **reuse it**, and honor a folder the user names. **Confirm the chosen root in one line** before writing. Every `research/<target>/` path in this harness is the *default form* — read it as `<corpus>/<target>/`, relative to the resolved root.
+**0. Resolve the corpus root** — the folder this run writes into. The harness chooses it _intelligently_ rather than hardcoding one: default `research/` at the repo root, but if the project already holds a discovery corpus (any folder with a prior run's `*/00-scope-verdict.md`) under another name (`recon/`, `discovery/`, `teardowns/`, `analysis/`, …) **reuse it**, and honor a folder the user names. **Confirm the chosen root in one line** before writing. Every `research/<target>/` path in this harness is the _default form_ — read it as `<corpus>/<target>/`, relative to the resolved root.
 
-1. **Scope-feasibility gate** — run the `.claude/rules/discovery.md` Part A (scope gate) algorithm: resolve
-   identity → ambiguity → ethics → suite-size → primitive → reachability. If the verdict isn't
-   `accept`, **halt** (present the narrowing/redirect prompt, or refuse). Write
-   `research/<target>/00-scope-verdict.md`.
+1. **Scope-feasibility gate** — run the `.claude/rules/discovery.md` Part A (scope gate) algorithm: resolve identity → ambiguity → ethics → suite-size → primitive → reachability. If the verdict isn't `accept`, **halt** (present the narrowing/redirect prompt, or refuse). Write `research/<target>/00-scope-verdict.md`.
 2. **Grade the access vector** (the four axes, with evidence) per `discovery` (Part B).
-3. **Probe each of the 11 dimensions** (cheap signals only); mark ✅ available / ⚠️ partial /
-   ❌ absent with evidence. An absent dimension is a finding.
-4. Write `research/<target>/00-recon-plan.md` — frontmatter carries `scope:` + the `access_grade`
-   vector; the body is the dimension-availability table + the per-dimension collection plan (warm entry
-   points) + the gating/ethics flags.
+3. **Probe each of the 11 dimensions** (cheap signals only); mark ✅ available / ⚠️ partial / ❌ absent with evidence. An absent dimension is a finding.
+4. Write `research/<target>/00-recon-plan.md` — frontmatter carries `scope:` + the `access_grade` vector; the body is the dimension-availability table + the per-dimension collection plan (warm entry points) + the gating/ethics flags.
 
 ---
 
 ## Mode 2 — Ingestion
 
-Dispatch one collector per available dimension; collect exhaustively before context is lost. Every collector
-writes `research/<target>/dimensions/<dim>/_summary.md` (with the **provenance frontmatter** —
-method · confidence · completeness · gaps) + `raw/`, obeying `.claude/rules/ingestion.md`.
-
-- **Run independents in parallel** — dispatch `docs`, `packages`, `api`, `website`, `community`,
-  `deployed-client-bundle`, `infra-backend-fingerprint`, `distribution-artifacts` together
-  (`subagent_type='<dimension>'`, one message, multiple Agent calls). Seed each collector with **warm
-  entry points (URLs / repos / hosts), not claimed facts** — any fact **or inference** carried from
-  Discovery (a price, a tier name, a version — **or a derived hypothesis like "localStorage-key X ⇒
-  backend is Y"**) is tagged `verify:may-be-stale` so the collector **re-derives it instead of anchoring**
-  on a possibly-stale (or possibly-wrong) value. A Discovery *inference* is never seeded as a plan fact:
-  label it a hypothesis in `00-recon-plan.md` and tag it `verify:` in the seed, so a collector that
-  inherits it reports it hedged rather than echoing it as observed (a real run seeded an
-  `apolloAnonId ⇒ GraphQL backend` guess that two captures then repeated before the session refuted it).
-  Only one dimension may drive the browser at a time (see
-  `ingestion` §7 rule 9): the parallel collectors use WebFetch/curl, leaving Chrome to `session`.
-- **Codebase fan-out** — dispatch `codebase`; it clones + maps + returns a per-package work-list;
-  then the main session fans out one reader per substantial package.
-- **Gated dimensions** — `session` and `wire-capture` (rung ≥2) need explicit user authorization
-  first (see `ingestion` §7). `session` follows `.claude/rules/ingestion.md` §9. When `session`
-  is authorized, **dispatch the non-browser collectors in the background (`run_in_background`) and drive
-  the gated browser session in the main session concurrently** — they don't contend (Chrome belongs to
-  the main session; the collectors use WebFetch/curl), so the whole of Ingestion runs in parallel.
-- **Shared seam** — **seed the two shared files `dimensions/_shared/{api-path-catalog.md,
-  feature-flags.md}` (empty, with a header) once, before the collector fan-out**; bundle/session/wire/
-  distribution then each *append* a `source:`-tagged section to the same physical file (never their own
-  copy). One owner dimension per static asset; a second mine of the same asset is one source, not
-  corroboration (`ingestion` §6).
-
-Validate each return (`_summary.md` + provenance present). A `blocked`/`partial` return is recorded,
-not blindly re-run.
-
-- **Capability gap = a checkpoint, not a silent fallback** (`ingestion` §8). If a *preferred* capture
-  capability is found unavailable mid-run (CDP/debugging port closed, browser MCP unreachable, a gated
-  proxy can't be stood up) and only a **materially weaker** method remains, **pause and confirm** with
-  the user before continuing on the fallback — naming what's unavailable and the coverage lost. (Distinct
-  from a planned method pre-grade, which is recorded, not confirmed.)
+Dispatch one collector per available dimension; collect exhaustively before context is lost. Every collector writes `research/<target>/dimensions/<dim>/_summary.md` (with the **provenance frontmatter** — method · confidence · completeness · gaps) + `raw/`, obeying `.claude/rules/ingestion.md`.
+
+- **Run independents in parallel** — dispatch `docs`, `packages`, `api`, `website`, `community`, `deployed-client-bundle`, `infra-backend-fingerprint`, `distribution-artifacts` together (`subagent_type='<dimension>'`, one message, multiple Agent calls). Seed each collector with **warm entry points (URLs / repos / hosts), not claimed facts** — any fact **or inference** carried from Discovery (a price, a tier name, a version — **or a derived hypothesis like "localStorage-key X ⇒ backend is Y"**) is tagged `verify:may-be-stale` so the collector **re-derives it instead of anchoring** on a possibly-stale (or possibly-wrong) value. A Discovery _inference_ is never seeded as a plan fact: label it a hypothesis in `00-recon-plan.md` and tag it `verify:` in the seed, so a collector that inherits it reports it hedged rather than echoing it as observed (a real run seeded an `apolloAnonId ⇒ GraphQL backend` guess that two captures then repeated before the session refuted it). Only one dimension may drive the browser at a time (see `ingestion` §7 rule 9): the parallel collectors use WebFetch/curl, leaving Chrome to `session`.
+- **Codebase fan-out** — dispatch `codebase`; it clones + maps + returns a per-package work-list; then the main session fans out one reader per substantial package.
+- **Gated dimensions** — `session` and `wire-capture` (rung ≥2) need explicit user authorization first (see `ingestion` §7). `session` follows `.claude/rules/ingestion.md` §9. When `session` is authorized, **dispatch the non-browser collectors in the background (`run_in_background`) and drive the gated browser session in the main session concurrently** — they don't contend (Chrome belongs to the main session; the collectors use WebFetch/curl), so the whole of Ingestion runs in parallel.
+- **Shared seam** — **seed the two shared files `dimensions/_shared/{api-path-catalog.md, feature-flags.md}` (empty, with a header) once, before the collector fan-out**; bundle/session/wire/ distribution then each _append_ a `source:`-tagged section to the same physical file (never their own copy). One owner dimension per static asset; a second mine of the same asset is one source, not corroboration (`ingestion` §6).
+
+Validate each return (`_summary.md` + provenance present). A `blocked`/`partial` return is recorded, not blindly re-run.
+
+- **Capability gap = a checkpoint, not a silent fallback** (`ingestion` §8). If a _preferred_ capture capability is found unavailable mid-run (CDP/debugging port closed, browser MCP unreachable, a gated proxy can't be stood up) and only a **materially weaker** method remains, **pause and confirm** with the user before continuing on the fallback — naming what's unavailable and the coverage lost. (Distinct from a planned method pre-grade, which is recorded, not confirmed.)
 
 ---
 
 ## Mode 3 — Evaluation
 
-Reconcile the collected dimensions into four cross-dimension rollups under `research/<target>/evaluation/`, plus
-the run `README.md`, **weighting every claim by how it was obtained**. Follow
-`.claude/rules/evaluation.md`: read each dimension's provenance frontmatter first; anchor +
-provenance-tag every claim `(api: raw/endpoint-catalog.md · openapi-verbatim · high)`; weight
-(max-of-sources, promote one band only on ≥2 *independent* dimensions, never average); present
-high→fact, low/single-source→tentative, conflict→flagged. The four rollups: `technology-architecture`,
-`product-features`, `data-model-api-surface`, `competitive-positioning`.
+Reconcile the collected dimensions into four cross-dimension rollups under `research/<target>/evaluation/`, plus the run `README.md`, **weighting every claim by how it was obtained**. Follow `.claude/rules/evaluation.md`: read each dimension's provenance frontmatter first; anchor + provenance-tag every claim `(api: raw/endpoint-catalog.md · openapi-verbatim · high)`; weight (max-of-sources, promote one band only on ≥2 _independent_ dimensions, never average); present high→fact, low/single-source→tentative, conflict→flagged. The four rollups: `technology-architecture`, `product-features`, `data-model-api-surface`, `competitive-positioning`.
+
+---
+
+## Mode 4 — Product Cartography & Coverage
+
+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. `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 4 — Self-correction (the run corrects itself; the harness improves only on approval)
-
-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):
-
-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.
-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).
-
-**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.)
+## 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–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.)
 
 ---
 
 ## Ethics (non-negotiable)
 
-For spec-writing, integration planning, and competitive analysis — **not** credential theft,
-rate-limit bypass, or scraping. Full rules: `.claude/rules/ingestion.md` §7.
+For spec-writing, integration planning, and competitive analysis — **not** credential theft, rate-limit bypass, or scraping. Full rules: `.claude/rules/ingestion.md` §7.
 
 - **Never enter credentials.** The user logs in; `session` and `wire-capture` rung 3 are opt-in.
 - **Redact every secret before writing `raw/`.** Cookies/tokens/JWT-signatures/API-keys never hit disk.
-- **wire-capture** climbs the 3-rung ladder (browser-tap → HAR → mitmproxy); rung 3 is user-run,
-  first-party traffic only. Wireshark is not used (TLS ciphertext).
+- **wire-capture** climbs the 3-rung ladder (browser-tap → HAR → mitmproxy); rung 3 is user-run, first-party traffic only. Wireshark is not used (TLS ciphertext).
 - **Confirm before any state change or cost.** **No destructive actions, no exfiltration.** Respect TOS/robots.
 
 ---
@@ -171,10 +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.
+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.