@atlassian/chippy 0.0.0-stage → 0.0.1-beta.1

package/lib/mcp-skill/references/command-surface.md

@@ -0,0 +1,183 @@
+# Chippy command surface
+
+For typed tools with automatic helper startup, use the [MCP adapter](mcp.md).
+This page owns the CLI contract; MCP keeps that implementation available as an
+alternative transport for the main inspection loop.
+
+Map each task to the public shell command that owns it. Run `./scripts/chippy.sh help` from the skill directory for mechanical signatures and [command-output-formats](command-output-formats.md) for exact response shapes.
+
+Every command that contacts the helper must run outside the agent sandbox. The agent runs the command; the user only controls visible browser actions when required.
+
+## Recipe lookup
+
+| Command | Purpose |
+|---|---|
+| `recipes <query...> [--limit N]` | Search the local grep-friendly task corpus without contacting the helper. It defaults to five results and accepts limits from 1 through 20. Each result includes an answer, completion signal, guardrail, and canonical deeper references. |
+
+Use recipe search when the operation or recovery route is not already obvious. It streams `recipes.txt` rather than loading the corpus into memory and ranks exact, prefix, and one-edit typo matches with a small BM25-style scorer. Plain `rg '^id=.*term' references/recipes.txt` or `rg 'term' references/recipes.txt` remains available when deterministic textual matching is preferable.
+
+## Runtime and connection
+
+| Command | Purpose |
+|---|---|
+| `start`, `stop`, `health` | Own the local helper lifecycle and readiness check. `start` backgrounds itself and binds `127.0.0.1`; `start --host 0.0.0.0` binds wide only when the user asks for network access. |
+| `inject-url` | Print the classic `inject.js` URL to stdout and the document-scoped reload warning to stderr. Prefer the ESM import recipe for new injection workflows. |
+| `pages [slice]` | List currently connected pages. This is connection truth. |
+| `recent-pages` | List recently disconnected page summaries for reload/navigation diagnosis. |
+| `page <clientId> [slice]` | Read one connected page with `minimal`, `standard`, or `full` detail. |
+| `snapshot <clientId> [slice]` | Read the helper's latest stored snapshot for a page. Probe `intent` and `comment` survive `minimal`, `standard`, and `full` slices. |
+| `request-snapshot <clientId>` | Ask the connected page to emit a fresh snapshot. |
+| `wait <clientId> [timeoutSeconds]` | Consume the oldest queued user-attached probe annotation, or wait for the next one. Default 300 seconds; valid range 1–1800. This is one cancellable long poll and never changes host hooks or configuration. |
+| `activate`, `deactivate` | Change Chippy activation state for one connected page. |
+| `context-ui <clientId> <on\|off>` | Show or hide context-provider enrichment (for example Jira ownership and error-boundary fields) in the active probe UI, including Storybook marker cards. It defaults to `on`; this command changes the current connected page at runtime. |
+| `ensure-probes`, `clear-probes` | Install or remove probe markers. Preserve probes while they remain evidence. |
+| `show-status`, `hide-status` | Control the page-visible Chippy status message. |
+| `command <type> [clientId]` | Generic command escape hatch. Prefer explicit subcommands. |
+
+## Probe inspection
+
+| Command | Purpose |
+|---|---|
+| `get-computed-style` | Read computed style for a resolved probe target or bounded parent/selector. |
+| `probe-dom` | Read the exact DOM target, text, attributes, source, styles, and test-id boundary. |
+| `probe-parents` | Read the `fiber.return` parent chain from a probe target. This is the production-safe fiber-walk command. |
+| `probe-boundaries` | Read every Error/Suspense boundary from the probe target to the root, ordered inner → outer. |
+| `probe-owners`, `probe-owner` | Read the React debug-build `_debugOwner` chain or one owner by positional index. This is not a production-build parent-chain route. |
+| `probe-props`, `probe-prop-value` | Read serializable props, reference identities, or one named prop at a chosen owner. |
+| `probe-hooks`, `probe-hooks-summary` | Read the hook tree or its prepared compact summary. |
+
+Start value traces with `probe-dom`, then owners, then props. Open the reported source location before searching the repository.
+
+## Fiber inspection and active stimulus
+
+| Command | Purpose |
+|---|---|
+| `find-fibers` | Find current fibers by component name, source file, prop, test-id, or text. |
+| `fiber-state-capture`, `fiber-state-list`, `fiber-state-compare` | Retain compact fiber/prop fingerprints for two rendered states—even on different pages—and return only their bounded structural diff. |
+| `page-boundaries` | Read the whole page as a nested Error/Suspense-only forest. Ordinary component fibers are removed while declarative-boundary containment is preserved. |
+| `explain-component` | Return compact semantic text by default; use `--complexity` for the bounded complexity section or `--json` for the full transport payload. May use dispatcher replay, with status and warnings in the result. |
+| `describe-component` | Return the detailed hook tree as plain text by default; use `--json` for the full transport payload. May use dispatcher replay and degrades to fiber-only evidence when replay is unavailable. |
+| `inspect-fiber-hooks`, `inspect-fiber-hooks-summary` | Read detailed or compact hook data for one fiber. |
+| `inspect-fiber-props`, `inspect-fiber-owners`, `inspect-fiber-parents`, `inspect-fiber-boundaries` | Read props, `_debugOwner`, `fiber.return` parent context, or the complete declarative-boundary chain for one remembered fiber after `explain-component` or `find-fibers` yields a `fiberId`. |
+| `inspect-fiber-structure` | Return one hook and its neighboring folder structure; may use dispatcher replay and reports replay warnings. |
+| `page-click` | Click exactly one resolved DOM target. Active stimulus; requires an anchor contract. |
+| `fiber-prop-contract` | Inspect a function prop before invocation. Read-only. |
+| `fiber-invoke` | Invoke one proven function prop, optionally with JSON arguments. Active stimulus. |
+| `fiber-schedule-update` | Schedule one DevTools renderer update on a current composite fiber. Active stimulus; does not mutate a hook or prop. |
+
+Run the [debug replay preflight](active-stimulus.md#debug-replay-preflight) before `explain-component`, `describe-component`, or `inspect-fiber-structure`.
+
+Load [active-stimulus](active-stimulus.md) before an active command. A `fiber:*` token lives in the current page realm, but React may replace the current fiber after any commit. Re-run `find-fibers` after state changes, interactions, HMR, navigation, or reload instead of assuming a remembered token still points at the current alternate.
+
+## Avalanche capture and analysis
+
+| Command | Purpose |
+|---|---|
+| `avalanche-clear` | Clear capture history before a new bounded measurement. |
+| `avalanche-status` | Read installation, capture, and commit-count state. |
+| `avalanche-install`, `avalanche-recapture` | Install with fiber capture or reinstall and clear in one sequence. |
+| `avalanche-arm`, `avalanche-disarm` | Control live interaction capture without reloading the page. |
+| `reload-with-avalanche` | Arm, reload, wait, settle, and print initial-load evidence. |
+| `avalanche-hot-sources` | Rank source families before opening commit detail. |
+| `avalanche-commit-list` | Rank compact commits by a supported signal. |
+| `avalanche-commit-peek` | Join bounded detail for one commit. |
+| `avalanche-describe-action` | Expand one action breadcrumb and its owner/parent context. |
+| `avalanche-debug-hook` | Interrogate one captured `sourceId + hookIndex`. |
+| `avalanche-export` | Return the full export or last N commits. Do not open this first. |
+| `avalanche-save` | Save a full or bounded export for repeated offline analysis. |
+| `avalanche-offline` | Run `summary`, `commit-list`, `commit-peek`, `hot-sources`, `describe-action`, or `source-search --name` over a saved export; shapes match the live commands. |
+
+### Capture modes
+
+| Mode | Use it for | Boundary |
+|---|---|---|
+| `sources` | Default source and commit attribution | No per-component `renderedByCommit` evidence |
+| `full` | Per-component render, prop-change, and trasher evidence | Higher collection cost |
+| `stats` | Aggregate capture statistics | No source or rendered detail needed |
+| `amplifiers` | Amplifier-focused capture | Specialized analysis; load Avalanche reference first |
+
+`avalanche-arm` and `reload-with-avalanche` also accept `captureFibers=true|false`. Keep it `true` when debug-hook or fiber-backed analysis may follow.
+
+### Commit selectors
+
+`avalanche-commit-list` live `by` values are `collateral`, `sources`, `restarts`, `performedWork`, `effects`, `memos`, `callbacks`, `contextUpdates`, `unmountedComponents`, and `unmountedSubtrees`.
+
+`avalanche-commit-peek` live `include` values are `stats`, `sources`, `timing`, `metrics`, `unmounts`, `actions`, and `rendered`; `atl` is a deprecated alias of `metrics`. `rendered` requires `detectionMode=full`.
+
+Load [avalanche-detector](avalanche-detector.md) for schemas and evidence-reading rules.
+
+## Snippets, navigation, and automation
+
+| Command | Purpose |
+|---|---|
+| `eval-snippets` | List packaged snippets. |
+| `eval-page` | Execute one packaged or local snippet in the connected page realm with `--key value` arguments. |
+| `page-reload`, `page-wait-reload` | Request a reload and wait for the helper's reconnect transition. For a Storybook integration, `page-reload` emits `FORCE_REMOUNT`, remounting only the current SUT without navigating the preview iframe. |
+| `handoff-to-playwright` | Transfer a connected page URL and selected probes into a Playwright session configuration. |
+| `proxy-state`, `proxy-start`, `proxy-stop` | Inspect or control the helper's local proxy. |
+
+`eval-page` has a fixed five-second page-script timeout through the shell wrapper. The helper HTTP API accepts a timeout field, but `chippy.sh eval-page` does not expose a timeout option.
+
+## Full signatures
+
+```text
+start | stop | health | inject-url
+recipes <query...> [--limit N]
+pages [slice] | recent-pages | page <clientId> [slice]
+snapshot <clientId> [slice] | request-snapshot <clientId>
+wait <clientId> [timeoutSeconds]
+activate <clientId> | deactivate <clientId>
+context-ui <clientId> <on|off>
+ensure-probes <clientId> | clear-probes <clientId>
+show-status <clientId> <text> | hide-status <clientId>
+command <type> [clientId]
+get-computed-style <clientId> <probeId> [parentLevel] [selector]
+probe-dom <clientId> <probeId> [parentLevel]
+probe-parents <clientId> <probeId> [max]
+probe-boundaries <clientId> <probeId> [max]
+probe-owners <clientId> <probeId>
+probe-owner <clientId> <probeId> <ownerIndex>
+probe-props <clientId> <probeId> [ownerIndex]
+probe-prop-value <clientId> <probeId> <propName> [ownerIndex]
+probe-hooks <clientId> <probeId>
+probe-hooks-summary <clientId> <probeId>
+page-click <clientId> <selector|probeId|fiberId>
+fiber-prop-contract <clientId> <fiberId> <propName>
+fiber-invoke <clientId> <fiberId> <propName> [--args JSON]
+fiber-schedule-update <clientId> <fiberId> [--ownerIndex N]
+find-fibers <clientId> [--name regex] [--file regex] [--prop name] [--testid regex] [--text regex] [--max N]
+fiber-state-capture <clientId> [label] [maxFibers]
+fiber-state-list
+fiber-state-compare <beforeCaptureId> <afterCaptureId> [maxChanges]
+page-boundaries <clientId> [max]
+inspect-fiber-hooks <clientId> <fiberId>
+inspect-fiber-hooks-summary <clientId> <fiberId>
+inspect-fiber-props <clientId> <fiberId>
+inspect-fiber-owners <clientId> <fiberId>
+inspect-fiber-parents <clientId> <fiberId> [max]
+inspect-fiber-boundaries <clientId> <fiberId> [max]
+inspect-fiber-structure <clientId> <fiberId> <hookIndex> [windowSize]
+describe-component <clientId> <fiberIdOrName> [--text|--json]
+explain-component <clientId> <probeId|fiberId|name> [--text|--json|--complexity]
+avalanche-clear <clientId>
+avalanche-status <clientId>
+avalanche-export <clientId> [lastN]
+avalanche-hot-sources <clientId> [limit]
+avalanche-commit-list <clientId> [top] [by]
+avalanche-commit-peek <clientId> <commitId> [include] [depth] [maxItems]
+avalanche-describe-action <clientId> <actionId>
+avalanche-install <clientId> [detectionMode]
+avalanche-recapture <clientId> [detectionMode]
+avalanche-debug-hook <clientId> <sourceId> <hookIndex> [window]
+avalanche-save <clientId> <file> [count]
+avalanche-offline <file> <summary|commit-list|commit-peek|source-search> [args...]
+eval-page <clientId> <snippet-file-or-name> [--key value ...]
+eval-snippets
+avalanche-arm <clientId> <origin> [maxCommits] [captureFibers=true|false] [detectionMode=sources|full|stats|amplifiers]
+avalanche-disarm <clientId> <origin>
+page-reload <clientId>
+page-wait-reload <clientId> [timeoutMs]
+reload-with-avalanche <clientId> <origin> [maxCommits] [timeoutMs] [settleMs] [captureFibers=true|false] [detectionMode=sources|full|stats|amplifiers]
+handoff-to-playwright <clientId> [url] [probeIdsCsv] [browserName] [headless]
+proxy-state | proxy-start <targetPort> [originalUrl] | proxy-stop
+```

package/lib/mcp-skill/references/cynefin.md

@@ -0,0 +1,99 @@
+# Cynefin positioning and OODA iteration for Chippy
+
+Cynefin (Snowden) positions a situation by the relationship between cause and effect. OODA drives the evidence iterations after that position is known. Chippy uses them together:
+
+> **Position with Cynefin; iterate with OODA; Apply only through the proof gate.**
+
+Every task starts unpositioned in ❓ Disorder. Mise en Place may run the read-only orientation needed to obtain the first concrete signal: `health`, `pages`, `request-snapshot`, and reads of existing probe state. Use that signal to name the initial domain before investigative stimuli, diagnosis, or source edits. Position once for the current evidence state; reposition only when evidence changes the cause/effect posture or the runtime becomes unstable.
+
+This is not theory. It is a guard against the two recurring Chippy failure modes:
+
+1. Treating a 🌀 Complex situation as ✅ Clear — confidently applying a one-line fix to an emergent cascade.
+2. Reading data from a 🔥 Chaotic surface — trusting a stale snapshot, a disconnected helper, or a mid-reload page.
+
+## The five domains
+
+### ✅ Clear (Obvious)
+
+- **Cause/effect:** known, repeatable, visible to everyone.
+- **Disposition:** sense → categorize → respond. Apply best practice. No deliberation.
+- **Chippy signature:** `probe-dom` resolves to one fiber with `source.fileName` + `lineNumber`. `probe-prop-value` returns a scalar that matches the user's words. The owner chain has one obvious carrier.
+- **Verb:** open file, read line, answer.
+- **Failure mode:** over-deliberating a Clear case — describing the component, arming Avalanche, spinning subagents when the answer is one `probe-dom` away.
+
+### 🔍 Complicated
+
+- **Cause/effect:** knowable, but requires expertise and analysis. Multiple defensible answers may exist.
+- **Disposition:** sense → analyze → respond. Apply good practice.
+- **Chippy signature:** prop forwarding crosses several hops. A hook tree has 50+ hooks. A commit list shows a clear hot source but the upstream trigger needs walking. The probe data is real and stable; the question is *which* documented chain to follow.
+- **Verb:** investigate with documented commands — `probe-owners`, `describe-component`, `avalanche-commit-list` + `commit-peek`, `find-fibers`, source open at exact lines.
+- **Failure mode:** treating Complicated as Complex — running speculative experiments when a careful read of existing data would answer the question.
+
+### 🌀 Complex
+
+- **Cause/effect:** emergent. No right answer up front. The answer is only visible *after* the system has been perturbed.
+- **Disposition:** probe → sense → respond. Run **safe-to-fail experiments** and watch what emerges.
+- **Chippy signature:** re-render cascades, avalanche storms, store-wave propagation, hook-order surprises, timing-dependent stability, "this only happens after the third click." The system has too many interacting parts to predict from static reading.
+- **Verb:** create the **observable SUT**. Build the smallest tapped white-box test or `eval-page` snippet that exposes the internals. Arm Avalanche, perform the stimulus under an anchor contract, read the emergent signal.
+- **Tap contract, one step at a time.** For no-rush Complex/Complicated work, tap one stable contract seam, observe whether the target signal moves there, then choose the next step. Each step should move, reproduce, or falsify the observed failure before a permanent fix is chosen.
+- **Safe-to-fail criteria:** the experiment is bounded (timeout, commit cap), reversible (no source mutation, or HMR-reverted), and instrumented (you can read the result without re-running). Active-stimulus commands (`page-click`, `fiber-invoke`, `stability-nudge`) declare an anchor contract — what they touch, what becomes opaque, what the caller must guarantee.
+- **Confidence:** emergent systems usually return `likely` or `partial`. If certainty is required, run another bounded experiment and compare the same signal.
+
+### 🔥 Chaotic
+
+- **Cause/effect:** none discernible. The surface is moving.
+- **Disposition:** act → sense → respond. Stabilize first, analyze later.
+- **Chippy signature:** helper disconnected, `clientId` stale, page mid-reload, avalanche unbounded and still capturing, snapshot older than the last interaction, HMR in flight.
+- **Verb:** stabilize the runtime — reload, reconnect, `health` → `pages` → `request-snapshot`, get a clean baseline. **Only then** read a signal.
+- **Failure mode:** reading any signal from a chaotic surface. Stale data from chaos is worse than no data — it produces confident-sounding but wrong conclusions.
+
+### ❓ Disorder / Confusion
+
+- **Cause/effect:** not yet known. The domain itself is unclassified.
+- **Disposition:** **orient read-only, then classify before investigating or mutating.** Every Chippy task starts here.
+- **Chippy signature:** the user just said a thing. No probe yet. No snapshot. No domain.
+- **Verb:** **Mise en Place** — stage the page, run the runtime ceremony (`health` → `pages` → `request-snapshot`), look at the first concrete signal, then declare which of the four real domains this task lives in.
+- **Failure mode:** diagnosing, stimulating, or editing from Disorder. Read-only orientation is permitted; treating an unpositioned signal as proof is not.
+
+## OODA inside the named domain
+
+Cynefin chooses the class of move. OODA chooses and evaluates the next concrete move:
+
+| OODA step | Chippy contract |
+|---|---|
+| **Observe** | Read the smallest current runtime, structure, source, or signal fact. |
+| **Orient** | Compare it with the named domain, case invariant, existing evidence, and exact proof gap. |
+| **Decide** | Choose one move allowed by the domain: recognize, analyze with a sensor, run a bounded experiment, or stabilize. |
+| **Act** | Execute exactly that move, record what changed or was falsified, then observe again. |
+
+OODA **Act** is not Chippy **Apply**. An OODA action may be a read-only probe, source read, analysis command, bounded active stimulus, or runtime stabilizer. It grants no independent permission to mutate the page or edit source. Active stimuli still require an anchor contract; source edits still require the [operating-model](operating-model.md) Apply gate and user intent.
+
+Use one OODA cycle for a Clear answer and as many bounded cycles as the proof gap requires for Complicated or Complex work. In Chaotic work, the domain's act-first stabilizer runs before the normal evidence loop. Reposition when a cycle proves that the current domain no longer fits; do not relabel the task after every command.
+
+## Mapping to Chippy primitives
+
+| Chippy concept | Position or iteration role |
+|---|---|
+| Mise en Place | Read-only orientation that exits ❓ Disorder. |
+| OODA | Repeat the next evidence move inside the named domain. |
+| `probe-dom`, `probe-owners`, `probe-props` (read-only) | **Sensors** for ✅/🔍. |
+| `describe-component`, `find-fibers`, `inspect-fiber-structure` | **Analysis tools** for 🔍. |
+| `avalanche-arm`, `avalanche-commit-list`, `eval-page` snippets, tapped white-box tests | **Experiments** for 🌀. |
+| `page-click`, `fiber-invoke`, `stability-nudge` | **Active-stimulus experiments** for 🌀 — require anchor contract. |
+| `reload-with-avalanche`, `health` after disconnect | **Stabilizers** for 🔥. |
+| Proof packet `confidence` field | Confidence reports the domain implicitly: `confirmed` = ✅/🔍, `likely`/`partial` = 🌀, missing = ❓. |
+| Apply gate | Separates source editing from OODA Act. |
+
+## Cross-domain anti-patterns
+
+- **Clear-in-Complex:** confident one-line edit against an emergent cascade. Symptom: "this is probably the cause" without an experiment.
+- **Complicated-in-Chaotic:** carefully analyzing a snapshot that is already stale. Symptom: reading a `clientId` from a prior turn instead of re-snapshotting.
+- **Complex-in-Complicated:** spinning up experiments and avalanche captures when a documented `probe-owners` chain would resolve the question. Symptom: token-budget burn with no new signal.
+- **Investigating-from-Disorder:** diagnosing, stimulating, or editing before read-only orientation establishes a domain. Symptom: treating the first unpositioned signal as proof.
+
+## Cross-references
+
+- [operating-model](operating-model.md) — phase contracts. Observe exits Disorder, Prove contains the OODA evidence loop, and Apply remains independently gated.
+- [stability-render](stability-render.md) — canonical observable-SUT play for Complex stability questions.
+- [bdd-router](bdd-router.md) — selects the procedure once the domain is named.
+- [active-stimulus](active-stimulus.md) — anchor-contract rules for safe-to-fail experiments.

package/lib/mcp-skill/references/debug-hook.md

@@ -0,0 +1,161 @@
+# Debug-hook
+
+Fiber-to-source hook locator. Resolves a single hook on a single committed source: not just what primitive hook it is, but **how to find that hook in source** when React only gave you a flat primitive index like `230`.
+
+Not a profiler. Not a source finder for the component itself. Not a wave analyzer. A focused **locator/interrogation tool** for a hook you already suspect.
+
+Lifecycle stage: **hook localization after triage/experiment**. Enter only when a prior commit analysis or stability-render result already gives a `sourceId` and changed `hookIndex`.
+
+Exit when you can walk from the known component source to the target hook using the output: primitive kind, custom-hook parent folders, relative order, and any `useDebugValue` landmarks. Then return to [fixing-performance](fixing-performance.md) for fix-layer choice, or to provider/context analysis if the result is `Context`/`partial`.
+
+Purpose: React fibers store only the real primitive hook chain. They do not preserve the nested custom-hook structure developers read in source. `debug-hook` exists to bridge that gap. Given a known source component and a primitive hook index, it should reconstruct enough nested structure — component → custom hooks → primitive hooks, plus relative landmarks such as `useDebugValue` — that Chippy can say *which* `useMemo` / `useState` / `useSyncExternalStore` to inspect in code.
+
+Capability boundary: debug-hook does **not** find the component source from scratch. It starts from a component/source location already known from prior Chippy/Avalanche evidence. Its job is to convert a flat fiber hook coordinate into a source-walkable path inside that known component.
+
+## When to use
+
+Use after **another tool already pointed at a source and a changed hook index**:
+
+- avalanche commit-peek surfaced a hot/source component with a changed hook index
+- stability-render shows leak/cascade isolated to a single source
+
+Do not use to:
+
+- find sources (`avalanche-hot-sources`, `avalanche-commit-list`)
+- find triggers / waves (`fixing-performance`)
+- grade a subtree (`stability-render`)
+- read all hooks on a fiber (this tool answers about **one** hook + its near neighbors)
+
+## Inputs
+
+- `sourceId` — public id from a report (e.g. `StoreReader#1@6`)
+- `hookIndex` — fiber `memoizedState` index of the changed hook
+- `windowSize` — included neighborhood radius around the target index. Default `3`. Operationally: hook is included when `|hook.index - target| <= windowSize`.
+
+## Read order
+
+Always read the output in this order. Stop at the first step that gives you the answer.
+
+1. `target.primitive` — chooses the remediation branch entirely. Read first.
+2. `target.value` — current committed hook value summary. This is now the primary evidence.
+3. `parents` — custom-hook owner chain if available. Can be empty in the working fiber-chain reconstruction.
+4. `target.debugValues` — semantic labels if available.
+5. `neighborhood[*].debugValues` — labels on adjacent hooks when available.
+6. `flat` — one-liner summary for log-scrolling humans, not for decisions.
+
+## Field semantics
+
+- `target.primitive` — primitive React hook kind: `SyncExternalStore`, `State`, `Reducer`, `Memo`, `Callback`, `Effect`, `LayoutEffect`, `Ref`, `Context`, `DebugValue`, `Id`, `ImperativeHandle`, `InsertionEffect`, `DeferredValue`, `Transition`, `CacheRefresh`, `MemoCache`, `Unknown`.
+- `parents` — custom-hook owner chain when available from hook metadata. **Empty parents does not mean failure**: it can mean the target hook is called directly inside the component, or that the current reconstruction only knows the component frame. Empty `parents` + non-empty `target` is still `confirmed`.
+- `neighborhood` — primitive hooks within `windowSize` of the target.
+- `confidence` — tri-state. See below.
+- `reconstruction` — tells you which runtime strategy produced the answer. Current working path is `fiber-hook-chain + _debugHookTypes`.
+
+## Confidence
+
+The API field `confidence` is binary: `confirmed | partial`. A third logical state — *unknown* — is not a `confidence` value; it is signaled by `ok: false` or a present `renderError`. Read all three together.
+
+| state | how to detect | next |
+|---|---|---|
+| `confirmed` | `ok: true`, `confidence: 'confirmed'`, `target` resolved, no `renderError`. | act on remediation table. |
+| `partial` | `ok: true`, `confidence: 'partial'`, no `target` (index out of range, `Context`, `DebugValue`, or `MemoCache` cell). | re-pick `hookIndex`, or switch to provider/context analysis. |
+| *unknown* (logical) | `ok: false` or `renderError` present. | report `renderError`. Do not infer cause. Re-run once if it looks transient; otherwise raise it as a tool gap. |
+
+## What to do next, by primitive
+
+- **SyncExternalStore** — external store fired. See *Root causes / remediations*.
+- **State / Reducer** — in-component update. Trace the `setX` / `dispatch` caller. Two sub-cases:
+  - value churn — the new state is genuinely different.
+  - identity churn — `dispatch` / `setX` is treated as identity-stable, but the consumer received a new object (e.g. a closed-over reducer rebuilt every render). Check whether the dispatcher itself is recreated.
+- **Memo / Callback** — identity churn. Inspect the deps array; an object/function/array rebuilt each render is the usual cause.
+- **Effect / LayoutEffect / InsertionEffect** — side-effect ran. Inspect deps. Effect *running* is rarely the perf cause; the effect's body is. If body calls `setState`, jump to State cascade.
+- **Ref** — mutation, not a render cause. Mark benign.
+- **Context** — has no fiber `memoizedState` slot you can index. Switch to provider-side analysis (`stability-render` on the provider value).
+- **DebugValue / Id / MemoCache** — diagnostic / structural slots. Not a cause. Re-pick `hookIndex`.
+- **DeferredValue / Transition / CacheRefresh** — concurrent-mode primitives. Treat as advisory; cause is upstream.
+- **ImperativeHandle** — handle re-creation; rare cause.
+- **Unknown** — hook shape did not match any classifier. Report as a debug-hook gap; do not guess.
+
+## Root causes / remediations
+
+Mutually exclusive rows. Pick by `target.primitive` and the **detection** column. Detection columns may mention `debugValues` fields such as `selector`; use them only when the source already emits those labels. When labels are absent, join the primitive and value with the known component's hook call order. If that still cannot distinguish the call site, report the localization gap rather than editing source during Prove.
+
+| Primitive | Root cause | Detection (from debugHook output) | Remediation |
+|---|---|---|---|
+| SyncExternalStore | **over-broad subscription** | `target.value` differs each commit *and* differs by fields the consumer doesn't read; debugValues `selector` returns a wide slice (object/array of many keys). | Narrow the slice to only fields the consumer reads. Return primitives where possible. |
+| SyncExternalStore | **selector returns wrong identity** | `target.value` deep-equals previous but identity differs each commit (new object/array literal); debugValues `selector` ends in `map`/`filter`/`{...}`/`[...]`. | Stable selector: memoize, return a primitive, or subscribe with shallow-equal. |
+| SyncExternalStore | **store mutation rate too high** | identity *and* value change, debugValues store is shared, multiple unrelated sources hit the same store on the same commit. | Split store, debounce writes, or move the read closer to the consumer. |
+| State / Reducer | **unconditional setState in render or layout effect** | repeated `confirmed` debugHook results on the same source per interaction; State value oscillates / monotonic-grows each commit. | Hoist or guard the update. Remove the avoidable setState. |
+| State / Reducer | **dispatcher identity churn** | State *value* unchanged but consumers below re-render; reducer object recreated per render. | Stabilize reducer/dispatcher identity (module scope or `useRef`). |
+| Memo / Callback | **deps contain a recreated reference** | `target.primitive` is Memo/Callback on a hot source; debugValues / context show a parent re-rendering with new object/function props. | Stabilize deps (lift constants, memoize source object, switch to primitive deps). |
+| Effect / LayoutEffect | **deps churn** | Effect runs every commit; deps array contains a recreated reference. | Stabilize deps. Then verify the effect is needed at all. |
+| Context | **provider value identity churn** | `target.primitive` is Context (or provider rendered directly above the source); value identity differs commit-over-commit. | Memoize provider value or split context. Use `stability-render` on the provider to verify. |
+| Ref | none — benign | `target.primitive` is Ref. | No action. |
+| Unknown | classifier gap | `target.primitive === 'Unknown'`. | Report as debug-hook gap. Do not invent a cause. |
+
+## Read existing `useDebugValue` landmarks
+
+Use the existing output. No source edits.
+
+**Stop (you have the answer) when all hold:**
+
+- `target.primitive` is a single concrete kind (not `Unknown`, not `MemoCache`).
+- `target.value` is a primitive, OR a stable reference already named in `debugValues`.
+- `parents` either names the custom hook you expected, OR is empty *and* the source component itself is the owner you expected.
+- you can name the store / state / memo this hook represents in one sentence using the data shown.
+
+**The runtime result is insufficient if any hold:**
+
+- `parents` is generic-only (`["useState"]`, `["useReducer"]`) and you cannot tell which logical hook it represents. (Empty `parents` + recognizable source name is *not* this case — that's a stop, see Phase A above.)
+- `target.value` renders as `[object]`, `[function]`, `[array:N]` and the identity matters for the question.
+- multiple sibling hooks in `neighborhood` have the same primitive and you cannot tell them apart.
+- repeated triggers produce identical-looking output and existing labels do not distinguish the call sites.
+
+When the runtime result is insufficient, open the already-known component source and align the primitive with hook call order, custom-hook calls, and the returned neighborhood. If more than one call site still fits, return `confidence: partial` with the exact ambiguous calls. Adding diagnostic source labels is a separate, user-authorized change and must pass the normal P-15/P-16 edit gate before it occurs.
+
+## Playwright verification path
+
+Use this exact flow when verifying debug-hook under Playwright without the browser extension. Playwright is a contract here, not a specific runner. Runtime globals must match the names defined in the Chippy skill's **Runtime globals contract** — only `window.__CHIPPY` and `window.__AVALANCHE__` (with the trailing `__`) are valid.
+
+Prerequisites (do not skip):
+
+- Chippy helper is running (`chippy.sh start`, `chippy.sh health` ok).
+- The target page is being served and can be opened by Playwright.
+
+Steps:
+
+1. Install the helper-served devtools-hook shim with `addInitScript` before navigation, then open the exact target page in Playwright.
+2. Inject `inject.mjs` (preferred), or inject `inject.js` followed by `avalanche.iife.js`.
+3. Verify the connection with `chippy.sh pages` and pick the matching `dev` client for that page URL.
+4. Run `chippy.sh avalanche-install <clientId>`; loading `window.__AVALANCHE__` does not install the detector in Mode A.
+5. Run `chippy.sh avalanche-clear <clientId>`, then replay one trigger through Playwright.
+6. Read runtime source evidence from `avalanche-hot-sources` / `avalanche-commit-peek`.
+7. Run `chippy.sh avalanche-debug-hook <clientId> <sourceId> <hookIndex> 3`.
+
+Do not treat missing top-level `__chippyPageBridge` as an injection failure. In this mode the reliable checks are `window.__CHIPPY` in the page, `window.__AVALANCHE__` after step 4, and the matching client appearing in `chippy.sh pages`. Any other global name (e.g. `window.__avalanche`) is wrong by contract.
+
+## Recovering from `source fiber unavailable`
+
+debug-hook needs the detector to retain fibers. If the response is:
+
+```
+{ ok: false, error: "source fiber unavailable; install with captureFibers=true" }
+```
+
+the current capture cannot answer debug-hook. No reload is required:
+
+1. Re-install the detector with fiber capture on the live page:
+   `chippy.sh avalanche-install <clientId>` (uses `captureFibers=true`, `detectionMode=sources`).
+2. Clear and reset history if needed: `chippy.sh avalanche-recapture <clientId>` does install + clear + status in one call.
+3. Reproduce the trigger:
+   - Interactive (extension): ask the user to redo the same interaction so the new detector observes it.
+   - Playwright: re-run the same Playwright step that produced the symptom.
+4. Re-run `avalanche-debug-hook` with the same `sourceId` + `hookIndex`.
+
+Never preload-only. Fiber capture is a runtime setting and can be activated at any time; only the *next* capture window contains fiber data.
+
+## Limits
+
+- Minified production: `parents` degrade — function names collapse to short aliases or empty strings. Primitive classification still works.
+- Current working implementation reconstructs from the fiber hook chain plus `_debugHookTypes`. That makes primitive/value output reliable, but custom-hook ownership can be shallower than the ideal replay-based form.
+- `Context`, `DebugValue`, `MemoCache` do not occupy indexable `memoizedState` slots in the way the other hooks do; expect `partial` confidence if `hookIndex` lands on them.