@blxzer/cursor-trellis 0.4.2 → 0.4.3

package/dist/templates/common/bundled-skills/cstl-skill-creator/references/review-checklist.md

@@ -5,9 +5,10 @@ Use this checklist before handing off a new or modified skill.
 ## Frontmatter
 
 - [ ] `name` uses lowercase letters, numbers, and hyphens only.
-- [ ] `description` is third-person and trigger-rich.
-- [ ] `description` includes both what the skill does and when to use it.
+- [ ] `description` is third-person, specific, and includes trigger terms.
+- [ ] `description` includes both what the skill does (WHAT) and when to use it (WHEN).
 - [ ] The skill name does not collide with a platform built-in helper unless that is intentional.
+- [ ] The skill name is specific (`processing-pdfs`), not vague (`helper`, `utils`, `tools`).
 
 ## Scope And Boundaries
 
@@ -15,14 +16,18 @@ Use this checklist before handing off a new or modified skill.
 - [ ] `When NOT To Use` or equivalent boundary guidance is present when triggers may overlap.
 - [ ] Project-private rules are in `.cstl/spec/` or a project-local skill, not in a public bundled skill.
 - [ ] The skill distinguishes local project customization from upstream Trellis source changes.
+- [ ] Terminology is consistent throughout.
 
 ## Entry File
 
 - [ ] `SKILL.md` is concise and under 500 lines.
+- [ ] `SKILL.md` is written in English unless the target platform or user explicitly requires another language.
 - [ ] `SKILL.md` contains the minimum routing and workflow needed to start.
 - [ ] `## Hard Constraints` appears before `## Workflow` when constraints exist.
-- [ ] Hard constraints are imperative one-liners.
-- [ ] The same rule is not repeated in multiple sections.
+- [ ] Hard constraints are imperative one-liners (`Always X. Never Y.`).
+- [ ] The same rule is not repeated in multiple sections; Hard Constraints is the only rule list.
+- [ ] Workflow has an explicit tool-call sequence and stop conditions.
+- [ ] Tool usage limits are stated when applicable.
 
 ## References And Assets
 
@@ -36,7 +41,7 @@ Use this checklist before handing off a new or modified skill.
 - [ ] Scripts are necessary for determinism, not decorative.
 - [ ] Scripts expose only necessary parameters.
 - [ ] Scripts do not rely on shell variables or state from a previous tool call.
-- [ ] Scripts return structured JSON when they mutate files or provide machine-readable status.
+- [ ] Scripts return structured JSON to stdout when they mutate files or provide machine-readable status.
 - [ ] Syntax checks were run for modified scripts when applicable.
 
 ## Trellis Template Integration

package/dist/templates/common/commands/continue.md

@@ -41,21 +41,22 @@ Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
 
 ## Step 4: Decide Where You Are
 
-When a task is selected, `get_context.py` shows the selected task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
+When a task is selected, `get_context.py` shows the selected task. Route by Kernel / persisted `required_controls.rigor` and `topology.kind`, not by whether `design.md` or `implement.md` exist. `status` is a projection, not the sole truth. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
 
 - `status=planning` + no `prd.md` → **1.1** (Read `.cstl/framework/prd-grill-frontier.md` for PRD Grill discipline)
