@nurix/etna 0.15.7 → 0.15.8

package/data/harnesses/{re/rules/re-discovery.md → discover/rules/discovery.md}

@@ -1,19 +1,32 @@
 # Discovery Reference — Scope Gate · Access Vector · Dimension Catalog
 
-The reference knowledge for **Discovery** (`re` harness, Mode 1). It carries all three of
-Discovery's steps in the order they run:
+The reference knowledge for **Discovery** (`discover` harness, Mode 1). It carries all three of
+Discovery's steps in the order they run (preceded by corpus-root resolution, Step 00 below):
 
 - **Part A — Scope-feasibility gate** (Step 0): resolve the target's identity and emit a verdict
   so the run never wastes effort on an infeasible target.
 - **Part B — Access vector** (Step 1): grade the four-axis capability vector that decides which
   dimensions are reachable and which method each uses.
 - **Part C — Dimension catalog** (Step 2): the canonical list of dimensions, their detection
-  signals, dump strategy, and owning agent.
+  signals, collection strategy, and owning agent.
 
 `ingestion` also reads **Part C** to dispatch the right agent with the right method.
 
 ---
 
+# Step 00 — Resolve the corpus root (before the gate)
+
+Before Part A, decide **where this run writes** — the harness picks intelligently, it does not hardcode `research/`:
+
+1. **Reuse an existing discovery corpus** if the project has one — search for any folder containing a prior run's `*/00-scope-verdict.md` (commonly `research/`, but also `recon/`, `discovery/`, `teardowns/`, `analysis/`, or a folder the user names).
+2. If several exist, prefer the one the user points at, else the most recently written.
+3. If none exists and the user hasn't named one, default to `research/` at the repo root.
+4. **Confirm the chosen root in one line** before writing `00-scope-verdict.md`.
+
+All `research/<target>/` paths in the harness are the *default form*, relative to the resolved `<corpus>/`.
+
+---
+
 # Part A — Scope-feasibility gate (Step 0)
 
 Run this **before** any dimension probing. It resolves the target's identity and emits one of four
@@ -152,6 +165,14 @@ dimensions). Rules:
 
 Discovery records the resolved vector in the `access_grade` frontmatter of `00-recon-plan.md`.
 
+> **Hypotheses are not facts (seed them tagged, never echo them).** Any *derived inference* Discovery
+> makes beyond the four graded axes — e.g. "this `localStorage` key implies a GraphQL backend", "this
+> host is the realtime endpoint" — is recorded in `00-recon-plan.md` **as a labelled hypothesis**, never
+> as a plan fact, and is tagged `verify:may-be-stale` when seeded to a collector (CLAUDE.md Mode 2) so
+> Ingestion **re-derives** rather than echoes it. A wrong inference seeded as framing propagates: a real
+> run's `apolloAnonId ⇒ GraphQL` guess was repeated (hedged) by two captures before the `session` dimension
+> refuted it (the backend was RSC + Server Actions; the key was an Apollo.io tracker).
+
 ---
 
 # Part C — The dimension catalog (Step 2)
@@ -164,7 +185,7 @@ Discovery records the resolved vector in the `access_grade` frontmatter of `00-r
 | 4 | **api** | `api` | runtime/presence | OpenAPI/GraphQL → endpoint catalog (+ **MCP/tool-catalog fold-in**) |
 | 5 | **website** | `website` | presence | crawl public pages → features, pricing, positioning |
 | 6 | **community** | `community` | presence | first-party changelog/issues/discord themes |
-| 7 | **session** | `session` | auth:have-login | delegate to the session playbook (§9 of `re-ingestion`: 3-pass, P0–P6) |
+| 7 | **session** | `session` | auth:have-login | delegate to the session playbook (§9 of `ingestion`: 3-pass, P0–P6) |
 | 8 | **deployed-client-bundle** | `deployed-client-bundle` | runtime:reachable | unauth SPA: route table, API-path catalog, flags, env, source maps |
 | 9 | **infra-backend-fingerprint** | `infra-backend-fingerprint` | runtime/presence | DNS, cert-transparency, CDN/cloud, headers (+ **sub-processor/trust fold-in**) |
 | 10 | **wire-capture** | `wire-capture` | runtime (source:none) | the 3-rung ladder for non-browser/no-source clients (gated) |
@@ -177,7 +198,7 @@ Discovery records the resolved vector in the `access_grade` frontmatter of `00-r
 > issues/roadmap/changelog/forum — feedback funnelled to a gated channel), flag `external-reputation`
 > as **recommended-for-this-run** in `00-recon-plan.md`, so the user-sentiment blind spot is a surfaced
 > choice rather than a silent gap (the `community` user-pain claims are then capped at tentative —
-> re-evaluation closed-feedback cap).
+> evaluation closed-feedback cap).
 
 An **absent** dimension is a finding — record it with its evidence; never silently drop it.
 
@@ -188,24 +209,39 @@ See git history / the source playbook for the full strategy text; in brief:
   packages + internal dep hierarchy, return a per-package work-list for the main-session fan-out.
 - **docs** — prefer in-repo docs, then `llms.txt`/`llms-full.txt`, then crawl; organize by section.
 - **packages** — per public package: registry metadata, `exports` map + `.d.ts` type surface, health.
