browser-debugger-cli 0.10.0 → 0.11.0

package/.claude/skills/bdg/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: bdg
+description: Use bdg CLI to drive and debug a real Chrome via Chrome DevTools Protocol - navigate, click, fill and submit forms, check what an action changed (navigation, new messages, pending requests), inspect elements without screenshots (box, layout, fonts, colors, a11y), read network requests and console errors, and call any CDP method. Use this skill when you need to verify a UI change in a running app, debug a page, automate a browser flow, or scrape dynamic content.
+---
+
+# bdg - Browser Automation CLI
+
+## Quick Start
+
+```bash
+bdg https://example.com          # Start session (launches Chrome)
+bdg dom screenshot /tmp/page.png # Take screenshot
+bdg stop                         # End session
+```
+
+## Session Management
+
+```bash
+bdg <url>                  # Start session (1920x1080, headless if no display)
+bdg <url> --headless       # Force headless mode
+bdg <url> --no-headless    # Force visible browser window
+bdg status                 # Check session status
+bdg peek                   # Preview collected telemetry
+bdg stop                   # End session (use sparingly)
+bdg cleanup                # Clean up after a crashed session
+bdg cleanup --force        # Kill a stuck session (daemon + its Chrome)
+```
+
+**Sessions run indefinitely by default** (no timeout). With HMR/hot-reload dev servers, keep the session running:
+
+```bash
+bdg http://localhost:5173      # Start once
+# ... make code changes, HMR updates the page ...
+bdg dom screenshot /tmp/s.png  # Check anytime
+bdg peek                       # Preview collected data
+# No need to stop/restart - Chrome stays on the page
+```
+
+**Don't stop sessions prematurely** - use `bdg peek` to inspect data. Only call `bdg stop` when completely done with browser automation.
+
+## Screenshots
+
+Always use `bdg dom screenshot` (raw CDP is blocked):
+
+```bash
+bdg dom screenshot /tmp/page.png                    # Full page
+bdg dom screenshot /tmp/viewport.png --no-full-page # Viewport only
+bdg dom screenshot /tmp/el.png --selector "#main"   # Element only
+bdg dom screenshot /tmp/scroll.png --scroll "#target" # Scroll to element first
+```
+
+## Actions Report What Changed
+
+`dom click`, `fill`, `submit`, `pressKey`, `hover` and `scroll` wait for the requests the action starts, then say what happened. Read this before reaching for a screenshot:
+
+```text
+✓ Element Clicked
+Page: navigated to https://app.test/secure (200)    # navigation (or "URL changed ... (same document)")
+New text: "Your password is invalid!" (div#flash)   # alert/status/aria-live messages that appeared
+⚠ Element Clicked (no visible effect observed ...)  # nothing changed - wrong element or a broken handler
+```
+
+- In `--json`: `navigation`, `messages`, `effect: "none"` and pending work (timers, spinners) are fields on `data`.
+- Results the page shows later are not waited for: follow up with `bdg dom wait` (below).
+
+## Form Interaction
+
+```bash
+# Discover forms
+bdg dom form --brief              # Quick scan: field names, types, required
+
+# Fill and interact
+bdg dom fill "input[name='user']" "myuser"    # Fill by selector
+bdg dom fill 0 "value"                         # Fill by index (from query)
+bdg dom click "button.submit"                  # Click element
+bdg dom submit "form" --wait-navigation        # Submit and wait for page load
+bdg dom pressKey "input" Enter                 # Press Enter key
+
+# Options
+--no-wait          # Skip network stability wait
+--wait-navigation  # Wait for page navigation (traditional forms)
+--wait-network <ms> # Wait for network idle (SPA forms)
+--index <n>        # Select nth element when multiple match
+```
+
+## DOM Inspection
+
+```bash
+bdg dom query "selector"     # Find elements, returns [0], [1], [2]... (0-based)
+bdg dom get "selector"       # Get semantic a11y info (token-efficient)
+bdg dom get "selector" --raw # Get full HTML
+bdg dom eval "js expression" # Run JavaScript
+bdg dom a11y "role:button"   # Query by accessibility role/name
+```
+
+Selectors search open shadow roots and same-origin iframes, and accept `:has-text("...")` and `:visible`.
+
+### Look Without a Screenshot
+
+```bash
+bdg dom inspect "button.primary"   # Box, layout, rendered font, colors + WCAG contrast, borders, state (~60-100 tokens)
+bdg dom inspect ".card" --why color  # Which CSS rule set a property, and what it overrode
+bdg dom layout ".card"             # Positions/sizes of every match: above/below the fold, hidden, covered
+bdg dom listeners "#save"          # Event listeners that run for an element (incl. delegated, React/Preact)
+bdg page emulate --viewport 390x844 --color-scheme dark   # Responsive/theme check mid-session
+```
+
+### Wait for Something
+
+```bash
+bdg dom wait '#result' --visible       # Appears and is visible
+bdg dom wait '.toast' --text 'Saved'   # Contains text
+bdg dom wait '#loading' --gone         # Spinner went away
+bdg dom wait --load                    # Page finished loading
+```
+
+## Network and Console
+
+```bash
+bdg network list                              # Requests (DevTools-style)
+bdg network list --filter "status-code:>=400" # Failed requests
+bdg details network <id>                      # Headers, timing, body of one request
+bdg console --level error                     # Console errors on the current page
+bdg console --follow                          # Stream messages live
+bdg network har /tmp/session.har              # Export HAR 1.2
+```
+
+## CDP Access
+
+Direct access to Chrome DevTools Protocol:
+
+```bash
+# Execute any CDP method
+bdg cdp Runtime.evaluate --params '{"expression": "document.title", "returnByValue": true}'
+bdg cdp Page.navigate --params '{"url": "https://example.com"}'
+bdg cdp Page.reload --params '{"ignoreCache": true}'
+
+# Discovery
+bdg cdp --list                    # List all domains
+bdg cdp Network --list            # List methods in domain
+bdg cdp Network.getCookies --describe  # Show method schema
+bdg cdp --search cookie           # Search methods
+```
+
+**Important**: Always use `returnByValue: true` for Runtime.evaluate to get serialized values.
+
+## Common Patterns
+
+### Login Flow
+```bash
+bdg https://example.com/login
+bdg dom form --brief
+bdg dom fill "input[name='username']" "$USER"
+bdg dom fill "input[name='password']" "$PASS"
+bdg dom submit "button[type='submit']" --wait-navigation
+bdg dom screenshot /tmp/result.png
+bdg stop
+```
+
+### Verify a UI Change (dev server with HMR)
+```bash
+bdg http://localhost:5173                 # Once; keep the session running
+bdg dom click "button.save"               # Read the reported effect
+bdg dom wait '.toast' --text 'Saved'
+bdg console --level error                 # Anything thrown?
+bdg dom inspect ".toast"                  # Looks right? (no screenshot needed)
+```
+
+### Extract Data
+```bash
+bdg cdp Runtime.evaluate --params '{
+  "expression": "Array.from(document.querySelectorAll(\"a\")).map(a => ({text: a.textContent, href: a.href}))",
+  "returnByValue": true
+}' | jq '.data.result.result.value'
+```
+
+## JSON Output and Exit Codes
+
+Add `--json` (`-j`) to any command for `{ version, success, data }` (or `{ success: false, error, exitCode, suggestion }`). `bdg --help --json` lists every command, flag and exit code.
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| 0 | Success | - |
+| 81 | Invalid arguments (incl. blocked raw CDP methods) | Read the suggestion, use the alternative |
+| 83 | Resource not found | Element/session doesn't exist |
+| 85 | Session busy (still starting/stopping) | Retry shortly |
+| 87 | Stale index (page changed since `dom query`) | Re-run the query |
+| 91 | `dom eval` script threw | Fix the JavaScript |
+| 101 | CDP connection failure | Run `bdg cleanup --force` and retry |
+| 102 | Timeout (CDP, or `dom wait --timeout`) | Increase timeout or check page load |
+
+## Troubleshooting
+
+```bash
+bdg status --verbose      # Full diagnostics
+bdg cleanup               # Clean up after a crashed session
+bdg cleanup --force       # Kill a stuck session (daemon + its Chrome)
+```
+
+**Chrome won't launch?** Run `bdg cleanup --force` then retry.
+
+**Session stuck?** Run `bdg cleanup --force` to reset.
+
+### Custom Chrome Flags
+
+Use `--chrome-flags` or `BDG_CHROME_FLAGS` for self-signed certificates, CORS, etc.:
+
+```bash
+# CLI option
+bdg https://localhost:5173 --chrome-flags="--ignore-certificate-errors"
+
+# Environment variable
+BDG_CHROME_FLAGS="--ignore-certificate-errors" bdg https://localhost:5173
+
+# Multiple flags
+bdg https://example.com --chrome-flags="--ignore-certificate-errors --disable-web-security"
+```
+
+**Common flags for development:**
+- `--ignore-certificate-errors` - Self-signed SSL certs
+- `--disable-web-security` - CORS issues in development
+- `--allow-insecure-localhost` - Insecure localhost
+- `--disable-features=IsolateOrigins,site-per-process` - Cross-origin iframes
+
+## Verification Best Practices
+
+**Prefer DOM queries over screenshots** for verification:
+
+```bash
+# GOOD: Fast, precise, scriptable
+bdg cdp Runtime.evaluate --params '{
+  "expression": "document.querySelector(\".error-message\")?.textContent",
+  "returnByValue": true
+}'
+
+# GOOD: Check element exists
+bdg dom query ".submit-btn"
+
+# GOOD: Check text content
+bdg cdp Runtime.evaluate --params '{
+  "expression": "document.body.innerText.includes(\"Success\")",
+  "returnByValue": true
+}'
+
+# AVOID: Screenshots for simple verification (slow, requires visual inspection)
+bdg dom screenshot /tmp/check.png  # Only use when you need visual proof
+```
+
+**When to use screenshots:**
+- Visual regression testing
+- Capturing proof for user review
+- Debugging layout issues
+- When DOM structure is unknown
+
+**When to use DOM queries:**
+- Verifying text content appeared
+- Checking element exists/visible
+- Validating form state
+- Counting elements
+- Any programmatic assertion
+
+## When NOT to Use bdg
+
+- **Static HTML** - Use `curl` + `htmlq`/`pq`
+- **API calls** - Use `curl` + `jq`
+- **Simple HTTP** - Use `wget`/`curl`
+
+Use bdg when you need: JavaScript execution, dynamic content, browser APIs, screenshots, or network manipulation.