-- `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
-- `status=planning` + complex artifacts complete + sub-agent jsonl not curated (only the seed `_example` row) → **1.3**
+- `status=planning` + `prd.md` + rigor is lite (or missing contract = explicit Lite) → **1.4** review / execution gate
+- `status=planning` + rigor is full + required planning artifacts not complete → stay in planning (`design.md` / `implement.md` only when `required_controls` says so)
 - `status=planning` + required artifacts complete + required jsonl curated or inline mode → execution gate (run `task.py start-execution <task> --check`, report PASS, ask for explicit execution approval, then run `task.py start-execution <task> --approved`)
 - `status=in_progress` + implementation not started → **2.1**
 - `status=in_progress` + implementation done, not yet checked → **2.2**
 - `status=in_progress` + check passed → **3.1**
 - `status=completed` (rare; usually archived immediately) → archive flow
+- `topology.kind=parent-child` → Parent integration path, not ordinary Child closeout. `parent_id` alone does **not** make a Child a Parent.
 
 Phase rules (full detail in `.cstl/workflow.md`):
 
 1. Run steps **in order** within a phase — `[required]` steps must not be skipped
-2. `[once]` steps are already done if the required output exists. `prd.md` alone can be enough only for lightweight tasks; complex tasks also need `design.md` and `implement.md`.
+2. `[once]` steps are already done if the required output exists. `prd.md` alone can be enough when rigor is Lite; Full follows `required_controls`, not file presence.
 3. You may go back to an earlier phase if discoveries require it
 
 ## Step 5: Load the Specific Step

package/dist/templates/common/index.d.ts

@@ -28,6 +28,17 @@ export interface CommonBundledSkill {
     /** Files that must be written under the skill directory */
     files: CommonBundledSkillFile[];
 }
+/**
+ * Optional/experimental skill — same shape as bundled skills, but lives under
+ * `optional-skills/` which `getBundledSkillTemplates()` does NOT scan.
+ * Installed only via `cstl init --with-optional <name>` (default off).
+ */
+export interface CommonOptionalSkill {
+    /** Skill directory name, e.g. "chrome-cdp" */
+    name: string;
+    /** Files that must be written under the skill directory */
+    files: CommonBundledSkillFile[];
+}
 /**
  * Get all command templates (stay as slash commands on all platforms).
  * Results are cached after first call.
@@ -45,4 +56,13 @@ export declare function getSkillTemplates(): CommonTemplate[];
  * lazy-loadable instead of being flattened into one oversized SKILL.md.
  */
 export declare function getBundledSkillTemplates(): CommonBundledSkill[];
+/**
+ * Get all optional/experimental skills (e.g. `optional-skills/chrome-cdp/`).
+ *
+ * Deliberately separate from {@link getBundledSkillTemplates}: `optional-skills/`
+ * is NOT scanned by the bundled pipeline, so default `cstl init` never installs
+ * these. They are installed only through `cstl init --with-optional <name>`.
+ * Results are cached after first call.
+ */
+export declare function getOptionalSkillTemplates(): CommonOptionalSkill[];
 //# sourceMappingURL=index.d.ts.map

package/dist/templates/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAMpD;AAuCD;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,EAAE,CAM/D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAQD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAMpD;AA2CD;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,EAAE,CAM/D;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,mBAAmB,EAAE,CAMjE"}

package/dist/templates/common/index.js

@@ -32,6 +32,7 @@ function listMarkdownFiles(dir) {
 let cachedCommands;
 let cachedSkills;
 let cachedBundledSkills;
+let cachedOptionalSkills;
 /**
  * Get all command templates (stay as slash commands on all platforms).
  * Results are cached after first call.
@@ -67,8 +68,8 @@ function listDirectories(dir) {
 function toPosixRelativePath(root, filePath) {
     return relative(root, filePath).split(sep).join("/");
 }
-function listBundledSkillFiles(skillDir) {
-    const root = join(__dirname, "bundled-skills", skillDir);
+function listSkillFiles(rootDir, skillDir) {
+    const root = join(__dirname, rootDir, skillDir);
     const files = [];
     function walk(dir) {
         for (const entry of readdirSync(dir)) {
@@ -88,6 +89,9 @@ function listBundledSkillFiles(skillDir) {
     walk(root);
     return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
 }
+function listBundledSkillFiles(skillDir) {
+    return listSkillFiles("bundled-skills", skillDir);
+}
 /**
  * Get all multi-file built-in skills.
  *
@@ -101,4 +105,19 @@ export function getBundledSkillTemplates() {
     }));
     return cachedBundledSkills;
 }
+/**
+ * Get all optional/experimental skills (e.g. `optional-skills/chrome-cdp/`).
+ *
+ * Deliberately separate from {@link getBundledSkillTemplates}: `optional-skills/`
+ * is NOT scanned by the bundled pipeline, so default `cstl init` never installs
+ * these. They are installed only through `cstl init --with-optional <name>`.
+ * Results are cached after first call.
+ */
+export function getOptionalSkillTemplates() {
+    cachedOptionalSkills ??= listDirectories("optional-skills").map((name) => ({
+        name,
+        files: listSkillFiles("optional-skills", name),
+    }));
+    return cachedOptionalSkills;
+}
 //# sourceMappingURL=index.js.map

package/dist/templates/common/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/common/optional-skills/chrome-cdp/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: chrome-cdp
+description: Interact with local Chrome browser session (only on explicit user approval after being asked to inspect, debug, or interact with a page open in Chrome)
+---
+
+> **experimental** — optional skill, installed on explicit request only (`cstl init --with-optional chrome-cdp`). Not a default Trellis capability.
+>
+> vendored from `blaze-skills/chrome-cdp@4ed61ff`（源 commit）；同步机制：改源 → 拷副本 → 更新本标记。不要直接在本副本上分叉内容。
+
+# Chrome CDP
+
+Lightweight Chrome DevTools Protocol CLI. Connects directly via WebSocket — no Puppeteer, works with 100+ tabs, instant connection.
+
+## Required Safety Wording
+
+> Use Chrome CDP only after the user explicitly approves interacting with their existing local Chrome browser session for this task. This skill can reveal open tabs, page content, authenticated data, screenshots, profile state, and extension-influenced behavior, and it can mutate real browser state through navigation, clicks, typing, new tabs, or arbitrary CDP commands. Prefer Playwright MCP for reproducible browser automation and UI verification. Ask before `list`; ask again before inspecting content, taking screenshots, evaluating JavaScript, navigating, clicking, typing, opening tabs, or using raw CDP commands. Never use this skill for routine browser tests or when a controlled Playwright/sessionless check is sufficient.
+
+## Channel Selection (three-way)
+
+| Channel | Status | Use for |
+| --- | --- | --- |
+| Playwright MCP | **default** | Reproducible browser automation, rendered UI evidence, screenshots, UI smoke verification |
+| `cursor-ide-browser` (IDE preview) | IDE 预览 | Page inspection/preview inside the IDE without touching the user's real Chrome profile |
+| `chrome-cdp` (this skill) | real Chrome, attach-only on approval | Inspect/debug/interact with the user's **already-open local Chrome session** (login state, cookies, tabs) — only after explicit user approval |
+
+- If a `mcp__chrome-devtools__*` server is present in the environment, ask the user which channel they want: the chrome-devtools MCP server and this CDP CLI are **mutually exclusive** for a given interaction — never run both against the same tab.
+- Never switch to MCP when the user explicitly requires CDP. CDP may have login state that MCP does not.
+
+## Prerequisites
+
+- Chrome (or Chromium, Brave, Edge, Vivaldi) with remote debugging enabled: open `chrome://inspect/#remote-debugging` and toggle the switch
+- Node.js 22+ (uses built-in WebSocket)
+- If your browser's `DevToolsActivePort` is in a non-standard location, set `CDP_PORT_FILE` to its full path
+
+## Hard Constraints
+
+- Never use `shot` to read page content. Use it only for visual debugging as a last resort.
+- Always prefer `eval` plus `getBoundingClientRect()` over `shot` to find element coordinates.
+- Always prefer `clickxy` over `click <selector>` unless you have a specific reason to use DOM click.
+- Always check `window.location.href` and `list` after clicking.
+- Always collect volatile page data in one `eval` call when possible.
+- Never switch to MCP when the user explicitly requires CDP. CDP may have login state that MCP does not.
+
+## Commands
+
+All commands use `scripts/cdp.mjs`. The `<target>` is a **unique** targetId prefix from `list`.
+
+```bash
+scripts/cdp.mjs list                          # list all open tabs (* marks current active tab)
+scripts/cdp.mjs eval   <target> <expr>        # run JS in page context
+scripts/cdp.mjs clickxy <target> <x> <y>      # real mouse click at CSS px coords (preferred)
+scripts/cdp.mjs click  <target> <selector>    # DOM click by CSS selector (SPA-unreliable)
+scripts/cdp.mjs nav    <target> <url>         # navigate and wait for load
+scripts/cdp.mjs snap   <target>               # accessibility tree (token-light alternative to shot)
+scripts/cdp.mjs type   <target> <text>        # insert text at current focus
+scripts/cdp.mjs html   <target> [selector]    # full page or element HTML
+scripts/cdp.mjs shot   <target> [file]        # screenshot (last resort, very token-heavy)
+scripts/cdp.mjs net    <target>               # network performance entries (resource timing)
+scripts/cdp.mjs loadall <target> <selector> [ms]  # [exceptional] repeatedly click a "load more" button until it disappears
+scripts/cdp.mjs evalraw <target> <method> [json]  # [exceptional] send a raw CDP command; returns JSON result
+scripts/cdp.mjs open   [url]                  # open new tab
+scripts/cdp.mjs stop   [target]               # stop daemon(s)
+```
+
+- `net` is safe, read-only (resource timing entries).
+- `loadall` is **exceptional**: it mutates the real page repeatedly; ask for explicit approval before using it.
+- `evalraw` is **exceptional**: it exposes arbitrary CDP methods beyond the curated command list; require exceptional approval before using it.
+
+## Active Tab Detection (macOS)
+
+`list` automatically marks the currently focused Chrome tab with `*` using AppleScript:
+
+```
+(* = current active tab in Chrome)
+* B5404DDD  MiMo-V2-Pro & Omni & TTS ...   https://www.reddit.com/...
+  5BE8FE3C  Google 新聞                      https://news.google.com/...
+```
+
+- On first run, macOS may show an automation permission dialog — click Allow once.
+- Only works on macOS; silently skipped on other platforms.
+- Reflects the real Chrome foreground tab, updates on every `list` call.
+- **Use this to quickly identify the target without manually matching URLs.**
+
+## Windows
+
+- Windows uses a **named pipe** per tab (`\\.\pipe\cdp-<targetId>`) instead of a Unix socket; runtime files live under `%LOCALAPPDATA%\cdp\`.
+- Chrome may show an **"Allow debugging?"** popup once per tab daemon — click Allow once. If the daemon fails to start, the error message explicitly asks whether you clicked Allow in Chrome.
+- Remote debugging must be enabled at `chrome://inspect/#remote-debugging` (Windows supported; `DevToolsActivePort` is discovered under `%LOCALAPPDATA%\<browser>\User Data\`).
+
+## Coordinates
+
+`shot` saves at native resolution: image pixels = CSS pixels × DPR. `clickxy` takes **CSS pixels**.
+Use this conversion only if you already have a screenshot for visual debugging. Do not take a screenshot just to compute click coordinates.
+
+```
+CSS px = screenshot px / DPR
+```
+
+## Workflow
+
+### Identify the right target quickly
+
+```bash
+# Run list — the * tab is what the user currently has open in Chrome
+scripts/cdp.mjs list
+# → use the * prefix directly as <target>
+```
+
+### Click a JS-driven link (SPA / Google News / React apps)
+
+```bash
+# 1. Get element center in CSS px via JS (no screenshot needed)
+eval <target> "var el=document.querySelector('a[href*=\"keyword\"]'); var r=el.getBoundingClientRect(); ((r.left+r.right)/2)+','+((r.top+r.bottom)/2)"
+# → "908,555"
+
+# 2. Click using real mouse input
+clickxy <target> 908 555
+
+# 3a. Check if current tab navigated
+eval <target> "window.location.href"
+
+# 3b. Check if a new tab opened (compare before/after)
+list
+```
+
+### Detect new tab after click
+
+```bash
+# Before click — note existing targetIds
+list
+# Click ...
+# After click — new entry = new tab
+list
+# Inspect the new tab
+eval <new-target-prefix> "window.location.href"
+eval <new-target-prefix> "document.title"
+```
+
+### Inspect page content efficiently
+
+```bash
+# Preferred: JS query (near-zero tokens)
+eval <target> "document.title"
+eval <target> "Array.from(document.querySelectorAll('a[href*=\"/news/\"]')).map(a=>a.innerText+' | '+a.href).join('\n')"
+
+# Alternative: accessibility tree (compact, structured)
+snap <target>
+
+# Avoid: screenshot (only when visual layout truly needed)
+shot <target>
+```
+
+## Token Cost Guide
+
+| Command | Relative cost | Use when |
+|---------|--------------|----------|
+| `eval`  | Very low     | Reading text, coords, URLs, DOM state |
+| `snap`  | Low–Medium   | Need page structure overview |
+| `html`  | Medium       | Need raw HTML of a section |
+| `shot`  | Very high    | Visual debugging only (last resort) |
+
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| [`examples/fetch-hook-api-capture.md`](examples/fetch-hook-api-capture.md) | Intercept SPA API responses by injecting a fetch/XHR hook via `eval` — covers inject → trigger → read → paginate workflow |
+
+## Runtime Artifacts & Cleanup
+
+- Each tab runs a per-tab daemon (holds the CDP session; auto-exits after 20 min idle or when the tab closes).
+- `pages.json` cache + screenshots live in the runtime dir: `%LOCALAPPDATA%\cdp\` (Windows), `$XDG_RUNTIME_DIR/cdp` or `~/.cache/cdp` (Linux), `~/Library/Caches`-adjacent `~/.cache/cdp` (macOS).
+- Stop daemons explicitly when done: `scripts/cdp.mjs stop` (all) or `scripts/cdp.mjs stop <target>` (one).
+- Screenshots saved without an explicit path land in the runtime dir (`screenshot-<target>.png`) — delete them after use; they are local residual artifacts, not evidence for task verification.
+
+## When NOT to use this skill
+
+- Page content can be fetched statically (use `WebFetch` instead).
+- User has not explicitly asked to interact with Chrome.
+- A controlled Playwright/sessionless check is sufficient.

package/dist/templates/common/optional-skills/chrome-cdp/examples/fetch-hook-api-capture.md

@@ -0,0 +1,149 @@
+# Fetch Hook — Intercept SPA API Responses
+
+The CDP skill does not support `Network` domain event listening (`cdp.mjs` uses a request/response architecture and cannot receive push events like `Network.responseReceived`). Injecting a fetch hook via `eval` is the best alternative for capturing API data from SPA pages.
+
+## When to Use
+
+- Page loads data via `fetch` / `XMLHttpRequest` from a backend API (SPA, Next.js, Convex, etc.)
+- You need raw JSON responses rather than reverse-parsing from the DOM
+- You need request parameters for replay or pagination
+
+## Workflow
+
+### Step 1: Inject Hook
+
+Inject **after the page has finished loading**. The hook is lost on navigation/refresh, so it must be injected after `nav`.
+
+```bash
+scripts/cdp.mjs eval <target> "
+window.__captured = [];
+var _origFetch = window.fetch;
+window.fetch = async function() {
+  var url = typeof arguments[0] === 'string' ? arguments[0] : (arguments[0] && arguments[0].url || '');
+  var opts = arguments[1] || {};
+  var reqBody = '';
+  if (opts.body) { try { reqBody = typeof opts.body === 'string' ? opts.body : JSON.stringify(opts.body); } catch(e) {} }
+  var resp = await _origFetch.apply(this, arguments);
+  try {
+    var clone = resp.clone();
+    var text = await clone.text();
+    window.__captured.push({ url: url, method: opts.method || 'GET', reqBody: reqBody, resBody: text, len: text.length });
+  } catch(e) {}
+  return resp;
+};
+'hook installed'
+"
+```
+
+**Key points:**
+- Must `clone()` the response before reading the body — otherwise the original response stream is consumed and the page breaks
+- Data is stored in `window.__captured` array, read later via `eval`
+- The hook only captures requests made **after** injection — it cannot retroactively capture requests that already completed during page load
+
+### Step 2: Trigger API Calls
+
+After injecting the hook, interact with the page to trigger new API requests:
+
+```bash
+# Option A: scroll to trigger infinite scroll
+scripts/cdp.mjs eval <target> "window.scrollTo(0, document.body.scrollHeight); 'scrolled'"
+
+# Option B: click a "Load More" button
+scripts/cdp.mjs click <target> "button.load-more"
+
+# Option C: change sort/filter to trigger a new request
+scripts/cdp.mjs click <target> "select#sort-by"
+```
+
+Wait 1-2 seconds for requests to complete before reading.
+
+### Step 3: Read Captured Data
+
+```bash
+# Overview of captured requests
+scripts/cdp.mjs eval <target> "
+var c = window.__captured || [];
+'Captured: ' + c.length + ' requests\n' + c.map(function(r,i) {
+  return i + ': ' + r.method + ' ' + r.url.substring(0,80) + ' (' + r.len + ' bytes)';
+}).join('\n');
+"
+
+# Read a specific response body (truncate to avoid token explosion)
+scripts/cdp.mjs eval <target> "window.__captured[0].resBody.substring(0, 2000)"
+
+# Read request parameters (to understand API format, pagination cursor, etc.)
+scripts/cdp.mjs eval <target> "window.__captured[0].reqBody"
+```
+
+### Step 4: Replay API with Pagination
+
+Once you understand the API format, replay calls directly in the page context to fetch all data automatically:
+
+```bash
+scripts/cdp.mjs eval <target> "
+(async function() {
+  var allItems = [];
+  var cursor = null;
+  var hasMore = true;
+  while (hasMore) {
+    var resp = await fetch('https://example.com/api/query', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        path: 'items:list',
+        args: [{ cursor: cursor, numItems: 100 }]
+      })
+    });
+    var data = await resp.json();
+    allItems = allItems.concat(data.value.page);
+    hasMore = data.value.hasMore;
+    cursor = data.value.nextCursor;
+  }
+  window.__allItems = allItems;
+  return 'Total: ' + allItems.length;
+})()
+"
+```
+
+Then read results in batches to avoid oversized output:
+
+```bash
+# Read first 50
+scripts/cdp.mjs eval <target> "JSON.stringify(window.__allItems.slice(0, 50).map(function(it) { return { name: it.name, author: it.author }; }))"
+
+# Read 50-100
+scripts/cdp.mjs eval <target> "JSON.stringify(window.__allItems.slice(50, 100).map(function(it) { return { name: it.name, author: it.author }; }))"
+```
+
+## Caveats
+
+| Limitation | Details |
+|------------|---------|
+| **Lost on navigation** | `nav` / page refresh clears the hook and `window.__captured` — re-inject after each navigation |
+| **fetch only** | Does not intercept `XMLHttpRequest` by default; see XHR hook below if needed |
+| **Memory growth** | `__captured` array grows indefinitely during long sessions — periodically clear with `window.__captured = []` |
+| **CORS** | Step 4 API replay runs in the page's origin context and is subject to same-origin policy; this is fine if the original request was made by the page itself |
+| **Large responses** | Returning large data via `eval` is token-expensive — use `.substring()` to truncate or `.map()` to extract only the fields you need |
+
+## XMLHttpRequest Hook (Optional)
+
+If the page uses `XMLHttpRequest` instead of `fetch`:
+
+```bash
+scripts/cdp.mjs eval <target> "
+var _origOpen = XMLHttpRequest.prototype.open;
+var _origSend = XMLHttpRequest.prototype.send;
+XMLHttpRequest.prototype.open = function(method, url) {
+  this.__method = method;
+  this.__url = url;
+  return _origOpen.apply(this, arguments);
+};
+XMLHttpRequest.prototype.send = function(body) {
+  this.addEventListener('load', function() {
+    window.__captured.push({ url: this.__url, method: this.__method, reqBody: body || '', resBody: this.responseText, len: this.responseText.length });
+  });
+  return _origSend.apply(this, arguments);
+};
+'xhr hook installed'
+"
+```