+  **Registry-ownership cheap-test (grade ownership before calling an SDK "partial/unverified").** Read
+  the registry `author`/`maintainers`/`summary`/`project_urls`/`Homepage` fields and check the
+  dependency set for a generator fingerprint (Stainless: `httpx`/`pydantic`/`anyio`/`distro`/`sniffio`
+  + in-file "generated by Stainless" headers; Speakeasy; OpenAPI-Generator). An `author`/`summary` that
+  says "official … library for the X API" + a vendor-domain `project_urls` confirms **official**
+  ownership at **high** confidence even when the *source* repo is private — the published tarball IS the
+  public-API mirror (a high-confidence `registry-metadata` anchor), so it is **not** "partial." Tag a
+  genuinely third-party/community package (different author/scope) as such, but don't down-grade an
+  official-but-private-source SDK to "unverified."
 - **api** — fetch the spec verbatim, build an endpoint catalog (auth, envelope, pagination, webhooks).
   **Grade the method from a RETRIEVED artifact, never a label.** Before grading `openapi-verbatim`,
   actually fetch the candidate spec URL and confirm a **parseable JSON/YAML body** — a docs page merely
   *titled* "OpenAPI" with no served `spec.json` (or a `/swagger` that 403s) is `docs-reconstructed`
   (capped medium), and Discovery must pre-grade it that way so the plan matches reality. **A
   sibling-declared host/op/route count is a coverage checklist (a floor), never a ceiling** — every
-  dumper expands from sibling-mined hosts/routes and records the predicted-vs-found delta.
+  collector expands from sibling-mined hosts/routes and records the predicted-vs-found delta.
   **NEW fold-in:** also probe MCP/tool surfaces — `/.well-known/mcp`, an MCP server manifest, a
   function-calling tool schema, an LLM "actions" file — and write `raw/tool-catalog.md` (an MCP tool
-  list *is* an API catalog; it lives here, not in its own dimension).
+  list *is* an API catalog; it lives here, not in its own dimension). **Unauth MCP-probe recipe (when
+  the tool catalog itself is auth-gated):** a `GET /mcp` → `405` body often names the transport
+  (e.g. "stateless; only POST is supported" = streamable-HTTP); `GET /sse` presence/absence tells
+  legacy-SSE vs streamable; and `/.well-known/oauth-authorization-server` + `/.well-known/oauth-protected-resource/{name}`
+  reveal the **OAuth/PKCE model + issuer** (e.g. a `jwks_uri` on the auth vendor names Clerk/Auth0/etc.)
+  — all without a token. Capture transport + auth + issuer from these, reconstruct the tool list from
+  docs/SDK, and mark the verbatim `tools/list` **partial** (OAuth-gated).
 - **website** — crawl home/features/pricing/customers/integrations; extract positioning, pricing
   matrix, target market.
 - **community** — *first-party only*: changelog cadence + direction, issue/discussion themes, blog.
 - **session** — the deepest, opt-in, user-gated dimension; delegates to the session playbook in
-  `re-ingestion` §9 (3-pass, P0–P6, captures/raw/curls). For any `auth:have-login`/`auth:claimed`
+  `ingestion` §9 (3-pass, P0–P6, captures/raw/curls). For any `auth:have-login`/`auth:claimed`
   target, Discovery **seeds the Pass-2 decision** (`pass2: offered-pending | declined-by-user |
   deferred`) into `00-recon-plan.md`, so a Pass-1-only (read-only) session is a *recorded choice*, not a
-  silent omission of the write surface (re-ingestion §9.2).
+  silent omission of the write surface (ingestion §9.2).
 
 ## 8 — deployed-client-bundle — `deployed-client-bundle`
 
@@ -220,12 +256,12 @@ bootstrap-config paths (`/config`, `/backend/config/*`, `/env.json`, a runtime-c
 200 here is both a method pre-grade and a possible unauth config/secret leak (a finding).
 
 **Strategy:** fetch the main bundle(s); string-mine the **route table**, the **API-path catalog**
-(→ append to the shared `dimensions/_shared/api-path-catalog.md`, `source: bundle` — re-ingestion §6),
+(→ append to the shared `dimensions/_shared/api-path-catalog.md`, `source: bundle` — ingestion §6),
 **feature flags** (→ shared `dimensions/_shared/feature-flags.md`), embedded **env config** (`VITE_*`,
 `NEXT_PUBLIC_*`, public keys — field-names only, redact values), and reassemble **source maps** if
 shipped (`method: source-map-reassembly`, confidence high). Digest huge bundles, don't paste. This
 dimension **owns** the app-API bundle mine — other dimensions cite its catalog by path, never re-mine
-the same bundle (re-ingestion §6).
+the same bundle (ingestion §6).
 
 **Artifacts:** `_summary.md` + `raw/{route-table.md, env-config.md, bundle-map.md}` + appends to the
 shared `dimensions/_shared/{api-path-catalog.md, feature-flags.md}`.
@@ -253,15 +289,16 @@ what hosts it *might* call; the capture says what it *actually* calls.
 **Detection:** a non-browser client exists (from distribution-artifacts) OR an unauth SPA makes
 structured XHRs worth a tap, AND the appropriate ethics rung is authorized.
 
-**Strategy:** the **3-rung ladder** (lowest privilege first) — see `re-ingestion` §7.1:
+**Strategy:** the **3-rung ladder** (lowest privilege first) — see `ingestion` §7.1:
 1. browser network tap (unauth, default) → `wire-tap-browser`;
 2. HAR export → `wire-har`;
-3. mitmproxy (**gated, opt-in, user-run, first-party traffic only**) → `wire-mitmproxy`.
+3. mitmproxy (**gated, opt-in, user-run, first-party traffic only**) → `wire-mitmproxy`;
+4. **first-party SDK-harness** (when the product publishes an official SDK + the *user* can provision keys) — scaffold + instrument a throw-away client you own (`document_start` taps, full wire) → `sdk-harness` (`ingestion` §7.1). The deepest lane for a `runtime:reachable + source:none` product whose SDK is the only public mirror of the runtime; gated like rung 3.
 
 **Fold note (common path):** when there is no separate non-browser client, wire-capture **folds into
-`session`** (which owns the browser singleton), **never into a curl/WebFetch dumper** (a non-browser
-dumper cannot run rung-1's in-page tap, and routing it there yields zero `source: wire` rows —
-re-ingestion §7.1). The folded rung-1 *is* the interceptor `session` installs; its observed paths
+`session`** (which owns the browser singleton), **never into a curl/WebFetch collector** (a non-browser
+collector cannot run rung-1's in-page tap, and routing it there yields zero `source: wire` rows —
+ingestion §7.1). The folded rung-1 *is* the interceptor `session` installs; its observed paths
 append to the shared `dimensions/_shared/api-path-catalog.md` as `source: wire`. A folded wire-capture
 still leaves a one-paragraph `_summary.md` (`status: folded`, naming the fold target) — never a silent
 drop.
@@ -283,7 +320,7 @@ capability map). **Electron** — `npx asar extract app.asar` → map JS modules
 route/API/flag catalog from the desktop client (often richer than web). **mobile** — `Info.plist`/
 `AndroidManifest` hosts, ATS exceptions, embedded-SDK list from strings (**redact any embedded
 keys**). **CLI** — help text/subcommands = an API catalog. Read the artifact's EULA first (see
