td-ai-tools 1.1.4 → 1.1.6

package/README.md

@@ -45,12 +45,22 @@ The installer copies requested items into both agent layouts:
 
 - Skills: `.claude/skills/<name>/` and `.agents/skills/<name>/`
 
+If a skill bundles a sub-agent prompt (any `.md` with a `name:` field in `skills/<name>/agents/`), the installer also registers it to `.claude/agents/<sub-agent>.md` and `.agents/agents/<sub-agent>.md` so Claude Code and `.agents`-aware runtimes such as Codex can discover the same definition. `delete` removes these registrations alongside the skill.
+
 This keeps the installed assets available to both Claude-style and `.agents`-style project conventions.
 
 `install` now errors when the target item already exists. Use `update` to replace an existing installed skill or agent pack.
 
 `delete` removes installed items from both `.claude/` and `.agents/` target directories, and works on any installed skill or agent pack regardless of whether it is in the catalogue.
 
+## Versioning
+
+Every skill and agent pack carries a `version:` field in its frontmatter (`SKILL.md` / `AGENTS.md`), following semantic versioning (`MAJOR.MINOR.PATCH`). Because the installer copies these files verbatim into the target project, the installed copy itself records the version that was installed — no lockfile is needed.
+
+`list` and the interactive `update` menu compare the installed version against the catalog and flag anything out of date, e.g. `v1.0.0 → v1.2.0  ⬆ outdated`. When any installed item is stale, the CLI prints a nudge: `You have N items out of date — run npx td-ai-tools update`. An item installed before versioning existed (no `version:` field) is also treated as out of date.
+
+**Maintainers:** bump an item's `version:` whenever you change its contents — `PATCH` for fixes/tweaks, `MINOR` for new behavior, `MAJOR` for breaking changes. Without a bump, users will not see the update flagged.
+
 ## Local Verification
 Run the local smoke test to package the repo and verify installation into a throwaway project:
 

package/agents/component-library-section-blocks/AGENTS.md

@@ -1,3 +1,7 @@
+---
+version: 1.0.0
+---
+
 # .codex/AGENTS.md — Theory Digital
 
 ## Scope

package/agents/horizon-component-library/AGENTS.md

@@ -1,3 +1,7 @@
+---
+version: 1.0.0
+---
+
 # .codex/AGENTS.md — Theory Digital
 
 ## Scope

package/bin/cli.js

@@ -63,6 +63,121 @@ function readFrontmatterField(mdPath, field) {
   return match ? match[1].trim() : '';
 }
 
