@atlassian/chippy 0.0.1-beta.1 → 0.0.1-beta.2

package/lib/mcp-skill/references/browser-runtime-api.md

@@ -34,7 +34,7 @@ Important behavior:
 - extension-owned pages initially render one small bottom-corner Chippy launcher; expanding it reveals compact `P1 — drag to source` / `P2 — drag to source` rows that serve as each probe's dock and detail surface
 - dragging a probe does not collapse the panel; an undocked probe uses document coordinates and stays anchored to its target while the page scrolls
 - the extension toolbar popup contains only Enable and Disable for the current origin; helper and proxy configuration stay in the in-page panel
-- extension-owned panels expose the helper URL and optional forward-port settings behind the gear; the isolated content script mounts the form in a closed shadow root, with no iframe and no page access to extension storage
+- extension-owned panels expose the helper URL and plugin settings behind the gear; the isolated content script mounts the form in a closed shadow root, with no iframe and no page access to extension storage
 - Storybook host-panel mode keeps a standalone dock in the preview frame because probe details live in the manager frame
 - docked probes are inactive
 - while dragging:
@@ -66,7 +66,7 @@ The helper must be a real local process reachable by the user's browser. The age
 
 `contextUiEnabled` defaults to `true`. It controls only context-provider cards in the active probe UI, including Storybook marker cards; generic probe resolution and snapshots continue when it is false.
 
-Source reads are cross-version. React <=18 locations come from `_debugSource`. React 19 locations start at `_debugStack`, skip dependency frames, and resolve the served module through its inline or external Source Map v3 payload. Snapshot publication is immediate and may be followed by a `<reason>-source-resolved` snapshot when the authored position differs; `describe-component` and `explain-component` await the mapped position.
+Source reads are cross-version. React <=18 locations come from `_debugSource`; when the module the page loaded for that file carries a source map, its recorded literal is mapped back to correct lines shifted by an earlier transform. React 19 locations start at `_debugStack`, skip dependency frames, and resolve the served module through its inline or external Source Map v3 payload. Snapshot publication is immediate and may be followed by a `<reason>-source-resolved` snapshot when the authored position differs; `find-fibers`, `describe-component`, and `explain-component` await the mapped position.
 
 `integration.kind` is `extension`, `import`, or `storybook`. `who` names the host that established Chippy and `source` points to its real setup source file. Import integrations report `reinjectsOnReload: false`; a full reload/navigation requires the user or automation to run the import again.
 
@@ -83,10 +83,10 @@ The Avalanche panel installs and refreshes capture state while selected. It grou
 When either panel is `failed` or `reconnecting`, it may offer:
 
 ```bash
-npx @atlassian/chippy install
+npx skills add atlassian-labs/chippy --skill chippy -g
 ```
 
-That command installs Chippy when it is absent. It does not start or verify the helper; the agent still follows [troubleshooting](troubleshooting.md) and runs the helper checks.
+That command installs the Chippy skill with the skills CLI when it is absent. It does not start or verify the helper; the agent still follows [troubleshooting](troubleshooting.md) and runs the helper checks.
 
 ## `window.__CHIPPY.resolveProbes` / `window.__CHIPPY.resolveProbesCompact`
 

package/lib/mcp-skill/references/command-output-formats.md

@@ -53,10 +53,11 @@ Fields: `ok` (bool), `now` (ISO 8601 timestamp).
 
 ## `inject-url`
 
-Prints a lifecycle warning to stderr:
+Prints a lifecycle warning and the second required asset to stderr:
 
 ```text
 Import integration is document-scoped: a full reload/navigation removes Chippy and requires the user or automation to inject it again.
+The classic inject.js installs Chippy only; load http://127.0.0.1:7823/__chippy/avalanche.iife.js after it for bridge and Avalanche commands, or import http://127.0.0.1:7823/__chippy/inject.mjs instead.
 ```
 
 Then prints the classic-script URL to stdout, one line:
@@ -153,7 +154,7 @@ Records are separated by one blank line. `score` is useful only for ordering res
 
 `buildMode`: `"dev" | "production" | "unknown"`
 