-`re-ingestion` §7.2); never silently decompile a restrictively-licensed binary.
+`ingestion` §7.2); never silently decompile a restrictively-licensed binary.
 
 **Artifacts:** `_summary.md` + `raw/{extension-manifest.md, electron-asar-map.md, mobile-strings.md, cli-catalog.md}` (whichever apply) + appends to shared `dimensions/_shared/api-path-catalog.md` (source: distribution).
 

package/data/harnesses/{re/rules/re-evaluation.md → discover/rules/evaluation.md}

@@ -27,13 +27,19 @@ agreeing is still one source. A bundle-declared route + a session-observed route
 one spec / one binary) are **one source** — never a band-bump — even when they report different
 counts; the divergent counts are a **reported range, not a flagged conflict** (`deployed-client-bundle`
 278 vs `website` 361 over one bundle is one finding with a range, not corroboration and not a conflict).
+**OSS distribution clients are an independent corroboration lane.** An API-surface claim resting on a
+single *third-party* wrapper (a community MCP server, an unofficial SDK) is tentative — but a
+**first-party open-source integration client** (`distribution-artifacts`: a Unity/Figma/CLI plugin or
+published SDK source) that calls the same routes is **independent of both marketing and the third-party
+wrapper**, and corroborates it → promotes. (A legacy/granular route family seen only in a third-party
+MCP becomes a real finding once the official OSS client calls it too.)
 
 **Closed-feedback confidence cap.** When the `community` dimension finds **no first-party feedback
 loop** (no public issues / roadmap / changelog / forum — feedback funnelled to a gated channel), its
 user-pain / most-requested-feature claims are **inference-from-changelog only → capped at
 `low`/tentative**, never promoted on changelog frequency alone. The surface that *would* corroborate
 user sentiment is `external-reputation` (a deferred dimension) — flag it as recommended-for-this-run
-when this cap fires (see re-discovery Part C deferred-dimension trigger).
+when this cap fires (see discovery Part C deferred-dimension trigger).
 
 **Write-side-unobserved cap.** A `session` dimension carrying `write_side_observed: false` (a
 Pass-1-only run) has observed feature *existence/gating* but **not** feature *execution behavior*. Any
@@ -129,3 +135,8 @@ prose, not via a separate `claims.yaml`.)
 4. Tag every claim with provenance; weight per the rules above; flag every disagreement; record
    every gap. A confident doc built on one low-confidence dimension is worse than an honest
    "single-source, unverified."
+
+> **Classifying a raw observation** — to turn a storage-key prefix, an auth tell, an envelope shape,
+> or a realtime frame into a *named* stack finding, use the fingerprint tables in
+> `tradecraft.md` (storage→stack, auth-provider, API-envelope, realtime-trap). They name what
+> a finding *is*; this file governs how confidently to *state* it.

package/data/harnesses/{re/rules/re-ingestion.md → discover/rules/ingestion.md}

@@ -1,15 +1,15 @@
-# Ingestion Contract — Dump Shape · Provenance · Ethics · Session Playbook
+# Ingestion Contract — Capture Shape · Provenance · Ethics · Session Playbook
 
-The reference knowledge for **Ingestion** (`re` harness, Mode 2). Every dimension dump obeys the
+The reference knowledge for **Ingestion** (`discover` harness, Mode 2). Every dimension capture obeys the
 contract in §1–8 so (a) the **evaluation** mode can rely on a stable shape and weight each claim by
-*how it was obtained*, and (b) a future agent can reproduce or extend any dump. §9 carries the
+*how it was obtained*, and (b) a future agent can reproduce or extend any capture. §9 carries the
 deepest, gated dimension's method — the logged-in browser-session playbook — which the `session`
 agent follows.
 
 This contract generalizes the source playbook's three-format contract (`captures/*.md` narrative +
 `raw/*.json` verbatim + `curls.md`) to *any* dimension.
 