package/README.md

@@ -43,6 +43,17 @@ npm install -g browser-debugger-cli
 - ✅ Windows via WSL
 - ❌ PowerShell/Git Bash (not yet)
 
+## Use with Claude Code and Other Agents
+
+bdg ships an agent skill (`SKILL.md`) that teaches the workflow: start once, act, read what the action changed, inspect without screenshots, check network and console.
+
+```bash
+bdg install-skill            # ~/.claude/skills/bdg (Claude Code) + ~/.agents/skills/bdg (Codex, Gemini CLI, ...)
+bdg install-skill --claude   # Claude Code only
+```
+
+Start a new agent session afterwards, and re-run `bdg install-skill` after upgrading bdg. In Claude Code the skill loads when a task needs a browser, or on demand with `/bdg`.
+
 ## Quick Start
 
 ```bash

package/dist/commands/installSkill.d.ts

@@ -0,0 +1,20 @@
+import type { Command } from 'commander';
+import type { InstalledSkill, SkillTarget } from '../types.js';
+/**
+ * Copy the bdg skill into each target's skill directory, overwriting an
+ * older copy.
+ *
+ * @param targets - Agents to install for
+ * @param home - Home directory the skill roots are relative to
+ * @param source - SKILL.md to copy
+ * @returns One entry per target, in the given order
+ * @throws CommandError when the source is missing (83) or a write fails (82)
+ */
+export declare function installSkill(targets: SkillTarget[], home?: string, source?: string): InstalledSkill[];
+/**
+ * Register the install-skill command.
+ *
+ * @param program - Commander.js Command instance to register commands on
+ */
+export declare function registerInstallSkillCommand(program: Command): void;
+//# sourceMappingURL=installSkill.d.ts.map

package/dist/commands/installSkill.js

@@ -0,0 +1,87 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { CommandError } from '../errors/index.js';
+import { skillSourceMissingError, skillWriteFailedError } from '../errors/messages.js';
+import { formatInstalledSkills } from '../ui/formatters/installSkill.js';
+import { getErrorMessage } from '../utils/errors.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+import { PACKAGE_ROOT } from '../utils/packageRoot.js';
+/** The skill shipped with the package (also used by agents working in this repo). */
+const SKILL_SOURCE_PATH = join(PACKAGE_ROOT, '.claude', 'skills', 'bdg', 'SKILL.md');
+/** Skill roots, relative to the home directory, of the agents the skill is installed for. */
+const SKILL_ROOTS = {
+    claude: join('.claude', 'skills'),
+    agents: join('.agents', 'skills'),
+};
+/**
+ * Copy the bdg skill into each target's skill directory, overwriting an
+ * older copy.
+ *
+ * @param targets - Agents to install for
+ * @param home - Home directory the skill roots are relative to
+ * @param source - SKILL.md to copy
+ * @returns One entry per target, in the given order
+ * @throws CommandError when the source is missing (83) or a write fails (82)
+ */
+export function installSkill(targets, home = homedir(), source = SKILL_SOURCE_PATH) {
+    if (!existsSync(source)) {
+        const err = skillSourceMissingError(source);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    const content = readFileSync(source, 'utf-8');
+    return targets.map((target) => writeSkill(target, join(home, SKILL_ROOTS[target], 'bdg', 'SKILL.md'), content));
+}
+/**
+ * Write the skill to one path unless it already holds the same content.
+ *
+ * @param target - Agent the path belongs to
+ * @param path - Destination SKILL.md
+ * @param content - Skill text
+ * @returns What happened to the file
+ * @throws CommandError (82) when the directory or file cannot be written
+ */
+function writeSkill(target, path, content) {
+    const existing = existsSync(path) ? readFileSync(path, 'utf-8') : undefined;
+    if (existing === content) {
+        return { target, path, status: 'unchanged' };
+    }
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content);
+    }
+    catch (caught) {
+        const err = skillWriteFailedError(path, getErrorMessage(caught));
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.PERMISSION_DENIED);
+    }
+    return { target, path, status: existing === undefined ? 'installed' : 'updated' };
+}
+/**
+ * Targets picked by the flags; no flag means every agent.
+ *
+ * @param options - Parsed command options
+ * @returns Targets to install for
+ */
+function selectedTargets(options) {
+    const picked = Object.keys(SKILL_ROOTS).filter((target) => options[target]);
+    return picked.length > 0 ? picked : Object.keys(SKILL_ROOTS);
+}
+/**
+ * Register the install-skill command.
+ *
+ * @param program - Commander.js Command instance to register commands on
+ */
+export function registerInstallSkillCommand(program) {
+    program
+        .command('install-skill')
+        .description('Install the bdg agent skill for Claude Code (~/.claude/skills) and agents reading ~/.agents/skills (Codex, Gemini CLI, ...); re-run after upgrading bdg')
+        .option('--claude', 'Only ~/.claude/skills (Claude Code)')
+        .option('--agents', 'Only ~/.agents/skills (Codex, Gemini CLI and other agents)')
+        .addOption(jsonOption())
+        .action(async (options) => {
+        await runCommand((opts) => Promise.resolve({ success: true, data: { skills: installSkill(selectedTargets(opts)) } }), options, formatInstalledSkills);
+    });
+}
+//# sourceMappingURL=installSkill.js.map

package/dist/commands.js

@@ -4,6 +4,7 @@ import { registerConsoleCommand } from './commands/console.js';
 import { registerDetailsCommand } from './commands/details.js';
 import { registerFormInteractionCommands } from './commands/dom/formInteraction.js';
 import { registerDomCommands } from './commands/dom/index.js';
+import { registerInstallSkillCommand } from './commands/installSkill.js';
 import { registerNetworkCommands } from './commands/network/index.js';
 import { registerPageCommands } from './commands/page.js';
 import { registerPeekCommand } from './commands/peek.js';
@@ -44,5 +45,7 @@ export const commandRegistry = [
     registerNetworkCommands,
     addCommandGroup('Console Commands:'),
     registerConsoleCommand,
+    addCommandGroup('Agent Setup:'),
+    registerInstallSkillCommand,
 ];
 //# sourceMappingURL=commands.js.map

package/dist/errors/messages.d.ts

@@ -973,5 +973,21 @@ export declare function formInIframeError(iframeUrl: string, crossOrigin: boolea
 export declare function cdpCallError(method: string, message: string): ErrorWithSuggestion & {
     notFound: boolean;
 };
+/**
+ * The skill file is not where the package should have it (a broken or
+ * partial install).
+ *
+ * @param source - Expected SKILL.md path
+ * @returns Message and suggestion
+ */
+export declare function skillSourceMissingError(source: string): ErrorWithSuggestion;
+/**
+ * The skill could not be written to an agent's skill directory.
+ *
+ * @param path - Destination SKILL.md
+ * @param reason - The file system error
+ * @returns Message and suggestion
+ */
+export declare function skillWriteFailedError(path: string, reason: string): ErrorWithSuggestion;
 export {};
 //# sourceMappingURL=messages.d.ts.map

package/dist/errors/messages.js

@@ -1751,4 +1751,30 @@ export function cdpCallError(method, message) {
         notFound: false,
     };
 }
+/**
+ * The skill file is not where the package should have it (a broken or
+ * partial install).
+ *
+ * @param source - Expected SKILL.md path
+ * @returns Message and suggestion
+ */
+export function skillSourceMissingError(source) {
+    return {
+        message: `The bdg skill is missing from the installed package (${source})`,
+        suggestion: 'Reinstall bdg: npm install -g browser-debugger-cli',
+    };
+}
+/**
+ * The skill could not be written to an agent's skill directory.
+ *
+ * @param path - Destination SKILL.md
+ * @param reason - The file system error
+ * @returns Message and suggestion
+ */
+export function skillWriteFailedError(path, reason) {
+    return {
+        message: `Could not write ${path}: ${reason}`,
+        suggestion: 'Check the permissions of that directory, or install for the other agent only (--claude or --agents)',
+    };
+}
 //# sourceMappingURL=messages.js.map

package/dist/index.js

@@ -3358,6 +3358,18 @@ function formInIframeError(iframeUrl, crossOrigin) {
     suggestion: crossOrigin ? "Cross-origin iframes cannot be read or controlled; open the iframe URL directly: bdg <iframe url>" : 'dom form lists forms of the main document only; its fields are reachable directly: bdg dom query "input, select, textarea", then bdg dom fill <index> <value>'
   };
 }
+function skillSourceMissingError(source) {
+  return {
+    message: `The bdg skill is missing from the installed package (${source})`,
+    suggestion: "Reinstall bdg: npm install -g browser-debugger-cli"
+  };
+}
+function skillWriteFailedError(path6, reason) {
+  return {
+    message: `Could not write ${path6}: ${reason}`,
+    suggestion: "Check the permissions of that directory, or install for the other agent only (--claude or --agents)"
+  };
+}
 var LAUNCHED_CHROME_DESCRIPTION, A11Y_NAME_QUERY_EXAMPLE, SCOPED_FILTER_EXAMPLES, PLAYWRIGHT_ONLY_SYNTAX, MALFORMED_SELECTOR_DETAILS, SESSION_DIR_SUGGESTION, SCROLL_PROBLEMS, VIA_LABEL_SUFFIX, NAME_QUERY_PLACEHOLDER, LABEL_WITHOUT_CONTROL;
 var init_messages = __esm({
   "src/errors/messages.ts"() {
@@ -16670,6 +16682,87 @@ function registerDomCommands(program2) {
   );
 }
 
+// src/commands/installSkill.ts
+import { existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync8, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname5, join as join6 } from "path";
+init_errors3();
+init_messages();
+
+// src/ui/formatters/installSkill.ts
+init_formatting();
+import { homedir as homedir2 } from "os";
+function tildePath(path6) {
+  const home = homedir2();
+  return path6.startsWith(`${home}/`) ? `~${path6.slice(home.length)}` : path6;
+}
+function formatInstalledSkills(data) {
+  const fmt = new OutputFormatter().text("bdg skill:");
+  for (const skill of data.skills) {
+    fmt.text(`  ${skill.target.padEnd(6)}  ${skill.status.padEnd(9)}  ${tildePath(skill.path)}`);
+  }
+  return fmt.hints("Next:", [
+    "Start a new agent session to load it (running sessions keep the old list)",
+    "After upgrading bdg, run bdg install-skill again"
+  ]).build();
+}
+
+// src/commands/installSkill.ts
+init_errors();
+init_exitCodes();
+var SKILL_SOURCE_PATH = join6(PACKAGE_ROOT, ".claude", "skills", "bdg", "SKILL.md");
+var SKILL_ROOTS = {
+  claude: join6(".claude", "skills"),
+  agents: join6(".agents", "skills")
+};
+function installSkill(targets, home = homedir3(), source = SKILL_SOURCE_PATH) {
+  if (!existsSync10(source)) {
+    const err = skillSourceMissingError(source);
+    throw new CommandError(
+      err.message,
+      { suggestion: err.suggestion },
+      EXIT_CODES.RESOURCE_NOT_FOUND
+    );
+  }
+  const content = readFileSync8(source, "utf-8");
+  return targets.map(
+    (target) => writeSkill(target, join6(home, SKILL_ROOTS[target], "bdg", "SKILL.md"), content)
+  );
+}
+function writeSkill(target, path6, content) {
+  const existing = existsSync10(path6) ? readFileSync8(path6, "utf-8") : void 0;
+  if (existing === content) {
+    return { target, path: path6, status: "unchanged" };
+  }
+  try {
+    mkdirSync3(dirname5(path6), { recursive: true });
+    writeFileSync2(path6, content);
+  } catch (caught) {
+    const err = skillWriteFailedError(path6, getErrorMessage(caught));
+    throw new CommandError(
+      err.message,
+      { suggestion: err.suggestion },
+      EXIT_CODES.PERMISSION_DENIED
+    );
+  }
+  return { target, path: path6, status: existing === void 0 ? "installed" : "updated" };
+}
+function selectedTargets(options) {
+  const picked = Object.keys(SKILL_ROOTS).filter((target) => options[target]);
+  return picked.length > 0 ? picked : Object.keys(SKILL_ROOTS);
+}
+function registerInstallSkillCommand(program2) {
+  program2.command("install-skill").description(
+    "Install the bdg agent skill for Claude Code (~/.claude/skills) and agents reading ~/.agents/skills (Codex, Gemini CLI, ...); re-run after upgrading bdg"
+  ).option("--claude", "Only ~/.claude/skills (Claude Code)").option("--agents", "Only ~/.agents/skills (Codex, Gemini CLI and other agents)").addOption(jsonOption()).action(async (options) => {
+    await runCommand(
+      (opts) => Promise.resolve({ success: true, data: { skills: installSkill(selectedTargets(opts)) } }),
+      options,
+      formatInstalledSkills
+    );
+  });
+}
+
 // src/commands/network/har.ts
 import * as fs13 from "fs";
 import * as path5 from "path";
@@ -18300,7 +18393,7 @@ var SessionDirError = class extends DaemonError {
 // src/daemon/launcher.ts
 import { spawn } from "child_process";
 import fs14 from "fs";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 init_messages();
 init_paths();
 init_logging();
@@ -18321,7 +18414,7 @@ async function launchDaemon() {
     );
   }
   assertUsableSessionDir();
-  const logPath = join7(getSessionDir(), "daemon.log");
+  const logPath = join8(getSessionDir(), "daemon.log");
   rotateLog(logPath);
   const logFd = fs14.openSync(logPath, "a");
   log24.debug(`Starting daemon: ${DAEMON_SCRIPT_PATH}`);
@@ -18382,7 +18475,7 @@ async function waitForDaemonReady(hasExited) {
     }
     if (hasExited() && !await isDaemonAlive()) {
       throw new DaemonStartupError(
-        `Daemon exited during startup. See ${join7(getSessionDir(), "daemon.log")}`,
+        `Daemon exited during startup. See ${join8(getSessionDir(), "daemon.log")}`,
         "DAEMON_EXITED"
       );
     }
@@ -19741,7 +19834,9 @@ var commandRegistry = [
   addCommandGroup("Network Commands:"),
   registerNetworkCommands,
   addCommandGroup("Console Commands:"),
-  registerConsoleCommand
+  registerConsoleCommand,
+  addCommandGroup("Agent Setup:"),
+  registerInstallSkillCommand
 ];
 
 // src/index.ts

package/dist/types.d.ts

@@ -668,4 +668,12 @@ export interface FormDiscoveryResult {
     }>;
     brief?: boolean | undefined;
 }
+/** Agent whose skill directory receives the bdg skill (`bdg install-skill`). */
+export type SkillTarget = 'claude' | 'agents';
+/** What `bdg install-skill` did to the skill file in one agent's skill directory. */
+export interface InstalledSkill {
+    target: SkillTarget;
+    path: string;
+    status: 'installed' | 'updated' | 'unchanged';
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/ui/formatters/installSkill.d.ts

@@ -0,0 +1,11 @@
+import type { InstalledSkill } from '../../types.js';
+/**
+ * Format where the skill was installed, one line per agent.
+ *
+ * @param data - Install results
+ * @returns Human-readable summary
+ */
+export declare function formatInstalledSkills(data: {
+    skills: InstalledSkill[];
+}): string;
+//# sourceMappingURL=installSkill.d.ts.map

package/dist/ui/formatters/installSkill.js

@@ -0,0 +1,31 @@
+import { homedir } from 'os';
+import { OutputFormatter } from '../formatting.js';
+/**
+ * Shorten a path under the home directory to `~/...`.
+ *
+ * @param path - Absolute path
+ * @returns Path as the user would type it
+ */
+function tildePath(path) {
+    const home = homedir();
+    return path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+/**
+ * Format where the skill was installed, one line per agent.
+ *
+ * @param data - Install results
+ * @returns Human-readable summary
+ */
+export function formatInstalledSkills(data) {
+    const fmt = new OutputFormatter().text('bdg skill:');
+    for (const skill of data.skills) {
+        fmt.text(`  ${skill.target.padEnd(6)}  ${skill.status.padEnd(9)}  ${tildePath(skill.path)}`);
+    }
+    return fmt
+        .hints('Next:', [
+        'Start a new agent session to load it (running sessions keep the old list)',
+        'After upgrading bdg, run bdg install-skill again',
+    ])
+        .build();
+}
+//# sourceMappingURL=installSkill.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-debugger-cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to Chrome's debugging port.",
   "type": "module",
   "bin": {
@@ -90,6 +90,7 @@
   },
   "files": [
     "dist",
+    ".claude/skills/bdg/SKILL.md",
     "!dist/**/__tests__",
     "!dist/__testutils__",
     "!dist/__testfixtures__",