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

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

@@ -0,0 +1,199 @@
+# Hook metrics — `setStateCount` + the hook-update tracker
+
+Reference for the two snippets that consume the react-dom patch's hook metrics:
+`hook-metrics` (read-only) and `hook-tracker` (drives the `onHookUpdate` callback).
+They belong to the ATL plugin: they read the ATL adapter's `__ATL_REACT_METRICS`
+slot and need Atlassian's patched `react-dom` to report anything.
+
+These are the **why** layer under Avalanche. Avalanche tells you *what* re-rendered and
+*how much collateral* a commit caused. Hook metrics tell you *why a component's work
+repeated*: how many state dispatches were scheduled, and which memo/callback/effect slots
+recomputed because their deps actually changed. ~99% of the time you reach for these
+**after** an Avalanche capture has already named a hot component.
+
+## What the patch emits
+
+The react-dom patch adds exactly two hook-related surfaces to the host metrics object
+`__ATL_REACT_METRICS`:
+
+| Surface | Kind | Meaning | Where it fires |
+|---|---|---|---|
+| `setStateCount` | plain counter | `useState`/`useReducer` **dispatches scheduled** | `dispatchSetState` / reducer dispatch, bumped unconditionally (`m.setStateCount++`) |
+| `onHookUpdate(fiber, kind, slot)` | callback slot | one memo/callback/effect **recomputed because its deps changed** | update path only, *after* the deps-equality check — never on mount, never when deps were equal |
+
+Hook kinds are numeric on the hot path: **`1 = memo`, `2 = callback`, `3 = effect`**.
+
+**The metrics object is host-owned.** The patch never creates it and never stores hook
+history — it only *bumps a counter* and *calls a callback if one is present*. This is the
+core distinction from Avalanche:
+
+- **Avalanche** installs everything for itself (`window.__AVALANCHE__`, its own detector).
+- **Hook metrics** are emitted by the patched runtime into a slot the *app* owns. Chippy
+  **reads** `setStateCount`, and **installs one thing** — the `onHookUpdate` callback — the
+  same way the patch's own `hookTracker.ts` is meant to be installed independently.
+
+### `setStateCount` caveats
+
+- The host may seed `setStateCount` as `null`. The patch then does `null++` → `NaN`. Once
+  numeric it is monotonic-per-run. `hook-metrics` reports `setStateCountValid:false` and a
+  note when it sees a non-finite value instead of pretending it is a clean counter.
+- Some hosts **wipe** `__ATL_REACT_METRICS` to
+  `undefined` after hydration. `hook-metrics` reports `present:false, wiped:true`. The
+  `hook-tracker install` action **seeds a minimal object** in that case so the tracker can
+  still own `onHookUpdate` — it never overwrites an existing host object.
+
+## `hook-metrics` — read-only
+
+```bash
+./scripts/chippy.sh eval-page <clientId> hook-metrics
+./scripts/chippy.sh eval-page <clientId> hook-metrics --keys setStateCount,contextUpdateCount,totalCommitCount
+./scripts/chippy.sh eval-page <clientId> hook-metrics --raw     # every own key, functions tagged
+```
+
+Returns `{ present, wiped, setStateCount, setStateCountValid, onHookUpdateInstalled, counters:{…} }`.
+Use it to read the current dispatch volume without installing anything. If `present:false`,
+the host hasn't created the object yet (or wiped it) — use `hook-tracker install` to own the
+slot regardless.
+
+## `hook-tracker` — drive the hook-update tracker
+
+State persists across calls on `window.__CHIPPY_HOOK_TRACKER`, because install / reproduce /
+read / uninstall are separate `eval-page` invocations.
+
+```bash
+CID=<clientId>
+./scripts/chippy.sh eval-page $CID hook-tracker --action install          # own onHookUpdate, mode=counts
+./scripts/chippy.sh eval-page $CID hook-tracker --action mode --mode debug # carry fiber refs for source locations
+#   ... reproduce the interaction (user gesture, or Playwright clicks) ...
+./scripts/chippy.sh eval-page $CID hook-tracker --action counts            # source of truth, compact
+./scripts/chippy.sh eval-page $CID hook-tracker --action histogram --buckets 3,6,11
+./scripts/chippy.sh eval-page $CID hook-tracker --action offenders --threshold 10
+./scripts/chippy.sh eval-page $CID hook-tracker --action uninstall         # restore slot (only if still owned)
+```
+
+### Actions
+
+| Action | Effect |
+|---|---|
+| `install` | seed metrics if absent, set `onHookUpdate = record`, mode → `counts` |
+| `mode --mode off\|counts\|debug` | `off` no-ops; `counts` aggregates; `debug` additionally keeps the last fiber per type so `offenders` can report source file:line |
+| `status` | installed?, mode, whether we still own the slot, entry count, current `setStateCount` |
+| `counts` | per component-type: `{ totalUpdates, activeSlots, slots:[{slot,count,kind}] }`, sorted |
+| `histogram --buckets a,b,c` | DB-safe: for each kind, count of `type:slot` identities whose total reached each bucket |
+| `offenders --threshold N [--top M]` | dev-only: slots with `count > N`, carrying component name + source (needs `debug` mode) |
+| `reset` | clear counts, stay installed |
+| `uninstall` | restore `onHookUpdate` **only if we still own it**; retains last counts for a final read |
+
+### Reading the numbers
+
+- Counts aggregate by **component type**, not per instance — 100 rows of the same list item
+  collapse into one entry. This is intentional (type-level hotspots), matching `hookTracker.ts`.
+- `counts[slot]` is how many times that hook slot recomputed. `type[slot]` is the numeric kind.
+- **Use `counts`/`histogram` in prod-like runs; `offenders` only in dev**, since minified
+  bundles have no readable hook ids or source.
+- A slot with a high count = a memo/callback/effect whose **deps keep changing**. That is
+  dependency churn, and it is usually an unstable identity upstream (a new object/array/
+  function created every render), not a bug in the memo itself.
+
+## Lighthouse numbers vs Avalanche — the cost argument
+
+The most useful framing for these metrics is **lighthouse numbers**: cheap integer
+counters you could sample on every hydration and every route transition and forward to a
+dashboard, for *real users in realtime*.
+
+- **Avalanche** hooks React at a low level (`onCommitFiberRoot` + full fiber walk per
+  commit). It sees the whole picture — collateral, penetration depth, context waves,
+  unmount branches — but that instrumentation is far too expensive to leave on for every
+  user. It is an *on-demand debugger*.
+- **The patch's metrics** are just `count++` inline in react-dom plus one optional
+  callback. Reading `setStateCount` is reading an integer. That is cheap enough to ship.
+
+So the two are not competitors — they sit at opposite ends of a cost/detail axis:
+
+| | `setStateCount` / hook-tracker | Avalanche |
+|---|---|---|
+| Cost | integer read / one callback | full fiber walk per commit |
+| Detail | counts only (no tree, no collateral) | complete commit graph |
+| Realtime / all-users | yes (lighthouse) | no (on-demand only) |
+| Answers | "how much settling happened" | "what re-rendered and how far it spread" |
+
+## `hook-metrics-sample` — labeled before/after delta in one call
+
+The "lighthouse number" as a first-class read. Sample the counter, optionally click a
+`data-testid`, sample again, return the delta:
+
+```bash
+./scripts/chippy.sh eval-page <clientId> hook-metrics-sample --label hydration --settleMs 500
+./scripts/chippy.sh eval-page <clientId> hook-metrics-sample --label tick --click tick --clicks 4
+```
+
+Returns `{ available, label, before, after, delta, clicked, settleMs }`. **Metric-optional:**
+if the patch is absent / wiped / `NaN` it returns `{ available:false, reason }` and never
+throws.
+
+## Avalanche integration — `setStateCount` per commit
+
+When the react-dom patch is present, Avalanche now records `setStateCount` **per commit** as
+an optional field on the ATL commit delta (`ATLCommitDelta.setStateCount`,
+`ATLCommitDeltaDTO.setStateCount`). Read it with:
+
+```bash
+./scripts/chippy.sh avalanche-commit-peek <clientId> <commitId> atl
+# → "atl": { ..., "setStateCount": 12 }
+```
+
+**Optional and self-degrading.** It is computed only when `__ATL_REACT_METRICS` is live at
+commit time (`atlDeltaAvailable`), and the delta line is omitted entirely when neither
+snapshot carries a numeric `setStateCount` — so on an unpatched host the field is simply
+absent, never a bogus `0`. Every other ATL delta field can be `null` while `setStateCount`
+is a real number; they are independent.
+
+A sequence such as **1, 12, 1** distinguishes one top-level dispatch, a batched effect or
+store wave, and another single dispatch. Treat the per-commit value as a *commit-shape*
+signal: it distinguishes a burst of state dispatches from a single top-level update, but it
+does not locate their source.
+
+**Does it aid source detection?** Modestly, and only as a *disambiguator*, not a locator.
+Avalanche already names the source component and `nearestTestId`. `setStateCount` per commit
+adds one axis: a commit with `performedWork` high but `setStateCount` low = re-render driven
+from *above* (props/context), not local state; high `setStateCount` = the work originated
+from state dispatches in that commit window. It narrows *which kind* of trigger to chase; it
+does not by itself point at a file. Treat it as a tie-breaker on top of the owner chain,
+never a replacement for it. **And because the patch is optional, never build a source-tracing
+procedure that requires it** — it is an enrichment when present, nothing when absent.
+
+## What this diagnoses (and how it pairs with Avalanche)
+
+| Symptom | Metric read | Interpretation | Next |
+|---|---|---|---|
+| Component renders far more than its parent | `setStateCount` climbing on one interaction | high state-dispatch volume — often a store/effect firing setState in a loop | trace the dispatcher; check for setState-in-render or effect cascades |
+| Avalanche shows a hot source, unclear why | `hook-tracker counts` on that type | one slot thrashing vs many slots each once | one slot → chase that dep's identity; many slots → the whole component re-runs (parent/props identity) |
+| Suspected unstable memoization | `offenders` (debug) | a `memo`/`callback` slot with count ≈ render count | the memo's deps are unstable — fix identity **above** the boundary (see [fixing-performance](fixing-performance.md)) |
+| Effect running too often | `histogram` effect column | count of effect identities reaching each bucket | effect deps churn → stabilize deps or split the effect |
+| Type-level hotspot across many instances | `counts` aggregation | one component type dominates total updates | fix once at the type, not per instance |
+
+**Lifecycle placement** (see [evidence and edit gates](../SKILL.md#evidence-and-edit-gates)):
+
+1. **Triage** with Avalanche (`avalanche-hot-sources`, `avalanche-commit-list`) → candidate hot component.
+2. **Attribution**: `hook-tracker install` → reproduce → `counts` on that component type →
+   is it *one slot thrashing* (dep churn) or *the whole component re-running* (identity/props)?
+3. **Experiment**: after a fix, `hook-tracker reset` → reproduce → `counts` again, or use
+   [stability-render](stability-render.md) to verify without a user gesture. Same signal,
+   before/after.
+4. **`uninstall`** to hand the slot back.
+
+## Anchor contract
+
+`hook-tracker` does **not** mutate product state, hooks, or props. It only:
+
+- reads `setStateCount` (a counter the patch already writes), and
+- **owns `onHookUpdate`** — a slot the host leaves for exactly this purpose.
+
+What becomes opaque while installed: any *other* consumer of `onHookUpdate` is displaced
+until `uninstall`. `uninstall` restores the slot **only if Chippy still owns it** (it checks
+`onHookUpdate === record`), so a host that re-seeded the object after install is not clobbered.
+If the host wiped the object and `install` had to seed one, that seeded object persists after
+uninstall with `onHookUpdate = undefined` — harmless, and re-wiped on the next host reset.
+
+Always `uninstall` when the investigation is done, and `reset` between reproduction runs so
+counts from an earlier gesture don't bleed into the next measurement.

package/lib/mcp-skill/references/hooks-inspection.md

@@ -0,0 +1,61 @@
+# Hooks inspection
+
+**To inspect hooks** — `probe-hooks <clientId> <probeId>`:
+- Returns an array of hook nodes walked from `fiber.memoizedState`.
+- Tags: `State`, `Reducer`, `Ref`, `Effect`, `Memo`, `Callback`, `Context?`, `Deferred`, `Unknown`.
+- `State` → `value` is the current state value. `Reducer` → `value` is the last rendered state.
+- `Ref` → `current` is the ref value.
+- `Effect` → `deps` count + `hasCleanup`.
+- `Memo` / `Callback` → `value` + `deps` count.
+- Walks the full hook list up to a high safety cap (`maxHooks: 500`). If the response stops at that cap, `truncated: true` tells you.
+- POD values inlined; objects/arrays/functions safe-serialized.
+- If the hook list is malformed or cyclic, Chippy stops deterministically and marks the break in the output.
+- Hook index is exact within the returned list.
+- No hidden mini-cap for Jira-scale components.
+- Hook output is still for inspection, not for counting business data.
+- Re-run after code changes if you need fresh positions.
+- Use `hookCount`, `truncated`, and `maxHooks` together when judging completeness.
+- If `truncated` is false, the full visible hook chain was walked.
+- If `truncated` is true on a real component, the component is unusually deep and worth noting explicitly.
+- The cap is safety, not guidance.
+- Deep Jira fibers are expected to work.
+- Large outputs may still be verbose; inspect around known anchors.
+- Prefer a nearby `State`/`Ref`/`useDebugValue` landmark when scanning hundreds of hooks.
+- Counts can shift between renders.
+- The list reflects one render snapshot only.
+- This is deterministic from the exact probed fiber.
+- If the page rerenders, probe again.
+- The returned `hookCount` is the number of entries emitted in this result.
+- For capped responses, `hookCount` equals `maxHooks`.
+- For cycle breaks, one final synthetic `Unknown` entry may be appended with a note.
+- This keeps failures inspectable instead of silent.
+- The cap exists only to guard against broken or pathological hook lists.
+- Jira with 300 hooks is fine.
+- Very large components are noisy, but now observable.
+- Use the index numbers as exact anchors.
+- Do not infer missing hooks unless `truncated` says they are missing.
+- When in doubt, call `probe-hooks` again after the next render settles.
+
+Note: if you hit `truncated: true` at 500 in practice, that is a signal to improve the command surface further, not to guess past the boundary.
+
+**Result shape adds**:
+- `hookCount` — number of returned hook entries
+- `truncated` — whether Chippy stopped at the safety cap
+- `maxHooks` — current safety cap used for this walk
+- `hooks[N].note` — optional note on synthetic break entries such as cycle detection
+
+**Reading very deep results**:
+- Default reading is **collapsed by repetition**: group consecutive hooks belonging to the same custom-hook family (e.g. `useSweetState [12..16]`) instead of listing each leaf. Expand a family fully when it is the only instance, or when the user explicitly asks for the raw list (`dump`, `expanded`, `every hook`).
+- For "where exactly is complexity" asks, produce a concentration view first: hook ranges, top-level custom-hook/subtree label, primitive counts, cleanup counts, and landmarks such as `State`, `Ref`, or `useDebugValue`.
+- find a stable hook anchor first (`State` value, `Ref.current`, `useDebugValue`)
+- then use surrounding indexes to orient
+- do not treat raw length alone as meaningful
+- the useful signal is where a known value sits in the deterministic sequence
+
+**Safety rule**:
+- the hook walker should prefer explicit truncation over hanging, looping, or pretending the list ended naturally
+- deterministic failure beats silent loss
+
+**To locate a specific hook**, first use an existing `useDebugValue`, `State`, or `Ref` landmark and its neighboring indexes. If multiple source call sites still fit, report the ambiguity. Adding a new `useDebugValue` is a source edit and requires user intent plus the normal P-15/P-16 gate before changing the code.
+
+**Hook index is stable within a render** but shifts if hooks are added/removed. Always re-run `probe-hooks` after code changes.

package/lib/mcp-skill/references/jira-taxonomy.md

@@ -0,0 +1,81 @@
+# Jira-specific component taxonomy
+
+Signals to keep and use when probing Jira-like production pages.
+
+The `owner` boundary and Jira ownership fields appear only when the built-in Jira plugin is enabled. The wrapper names below apply to Jira pages whether or not it is.
+
+## Probe Jira context
+
+Chippy enriches a selected fiber with three collateral-scope boundaries. The extension/import panel renders them in-page; the Storybook addon renders the same three inside the matching marker card (feature parity — same data, host-specific rendering). It scans a bounded current/return/debug-owner path.
+
+The three boundaries (`markers[id].context.boundaries = { owner, error, suspense }`) each carry a **`distance`** — the number of fiber hops from the probed fiber. Distance is the primary signal: it says how far each collateral boundary is without resolving it in full. Each block is **clickable**; a click reports the selected boundary (`{ markerId, boundaryKind, boundary, distance }`) to the backend as an `inspect-boundary` signal for later investigation (readable as `lastInspectedBoundary` on the client summary).
+
+- **error** and **suspense** are **fiber-native React primitives**, detected generically on *any* React page (not just Jira). Error boundaries are found by React lifecycle (`getDerivedStateFromError` / `componentDidCatch`) with a name-heuristic fallback (`detectedBy: 'lifecycle' | 'name'`); Suspense by fiber tag 13. The error block shows the detailed fields; on Jira it is enriched from `JSErrorBoundary` props (`id`, `packageName`, `teamName`, `fallback`).
+- **owner** is the Jira-specific semantic/team owner (`OwnerMark___<type>___<name>___<package>___<variant>`) — *not* the React render owner. It renders as a **short clickable lozenge** (name + distance only); its fields are intentionally not dumped because the OwnerMark commonly wraps the error boundary and would duplicate it.
+- The nearest Suspense boundary in deep trees (e.g. Jira) can sit ~170+ fiber-hops above a leaf; the ancestry walk reaches it (ceiling 400) but early-exits once all three are found.
+- This is live runtime metadata, not a repository or organizational lookup. Treat it as a production source hint and retain the existing confidence caveat when neither `_debugSource` nor a usable React 19 `_debugStack` source is available.
+- Use `context-ui <clientId> off` to hide the boundary cards for the current page, and `context-ui <clientId> on` to show them again. This applies to both in-page and Storybook marker cards; generic probe data remains available in either state.
+
+## `OwnerMark___<type>___<name>___<package>___<variant>`
+Declarative boundary marker near error/lazy boundaries. Often the closest thing to a source name in production.
+
+## `Connect(X)`
+Redux wrapper. The wrapped name is the real component.
+
+When reading avalanche traces:
+- `Connect(X)` is usually transport, not ownership.
+- Promote `X` or the nearest Jira-owned child/self-updater before ranking it as a source.
+- If the trace only names `Connect(X)`, use its wrapped name as the business component label.
+
+## `ComponentWithCondition[]`
+Feature-gate branch marker.
+
+When reading avalanche traces:
+- Ignore as a primary source.
+- Treat as path metadata only: it explains which gated branch is active.
+- Promote the nearest Jira-owned parent or child with concrete `whatChanged` / `hookChanges` evidence.
+- Broad collateral under this node does not mean the gate owns the update.
+
+## `WithAnalyticsEvents(X)` / `WithAnalyticsContext(X)` / `WithAnalytics(X)`
+Analytics wrappers. Usually structural noise.
+
+## `JiraUFOSegmentWrapper` → `SsrRenderProfiler` → `UFOSegment`
+Performance instrumentation seam. Useful as a feature boundary marker.
+
+## `SuspensePlaceholder` → `SuspenseWrapper` → `OwnerMark___placeholder___X`
+Lazy-loaded section marker.
+
+When reading avalanche traces:
+- `SuspensePlaceholder` is not a real business source.
+- It artificially holds or releases child propagation during lazy/suspense transitions.
+- Treat as environment/path metadata unless no Jira-owned source exists above or below it.
+- Large collateral here usually means the subtree beneath it woke up; inspect the nearest Jira-owned child/self-updater next.
+
+## `Safe(X)`
+Crash-safe wrapper.
+
+## `Container(X)`
+SweetState/local shared state boundary. Strong hint for data origin.
+
+When reading avalanche traces:
+- Higher-value source candidate than wrappers/placeholders.
+- If `Container(X)` is a self-updater with concrete field changes, keep it in the suspect list.
+
+## `ConnectedXxxRelayWithSuspense`
+Relay/GraphQL data boundary.
+
+When reading avalanche traces:
+- Often a real data boundary, not just noise.
+- Keep when export shows concrete field/store changes or repeated self-updates.
+- If only suspense transport is visible, keep drilling to the Jira-owned child.
+
+## Avalanche ranking rules for Jira
+- Filter helper nodes first: feature gates, placeholders, analytics wrappers, profiler seams.
+- Do not equate blast radius with ownership. Broad hotspot can still be transport.
+- Prefer the nearest Jira-owned self-updater with concrete `whatChanged` / `hookChanges` evidence.
+- Repeated commits beat one broad placeholder event when picking real work.
+- Parent/child environment still matters: keep helper nodes in notes to justify the branch shape, but not as the fix target.
+- Before writing work items, normalize wrapper names to the business component that owns the update.
+
+## Noise to skip
+`AnalyticsContext`, `AnalyticsListener`, `GenericAnalyticsListener`, `SsrRenderProfiler`, `ExperienceTrackingProvider`, single-character minified HOCs, and similar non-structural wrappers.

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

@@ -0,0 +1,122 @@
+# Chippy over MCP
+
+Use the local stdio MCP adapter when your agent host supports MCP tools. It starts
+or reuses the helper automatically, so the agent does not need a shell command to
+start a background server. The browser still needs the extension, module import,
+or Storybook integration.
+
+## Connect your agent
+
+Follow these steps when the user asks you to connect Chippy over MCP. They apply
+to any agent host that supports stdio MCP servers.
+
+1. Resolve the absolute path of the directory that contains this skill's
+   `SKILL.md`. It may be a user-level or a project-local install; do not assume
+   `~/.agents/skills/chippy`. Confirm that `scripts/chippy-mcp.cjs` exists there. Check that `node --version` reports 22.12 or later.
+2. Register a stdio MCP server named `chippy` that runs `node` with that
+   absolute `scripts/chippy-mcp.cjs` path as its only argument. Use your host's
+   documented way to add an MCP server: its own command if it has one, otherwise
+   its MCP configuration file. Register it for the user, not one project, unless
+   the user asks otherwise.
+3. Merge the entry into the existing configuration. Keep the other servers, and
+   update an existing `chippy` entry instead of adding a second one.
+4. If your host loads MCP servers only at startup, tell the user to restart or
+   reload it.
+5. Verify the connection with `chippy_status`. If the Chippy tools do not
+   appear, report what you changed and use `scripts/chippy.sh` until they do.
+
+If your host has no MCP support, skip these steps and use `scripts/chippy.sh`.
+
+## Server configuration
+
+The server entry, in the common `mcpServers` JSON shape. Replace the example path
+with the **absolute installed skill path**; JSON arguments do not expand `~`.
+
+```json
+{
+  "mcpServers": {
+    "chippy": {
+      "command": "node",
+      "args": ["/absolute/path/to/chippy/scripts/chippy-mcp.cjs"]
+    }
+  }
+}
+```
+
+Node.js 22.12+ is required. The executable bundles its MCP dependencies and their
+licenses; the installed skill needs no `npm install`. The Chippy npm library also
+includes the `chippy-mcp` executable.
+Host configuration syntax varies; the example shows the command and arguments
+that the host must launch, not a file Chippy installs into your host.
+
+Start with `chippy_status`, then `chippy_pages`. Select a page by URL and title,
+read `chippy_snapshot`, and inspect the relevant probe or find components directly.
+A ready helper with `browserConnected: false` means enable Chippy on a browser page,
+not restart the server. The skill's replay, stimulus, evidence, and edit rules apply
+to MCP calls exactly as they do to CLI calls.
+
+## Helper lifecycle and sandbox behavior
+
+- New helpers bind to `127.0.0.1:7823`. Set `CHIPPY_HELPER_PORT` in the MCP process
+  environment to use another port (integer 1–65535); configure the browser's helper
+  URL to match. Set `CHIPPY_HELPER_HOST` (for example `0.0.0.0`) only when the
+  browser must reach the helper over the network. The adapter always connects to
+  loopback on that port.
+- A matching helper version is reused. An incompatible response or occupied port
+  produces a tool error; Chippy does not replace that process. Stop or upgrade it
+  explicitly, or choose another port.
+- The helper is a persistent shared service. Closing the MCP host/session closes
+  the stdio adapter but leaves the helper, probes, and other sessions available.
+  Default-port helpers can be stopped with the existing `chippy.sh stop` when no
+  session needs them. Chippy does not kill other helpers on shutdown.
+- `chippy_status` returns `helperUrl`, `startedPid` (the child started by this MCP
+  process, otherwise null), `lifetime: "persistent"`, `browserConnected`, `pages`,
+  `hint`, and `ok`. An empty page list is normal setup state.
+- The MCP process needs host permission to launch Node and connect to the helper.
+  MCP avoids reliance on the agent's shell sandbox only when the host launches
+  MCP servers with suitable access. It cannot bridge an isolated container to a
+  browser without networking/forwarding supplied by the environment.
+- Logs use stderr; stdout contains only MCP messages. Requests are cancellable.
+  Helper errors are returned as MCP tool errors, not as successful empty evidence.
+
+The adapter reads the helper's access token from `~/.chippy/helper-<port>.token`
+(or `$CHIPPY_STATE_DIR`) on each request, so it keeps working after a helper
+restart. `CHIPPY_HELPER_TOKEN` overrides the file. Reusing an existing helper does
+not change its listening address.
+
+## Tools
+
+All page tools require `clientId`. Resolve it afresh after navigation. Optional
+`timeoutMs` defaults to 5000 and accepts integers 1–60000, except annotation waits,
+which default to 30000. Structured results preserve the existing helper response
+and are also included as JSON text.
+
+| Tool | Arguments and behavior |
+| --- | --- |
+| `chippy_status` | No arguments; starts/reuses helper and reports browser readiness. |
+| `chippy_pages` | No arguments; lists connected pages. |
+| `chippy_snapshot` | `clientId`, `refresh` (default false). Reads stored evidence; true requests an asynchronous refresh, so read again after the page responds. |
+| `chippy_probe` | `clientId`, `probeId`, `view`, optional `ownerIndex`, `prop`, `parentLevel`, `max`, `timeoutMs`. Views: `dom`, `parents`, `boundaries`, `owners`, `props`, `prop-value`, `hooks`, `hooks-summary`. `prop-value` requires `prop`. `owners` uses the existing live-owner route and cached-snapshot fallback. |
+| `chippy_find_fibers` | `clientId`, `filters`, optional `timeoutMs`. Filters: `name`, `file`, `prop`, `testid`, `text`, `max`. Returns current fibers; refresh ids after commits or HMR. |
+| `chippy_inspect_fiber` | `clientId`, `fiberId`, `view`, optional `hookIndex`, `windowSize`, `max`, `timeoutMs`. Views: `props`, `owners`, `parents`, `boundaries`, `hooks`, `hooks-summary`, `structure`, `describe`, `explain`. `structure` requires `hookIndex`. Replay-capable views can execute component/hook bodies. |
+| `chippy_avalanche` | `clientId`, `action`, optional fields described below. Uses the existing Avalanche command builder. |
+| `chippy_interact` | `clientId`, `action`, `target`, optional `targetKind` (default `selector`; alternatives `probeId`, `fiberId`), `propName`, `args`, `ownerIndex`, `timeoutMs`. Actions: `click`, `prop-contract`, `invoke`, `schedule-update`. `targetKind` selects click resolution; other actions take a fiber id as `target`. `prop-contract` and `invoke` require `propName`; `invoke` forwards a JSON argument array. Name the stimulus before execution and prove callback contracts before invoking them. |
+| `chippy_wait_annotation` | `clientId`, optional `timeoutMs` (default 30000, maximum 60000). Consumes one UI intent/comment, waits once, or returns normal `status: "timeout"`. Repeat only while the user-requested loop remains active; cancellation closes the HTTP long poll. |
+
+Avalanche actions: `status`, `install`, `uninstall`, `clear`, `export`,
+`export-last`, `hot-sources`, `commit-list`, `commit-peek`, `debug-hook`,
+`describe-action`. `install` starts capture; `clear` resets evidence;
+`uninstall` stops capture. Optional `options` contains `detectionMode`
+(`stats`, `sources`, `amplifiers`, `full`), `historySize`, and `captureFibers`.
+Analysis fields are `limit`, `count`, `top`, `by`, `commitId`, `include` (array),
+`depth`, `maxItems`, `sourceId`, `hookIndex`, `window`, `actionId`, and `timeoutMs`.
+Use captured ids for commit, hook, and action analysis. See the
+[Avalanche reference](avalanche-detector.md) for result semantics.
+
+Indices are nonnegative integers; limits, counts, maxima, and window sizes are
+positive integers, except Avalanche's `window`, which permits zero. Fields apply
+to their selected view/action; for example, owner selection does not apply to the
+owner-chain list. These nine tools cover the main inspection, capture, and UI-intent
+loop. The CLI remains available for recipes, snippets, reload/arm workflows,
+state comparisons, and other commands not exposed here. MCP does not change those
+contracts or modify agent-host lifecycle hooks.

package/lib/mcp-skill/references/mode-a-injection.md

@@ -0,0 +1,102 @@
+# Mode A injection contract — Playwright-controlled browser without the extension
+
+Mode A is the Chippy/Avalanche injection path used when there is **no browser extension** — Playwright opens a browser, navigates a page, and the test runner is responsible for everything the extension would normally do in Mode B. Skipping a step silently degrades capture quality — usually shows up as `commitCount: 0`, `integrationMode: "none"`, or empty `commitStats`.
+
+## When this applies
+
+- Headless verification under Vitest/Playwright/CI
+- Agent-side automation that opens its own Chromium
+- Any environment where the Chippy extension is **not** installed in the browser
+
+If the user is using their own browser with the extension, this contract does NOT apply — the extension's `webNavigation.onCommitted` + `chrome.scripting.executeScript` path handles everything below.
+
+## Required bootstrap and install order
+
+Mode A has two runtime-loading variants that end with the same explicit detector install. To record the initial load, use [pre-page start-up](#pre-page-start-up) instead; it installs the detector before React on every document.
+
+1. **Install the DevTools hook shim before navigation.** Use `page.addInitScript({ content: DEVTOOLS_HOOK_SHIM })` before `page.goto(...)`.
+   React-DOM checks `__REACT_DEVTOOLS_GLOBAL_HOOK__` at module-evaluation time. Installing the shim after navigation = no `currentDispatcherRef` = `replayComponentHooks` collapses to fiber-only fallback. The shim file is shipped with the Chippy skill at `extension/devtools-hook-shim.js`; the helper serves it at `/__chippy/devtools-hook-shim.js` (load that contents into the init script).
+2. **Load the Chippy and Avalanche runtimes using one variant:**
+   - **Packaged session loader:** call `installHelpers(page, { init: true })` before `page.goto(...)`. It registers the shipped helper scripts as init scripts, so they return on every navigation.
+   - **Ad-hoc / playwright-cli:** navigate first, then import `http://127.0.0.1:7823/__chippy/inject.mjs` (preferred), or add `inject.js` followed by `avalanche.iife.js`. The classic `inject.js` is intentionally split; bridge commands return `bridge module not loaded` until the IIFE is present.
+3. **Wait for the page client in `chippy.sh pages`.** A loaded global is not connection proof.
+4. **Run `chippy.sh avalanche-install <clientId>`.** Loading either runtime does not auto-install the detector in Mode A.
+   Auto-install is gated on `__CHIPPY_STARTUP_CONFIG.avalanche.autoStart`, which is written by the extension's MAIN-world script in Mode B. Neither loader above writes that startup configuration, so both must trigger install explicitly.
+
+## Pre-page start-up
+
+Use this variant when the agent must record the initial page load without the extension. It writes the startup configuration that the extension writes in Mode B, then adds the early scripts and the page bridge as init scripts. Every document, including each reload, installs Avalanche before React DOM evaluates.
+
+Register the init scripts before `page.goto(...)`, in this order. The files ship in this skill's `extension/` folder:
+
+```js
+const read = (file) => fs.readFileSync(path.join(skillDir, 'extension', file), 'utf8');
+
+await page.addInitScript(() => {
+  globalThis.__CHIPPY_STARTUP_CONFIG = {
+    enabled: true,
+    helperBaseUrl: 'http://127.0.0.1:7823',
+    avalanche: { autoStart: true },
+  };
+});
+await page.addInitScript({ content: read('devtools-hook-shim.js') });
+await page.addInitScript({ content: read('avalanche.iife.js') });
+await page.addInitScript({ content: read('early-bootstrap.js') });
+await page.addInitScript({
+  content: ['inspect-react.js', 'panel-dom.js', 'layout-lab.js', 'resolve-probes.js', 'chippy-page-bridge.js']
+    .map(read)
+    .join('\n'),
+});
+await page.goto(url);
+```
+
+- Skip the explicit `avalanche-install`; the detector is already installed and recording. `avalanche.options` accepts `detectionMode` and `captureFibers`, and `avalanche.max` sets the history size.
+- To capture a load, call `page.reload()` and let the page settle. Do not call `avalanche-reset` between the reload and the read; it clears the boot commits.
+- Read the capture with `chippy.sh avalanche-status <clientId>` and `avalanche-export` once the reloaded page appears in `chippy.sh pages`. If the client has not reconnected yet, read `window.__AVALANCHE__.exportLast()` in the page.
+
+## On reload (`page.reload(...)`)
+
+- Init scripts survive reload. The packaged loader restores its runtimes automatically; the ad-hoc variant must load them again.
+- The client id is kept in the tab's `sessionStorage`, so the reloaded page normally reconnects under the same id (`page-wait-reload` reports `reloaded: true`). The connection and the detector are new: repeat the explicit install.
+- If the runtimes are not loaded again, the page never reconnects: `page-wait-reload` reports `reloaded: false`, and `reload-with-avalanche` exits with an error instead of reading status from a client that no longer exists.
+
+## Boot-time commit loss in the packaged and ad-hoc variants
+
+This limit does not apply to [pre-page start-up](#pre-page-start-up). The ad-hoc `addScriptTag` variant loads the runtimes after page code. The packaged init-script variant loads them before page code, but its detector still remains uninstalled until the helper observes the new client and sends the explicit install.
+
+Any React commit that fires between page mount and your `avalanche-install` call is **invisible to Avalanche**. This includes:
+- initial mount
+- `useEffect` cleanup teardowns
+- Suspense fallback → content swaps
+- route transitions on first paint
+
+**Workaround:** use [pre-page start-up](#pre-page-start-up), or trigger the transition from the page after `avalanche-install`.
+
+## Failure signatures
+
+| Symptom | Likely cause |
+|---|---|
+| `commitCount: 0`, `integrationMode: "none"` | explicit detector install was skipped, or no commit occurred afterward |
+| `commitCount > 0` but `unmountedComponents: 0` despite expected unmounts | unmounts happened before detector install; trigger them post-install |
+| `bridge module not loaded` from `find-fibers` / `describe-component` | classic bootstrap omitted `avalanche.iife.js` |
+| `replayComponentHooks` returns flat fiber-only data, no custom-hook folders | DevTools hook shim was skipped or installed after navigation |
+| `coverage > 100%` in `meta.memoizedUpdatersSupport` | early commits missed (this is the boot-time gap, not a wiring bug) |
+
+## Verifying that capture worked
+
+- `chippy.sh avalanche-status <clientId>` → expect `installed: true`, `commitCount > 0`, and `integrationMode` matching the host (`adapter:atl` for a patched Atlassian host, `devtools` otherwise; earlier releases report `atl`), never `none` after a captured commit.
+- In `avalanche-export`, compare `meta.commits` vs `meta.memoizedUpdatersSupport.commitsWithData` — they should match. If `commitsWithData > meta.commits`, early commits were missed.
+- To tell the boot-time gap from a wiring fault, repeat the interaction after install. If that capture is also empty, the injection is broken; if only the pre-install interaction is missing, use [pre-page start-up](#pre-page-start-up).
+
+## Mode B reference (for contrast)
+
+In Mode B, the extension does the following automatically and silently for every navigation:
+1. `webNavigation.onCommitted` fires
+2. Background fetches `armedAvalanche` config from helper
+3. `chrome.scripting.executeScript({ injectImmediately: true, world: 'MAIN' })` runs the early scripts (`devtools-hook-shim.js`, `avalanche.iife.js`, `early-bootstrap.js`). Because steps 2–3 wait on network lookups, a fast page can evaluate React first.
+4. iife.ts reads `__CHIPPY_STARTUP_CONFIG.avalanche.autoStart` and self-installs
+5. `chrome.tabs.onUpdated` (`status === 'complete'`) injects late bundle scripts (bridge + probes)
+
+For a helper reload of an armed page (`page-reload` after `avalanche-arm`, as in `reload-with-avalanche`), the page bridge first stores the arm in `sessionStorage` and the extension registers the early scripts plus `startup-handoff.js` as a MAIN-world `document_start` content script for that one navigation. The next document installs Avalanche before any page script runs, so boot commits are captured. The reload ack's `earlyStartup` is `registered` when this path was prepared.
+
+The packaged and ad-hoc Mode A loaders do not provide the extension's pre-page `autoStart` configuration. They install only after client connection; that post-connection detector start is the structural reason for their boot-time gap. Pre-page start-up writes the configuration itself and has no such gap.