-> **Contract style = "lighter".** Provenance ("how it was dumped") lives in the
+> **Contract style = "lighter".** Provenance ("how it was captured") lives in the
 > **`_summary.md` frontmatter**, not a separate `manifest.yaml`. There is no parallel YAML
 > machine-spine — everything stays markdown-with-frontmatter. Evaluation reads the frontmatter
 > to weight claims; self-correction reads it to detect under-delivery.
@@ -50,7 +50,7 @@ Two layout rules the seam and the "absence is a finding" principle depend on:
 dimension: <codebase|docs|packages|api|website|community|session|deployed-client-bundle|infra-backend-fingerprint|wire-capture|distribution-artifacts>
 target: <slug>
 status: complete | partial | blocked
-# --- provenance (the "how it was dumped" layer evaluation weights on) ---
+# --- provenance (the "how it was captured" layer evaluation weights on) ---
 access_grade_used: <source:full | runtime:reachable | auth:have-login | presence:rich | ...>
 method: <the ACTUAL extraction method — see §3 vocabulary>
 completeness_pct: <0-100, honest self-estimate of reachable surface captured>
@@ -60,7 +60,7 @@ sources: [<urls / paths actually consulted>]
 gaps: [<structured — each is a thing evaluation must NOT treat as covered>]
 ---
 
-# <Target> — <Dimension> dump
+# <Target> — <Dimension> capture
 
 ## Method
 Exactly what was done, which tools, what was skipped and why. (The prose behind the frontmatter `method`.)
@@ -88,7 +88,7 @@ Keep `status` and `confidence` honest — they drive the entire evaluation weigh
 `method` is one of: `clone-and-map`, `source-map-reassembly`, `registry-metadata`,
 `openapi-verbatim`, `graphql-introspection`, `crawl-clip`, `docs-reconstructed`,
 `bundle-string-mine`, `dns-ct-fingerprint`, `wire-tap-browser`, `wire-har`, `wire-mitmproxy`,
-`binary-extract` (asar/apk/crx), `session-playbook`, `inferred`.
+`binary-extract` (asar/apk/crx), `session-playbook`, `sdk-harness`, `inferred`.
 
 **Confidence is a function of method** (evaluation relies on this mapping):
 - **high** — verbatim machine artifacts: `openapi-verbatim`, `graphql-introspection`, `registry-metadata`, `clone-and-map`, `binary-extract`.
@@ -133,13 +133,13 @@ flags**. To keep them consumable instead of triplicated **N times** (a real run
 
 - **One physical file, one canonical location, append-only.** The seam files live at
   `dimensions/_shared/api-path-catalog.md` and `dimensions/_shared/feature-flags.md` — **Ingestion
-  seeds the two empty files (with a header) once, before the dumper fan-out.** Every contributing
+  seeds the two empty files (with a header) once, before the collector fan-out.** Every contributing
   dimension **appends a `source:`-tagged section** (`source: bundle | session | wire | distribution`)
-  and **never creates its own copy**; each dumper's `_summary.md` Artifacts list **links** the shared
+  and **never creates its own copy**; each collector's `_summary.md` Artifacts list **links** the shared
   file rather than duplicating it. **Shared-seam allowlist:** these two filenames are the *only*
   shared/single-physical artifacts — every other `raw/*` is dimension-private.
 - Evaluation owns the **API-path diff** (an *adaptive N-way* diff over whichever runtime sources were
-  actually run — see re-evaluation template 3) in `data-model-api-surface.md`. A path that appears in
+  actually run — see evaluation template 3) in `data-model-api-surface.md`. A path that appears in
   `bundle` but never in `session`/`wire` is a dormant/unshipped route — a finding, not noise.
 
 > **Same artifact ⇒ ONE source (never independent corroboration).** Two dimensions that string-mine
