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

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,68 @@
+# 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 supported runtime-loading variants. Both end with the same explicit detector install.
+
+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 Mode A loader writes that startup configuration, so both must trigger install explicitly.
+
+## On reload (`page.reload(...)`)
+
+- Init scripts survive reload. The packaged loader restores its runtimes automatically; the ad-hoc variant must load them again.
+- Both variants receive a new client and detector instance. Re-resolve the client, then repeat the explicit install.
+
+## Boot-time commit loss — known limitation
+
+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:** stories under test must expose a manual trigger (e.g. `window.__triggerSwap()`) that you call AFTER `avalanche-install`. Document this trigger in the test fixture so the test reads end-to-end.
+
+## 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.
+- For end-to-end behavior, build a CONTROL test (trigger after install — must capture) AND a GAP test (trigger before install — documents the limitation) per fixture.
+
+## 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`) before any page script evaluates
+4. iife.ts reads `__CHIPPY_STARTUP_CONFIG.avalanche.autoStart` and self-installs
+5. `chrome.tabs.onUpdated` (`status === 'complete'`) injects late bundle scripts (bridge + probes)
+
+The supported 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 the boot-time gap.