+function itemFile(type) {
+  return type === 'skill' ? 'SKILL.md' : 'AGENTS.md';
+}
+
+function itemSubdir(type) {
+  return type === 'skill' ? 'skills' : 'agents';
+}
+
+function catalogVersion(type, name) {
+  const dir = type === 'skill' ? SKILLS_DIR : AGENTS_DIR;
+  return readFrontmatterField(path.join(dir, name, itemFile(type)), 'version') || null;
+}
+
+// Reads the version recorded in the user's installed copy. The installer copies
+// SKILL.md/AGENTS.md verbatim, so the installed file is itself the record of what
+// version was installed — no separate lockfile is needed. Returns null when the
+// item is not installed, or when it predates versioning (no version: field).
+function installedVersion(type, name) {
+  const sub = itemSubdir(type);
+  const file = itemFile(type);
+  for (const target of INSTALL_TARGETS) {
+    const md = path.join(TARGET_ROOT, target.root, sub, name, file);
+    if (fs.existsSync(md)) {
+      return readFrontmatterField(md, 'version') || null;
+    }
+  }
+  return null;
+}
+
+function compareSemver(a, b) {
+  const pa = String(a).split('.').map(n => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map(n => parseInt(n, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+// An installed item is outdated when its version is older than the catalog's, or
+// when it has no version: field at all (a legacy install from before versioning).
+function isInstalled(type, name) {
+  const sub = itemSubdir(type);
+  return INSTALL_TARGETS.some(target =>
+    fs.existsSync(path.join(TARGET_ROOT, target.root, sub, name)));
+}
+
+function itemStatus(type, name) {
+  const available = catalogVersion(type, name);
+  const installed = installedVersion(type, name);
+  let outdated = false;
+  if (available && isInstalled(type, name)) {
+    outdated = !installed || compareSemver(installed, available) < 0;
+  }
+  return { installed, available, outdated };
+}
+
+// Display string for an installed item's version state, e.g.
+// "v1.0.0 → v1.2.0  ⬆ outdated" or "v1.2.0 (up to date)". Returns null when there
+// is nothing meaningful to show (item not installed, or catalog has no version).
+function versionAnnotation(type, name) {
+  if (!isInstalled(type, name)) return null;
+  const { installed, available, outdated } = itemStatus(type, name);
+  if (!available) return null;
+  if (outdated) {
+    const from = installed ? `v${installed}` : 'no version';
+    return { text: `${from} → v${available}  ⬆ outdated`, outdated: true };
+  }
+  return { text: `v${installed} (up to date)`, outdated: false };
+}
+
+function getOutdatedInstalled() {
+  const availableSkills = new Set(getAvailable(SKILLS_DIR));
+  const availableAgents = new Set(getAvailable(AGENTS_DIR));
+  const out = [];
+  for (const name of getInstalled('skills')) {
+    if (availableSkills.has(name) && itemStatus('skill', name).outdated) {
+      out.push({ type: 'skill', name });
+    }
+  }
+  for (const name of getInstalled('agents')) {
+    if (availableAgents.has(name) && itemStatus('agent', name).outdated) {
+      out.push({ type: 'agent', name });
+    }
+  }
+  return out;
+}
+
+function printOutdatedNudge() {
+  const outdated = getOutdatedInstalled();
+  if (outdated.length === 0) return;
+  const n = outdated.length;
+  status('warn',
+    `You have ${n} item${n === 1 ? '' : 's'} out of date — run \`npx td-ai-tools update\` to update ${n === 1 ? 'it' : 'them'}.`);
+}
+
+// Sub-agent prompts bundled inside a skill: any `*.md` in <skill>/agents/ that
+// declares a `name:` frontmatter field. These are registered to every supported
+// target's agents directory so Claude Code and shared `.agents` runtimes can
+// discover the same definition on install.
+function getBundledAgents(skillSrc) {
+  const agentsDir = path.join(skillSrc, 'agents');
+  if (!fs.existsSync(agentsDir)) return [];
+  return fs.readdirSync(agentsDir)
+    .filter(f => f.endsWith('.md'))
+    .map(f => {
+      const srcPath = path.join(agentsDir, f);
+      return { file: f, srcPath, name: readFrontmatterField(srcPath, 'name') };
+    })
+    .filter(a => a.name);
+}
+
 function installSkill(name, { replaceExisting = false } = {}) {
   const src = path.join(SKILLS_DIR, name);
   if (!fs.existsSync(src)) {
@@ -81,12 +196,22 @@ function installSkill(name, { replaceExisting = false } = {}) {
     copyDir(src, dest);
     const action = replaceExisting ? 'updated' : 'installed';
     status('success', `skill: ${name} ${action} → ${target.root}/skills/${name}/`);
+
+    for (const agent of getBundledAgents(src)) {
+      const agentDest = path.join(TARGET_ROOT, target.root, 'agents', agent.file);
+      fs.mkdirSync(path.dirname(agentDest), { recursive: true });
+      fs.copyFileSync(agent.srcPath, agentDest);
+      status('success', `  ↳ sub-agent: ${agent.name} registered → ${target.root}/agents/${agent.file}`);
+    }
   }
   return true;
 }
 
 function deleteSkill(name) {
   let deletedAny = false;
+  // Determine bundled sub-agents from the catalog source (best effort — only
+  // available if the skill still exists in the package).
+  const bundledAgents = getBundledAgents(path.join(SKILLS_DIR, name));
   for (const target of INSTALL_TARGETS) {
     const dest = path.join(TARGET_ROOT, target.root, 'skills', name);
     if (fs.existsSync(dest)) {
@@ -94,6 +219,14 @@ function deleteSkill(name) {
       status('success', `skill: ${name} deleted from ${target.root}/skills/${name}/`);
       deletedAny = true;
     }
+    for (const agent of bundledAgents) {
+      const agentDest = path.join(TARGET_ROOT, target.root, 'agents', agent.file);
+      if (fs.existsSync(agentDest)) {
+        fs.rmSync(agentDest, { force: true });
+        status('success', `  ↳ sub-agent: ${agent.name} unregistered from ${target.root}/agents/${agent.file}`);
+        deletedAny = true;
+      }
+    }
   }
   if (!deletedAny) {
     status('error', `Skill "${name}" is not installed.`);
@@ -172,17 +305,25 @@ function printListPlain() {
 
   console.log('\nSkills:');
   for (const name of skills) {
-    const desc = readFrontmatterField(path.join(SKILLS_DIR, name, 'SKILL.md'), 'description');
-    const truncated = desc.length > 72 ? desc.slice(0, 72) + '...' : desc;
     console.log(`  ${name}`);
-    if (truncated) console.log(`    ${truncated}`);
+    const ann = versionAnnotation('skill', name);
+    if (ann) {
+      console.log(`    ${ann.text}`);
+    } else {
+      const desc = readFrontmatterField(path.join(SKILLS_DIR, name, 'SKILL.md'), 'description');
+      const truncated = desc.length > 72 ? desc.slice(0, 72) + '...' : desc;
+      if (truncated) console.log(`    ${truncated}`);
+    }
   }
 
   console.log('\nAgent Packs:');
   for (const name of agents) {
     console.log(`  ${name}`);
+    const ann = versionAnnotation('agent', name);
+    if (ann) console.log(`    ${ann.text}`);
   }
   console.log('');
+  printOutdatedNudge();
 }
 
 function printList() {
@@ -196,22 +337,30 @@ function printList() {
 
   p.intro(pc.bgCyan(pc.black(' AgentToolkit ')));
 
+  const lineFor = (type, name, fallbackHint) => {
+    const ann = versionAnnotation(type, name);
+    if (ann) {
+      const colored = ann.outdated ? pc.yellow(ann.text) : pc.dim(ann.text);
+      return `${pc.bold(name)}\n  ${colored}`;
+    }
+    return fallbackHint ? `${pc.bold(name)}\n  ${pc.dim(fallbackHint)}` : pc.bold(name);
+  };
+
   const skillsBody = skills.length
-    ? skills.map(name => {
-        const hint = getSkillHint(name);
-        return hint ? `${pc.bold(name)}\n  ${pc.dim(hint)}` : pc.bold(name);
-      }).join('\n')
+    ? skills.map(name => lineFor('skill', name, getSkillHint(name))).join('\n')
     : pc.dim('(none)');
   p.note(skillsBody, `Skills (${skills.length})`);
 
   const agentsBody = agents.length
-    ? agents.map(name => {
-        const hint = getAgentHint(name);
-        return hint ? `${pc.bold(name)}\n  ${pc.dim(hint)}` : pc.bold(name);
-      }).join('\n')
+    ? agents.map(name => lineFor('agent', name, getAgentHint(name))).join('\n')
     : pc.dim('(none)');
   p.note(agentsBody, `Agent Packs (${agents.length})`);
 
+  const outdated = getOutdatedInstalled();
+  if (outdated.length) {
+    p.log.warn(pc.yellow(
+      `${outdated.length} installed item${outdated.length === 1 ? '' : 's'} out of date — run \`npx td-ai-tools update\`.`));
+  }
   p.outro(pc.dim(`${skills.length} skills, ${agents.length} agent packs available.`));
 }
 
@@ -227,8 +376,14 @@ function printSelectionControls(action) {
 }
 
 function buildMenu() {
-  const skills = getAvailable(SKILLS_DIR).map(name => ({ type: 'skill', name }));
-  const agents = getAvailable(AGENTS_DIR).map(name => ({ type: 'agent', name }));
+  const installedSkills = new Set(getInstalled('skills'));
+  const installedAgents = new Set(getInstalled('agents'));
+  const skills = getAvailable(SKILLS_DIR)
+    .filter(name => !installedSkills.has(name))
+    .map(name => ({ type: 'skill', name }));
+  const agents = getAvailable(AGENTS_DIR)
+    .filter(name => !installedAgents.has(name))
+    .map(name => ({ type: 'agent', name }));
   return [...skills, ...agents];
 }
 
@@ -250,13 +405,23 @@ function buildUpdateMenu() {
   return [...skills, ...agents];
 }
 
-function toGroupOptions(menu, { hintForInstalled = false } = {}) {
+function menuHint(type, name, { hintForInstalled, showVersions }) {
+  if (showVersions) {
+    const ann = versionAnnotation(type, name);
+    return ann ? ann.text : '';
+  }
+  if (hintForInstalled) return '';
+  return type === 'skill' ? getSkillHint(name) : getAgentHint(name);
+}
+
+function toGroupOptions(menu, { hintForInstalled = false, showVersions = false } = {}) {
+  const opts = { hintForInstalled, showVersions };
   const skillItems = menu.filter(i => i.type === 'skill').map(i => {
-    const hint = hintForInstalled ? '' : getSkillHint(i.name);
+    const hint = menuHint('skill', i.name, opts);
     return { value: `skill:${i.name}`, label: i.name, hint: hint || undefined };
   });
   const agentItems = menu.filter(i => i.type === 'agent').map(i => {
-    const hint = hintForInstalled ? '' : getAgentHint(i.name);
+    const hint = menuHint('agent', i.name, opts);
     return { value: `agent:${i.name}`, label: i.name, hint: hint || undefined };
   });
   const out = {};
@@ -301,10 +466,11 @@ async function interactiveInstall(mode = 'install') {
 
   p.intro(pc.bgCyan(pc.black(' AgentToolkit ')));
   printSelectionControls(mode);
+  printOutdatedNudge();
 
   const selection = await p.groupMultiselect({
     message: `Select items to ${mode}`,
-    options: toGroupOptions(menu),
+    options: toGroupOptions(menu, { showVersions: mode === 'update' }),
     required: false,
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "td-ai-tools",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Install agent skills and packs into your project",
   "type": "module",
   "scripts": {

package/scripts/smoke-install.sh

@@ -21,12 +21,16 @@ popd >/dev/null
 tarball_path="$tmpdir/$tarball"
 
 pushd "$project_dir" >/dev/null
-npm exec --yes --cache "$cache_dir" --package "$tarball_path" td-ai-tools install pr-solver horizon-component-library
+npm exec --yes --cache "$cache_dir" --package "$tarball_path" td-ai-tools install pr-solver playwright-cli horizon-component-library
 popd >/dev/null
 
 required_paths=(
   "$project_dir/.claude/skills/pr-solver/SKILL.md"
   "$project_dir/.agents/skills/pr-solver/SKILL.md"
+  "$project_dir/.claude/skills/playwright-cli/SKILL.md"
+  "$project_dir/.agents/skills/playwright-cli/SKILL.md"
+  "$project_dir/.claude/agents/playwright-investigator.md"
+  "$project_dir/.agents/agents/playwright-investigator.md"
   "$project_dir/.claude/agents/horizon-component-library/AGENTS.md"
   "$project_dir/.agents/agents/horizon-component-library/AGENTS.md"
 )

package/skills/README.md

@@ -1,9 +1,9 @@
 # skills
 
 ## Available Skills
-- `barrage`: Convert a group of Basecamp todos or cards into a td-barrage queue.json task file.
 - `cache-reset`: Clear and warm Laravel and Statamic caches after content/template changes.
 - `horizon-component-migration`: Bundle Horizon components and recursive dependencies into a migration package for another theme.
+- `playwright-cli`: Drive a real browser for web testing, screenshots, and data extraction. Ships the `playwright-investigator` sub-agent for orchestrated URL investigations.
 - `pr-solver`: Resolve unresolved GitHub PR review threads with GraphQL-driven workflow.
 - `pull-request`: Generate structured pull request descriptions for Shopify theme work.
 - `td-js-vanilla-rules`: Theory Digital vanilla JavaScript standards for Shopify themes.
@@ -12,5 +12,11 @@
 ## Skill Structure Convention
 - `<skill-name>/SKILL.md`
 - `<skill-name>/agents/openai.yaml`
+- `<skill-name>/agents/<sub-agent>.md` (optional) — a reusable sub-agent prompt (frontmatter `name`/`description` + system prompt). Any `.md` here with a `name:` field is auto-registered to both `.claude/agents/` and `.agents/agents/` on install, so Claude Code and `.agents`-aware runtimes such as Codex can discover the same definition.
 - `<skill-name>/scripts/*` (optional)
 - `<skill-name>/references/*` (optional)
+
+## Versioning
+- Each `SKILL.md` frontmatter must include a `version:` field using semantic versioning (`MAJOR.MINOR.PATCH`).
+- Bump the version whenever the skill's contents change — `PATCH` for fixes/tweaks, `MINOR` for new behavior, `MAJOR` for breaking changes.
+- The CLI compares the installed version against this catalog version to flag outdated installs in `list` and `update`. If you do not bump the version, users will not be told to update.

package/skills/basecamp/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: basecamp
+version: 1.0.0
 description: |
     Interact with Basecamp via the Basecamp CLI. Full API coverage: projects, todos, cards,
     messages, files, schedule, check-ins, timeline, recordings, templates, webhooks,

package/skills/cache-reset/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: cache-reset
+version: 1.0.0
 description: Clear and warm Laravel and Statamic caches after content or template changes.
 alwaysApply: false
 ---

package/skills/car-ticket-generator/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: car-ticket-generator
+version: 1.0.0
 description: Generate a ticket for the codex-auto-runner queue
 alwaysApply: false
 ---

package/skills/everhour-basecamp-estimates/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: everhour-basecamp-estimates
+version: 1.0.0
 description: Bulk update Everhour task estimates from a Basecamp todo or todolist URL, then append bracketed hours to the Basecamp todo titles.
 alwaysApply: false
 ---

package/skills/forge-cli/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: forge-cli
+version: 1.0.0
 description: Manage Laravel Forge servers, sites, and provisioned resources from the terminal with the Laravel Forge CLI, falling back to the Forge HTTP API (Statamic-relevant endpoints documented here) for anything the CLI does not cover. Use when the user wants to inspect Forge state, switch active servers, deploy sites, update environment variables, view logs, run remote commands, use Tinker, manage services like PHP, Nginx, daemons, and databases, or perform Statamic site setup tasks the CLI lacks a verb for (site/SSL/git/worker/scheduler/backup/recipe/composer-auth management).
 ---
 

package/skills/horizon-component-migration/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: horizon-component-migration
+version: 1.0.0
 description: Bundle Shopify Horizon components into a migration package for a different theme, including recursive dependencies across sections, snippets, blocks, assets, templates, and locale strings. Use when asked to port or extract a Horizon component with all required files and setup notes.
 ---
 

package/skills/playwright-cli/PRIMER.md

@@ -0,0 +1,122 @@
+# playwright-cli — first-run primer
+
+Read this once per machine/clone before using the `playwright-cli` skill. It
+covers the one gotcha that breaks the first run, how to configure each agent
+runtime, and how to verify everything works. Delete this file and any reference 
+to it after following its instructions.
+
+## TL;DR
+
+```bash
+# 1. binary present?
+command -v playwright-cli || npm i -g @playwright/cli
+
+# 2. browser present? (Playwright-managed chromium, not branded Chrome)
+ls "${PLAYWRIGHT_BROWSERS_PATH:-$HOME/.cache/ms-playwright}"/chromium-* >/dev/null 2>&1 \
+  || npx playwright install chromium
+
+# 3. write per-agent config (choose one)
+.agents/skills/playwright-cli/setup.sh        # shared .agents + Claude settings
+.agents/skills/playwright-cli/setup.sh --all  # shared .agents + Claude + Codex
+
+# 4. smoke test
+PLAYWRIGHT_MCP_BROWSER=chromium playwright-cli open
+playwright-cli goto https://example.com
+playwright-cli eval "document.title"   # -> "Example Domain"
+playwright-cli close
+```
+
+## The one gotcha
+
+`playwright-cli open` defaults to **branded Chrome** at
+`/opt/google/chrome/chrome`. On most dev boxes (including WSL) that binary does
+not exist, so the bare command fails with:
+
+```
+Error: Chromium distribution 'chrome' is not found at /opt/google/chrome/chrome
+```
+
+What *is* installed is the **Playwright-managed chromium** under
+`~/.cache/ms-playwright`. Point the default browser at it in one of two ways:
+
+- per-command flag: `playwright-cli open --browser=chromium`
+- environment variable: `PLAYWRIGHT_MCP_BROWSER=chromium` (this is what
+  `setup.sh` pins for you — `BROWSER=chromium` does **not** work, only
+  `PLAYWRIGHT_MCP_BROWSER`).
+
+If chromium isn't installed yet: `npx playwright install chromium`. (This repo
+already uses `@playwright/test`, so it's normally present.)
+
+## Per-agent configuration
+
+Run `setup.sh` from the repo root. The script is installed into both
+`.agents/skills/playwright-cli/setup.sh` and
+`.claude/skills/playwright-cli/setup.sh`; prefer the `.agents` path when working
+provider-agnostically. With no flags it writes `.claude` + `.agents`; pass
+`--codex` or `--all` to also write the Codex sandbox config.
+
+| Target | File written | What it does |
+|---|---|---|
+| `--claude` | `.claude/settings.json` | Sets `env.PLAYWRIGHT_MCP_BROWSER=chromium` and adds `Bash(playwright-cli:*)` to `permissions.allow`. Merges into any existing file (invalid JSON is backed up to `.bak`). Applies on the **next** Claude Code session. |
+| `--agents` | `.agents/playwright-cli.env` | Shareable env file. Load with `set -a; . .agents/playwright-cli.env; set +a`. |
+| `--codex` | `.codex/config.toml` | Codex sandbox: `network_access`, `writable_roots` (browser cache + artifact dirs), and `PLAYWRIGHT_MCP_BROWSER=chromium`. Generated from `config.toml.template`. |
+
+All three output dirs (`.claude/`, `.agents/`, `.codex/`) are gitignored, so
+each clone generates its own — nothing machine-specific is committed.
+
+### Why config differs by agent
+
+- **Claude Code** reads `.claude/settings.json` (`env` + `permissions`). It does
+  not read `.codex/config.toml`. The env var is all it needs; the permission is
+  belt-and-suspenders since `SKILL.md` already declares `allowed-tools`.
+- **Codex** parses `config.toml` as static TOML and does **not** expand `~`,
+  `$HOME`, or `${VAR}` in paths — hence the generator that substitutes absolute
+  paths at setup time.
+- **`.agents/`** is the agent-agnostic home; any tool/shell can source the env
+  file.
+
+## Sub-agent registration
+
+Installing this skill registers `playwright-investigator.md` in both agent
+layouts:
+
+- `.claude/agents/playwright-investigator.md`
+- `.agents/agents/playwright-investigator.md`
+
+Claude Code discovers the `.claude` copy as a custom agent. Codex and other
+`.agents`-aware runtimes should use the `.agents` copy as the sub-agent
+definition when a multi-agent/sub-agent tool is available. The prompt is written
+as a shared contract: the agent needs shell command execution, file reads, and
+access to this `playwright-cli` skill; it returns only the final investigation
+report.
+
+## What the old setup got wrong
+
+The previous `setup-codex.sh` / template were Codex-only **and** misconfigured
+for this machine:
+
+- redirected `PLAYWRIGHT_BROWSERS_PATH` to an empty project dir while the real
+  browsers live in `~/.cache/ms-playwright`;
+- pinned `PLAYWRIGHT_MCP_EXECUTABLE_PATH` to `/usr/bin/chromium`, which doesn't
+  exist (there is no system chromium binary — it's Playwright-managed);
+- overrode `HOME`, moving Playwright away from its own browser cache;
+- never addressed the actual first-run failure (the `chrome` default).
+
+The current setup drops all of that: it keeps the managed browsers where they
+are and only pins the default-browser name.
+
+## Artifacts & cleanup
+
+`playwright-cli` writes snapshots and console/network logs to `.playwright-cli/`
+in the repo root (gitignored). Always `playwright-cli close` when done; use
+`playwright-cli list` / `close-all` / `kill-all` to manage stray browsers.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `'chrome' is not found at /opt/google/chrome/chrome` | Use `--browser=chromium` or set `PLAYWRIGHT_MCP_BROWSER=chromium` (run `setup.sh`). |
+| `Executable doesn't exist … run "playwright install"` | `npx playwright install chromium`. |
+| `command not found: playwright-cli` | `npm i -g @playwright/cli`, or use `npx playwright-cli …`. |
+| Env var ignored in Claude Code | `.claude/settings.json` is read at session start — restart the session, or pass `--browser=chromium` inline this session. |
+| Codex sandbox can't launch browser | Re-run `setup.sh --codex` so `writable_roots` includes the current `~/.cache/ms-playwright`. |

package/skills/playwright-cli/SKILL.md

@@ -1,11 +1,19 @@
 ---
 name: playwright-cli
+version: 1.1.0
 description: Automates browser interactions for web testing, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, take screenshots, test web applications, or extract information from web pages.
 allowed-tools: Bash(playwright-cli:*)
 ---
 
 # Browser Automation with playwright-cli
 
+> **First run in a new clone/machine?** Read [PRIMER.md](PRIMER.md) and run
+> `.agents/skills/playwright-cli/setup.sh` once (or the `.claude/...` copy if
+> you are using Claude Code only). For Codex, run it with `--codex` or `--all`.
+> Key gotcha: `playwright-cli` defaults to branded Chrome (usually absent) —
+> use `--browser=chromium` or set `PLAYWRIGHT_MCP_BROWSER=chromium`. Delete this
+> comment and the setup and primer files after a successful setup.
+
 ## Quick start
 
 ```bash
@@ -268,6 +276,17 @@ playwright-cli tracing-stop
 playwright-cli close
 ```
 
+## Sub-agent
+
+This skill ships a provider-agnostic sub-agent prompt, **`playwright-investigator`** ([agents/playwright-investigator.md](agents/playwright-investigator.md)), for orchestrated browser work. Dispatch it with a URL and an objective — diagnose the source of a problem, confirm a change applied correctly, or compare visual output against a target (screenshot or reference URL). It drives the browser through these commands, then returns a concise findings report, keeping all playwright-cli commands and raw output out of the orchestrator's context.
+
+Installing this skill auto-registers the sub-agent in both supported layouts:
+
+- `.claude/agents/playwright-investigator.md` for Claude Code custom agents.
+- `.agents/agents/playwright-investigator.md` for Codex and other runtimes that read the shared `.agents` convention.
+
+Claude Code can dispatch it through the Agent tool with no manual setup. In Codex, use the available multi-agent/sub-agent tool when the runtime exposes one, pointing it at the `.agents/agents/playwright-investigator.md` definition. If a runtime reads `.agents` assets but does not expose native sub-agent dispatch, use the same file as the investigator's system prompt and keep the final report contract unchanged.
+
 ## Specific tasks
 
 * **Request mocking** [references/request-mocking.md](references/request-mocking.md)
@@ -276,4 +295,4 @@ playwright-cli close
 * **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
 * **Test generation** [references/test-generation.md](references/test-generation.md)
 * **Tracing** [references/tracing.md](references/tracing.md)
-* **Video recording** [references/video-recording.md](references/video-recording.md)
+* **Video recording** [references/video-recording.md](references/video-recording.md)

package/skills/playwright-cli/agents/playwright-investigator.md

@@ -0,0 +1,65 @@
+---
+name: playwright-investigator
+description: Drives a browser via the playwright-cli skill to investigate a website on an orchestrator's behalf. Give it a URL and an objective — diagnose the source of a problem, confirm a change applied correctly, or compare visual output against a target (a screenshot file or a reference URL). It performs the browser work, gathers evidence, and returns a concise findings report. Use it to keep all playwright-cli commands and raw browser/snapshot output out of the orchestrator's context.
+tools: Bash, Read, Glob, Grep, Skill
+---
+
+You are a focused web investigation agent. An orchestrator hands you a URL and an objective; you drive a browser with the `playwright-cli` skill, gather the evidence needed to satisfy your objective, and hand back a clean, self-contained report.
+
+Your defining responsibility is **context isolation**. The orchestrator must never see playwright-cli commands, snapshot YAML, console dumps, or network logs. All of that lives and dies inside your context. The orchestrator receives only your final report.
+
+## Runtime Contract
+
+This definition is intentionally usable in both Claude Code's `.claude/agents/`
+layout and the shared `.agents/agents/` layout used by Codex-compatible
+runtimes. You need these capabilities, regardless of provider-specific tool
+names:
+
+- Run shell commands.
+- Read local files and generated artifacts.
+- Load or follow the `playwright-cli` skill documentation.
+
+The `tools:` frontmatter is Claude Code's native declaration; other runtimes
+should map it to the equivalent capabilities above.
+
+If your runtime does not expose a native skill-loading tool, read the installed
+`playwright-cli/SKILL.md` file directly and use it as your command reference.
+
+## Operating Principles
+
+- **Use the playwright-cli skill.** At the start of a task, invoke the `playwright-cli` skill to load its command reference, then drive the browser through `playwright-cli` commands run via Bash. If the global binary is missing, fall back to `npx playwright-cli`.
+- **Gather evidence** Run whatever sequence of commands the objective requires. You do not report on individual commands; you report on conclusions backed by concrete evidence.
+- **Always clean up.** End every task with `playwright-cli close` (or `close-all` if you opened named sessions), even if the task failed. Leave no orphaned browser.
+- **Report uncertainty honestly.** If the page wouldn't load, an element couldn't be found, auth blocked you, or the evidence is inconclusive, say so plainly. A wrong confident answer is worse than a flagged unknown.
+
+## Inputs You Expect
+
+The orchestrator should give you a **URL** and an **objective**. If a critical input is missing (e.g. a comparison target, or credentials for a gated page), state the blocker in your report rather than guessing.
+
+## Report Format
+
+Return **only** the report below as your final message. No preamble, no command logs.
+
+```markdown
+## Web Investigation Report
+
+**Objective:** [restate the objective in one line]
+**URL:** [url investigated]
+**Mode:** [Diagnosis | Change confirmation | Visual comparison]
+**Verdict:** [one-line bottom line — e.g. root cause identified / PASS / FAIL / 3 visual differences found / INCONCLUSIVE]
+
+### Findings
+- [Concrete finding backed by evidence. Cite the specific signal: console error text, failing request URL+status, DOM/CSS value, element ref, or screenshot region.]
+- [Additional findings as needed.]
+
+### Evidence
+- [Key evidence items: exact console errors, request statuses, eval results, screenshot file paths captured, computed values. Keep it tight — only what supports the findings.]
+
+### Recommendation / Next Steps
+[For diagnosis: the likely fix or where to look. For confirmation: confirmed live or what's still wrong. For comparison: what to change to match the target. Omit if not applicable.]
+
+### Caveats
+[Anything you couldn't verify, blockers hit, assumptions made, or scope you didn't cover. Write "None." if fully conclusive.]
+```
+
+Keep the report decision-ready: tight, specific, and grounded in evidence the orchestrator can act on without ever needing to see the browser session.