-`dev` source evidence is either React <=18 `_debugSource` or React 19 `_debugStack`. For React 19, the first snapshot may carry the served-module URL and generated position; the bridge resolves the module's inline or external Source Map v3 payload in the page realm and republishes the authored `fileName`, `lineNumber`, and `columnNumber` with reason `<original-reason>-source-resolved`. Explicit component descriptions await that resolution. If the module or map is unavailable, the served position remains the fallback.
+`dev` source evidence is either React <=18 `_debugSource` or React 19 `_debugStack`. For React 19, the first snapshot may carry the served-module URL and generated position; the bridge resolves the module's inline or external Source Map v3 payload in the page realm and republishes the authored `fileName`, `lineNumber`, and `columnNumber` with reason `<original-reason>-source-resolved`. For React <=18, the same resolution corrects a `_debugSource` line that a dev-server transform shifted; `fileName` stays the recorded path. `find-fibers` and explicit component descriptions await that resolution. If the module or map is unavailable, the recorded or served position remains the fallback.
 
 **`integration`** — identifies who established Chippy on this page:
 ```json
@@ -1034,6 +1035,7 @@ Proxy active:
   "proxy": {
     "active": true,
     "targetPort": 3000,
+    "targetHost": "localhost:3000",
     "originalUrl": "http://localhost:3000/issues/ABC-123",
     "injectTarget": { "pathname": "/issues/ABC-123", "search": "" },
     "startedAt": "2026-04-16T08:00:00.000Z"
@@ -1043,6 +1045,8 @@ Proxy active:
 
 `injectTarget` — the path+search the proxy will inject the Chippy bundle into. Derived from `originalUrl`. `null` if no `originalUrl` was given.
 
+`targetHost` — where requests are forwarded. The proxy forwards only to this machine: it uses the loopback host of `originalUrl` (`localhost`, `127.0.0.1`, `[::1]`), or `localhost` when none is given, and reaches servers listening on either IPv4 or IPv6. Into the injected document it adds the DevTools hook shim and the Avalanche runtime before page scripts, and the page bridge at the end of the body.
+
 ---
 
 ## `proxy-start <targetPort> [originalUrl]`
@@ -1054,6 +1058,7 @@ Success:
   "proxy": {
     "active": true,
     "targetPort": 3000,
+    "targetHost": "localhost:3000",
     "originalUrl": "http://localhost:3000/issues/ABC-123",
     "injectTarget": { "pathname": "/issues/ABC-123", "search": "" },
     "startedAt": "2026-04-16T08:00:00.000Z"
@@ -1066,6 +1071,11 @@ Bad port:
 { "ok": false, "error": "Invalid target port: abc" }
 ```
 
+Target off this machine:
+```json
+{ "ok": false, "error": "Proxy targets must be on this machine; originalUrl host example.com is not a loopback name" }
+```
+
 ---
 
 ## `proxy-stop`

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

@@ -21,7 +21,7 @@ Use recipe search when the operation or recovery route is not already obvious. I
 | 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. |
+| `inject-url` | Print the classic `inject.js` URL to stdout, and the document-scoped reload warning plus the second required asset to stderr. `inject.js` alone installs Chippy without the bridge; load `avalanche.iife.js` after it, or prefer the single ESM import 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. |
@@ -91,9 +91,9 @@ Load [active-stimulus](active-stimulus.md) before an active command. A `fiber:*`
 
 | 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 |
+| `sources` | Default source and commit attribution; rendered components with prop changes and `isSelfSource` | `trasherCounts` stay zero |
+| `full` | Everything in `sources` plus amplifier (`trasherCounts`) evidence | Higher collection cost |
+| `stats` | Aggregate capture statistics; rendered components with prop changes | No source tracking: `isSelfSource` stays false |
 | `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.
@@ -102,7 +102,7 @@ Load [active-stimulus](active-stimulus.md) before an active command. A `fiber:*`
 
 `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`.
+`avalanche-commit-peek` live `include` values are `stats`, `sources`, `timing`, `metrics`, `unmounts`, `actions`, and `rendered`; `atl` is a deprecated alias of `metrics`. `rendered` works in every mode; `trasherCounts` in it need `full` or `amplifiers`.
 
 Load [avalanche-detector](avalanche-detector.md) for schemas and evidence-reading rules.
 
@@ -112,7 +112,7 @@ Load [avalanche-detector](avalanche-detector.md) for schemas and evidence-readin
 |---|---|
 | `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. |
+| `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; it fails with HTTP 409 when no rendered story matches the selection. |
 | `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. |
 

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

@@ -12,7 +12,7 @@ If the user is using their own browser with the extension, this contract does NO
 
 ## Required bootstrap and install order
 