@@ -155,26 +155,135 @@ flags**. To keep them consumable instead of triplicated **N times** (a real run
 > host, and operation set. Always diff the two: operations the app uses but the public API omits, **and**
 > public operations the app never calls, are both findings. The published surface is the integration
 > story; the runtime surface is the real architecture. When a published API exists, Evaluation emits
-> this split as a *named* output, not inline prose (re-evaluation template 3).
+> this split as a *named* output, not inline prose (evaluation template 3).
 
 ---
 
 ## 7. Ethics & redaction (non-negotiable — binds EVERY dimension)
 
-Carried from the source playbook (`setup.md` §6). Violating them voids the work.
+Violating them voids the work. Rules 2–3 are enforced by the **runnable redaction layer in §7.0** —
+install it inside the tap wrapper so no secret can reach `raw/` in the first place.
 
 1. **Never enter credentials.** The user signs into any logged-in surface beforehand.
 2. **Storage: shape, not values.** No raw cookies/tokens/JWT-signatures. Decode JWT *structure* with identity claims (`sub`,`email`,`phone`,`user_id`,`uid`,`sid`) redacted.
-3. **Never save secrets.** Before any `raw/` write, redact every credential-shaped field → `<REDACTED:...>` + log in `_meta.redactions`. Field patterns: `api_key`,`*_secret`,`client_secret`,`webhook_secret`,`signing_*`,`password`,`private_key`,`access_token`/`refresh_token` in bodies, vendor-named secrets. Value patterns: `sk_live_…`/`pk_live_…` (Stripe), `sk-…` (OpenAI), `xox[bp]-…` (Slack), `AKIA…` (AWS), `gh[ps]_…` (GitHub), `AIza…` (Google), `eyJ…` (JWT), opaque base64 ≥32 chars in a credential field. Over-redact when unsure.
+3. **Never save secrets.** Before any `raw/` write, redact every credential-shaped field → `<REDACTED:...>` + log in `_meta.redactions`. Field patterns: `api_key`,`*_secret`,`client_secret`,`webhook_secret`,`signing_*`,`password`,`private_key`,`access_token`/`refresh_token` in bodies, vendor-named secrets. Value patterns: `sk_live_…`/`pk_live_…` (Stripe), `sk-…` (OpenAI), `xox[bp]-…` (Slack), `AKIA…` (AWS), `gh[ps]_…` (GitHub), `AIza…` (Google), `eyJ…` (JWT), opaque base64 ≥32 chars in a credential field. Over-redact when unsure. **The executable scrubbers that enforce this rule are in §7.0 below** (`SCRUB` / `redactSecrets` / `ULTRA`); the full keyboard layer lives in `tradecraft.md`.
 4. **Confirm before state changes** — anything that creates state, costs money, or is visible to others (even a draft toggle). State the exact action + estimated cost.
 5. **No destructive actions.** Document the absence; move on.
 6. **No bypassing safety harnesses** — redact, never evade.
 7. **No exfiltration.** Captures stay local under `research/<target>/`.
 8. **Respect TOS & robots.** For spec-writing / integration / competitive analysis — not credential theft, rate-limit bypass, or scraping.
-9. **One browser-driving dimension at a time.** Chrome MCP is a shared singleton. Only the gated `session`/`wire-capture` dimensions drive the browser; parallel non-browser dumpers use WebFetch/curl, or — if a page genuinely needs a real browser — create their **own** tab and never touch the session tab. Never run two browser-driving dumpers concurrently.
-10. **Verify an absence before asserting it.** A "host is NXDOMAIN / dimension is absent / endpoint 404s everywhere" claim that would *contradict another dimension* must be re-checked by a **second method** (alternate resolver, direct HTTP probe, second source) before it is written as fact. A single-resolver/single-probe negative is recorded as *tentative*, never as a cross-dimension directive. (An HTTP 4xx/5xx means the host **resolves** — present, not absent.)
+9. **One browser-driving dimension at a time.** Chrome MCP is a shared singleton. Only the gated `session`/`wire-capture` dimensions drive the browser; parallel non-browser collectors use WebFetch/curl, or — if a page genuinely needs a real browser — create their **own** tab and never touch the session tab. Never run two browser-driving collectors concurrently.
+10. **Verify an absence before asserting it.** A "host is NXDOMAIN / dimension is absent / endpoint 404s everywhere" claim that would *contradict another dimension* must be re-checked by a **second method** (alternate resolver, direct HTTP probe, second source) before it is written as fact. A single-resolver/single-probe negative is recorded as *tentative*, never as a cross-dimension directive. (An HTTP 4xx/5xx means the host **resolves** — present, not absent.) **Feedback-channel / changelog absence (`community`): a 404 on the marketing host's `/changelog` is NOT proof of "no public feedback loop"** — before asserting it, probe the common alternate homes: `feedback.`/`changelog.`/`updates.`/`roadmap.` subdomains, hosted boards (FeatureOS/Canny/Featurebase), a status-page "announcements" tab, and `<link rel="alternate" type="application/rss+xml">` autodiscovery on the docs/blog. Only after those miss is the closed-feedback cap (evaluation) warranted; a wrong-host 404 alone leaves it *tentative*.
 11. **Bounded live-token use (read-only, in-page only).** To fill a Pass-1 capture gap you MAY read the live token from its store and replay a **read-only** request with it — *only* if the token is used **in-page / in-process only**, is **never written to `raw/`, never returned, never logged**, and the replay changes no state. This is the single permitted touch of a live credential; rules 2–3 (shape-not-values, never-save-secrets) still bind everything written to disk.
 
+### 7.0 Redaction — runnable (the executable layer behind rule 3)
+
+These are **executable guardrails**, not prose policy. Install them **inside the tap/fetch wrapper** so every captured string is scrubbed *before it reaches the harness or disk* — credentials never reach `raw/`, and the browser MCP's content-block (`[BLOCKED: Cookie/query string data]`) never fires on a legitimate capture. Run `SCRUB(value)` on every string returned from a `javascript_tool` capture; run `redactSecrets(body, redactions)` on every object before any `Write` of `raw/*.json`; fall back to `ULTRA` only when the harness still blocks output.
+
+#### 1. `SCRUB` — the value-shape scrubber (run on every captured string)
+
+Combine into one `SCRUB` function and apply to every string returned from `javascript_tool`. It neutralises PII + provider-credential value shapes regardless of field name (catches credentials embedded in string concatenations like a deep-link URL or a log line):
+
+```js
+const SCRUB = (s) => String(s||'')
+  .replace(/eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+/g, '<jwt>')
+  .replace(/[A-Za-z0-9+/]{40,}={0,2}/g, '<b64>')
+  .replace(/data:image\/[^"]+/g, '<data-image>')
+  .replace(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, '<email>')
+  .replace(/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/g, '<uuid>')
+  .replace(/[a-f0-9]{32,}/g, '<hex>')
+  .replace(/(user|org|ins|sess|cli)_[A-Za-z0-9]{20,}/g, '.$1id.')   // Clerk-style IDs
+  .replace(/\+91\d{10}/g, '<phone-in>')                            // Indian phone numbers
+  .replace(/\+1\d{10}/g, '<phone-us>')                             // US phone numbers
+  .replace(/\b\d{10,15}\b/g, '<phone>')                            // generic numeric phone
+  .replace(/[?&]([a-z_]+)=([^&\s"]+)/gi, (_,k,v) => '?'+k+'=<v>');
+```
+
+The regex table behind `SCRUB` (PII value shapes + known provider-key prefixes), so a new run can extend it:
+
+| Pattern | Replacement | Catches |
+|---------|-------------|---------|
+| `eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+` | `<jwt>` | JWT tokens (3-segment base64) |
+| `[A-Za-z0-9+/]{40,}={0,2}` | `<b64>` | Long base64 |
+| `data:image/[^"]+` | `<data-image>` | Inline image data URIs |
+| `[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}` | `<uuid>` | UUIDs |
+| `[a-f0-9]{32,}` | `<hex>` | Long hex strings (hashes) |
+| `(user\|org\|ins\|sess\|cli)_[A-Za-z0-9]{20,}` | `.<group>id.` | Clerk-style IDs |
+| `\+91\d{10}` | `<phone-in>` | Indian phone numbers |
+| `\+1\d{10}` | `<phone-us>` | US phone numbers |
+| `\b\d{10,15}\b` | `<phone>` | Generic numeric phone |
+| `\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b` | `<email>` | Email addresses |
+| `[?&]([a-z_]+)=([^&\s"]+)` | `?$1=<v>` | Query string values |
+| `sk_(live\|test)_[A-Za-z0-9]{16,}` | `<REDACTED:STRIPE_SK>` | Stripe secret key |
+| `(rk\|pk)_(live\|test)_[A-Za-z0-9]{16,}` | `<REDACTED:STRIPE_KEY>` | Stripe restricted / publishable key |
+| `sk-(proj-)?[A-Za-z0-9_\-]{20,}` | `<REDACTED:OPENAI>` | OpenAI API key (incl. project-scoped) |
+| `xox[bpoars]-[A-Za-z0-9-]{10,}` | `<REDACTED:SLACK>` | Slack token |
+| `\b(AKIA\|ASIA)[A-Z0-9]{16}\b` | `<REDACTED:AWS_KEY_ID>` | AWS access key ID (long-lived + temporary) |
+| `gh[pousr]_[A-Za-z0-9]{30,}` | `<REDACTED:GITHUB>` | GitHub PAT / OAuth / refresh / server token |
+| `AIza[0-9A-Za-z_\-]{35}` | `<REDACTED:GOOGLE>` | Google API key |
+
+#### 2. `redactSecrets` — the field-name walker (run before every `raw/*.json` write)
+
+`SCRUB` catches known value *shapes*; some providers use opaque base64 tokens with **no recognisable prefix**, so you also need a recursive walker that redacts by **key name** regardless of value shape. Run both — `SCRUB` on captured strings, `redactSecrets` on the parsed object before any `Write`:
+
+```js
+const SECRET_KEY_RE = /(api[_-]?key|apikey|secret|password|passphrase|pwd|client[_-]?secret|webhook[_-]?secret|signing[_-]?(?:key|secret)|private[_-]?key|service[_-]?account[_-]?key|access[_-]?token|refresh[_-]?token|bearer[_-]?token|auth[_-]?token)$/i;
+
+function redactSecrets(obj, redactions) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (Array.isArray(obj)) return obj.map(v => redactSecrets(v, redactions));
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === 'string' && SECRET_KEY_RE.test(k) && v.length > 0) {
+      redactions.push(`${k} → <REDACTED:SECRET> (was ${v.length} chars)`);
+      out[k] = '<REDACTED:SECRET>';
+    } else {
+      out[k] = redactSecrets(v, redactions);
+    }
+  }
+  return out;
+}
+
+// Use:
+const redactions = [];
+const safeBody = redactSecrets(rawBody, redactions);
+// Then write { _meta: { ..., redactions }, body: safeBody, _decoded_fields: {...} }
+```
+
+At run time, append the **current session's** own identifiers (your user UUID, email, display name,
+org slug) as explicit `.replace(...)` lines in a final pass over the serialized output — but **never
+commit those literal values into this file.** The generic UUID / email / phone / Clerk-ID patterns
+above already neutralise them; the explicit pass is a belt-and-suspenders step that stays local to the
+run.
+
+For a logged-in session, also redact: the user's display name, the user's avatar URL, any organisation slug (`org_slug` claim) the user might want hidden, and phone numbers at any masking level. Over-redaction is cheap; a leaked partner API key is not.
+
+#### 3. `ULTRA` — the last-resort scrubber (when the harness still blocks output)
+
+When `SCRUB` isn't enough (e.g. the body has agent-generated content with patterns that match the blocklist), drop to a regex that strips everything except readable ASCII:
+
+```js
+const ULTRA = (s) => String(s||'').replace(/[^a-zA-Z0-9 _.,:!?\-/]/g,'.');
+```
+
+You lose JSON braces and special characters, but you keep the **structural information** (field names, enum values, lengths) — useful for getting any output at all when the body is irretrievably full of blocked patterns.
+
+#### 4. PII / value-shape coverage (what these patterns neutralise)
+
+- **JWTs** — 3-segment base64 `eyJ…` anywhere (body fields, not just `Authorization`).
+- **Phone numbers** — Indian `+91` (10 digits), US `+1` (10 digits), and generic 10–15-digit numeric.
+- **Emails** — `local@domain.tld` (and the user's own specific address explicitly).
+- **UUIDs** — canonical `8-4-4-4-12` hex (and the user's own specific user UUID explicitly).
+- **Clerk-style IDs** — `user_` / `org_` / `ins_` / `sess_` / `cli_` + 20+ chars.
+- **Query-string values** — every `?k=v` / `&k=v` value collapsed to `?k=<v>`.
+- **Long base64 / long hex** — `≥40`-char base64 and `≥32`-char hex (hashes, opaque tokens).
+- **Inline image data URIs** — `data:image/…`.
+- **Provider key prefixes** — Stripe (`sk_`/`rk_`/`pk_`), OpenAI (`sk-`/`sk-proj-`), Slack (`xox*`), AWS (`AKIA`/`ASIA`), GitHub (`gh[pousr]_`), Google (`AIza`).
+
+#### 5. Maintenance loop
+
+When a run uncovers a new key or value shape (a regional BSP / telephony token, a niche analytics SDK key, an internal-tool API, an opaquely-named credential field), **add the regex to the `SCRUB` table here** (and the field name to `SECRET_KEY_RE` if it's name-based) — the layer only stays a real guardrail if every new shape is folded back in.
+
 ### 7.1 wire-capture & active-interception ethics (the strictest tier)
 
 The `wire-capture` dimension climbs a **3-rung ladder, lowest privilege first**, and records the
@@ -191,8 +300,23 @@ chosen rung in `_meta`:
    *user* installs the CA and routes their client — the agent only ingests exported flows. →
    `method: wire-mitmproxy`. Same explicit-authorization loop as session Pass-2.
 
-> **Never fold a browser-rung into a non-browser (curl/WebFetch) dumper.** Rung 1 *is* a browser tap,
-> and the browser is a singleton owned by `session`/`wire-capture` — routing it to a curl dumper
+> **Rung 3+ — the first-party SDK-harness lane (the deepest method for a closed runtime that PUBLISHES
+> an SDK).** When the product ships an official client SDK (npm / PyPI / Maven / …) and the *user* can
+> provision credentials (free tier / trial), the deepest no-source method is not to intercept the
+> *vendor's* app but to **scaffold a minimal throw-away app with the product's OWN SDK + the user's keys,
+> run it, and instrument the client you control**: inject fetch/WS/EventSource taps at `document_start`
+> (so there is **no interceptor-timing problem** — you wrap the constructors before any connection
+> opens), observe every request/response shape, and — with the user routing it through *their own*
+> mitmproxy — the fully-decoded wire. Because you **own** the client, there is no third-party-traffic
+> concern and no missed on-load socket. **Gated exactly like rung 3 / session Pass-2:** the *user*
+> provisions the account + keys and runs any proxy; the **agent never self-signs-up and never enters
+> credentials**, only scaffolds + instruments, and confirms any cost/quota first. → `method: sdk-harness`
+> (a first-party runtime lane; confidence = what is actually observed, typically high since you control
+> the client). Especially powerful for `runtime:reachable + source:none` targets whose published SDK is
+> the only public mirror of the runtime — and it independently corroborates the `api`/`packages` lanes.
+
+> **Never fold a browser-rung into a non-browser (curl/WebFetch) collector.** Rung 1 *is* a browser tap,
+> and the browser is a singleton owned by `session`/`wire-capture` — routing it to a curl collector
 > produces zero `source: wire` rows (a real run did exactly this). When `wire-capture` is **folded**,
 > the rung-1 tap is the **in-page interceptor that `session` already installs**: `session` appends its
 > observed paths to `dimensions/_shared/api-path-catalog.md` as `source: wire`. A folded `wire-capture`
@@ -204,14 +328,14 @@ chosen rung in `_meta`:
 
 ### 7.2 distribution-artifacts ethics
 Downloading a public binary (CRX/`.asar`/`.ipa`/`.apk`) and reading its manifest/strings is fine.
-But binary **decompilation** can cross from "inspect" to "reverse-engineer in violation of EULA":
+But binary **decompilation** can cross from "inspect" to "decompile in violation of EULA":
 the agent reads the artifact's own license/EULA first and records a restrictive one as an Open
 question rather than silently decompiling.
 
 ---
 
 ## 8. Completeness check
-A dump is complete when: `_summary.md` exists with full provenance frontmatter + honest `status`;
+A capture is complete when: `_summary.md` exists with full provenance frontmatter + honest `status`;
 every Finding is backed by a `raw/` artifact or inline value; `raw/` artifacts have `_meta` +
 decoding (large ones digested); redaction pass run; `gaps` recorded (never fabricated).
 
@@ -220,15 +344,26 @@ decoding (large ones digested); redaction pass run; `gaps` recorded (never fabri
 (downloading many chunks, crawling many pages, deep pagination), then enrich it in place and flip to
 `complete`. **Bound** every fan-out — cap it by count / total bytes / wall-time (e.g. ≤40 items or
 ≤90 s) and record the remainder as a `gap` rather than fetching exhaustively; emit a progress note per
-batch. A dumper that fetches everything before writing anything can run many times longer than its
+batch. A collector that fetches everything before writing anything can run many times longer than its
 siblings and read as hung to the orchestrator, forcing a needless salvage. Partial-but-finalized beats
 complete-but-silent.
 
+**Capability gap = a checkpoint, not a silent fallback.** When a *preferred* capture capability is found
+**unavailable at runtime** — a CDP/remote-debugging port is closed, Chrome / the browser MCP is unreachable,
+a gated proxy or tool can't be stood up — such that you would proceed on a **materially weaker** method
+(e.g. source-only or a digest instead of a live wire tap), **pause and confirm with the user before
+continuing.** State plainly: what is unavailable, the degraded method you would fall back to, and the
+coverage that would be lost. This is distinct from a *planned* method pre-grade (e.g. `openapi-verbatim` →
+`docs-reconstructed` when no spec is served), which is **recorded, not confirmed** — the checkpoint is for an
+*infrastructure/capability* gap discovered mid-run, where silently degrading hides a real coverage loss
+behind a confident-looking capture. (A real run found the CDP port closed and silently fell back to a
+browser-MCP tap; it worked, but the degradation should have been surfaced first.)
+
 ---
 
 ## 9. The session dimension — logged-in browser-session playbook
 
-The method for the **session** dimension: reverse-engineering the *authenticated runtime* of a
+The method for the **session** dimension: discovering the *authenticated runtime* of a
 product by driving it through a browser (Chrome MCP) and instrumenting it. It produces a
 section-by-section understanding of a product's wire protocol, auth, and state model **without
 source-code access**. The `session` agent follows this section.
@@ -301,6 +436,11 @@ The same phases apply whether the target is an AI builder, analytics dashboard,
 
 ### 9.4 Runtime taps (Pass-1 instrumentation, run in-page)
 
+> **The runnable taps + the ~27-entry Chrome-MCP gotcha catalogue + the dead-end recovery table + the
+> Apollo read-side recipe + the fingerprint tables live in `tradecraft.md`** — paste them, do
+> not re-derive. The prose below is the *why*; that file is the *keyboard layer*. The §7.0 redaction
+> scrubbers (`SCRUB`/`redactSecrets`/`ULTRA`) install inside these tap wrappers.
+
 > **Install the in-page interceptor FIRST, then move section-to-section WITHOUT a full reload.**
 > CDP `read_network_requests` is unreliable for an already-loaded single-page app: it starts tracking
 > only when first called and silently misses requests already in flight or served from cache (seen on a
@@ -322,6 +462,24 @@ The same phases apply whether the target is an AI builder, analytics dashboard,
   first** — many "binary" protocols are framed text (STOMP, Phoenix, Centrifugo, a `+topic` channel
   prefix), so a legible prefix names the protocol in one step before a binary-codec guess. The frame
   *signature* is the finding; the payload is not.
+  - **Realtime-on-load capture (the connection that opens before you can wrap it).** The "install the
+    interceptor FIRST" rule assumes you are *already on* the target surface; it does **not** cover a
+    realtime connection that fires during the **initial load of a page you `navigate` to** (or a
+    lazy-loaded/`iframe`d live demo). A post-load interceptor **cannot** wrap a `WebSocket`/`EventSource`
+    constructed before injection, and an `offline`→`online`/`focus` reconnect-trigger may spawn no new
+    connection on such a demo — so frame capture comes back empty (a real run got 0 frames on a
+    collab-demo this way). When that happens: (a) capture the **CDP-visible auth/token-mint fetch** that
+    precedes the socket (it names the realtime host/handshake); (b) **the technique that works —
+    client-side-navigate within the SPA** (a router `<Link>` click, not a full reload): the in-page
+    wrapper **survives client-side nav**, and the next route **mounts a fresh room → a new socket through
+    your wrapper** (this captures the handshake + frames where `offline`/`online` reconnect-triggers
+    don't — a real run decoded Liveblocks' v8 JSON protocol this way after a 0-frame first pass); (c) if a
+    raw **CDP `Network.webSocketFrameReceived`** tap is reachable, it captures frames protocol-level with
+    no injection-timing problem at all (the browser MCP's HTTP-only `read_network_requests` does **not**
+    surface WS frames — that gap is what forces (b)); and (d) fall back to the `codebase`/`distribution`
+    lanes for the wire format — record it as a *folded* gap, not a silent miss, since the protocol is then
+    sourced independently rather than live-observed. **Decode captured frames against any in-repo protocol
+    enums** (message-code / op-code tables) so the live wire *validates* the source read.
 - **Storage shape inspector** — enumerate localStorage / sessionStorage / cookies / IndexedDB
   **key names + lengths**, never raw values.
 - **JWT decoder** — decode the token *structure* (alg, claim names, exp) with identity claims
@@ -344,8 +502,19 @@ The same phases apply whether the target is an AI builder, analytics dashboard,
   set, an RPC/tool method list — consume it as a **coverage checklist**: walk the routes/actions that
   trigger the un-observed entries so the declared-vs-observed diff (§6) reflects a real walk, not just the
   landing page.
-
-### 9.5 The capture contract (richer than a standard dimension dump)
+- **Server-side-read (RSC) check — don't mis-record "no read API."** In a modern Next.js App-Router /
+  React-Server-Components app (and similar SSR/streaming stacks), the initial **read** data is fetched
+  *server-side* with the session and streamed — so the client wire shows only mutations, asset/media
+  fetches, telemetry, and token-mints, and **no client-side data-read XHRs fire on load even though the
+  UI is fully populated.** Before recording "read API not observed," check for the server-side path: a
+  document/`?_rsc=` response with `text/x-component`, embedded `__next_f`/flight payloads, `_next/data`
+  JSON, or server actions. When reads are server-resolved, say so — and note that a sibling
+  bundle's app-own *path count* then **overstates the client read surface** (fold this into the
+  published-vs-app-own diff, §6, rather than reporting a phantom "unused routes" gap). (Writes can be
+  off-main-thread too — a generate POST issued from a **Web Worker** won't appear in a main-thread fetch
+  tap; corroborate via CDP / Performance resource timing.)
+
+### 9.5 The capture contract (richer than a standard dimension capture)
 
 Under `research/<target>/dimensions/session/`: