@blxzer/cursor-trellis 0.4.1 → 0.4.3

package/dist/templates/common/bundled-skills/cstl-skill-creator/references/general-authoring.md

@@ -0,0 +1,189 @@
+# General Skill Authoring
+
+Method and patterns for writing reusable agent skills. Imperative rules live in `SKILL.md` Hard Constraints; this file explains how to apply them. For Trellis location choice, read `cstl-skill-locations.md`. For description wording and anti-patterns, read `authoring-rules.md`.
+
+## Gather Requirements
+
+Collect these six elements before writing files:
+
+1. **Purpose and scope**: What specific workflow should this skill solve?
+2. **Trigger scenarios**: When should the agent automatically use it?
+3. **Target location**: Project skill, shared skill, bundled template, or personal skill?
+4. **Domain constraints**: Required tools, APIs, reliability constraints.
+5. **Output style**: Report template, checklist, strict schema, etc.
+6. **Existing patterns**: Are there existing skills or conventions to follow?
+
+### Inferring from Context
+
+If previous conversation already surfaced workflows, patterns, or domain knowledge, infer the skill from that context.
+
+Ask the user when requirements are ambiguous and discrete choices are needed.
+
+## Directory Layout
+
+```
+skill-name/
+├── SKILL.md            # required
+├── scripts/            # optional utility scripts
+├── bin/                # optional compiled binaries
+├── references/         # optional detailed docs (preferred over a single reference.md)
+├── examples/           # optional samples
+└── prompts/            # optional long prompts
+```
+
+Keep the entry file short. Put long guidance one level deep under `references/` and link it from `SKILL.md`.
+
+Generic storage scopes (`~/.agents/skills/` vs project `.agents/skills/`) are not enough for Trellis work. Use `cstl-skill-locations.md` to pick the target directory.
+
+## Core Authoring Principles
+
+### 1. Concise is Key
+
+The context window is shared with conversation history, other skills, and requests. Every token competes for space.
+
+Default assumption: the agent is already very smart. Only add context it does not already have.
+
+Challenge each piece of information:
+
+- Does the agent really need this explanation?
+- Can I assume the agent knows this?
+- Does this paragraph justify its token cost?
+
+### 2. Progressive Disclosure
+
+Put essential information in `SKILL.md`; detailed reference material in separate files that the agent reads only when needed.
+
+Keep references one level deep — link directly from `SKILL.md`. Nested reference chains may result in partial reads.
+
+### 3. One File, One Concern
+
+Each skill should address a single workflow. If a skill tries to do too many things, split it.
+
+### 4. Maximize Determinism
+
+Skills run through multiple independent tool calls. Each call is stateless — no shared session or persistent variables between calls.
+
+Eliminate ambiguity at every layer — description, workflow, script parameters, and output format.
+
+- Internalize decisions: if a value can be decided inside a script (output path, temp filename, timestamp), do not expose it as a parameter.
+- Use fixed literal paths in workflows. The agent copies commands verbatim. Never rely on shell variables staying consistent across separate tool calls.
+- Minimize script parameters. Only require what the agent must provide.
+- Scripts return structured JSON to stdout so the agent can parse the result deterministically.
+- Specify an exact tool-call sequence, for example: "Exactly 3 steps: write file → run command → deliver output."
+- Add stop conditions. Prevent open-ended tool loops for expensive operations.
+
+### 5. Set Appropriate Degrees of Freedom
+
+Match specificity to the task's fragility:
+
+| Freedom Level | When to Use | Example |
+|---------------|-------------|---------|
+| **High** (text instructions) | Multiple valid approaches, context-dependent | Code review guidelines |
+| **Medium** (pseudocode / templates) | Preferred pattern with acceptable variation | Report generation |
+| **Low** (specific scripts) | Fragile operations, consistency critical | Database migrations |
+
+## Recommended SKILL.md Sections
+
+1. Goal
+2. Hard Constraints (imperative one-liners; placed before Workflow)
+3. Workflow
+4. Output Template
+5. When NOT to use this skill
+
+## Common Patterns
+
+### Workflow Pattern
+
+Break operations into explicit steps with a clear tool-call sequence:
+
+```markdown
+## Workflow
+
+1. Gather input data
+2. Process: `<exact command the agent should run>`
+3. Parse output, proceed to the next step
+4. Stop when the condition is met
+```
+
+### Template Pattern
+
+Provide output format templates:
+
+````markdown
+## Output Template
+
+```markdown
+# [Title]
+
+## Summary
+[One-paragraph overview]
+
+## Findings
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+```
+````
+
+### Conditional Workflow Pattern
+
+Guide through decision points:
+
+```markdown
+## Workflow
+
+1. Determine the type:
+   **Creating new?** → Follow "Creation workflow" below
+   **Editing existing?** → Follow "Editing workflow" below
+```
+
+### Feedback Loop Pattern
+
+For quality-critical tasks, implement validation:
+
+```markdown
+1. Make edits
+2. Validate: `python scripts/validate.py output/`
+3. If validation fails → fix and re-validate
+4. Only proceed when validation passes
+```
+
+## Utility Scripts
+
+Pre-made scripts are more reliable than generated code, save tokens, and keep behavior consistent.
+
+Script design:
+
+- Only expose parameters the agent must supply (input data, mode selection).
+- Let the script handle internal decisions (output path, temp files, format defaults).
+- Return results as structured JSON to stdout.
+- State whether the agent should **execute** the script or **read** it as reference.
+
+## Minimal Template
+
+```markdown
+---
+name: skill-name
+description: Specific capability and trigger scenarios.
+---
+
+# Skill Name
+
+## Goal
+One clear objective.
+
+## Hard Constraints
+- Always X. Never Y.
+- Always validate the input before step 2.
+- Never call the API more than 5 times per run.
+
+## Workflow
+1. Step one
+2. Step two
+3. Stop when condition met
+
+## Output Template
+Required output structure.
+
+## When NOT to use this skill
+- Boundary cases.
+```

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** (load `cstl-brainstorm`)
-- `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` + no `prd.md` → **1.1** (Read `.cstl/framework/prd-grill-frontier.md` for PRD Grill discipline)
+- `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.