-Mode A has two supported runtime-loading variants. Both end with the same explicit detector install.
+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).
@@ -21,16 +21,48 @@ Mode A has two supported runtime-loading variants. Both end with the same explic
    - **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.
+   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.
-- Both variants receive a new client and detector instance. Re-resolve the client, then repeat the explicit install.
+- 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 — known limitation
+## Boot-time commit loss in the packaged and ad-hoc variants
 
-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.
+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
@@ -38,7 +70,7 @@ Any React commit that fires between page mount and your `avalanche-install` call
 - 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.
+**Workaround:** use [pre-page start-up](#pre-page-start-up), or trigger the transition from the page after `avalanche-install`.
 
 ## Failure signatures
 
@@ -54,15 +86,17 @@ Any React commit that fires between page mount and your `avalanche-install` call
 
 - `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.
+- 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`) before any page script evaluates
+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)
 
-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.
+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.

package/lib/mcp-skill/references/playwright-cli-setup.md

@@ -6,7 +6,7 @@ Use this when there is no Chippy browser extension on the page (`playwright-cli`
 
 Chippy assets are served by the local Chippy helper:
 
-- `http://127.0.0.1:7823/__chippy/inject.mjs` — **preferred ESM bootstrap**. Import side-effect installs `window.__CHIPPY`, registers the page with the helper, auto-loads `window.__AVALANCHE__` from the ESM-safe `avalanche.es.js` asset, activates probes immediately, and installs a small in-page control panel. The module default export is `window.__CHIPPY`; named export `ready` resolves to `{ chippy, avalanche, connState, integration, activated, probesActive }` immediately after bootstrap.
+- `http://127.0.0.1:7823/__chippy/inject.mjs` — **preferred ESM bootstrap**. Import side-effect installs `window.__CHIPPY`, registers the page with the helper, auto-loads `window.__AVALANCHE__` from the ESM-safe `avalanche.es.js` asset, and activates probes immediately. It renders no in-page control panel. The module default export is `window.__CHIPPY`; named export `ready` resolves to `{ chippy, avalanche, connState, integration, activated, probesActive }` immediately after bootstrap.
 - `http://127.0.0.1:7823/__chippy/inject.js` — **classic-script bootstrap**. Installs `window.__CHIPPY` only.
 - `http://127.0.0.1:7823/__chippy/avalanche.iife.js` — **Chippy runtime for bridge / Avalanche-backed commands**. Installs `window.__AVALANCHE__` when the classic bootstrap is used.
 
@@ -18,9 +18,9 @@ The same ESM bootstrap is also valid for a real user-controlled browser tab when
 import('http://127.0.0.1:7823/__chippy/inject.mjs')
 ```
 
-In that mode the import is intended to be extension-equivalent for the current page: it activates probes immediately and installs the in-page Chippy controls.
+In that mode the import activates probes for the current page without the extension's in-page controls.
 
-The equivalence lasts only for the current document. A full reload or navigation removes the imported runtime because no extension or Storybook host remains to inject it. The in-page import controls display this warning. The user—or Playwright—must run the import command again after every reload/navigation.
+The import lasts only for the current document. A full reload or navigation removes the imported runtime because no extension, proxy, or Storybook host remains to inject it. The user—or Playwright—must run the import command again after every reload/navigation. To keep Chippy across reloads without the extension, use the packaged init-script loader in [mode-a-injection](mode-a-injection.md) or the helper's local proxy.
 
 ## Steps
 
@@ -36,7 +36,7 @@ The equivalence lasts only for the current document. A full reload or navigation
 3. Prefer the ESM bootstrap when module loading is available:
 
    ```bash
-   yarn exec playwright-cli -s=<session> run-code "async page => {
+   playwright-cli -s=<session> run-code "async page => {
      await page.addScriptTag({
        content: `
          const script = document.createElement('script');
@@ -57,7 +57,7 @@ The equivalence lasts only for the current document. A full reload or navigation
    Fallback: classic script injection when ESM import is not available:
 
    ```bash
-   yarn exec playwright-cli -s=<session> run-code "async page => {
+   playwright-cli -s=<session> run-code "async page => {
      await page.addScriptTag({ url: 'http://127.0.0.1:7823/__chippy/inject.js' });
      await page.waitForTimeout(500);
      await page.addScriptTag({ url: 'http://127.0.0.1:7823/__chippy/avalanche.iife.js' });

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

@@ -123,7 +123,7 @@ overridden with `CHIPPY_HELPER_BASE`.
 
 The packaged `launchSession(...)` path installs the Chippy bridge and Avalanche runtime via `addInitScript`, so both runtimes exist before page scripts on every reload. The detector still starts uninstalled in each new page realm. `reloadWithAvalanche` therefore reloads, waits for the new client, calls the Avalanche `install` action explicitly, then settles and reads evidence. It does not use helper origin-arming.
 
-Commits that occur before that post-reload install are not captured. Use this helper for post-install triggers and settled-state checks, not to claim complete initial-load coverage.
+Commits that occur before that post-reload install are not captured. Use this helper for post-install triggers and settled-state checks, not to claim complete initial-load coverage. To record the initial load, use [pre-page start-up](mode-a-injection.md#pre-page-start-up).
 
 Flow:
 1. `page.reload()` via Playwright

package/lib/mcp-skill/references/recipes.txt

@@ -21,7 +21,7 @@ id=show-page-status | q=How do I show a short status message inside the inspecte
 id=hide-page-status | q=How do I remove Chippy's page-visible status message? | tags=hide status clear message page | a=Run `chippy.sh hide-status <clientId>`. | done=The page-visible Chippy status is absent. | guard=This does not clear probes or capture state. | refs=references/command-surface.md#runtime-and-connection
 id=identify-integration-owner | q=How do I tell whether Chippy came from the extension, Storybook, or a console import? | tags=integration identity owner extension storybook import reload behavior who source | a=Read `integration.kind`, `who`, `source`, `reinjectsOnReload`, and `reloadAction` from `chippy.sh pages`. | done=The injection owner and reload contract are explicit. | guard=Do not infer ownership from globals or the page URL. | refs=SKILL.md#connection-and-bootstrap
 id=inject-console-module | q=How do I load Chippy into a user-controlled page without the extension? | tags=inject import esm console module user controlled page | a=Run `import('http://127.0.0.1:7823/__chippy/inject.mjs')` in the browser console, then resolve the page through `chippy.sh pages`. | done=The page reports `integration.kind: import` and the bridge is ready. | guard=The import is document-scoped and must be repeated after full navigation or reload. | refs=SKILL.md#connection-and-bootstrap
-id=print-classic-inject-url | q=How do I obtain the classic Chippy injection URL? | tags=inject url classic inject.js fallback | a=Run `chippy.sh inject-url`; stdout contains the URL and stderr explains the reload boundary. | done=A valid helper-served `inject.js` URL is returned. | guard=Prefer the ESM import for new console workflows. | refs=references/command-surface.md#runtime-and-connection
+id=print-classic-inject-url | q=How do I obtain the classic Chippy injection URL? | tags=inject url classic inject.js fallback | a=Run `chippy.sh inject-url`; stdout contains the URL and stderr explains the reload boundary and the second asset. | done=A valid helper-served `inject.js` URL is returned. | guard=`inject.js` alone has no bridge; load `avalanche.iife.js` after it. Prefer the ESM import for new console workflows. | refs=references/command-surface.md#runtime-and-connection
 id=toggle-jira-enrichment | q=How do I show or hide Jira ownership and boundary enrichment in probe cards? | tags=jira context ui ownership error boundary enrichment on off cards | a=Run `chippy.sh context-ui <clientId> on` or `chippy.sh context-ui <clientId> off`. | done=The connected page renders or hides the enrichment consistently. | guard=This changes Chippy UI only and does not change Jira product behavior. | refs=references/command-surface.md#runtime-and-connection,references/jira-taxonomy.md
 
 # Probe, source, and component inspection

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

@@ -380,7 +380,7 @@ The effect attaches a subscription and dispatches state. It depends on `handler`
 - If the subscription is the only side effect, move attach/detach to a `useLayoutEffect` keyed on the stable subscription target rather than on a callback identity.
 
 **Pointer for the agent:**
-- File: `src/stability/StabilityChain.jsx`, `Leaf` component, `useEffect(..., [handler])`.
+- Location: the `Leaf` component's `useEffect(..., [handler])`.
 - Question to answer before editing: *what does this effect semantically depend on — the function identity, or the data the function reads?*
 - After the fix, re-run stability-render. Expected: `commitCount` drops to 1; `attach/detach` no longer grows per nudge.
 
@@ -389,7 +389,7 @@ The effect attaches a subscription and dispatches state. It depends on `handler`
 After Step 1 the effect is fine, but the callback still flips identity every render. That is harmless on its own — but the moment a memoised child uses it as a prop, the cascade comes back. Fix this *before* memoising any children, not *after*.
 
 **Pointer for the agent:**
-- File: `src/stability/StabilityChain.jsx`, `Leaf`, `useCallback(handler, [opts])`.
+- Location: `Leaf`'s `useCallback(handler, [opts])`.
 - Same dep narrowing logic as Step 1: depend on `opts.mode`, not on `opts`. The callback's body only uses `opts.mode`, so the wider dep is overcautious and breaks memoisation.
 - After the fix, re-run stability-render. Expected: callback identity stable across nudges; `Leaf`'s render count for the nudge stays at 1.
 
@@ -398,13 +398,13 @@ After Step 1 the effect is fine, but the callback still flips identity every ren
 `Parent` builds `opts = { mode }` inline. Step 1 + Step 2 made downstream consumers immune to that, but the next consumer added to this subtree will get the same trap. Wrap the object once.
 
 **Pointer for the agent:**
-- File: `src/stability/StabilityChain.jsx`, `StabilityChain`, `const opts = { mode };`.
+- Location: the parent's `const opts = { mode };`.
 - Wrap with `useMemo(() => ({ mode }), [mode])` — or, if `mode` is the only field, pass `mode` directly and drop the object.
 - After the fix, re-run stability-render. Expected: same numbers as after Step 2. This step is *prevention*, not *repair* — measurable improvement is "no regression when a new memoised consumer is added".
 
 ### What "deep explanation" means here
 
-When Chippy reports findings on this fixture, every pointer must answer three questions:
+When Chippy reports findings on this chain, every pointer must answer three questions:
 
 1. **What flips?** Name the identity that changes. (`opts` object reference; `handler` function reference; `useEffect` cleanup/attach pair.)
 2. **Why does that flip propagate?** Name the dep array or prop boundary it crosses. (Dep array of `useCallback`; dep array of `useEffect`; prop `opts` from Parent to Leaf.)

package/lib/mcp-skill/references/test-mode-playbook.md

@@ -132,7 +132,8 @@ Examples:
 ./scripts/chippy.sh pages
 # Select the page whose URL, title, integration identity, and recency match the target.
 CLIENT_ID=<confirmed-clientId>
-./scripts/chippy.sh reload-with-avalanche "$CLIENT_ID" http://localhost:9000 0 15000 5000
+ORIGIN=<that page's origin>
+./scripts/chippy.sh reload-with-avalanche "$CLIENT_ID" "$ORIGIN" 0 15000 5000
 ./scripts/chippy.sh avalanche-status "$CLIENT_ID"
 ./scripts/chippy.sh avalanche-hot-sources "$CLIENT_ID" 10
 ./scripts/chippy.sh avalanche-commit-list "$CLIENT_ID" 10 collateral

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

@@ -3,7 +3,7 @@
 ## Helper is down
 - `/__chippy/health` fails
 - no pages in `/__chippy/api/pages`
-- the Storybook Chippy and Avalanche panels conditionally offer `npx @atlassian/chippy install` while their connection state is `failed` or `reconnecting`
+- the Storybook Chippy and Avalanche panels conditionally offer `npx skills add atlassian-labs/chippy --skill chippy -g` while their connection state is `failed` or `reconnecting`
 - Chippy must run outside the agent sandbox; the agent owns this, not the user
 - sandbox failure mode: the helper can look alive inside the agent environment, but the browser cannot reach its isolated Node server/port
 - fix: agent runs `./scripts/chippy.sh start` using outside-sandbox / escalated execution, then verifies with `./scripts/chippy.sh health` and `./scripts/chippy.sh pages` (also outside-sandbox)
@@ -47,6 +47,11 @@
 - the served URL and generated line remain as a bounded fallback; do not present them as a mapped repository position
 - check that the page can fetch its own module URL and that the dev server emits an inline or external Source Map v3 payload
 
+## React <=18 source line is offset from the file
+- `_debugSource` records the line the JSX transform saw; a transform that ran earlier and added lines shifts it
+- Chippy corrects the line when it can fetch the module the page loaded for that file and the module's source map maps the recorded literal back into the same file
+- if the line still looks offset, check that the page loaded the module from its own origin and that the dev server emits a source map
+
 ## Multiple pages on same URL
 - use `clientId`, title, `latestSnapshotAt`, and `lastMessageAt` to identify the right page
 - usually prefer the most recently updated page when one candidate is clearly newer than the rest