@tea-agent/loop-agent 0.13.0-beta.0 → 0.14.0

package/docs/templates/frontend-eval/fixtures/functional/08-pure-local-no-remote.md

@@ -0,0 +1,27 @@
+# Functional fixture: pure local no-remote interaction
+
+- **fixtureId**: `fe-func-pure-local-no-remote`
+- **taskTitle**: 实现纯前端计数器与本地 localStorage 偏好
+- **expectedRoute**: `frontend-implementation`
+- **expectedRiskLevel**: `small`（M4 前仅标注）
+- **expectedGateIntensity**: mock assess 仍存在但策略应为 not-needed
+- **expectedMockStrategy**: `not-needed`（正证据：无远程 API）
+- **Browser**: **out-of-scope / not-run**
+
+## 需求要点
+
+- 状态仅存组件 state / localStorage。
+- 不添加 Mock 框架或 API client。
+- 交互可用 vitest + testing-library 验证。
+
+## allowedPaths 建议
+
+```text
+src/widgets/Counter/**
+test/widgets/Counter/**
+```
+
+## expected verification 形态
+
+- Static + behavior（本地交互）
+- 无 mock-verify 节点

package/docs/templates/frontend-eval/metrics.md

@@ -0,0 +1,138 @@
+# Frontend-implementation Eval 指标合同（M0）
+
+状态：M0 冻结定义；M3 前部分指标仅定义不采集。  
+边界：**不包含 Browser / 视觉 / 真实页面启动**；Browser 相关一律记 `not-run` 或从分母排除（见下）。
+
+## 通用规则
+
+### 样本量
+
+- **功能通过率类**：以选定 functional fixture 集为分母单元（每个 fixture × 每个 smoke target 记一次 trial，或按计划固定 trial 表）。
+- **失败行为类**：以 failure fixture 集为单元；期望「正确阻断 / 正确分类」为成功，误放行为失败。
+- **基线批次**：记录 `sampleSetId`、fixture 列表 hash、controller 版本、commit SHA。无记录则整批指标 `unavailable`。
+
+### 缺失数据
+
+| 符号 | 含义 |
+|------|------|
+| `N/A` | 能力尚未实现，指标定义保留但**禁止填 0** 伪装基线（例：M3 前 repair 后通过率） |
+| `unavailable` | 实现已存在但本批 run 未记录分子或分母所需字段（例：无 token 账本） |
+| `not-run` | 明确未执行的检查（例：Browser）；不得计入「通过」 |
+| `0` | 仅当分子与分母均有完整证据且分子确实为零 |
+
+报告必须同时写出 **分子、分母、比率、样本量 n、缺失原因**。禁止只写百分比。
+
+### 耗时 / token 来源
+
+| 字段 | 来源（优先序） |
+|------|----------------|
+| 墙钟耗时 | DAG run 起止时间戳（run.json / harness run record）；否则 shell `date` 外包测量 |
+| 节点耗时 | 各 node start/end；缺失则节点级 `unavailable`，仅汇总 run 级 |
+| token | executor / model usage 汇总（若 run 记录 `tokensUsed`）；否则 `unavailable`，**不得估计** |
+
+### Browser 边界
+
+- 任何指标不得因「未跑浏览器」而扣分或加分。  
+- 不得将 Mock-backed 或 component test 记为 Browser pass。  
+- 指标表中 Browser 行固定 `not-run`（本计划范围内）。
+
+---
+
+## 最低指标集
+
+### 1. 首次静态通过率
+
+- **名称**：`first_static_pass_rate`
+- **分子**：第一次执行 `frontend-static-verify-shell` 即 exit 0 的 trial 数  
+- **分母**：完成到 static verify 的 trial 数（writer 已跑且 static 已调度）  
+- **排除**：DAG 在 writer 前被 Mock/design gate 阻断的 trial（记入 gate 阻断类，不进分母）  
+- **M0**：定义 + 手工/脚本采集方式；基线可 `unavailable` 直至有 fixture dogfood
+
+### 2. 首次行为通过率
+
+- **名称**：`first_behavior_pass_rate`
+- **分子**：第一次执行 `frontend-behavior-verify-shell` 即 exit 0 的 trial 数  
+- **分母**：完成到 behavior verify 的 trial 数  
+- **说明**：行为通过不等于真实 API 联调；Mock-backed 仍可计入 behavior pass，但须另计「误报」指标
+
+### 3. repair 后最终通过率
+
+- **名称**：`post_repair_final_pass_rate`
+- **分子**：在 ≤ max repair attempts 后 static+behavior+review gate 均通过的 trial 数  
+- **分母**：进入 repair 资格判定的 trial 数（repairable 失败）  
+- **M0–M2**：固定记 **`N/A`**（无 frontend repair runtime）  
+- **M3+**：按 failure taxonomy 采集
+
+### 4. 需求追踪完整率
+
+- **名称**：`requirement_trace_completeness_rate`
+- **M0 分子**：`frontend-requirement-coverage-shell` 通过（或无显式 ID 时记 `not-applicable-trial`）且 closeout/plan 仍含全部绑定 ID 的 trial 数  
+- **M0 分母**：含显式 REQ/BR/AC 的 trial 数  
+- **语义**：M0 为 **identifier-presence**，不是文件/UI state 完整映射  
+- **M1+**：改为 validated contract 中每条 ID → target/state/test 映射完整率（届时更新本文件版本）
+
+### 5. 越界写入次数
+
+- **名称**：`forbidden_write_count`
+- **分子**：write-guard / exclusive writeSet 拒绝次数 + review 确认的越界路径写入次数（按 trial 计数事件，可 >1）  
+- **分母**：含 writer 的 trial 数（用于率：`forbidden_write_rate = 分子/分母`）  
+- **期望基线**：治理应使成功 closeout 的 trial 分子为 0
+
+### 6. 错误依赖次数
+
+- **名称**：`unapproved_dependency_count`
+- **分子**：未批准新增 dependency（package.json 变更未授权、review 标记 Important 等）事件数  
+- **分母**：含 writer 的 trial 数  
+- **采集**：diff 检查 + review findings 标签（需约定 finding code，M0 用人工标注）
+
+### 7. Mock / 真实联调误报次数
+
+- **名称**：`mock_real_integration_false_claim_count`
+- **分子**：closeout 或报告将 Mock-backed 证据描述为真实 API 已联通，或省略 `Real integration: pending` 的 trial 数  
+- **分母**：`MOCK_STRATEGY` 为 native | browser-intercept | request-adapter 且无真实后端证据的 trial 数  
+- **期望**：0
+
+### 8. 节点数 / 模型节点数
+
+- **名称**：`node_count`, `model_node_count`
+- **定义**：  
+  - `node_count` = `spec.tasks.length`  
+  - `model_node_count` = `executor === "pi"`（或非 shell/static）的节点数  
+- **报告**：按 topology 变体分别记录（standard / +coverage / +mock-verify / blocked）  
+- **M0 基线参考（standard 无 optional）**：`node_count=16`；模型节点含 contract/scout/mock-assess/plan/design/plan-revision/final-design-review/implement/review/closeout（以 builder 为准，测试锁定 id 列表）
+
+### 9. 墙钟耗时
+
+- **名称**：`wall_clock_ms`
+- **分子/分母**：不适用；报告 **p50 / p95 / max** 与 **n**  
+- **来源**：见通用规则；缺失 → `unavailable`
+
+### 10. Token
+
+- **名称**：`tokens_total`
+- **报告**：sum 与 per-role breakdown（若可得）；缺失 → `unavailable`  
+- **禁止**：用字符数或经验公式估算后当作实测
+
+---
+
+## 建议采集表头（CSV / Markdown）
+
+```text
+sampleSetId, trialId, fixtureId, targetId, controllerVersion, commitSha,
+topologyVariant, mockStrategy,
+first_static_pass (0|1|unavailable),
+first_behavior_pass (0|1|unavailable),
+post_repair_final_pass (0|1|N/A|unavailable),
+requirement_trace_ok (0|1|not-applicable|unavailable),
+forbidden_write_count,
+unapproved_dependency_count,
+mock_real_false_claim (0|1|n/a),
+node_count, model_node_count,
+wall_clock_ms, tokens_total,
+browser_status (not-run)
+```
+
+## 与 M1+ 的关系
+
+- 指标名称稳定；分子定义可在 M1（contract）、M3（repair）版本化增补，须在 CHANGELOG/本文件注明 **metrics schema version**。  
+- 当前 **metrics schema version: m0.1**。

package/docs/templates/frontend-eval/smoke-targets.md

@@ -0,0 +1,53 @@
+# Frontend-implementation Smoke Targets 策略（M0）
+
+## 原则
+
+1. **仅使用平台临时目录**（`os.tmpdir()` / CI runner temp），**不得**在 loop-agent 仓库根写入可运行 app、`node_modules` 或构建产物。  
+2. **不启动浏览器**；不安装 Playwright/Cypress；不声明 Browser verification。  
+3. M0 只冻结**目标描述与生成约定**；真正从 fixture 物化临时项目在 **M1+ dogfood** 时实施。  
+4. 临时项目生命周期：创建 → 最小依赖安装（仅 temp）→ 跑冻结 static/behavior 命令 → 删除；失败日志可复制到 run-owned harness 目录，不进 git。
+
+## 三类可控目标
+
+| targetId | 栈 | 最小信号 | 建议 static | 建议 behavior | Browser |
+|----------|----|----------|-------------|---------------|---------|
+| `react-vitest-min` | React + Vitest + TypeScript | `package.json` scripts: `typecheck`, `build`/`vite build`, `test`；`src/**/*.tsx` | `npm run typecheck`（+ build 若存在） | `npm test` / `npx vitest run` | not-run |
+| `nextjs-min` | Next.js（App Router 信号） | `app/` 或 `pages/` + `"next"` dependency；`"use client"` 边界样例 | `npm run typecheck` / `next build`（temp only） | 聚焦 unit/component test，**不** `next start` 作完成证据 | not-run |
+| `vue-vitest-min` | Vue 3 + Vitest | `*.vue` + vitest config | `npm run typecheck` 或 `vue-tsc` | `npm test` | not-run |
+
+## 临时项目生成约定（M1+ 实施）
+
+```text
+ROOT="$(mktemp -d "${TMPDIR:-/tmp}/fe-eval-XXXXXX")"
+# 从 docs/templates/frontend-eval/fixtures/... 渲染 package.json / 源文件骨架
+# npm install --prefix "$ROOT"   # 仅 temp
+# 在 $ROOT 执行冻结 verify 命令
+# rm -rf "$ROOT"
+```
+
+约束：
+
+- fixture **不得**内嵌密钥、真实 PII、恶意脚本。  
+- 依赖版本钉死在 fixture 清单，避免 eval 漂移。  
+- 不得 `npm link` 工作区 loop-agent 作为被测 app 依赖（controller 版本另按任务约束）。
+
+## 与 functional / failure fixtures 映射
+
+| fixture 类别 | 优先 target |
+|--------------|-------------|
+| simple component / style | react-vitest-min, vue-vitest-min |
+| form validation | react-vitest-min |
+| list/detail | react-vitest-min, nextjs-min |
+| API + Mock | react-vitest-min（+ MSW 骨架） |
+| permission UI | react-vitest-min, nextjs-min |
+| SSR / server-client boundary | nextjs-min |
+| shared component API | react-vitest-min |
+| pure local no-remote | 任一 |
+| failure: type/build | 任一 |
+| failure: mock production-on | react-vitest-min + mock 骨架 |
+
+## 明确不做
+
+- 不在本仓库 `website/**` 或 examples 中落永久 dogfood app 作为 M0 必需项。  
+- 不把 `scripts/check-repo.sh` 全量当作前端 app 验证。  
+- 不提交 temp 安装树或截图基线。

package/docs/templates/frontend-implementation-contract.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "frontend-implementation-contract-v1",
+  "title": "Frontend Implementation Contract v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "sourceBinding", "riskLevel", "targets", "requirements", "uiStates", "interactions", "mockApi", "designEvidence", "verificationTargets", "evidenceGaps"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "sourceBinding": { "$ref": "#/$defs/sourceBinding" },
+    "riskLevel": { "enum": ["small", "standard", "high-risk"] },
+    "targets": { "type": "object", "additionalProperties": false, "required": ["files"], "properties": { "files": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/path" } }, "routes": { "type": "array", "items": { "type": "string", "pattern": "^/" } }, "publicApiChanges": { "type": "array", "items": { "type": "string", "minLength": 1 } } } },
+    "requirements": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "implementationTargets", "verificationTargetIds"], "properties": { "id": { "$ref": "#/$defs/requirementId" }, "implementationTargets": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "verificationTargetIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "evidenceGap": { "$ref": "#/$defs/gap" } } } },
+    "uiStates": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["name", "applicable"], "properties": { "name": { "type": "string", "minLength": 1 }, "applicable": { "type": "boolean" }, "expectedBehavior": { "type": "string", "minLength": 1 }, "implementationTargets": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "verificationTargetIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "notApplicableReason": { "type": "string", "minLength": 1 } } } },
+    "interactions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["name", "implementationTargets", "verificationTargetIds"], "properties": { "name": { "type": "string", "minLength": 1 }, "implementationTargets": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "verificationTargetIds": { "type": "array", "items": { "type": "string" } } } } },
+    "mockApi": { "type": "object", "additionalProperties": false, "required": ["strategy", "productionDefaultOff", "activation", "endpoints"], "properties": { "strategy": { "enum": ["native", "browser-intercept", "request-adapter", "not-needed"] }, "productionDefaultOff": { "const": true }, "activation": { "type": "string", "minLength": 1 }, "endpoints": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["method", "path"], "properties": { "method": { "enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"] }, "path": { "type": "string", "pattern": "^/" }, "fixture": { "$ref": "#/$defs/path" }, "consumer": { "$ref": "#/$defs/path" } } } } } },
+    "designEvidence": { "type": "object", "additionalProperties": false, "required": ["source", "paths", "conflicts"], "properties": { "source": { "type": "string", "minLength": 1 }, "paths": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "conflicts": { "type": "array", "items": { "type": "string", "minLength": 1 } } } },
+    "verificationTargets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["id", "type", "commandLabel", "file", "requirementIds", "uiStates"], "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "enum": ["static", "unit", "component", "integration", "mock"] }, "commandLabel": { "type": "string", "minLength": 1 }, "file": { "$ref": "#/$defs/path" }, "symbol": { "type": "string", "minLength": 1 }, "requirementIds": { "type": "array", "items": { "$ref": "#/$defs/requirementId" } }, "uiStates": { "type": "array", "items": { "type": "string", "minLength": 1 } } } } },
+    "evidenceGaps": { "type": "array", "items": { "$ref": "#/$defs/gap" } }
+  },
+  "$defs": {
+    "path": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$" },
+    "requirementId": { "type": "string", "pattern": "^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$" },
+    "gap": { "type": "object", "additionalProperties": false, "required": ["description", "blocking"], "properties": { "requirementId": { "$ref": "#/$defs/requirementId" }, "description": { "type": "string", "minLength": 1 }, "blocking": { "type": "boolean" } } },
+    "sourceBinding": { "type": "object", "additionalProperties": false, "required": ["taskId", "requirementPath", "requirementSha256", "referencePaths", "requirementIds"], "properties": { "taskId": { "type": "string", "minLength": 1 }, "requirementPath": { "$ref": "#/$defs/path" }, "requirementSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "referencePaths": { "type": "array", "items": { "$ref": "#/$defs/path" } }, "requirementIds": { "type": "array", "items": { "$ref": "#/$defs/requirementId" } } } }
+  }
+}

package/docs/verification-matrix.md

@@ -59,7 +59,7 @@ Windows 上通过 Git Bash 或已配置的兼容 Bash 运行 `scripts/*.sh`。
 
 没有相关门禁的新鲜命令输出，不得声明完成。
 
-Production Readiness v0.1 工作以 `docs/production-readiness.md` 与 `docs/templates/production-readiness-checklist.md` 为验收契约。最终 hardening closeout 需要：
+Production Readiness v0.1 工作以 `ai_workspace/loop-agent/production-readiness.md` 与 `ai_workspace/loop-agent/templates/production-readiness-checklist.md` 为验收契约。最终 hardening closeout 需要：
 
 ```bash
 bash scripts/ci.sh

package/examples/decision-gate-agent-dag.json

@@ -6,7 +6,7 @@
     "contract-pi returns a read-only implementation contract",
     "implement-pi writes only inside the declared writeSet",
     "verify-shell archives deterministic verification outputs",
-    "decision-pi returns a DECISION_ENVELOPE_JSON block matching docs/templates/agent-dag-decision-envelope.schema.json",
+    "decision-pi returns a DECISION_ENVELOPE_JSON block matching ai_workspace/loop-agent/templates/agent-dag-decision-envelope.schema.json",
     "closeout-pi summarizes the result without writing files"
   ],
   "globalConstraints": [
@@ -77,7 +77,7 @@
         "artifacts/**"
       ],
       "outputContract": "Plain Markdown implementation contract; no file writes.",
-      "subtask_prompt": "Read the DAG objective, success criteria, docs/loop-agent-harness.md, and docs/agent-dag-runner.md. Return a concise contract covering scope, write boundaries, risks, and verification expectations. Do not edit files."
+      "subtask_prompt": "Read the DAG objective, success criteria, ai_workspace/loop-agent/loop-agent-harness.md, and ai_workspace/loop-agent/agent-dag-runner.md. Return a concise contract covering scope, write boundaries, risks, and verification expectations. Do not edit files."
     },
     {
       "id": "implement-pi",
@@ -144,8 +144,8 @@
         ".harness/**",
         "artifacts/**"
       ],
-      "outputContract": "Markdown with exactly one ```DECISION_ENVELOPE_JSON fenced block (info string DECISION_ENVELOPE_JSON, not json) matching docs/templates/agent-dag-decision-envelope.schema.json, plus a short evidence/risk summary. No file writes.",
-      "subtask_prompt_markdown": "../docs/templates/agent-dag-decision-gate.prompt.md",
+      "outputContract": "Markdown with exactly one ```DECISION_ENVELOPE_JSON fenced block (info string DECISION_ENVELOPE_JSON, not json) matching ai_workspace/loop-agent/templates/agent-dag-decision-envelope.schema.json, plus a short evidence/risk summary. No file writes.",
+      "subtask_prompt_markdown": "../ai_workspace/loop-agent/templates/agent-dag-decision-gate.prompt.md",
       "decisionGate": {
         "enabled": true,
         "schemaVersion": 1,

package/examples/hybrid-loop-agent-dag.json

@@ -77,7 +77,7 @@
         "artifacts/**"
       ],
       "outputContract": "Plain Markdown implementation contract summary; no file writes.",
-      "subtask_prompt": "阅读 ./README.md 与 docs/agent-dag-runner.md，返回 10 行以内的实现契约摘要（只读分析 + 文档建议，不改代码/文档/artifacts）。指出是否适合并行 scout 与窄 writeSet。"
+      "subtask_prompt": "阅读 ./README.md 与 ai_workspace/loop-agent/agent-dag-runner.md，返回 10 行以内的实现契约摘要（只读分析 + 文档建议，不改代码/文档/artifacts）。指出是否适合并行 scout 与窄 writeSet。"
     },
     {
       "id": "scout-src",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.13.0-beta.0",
+  "version": "0.14.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -55,7 +55,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.build.json && node -e \"const fs=require('node:fs');const p='dist/worker/observe/static';fs.mkdirSync(p,{recursive:true});fs.cpSync('src/worker/observe/static',p,{recursive:true});\"",
     "prepack": "npm run build",
-    "prepublishOnly": "node scripts/check-npm-publish-policy.mjs && npm run typecheck && npm test && npm run build",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "lint": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
     "test": "node scripts/run-tests.mjs",

package/skills/ai-engineering-context/SKILL.md

@@ -15,7 +15,7 @@ Context 是工程 artifact，不是 chat 残留。须显式保留 requirements
 
 ## Context Priority
 
-按以下顺序优先采信 facts：最新 user instruction；task source/contract；DAG/Loop artifacts；docs/plans/ADRs；code/tests；chat history 仅作 hint。
+按以下顺序优先采信 facts：最新 user instruction；task source/contract；DAG/Loop artifacts；ai_workspace/loop-agent/plans/ADRs；code/tests；chat history 仅作 hint。
 
 若 sources 冲突，停止并点明冲突。
 
@@ -37,7 +37,7 @@ read-only node 只能在 node output 返回 findings。不得在 repo 中创建
 
 ## Persistence Rules
 
-Requirements 与 constraints 写入 task `source/`。Execution state 与 node artifacts 写入 `.harness/`。Durable plans、reports、decisions 写入 `docs/`。可复用 process guidance 写入 `skills/`。Chat 仅 transient。
+Requirements 与 constraints 写入 task `source/`。Execution state 与 node artifacts 写入 `.harness/`。Durable plans、reports、decisions 写入 `ai_workspace/loop-agent/`。可复用 process guidance 写入 `.agents/skills/`。Chat 仅 transient。
 
 ## Failure Handling
 

package/skills/browser-tools/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: browser-tools
+description: Interactive browser automation via Chrome DevTools Protocol. Use when you need to interact with web pages, test frontends, or when user interaction with a visible browser is required.
+---
+
+# Browser Tools
+
+Chrome DevTools Protocol tools for agent-assisted web automation. These tools connect to Chrome running on `:9222` with remote debugging enabled.
+
+## Setup
+
+Run once before first use:
+
+```bash
+cd {baseDir}/browser-tools
+npm install
+```
+
+## Start Chrome
+
+```bash
+{baseDir}/browser-start.js              # Fresh profile
+{baseDir}/browser-start.js --profile    # Copy user's profile (cookies, logins)
+```
+
+Launch Chrome with remote debugging on `:9222`. Use `--profile` to preserve user's authentication state.
+
+## Navigate
+
+```bash
+{baseDir}/browser-nav.js https://example.com
+{baseDir}/browser-nav.js https://example.com --new
+```
+
+Navigate to URLs. Use `--new` flag to open in a new tab instead of reusing current tab.
+
+## Evaluate JavaScript
+
+```bash
+{baseDir}/browser-eval.js 'document.title'
+{baseDir}/browser-eval.js 'document.querySelectorAll("a").length'
+```
+
+Execute JavaScript in the active tab. Code runs in async context. Use this to extract data, inspect page state, or perform DOM operations programmatically.
+
+## Screenshot
+
+```bash
+{baseDir}/browser-screenshot.js
+```
+
+Capture current viewport and return temporary file path. Use this to visually inspect page state or verify UI changes.
+
+## Pick Elements
+
+```bash
+{baseDir}/browser-pick.js "Click the submit button"
+```
+
+**IMPORTANT**: Use this tool when the user wants to select specific DOM elements on the page. This launches an interactive picker that lets the user click elements to select them. The user can select multiple elements (Cmd/Ctrl+Click) and press Enter when done. The tool returns CSS selectors for the selected elements.
+
+Common use cases:
+- User says "I want to click that button" → Use this tool to let them select it
+- User says "extract data from these items" → Use this tool to let them select the elements
+- When you need specific selectors but the page structure is complex or ambiguous
+
+## Cookies
+
+```bash
+{baseDir}/browser-cookies.js
+```
+
+Display all cookies for the current tab including domain, path, httpOnly, and secure flags. Use this to debug authentication issues or inspect session state.
+
+## Extract Page Content
+
+```bash
+{baseDir}/browser-content.js https://example.com
+```
+
+Navigate to a URL and extract readable content as markdown. Uses Mozilla Readability for article extraction and Turndown for HTML-to-markdown conversion. Works on pages with JavaScript content (waits for page to load).
+
+## When to Use
+
+- Testing frontend code in a real browser
+- Interacting with pages that require JavaScript
+- When user needs to visually see or interact with a page
+- Debugging authentication or session issues
+- Scraping dynamic content that requires JS execution
+
+---
+
+## Efficiency Guide
+
+### DOM Inspection Over Screenshots
+
+**Don't** take screenshots to see page state. **Do** parse the DOM directly:
+
+```javascript
+// Get page structure
+document.body.innerHTML.slice(0, 5000)
+
+// Find interactive elements
+Array.from(document.querySelectorAll('button, input, [role="button"]')).map(e => ({
+  id: e.id,
+  text: e.textContent.trim(),
+  class: e.className
+}))
+```
+
+### Complex Scripts in Single Calls
+
+Wrap everything in an IIFE to run multi-statement code:
+
+```javascript
+(function() {
+  // Multiple operations
+  const data = document.querySelector('#target').textContent;
+  const buttons = document.querySelectorAll('button');
+  
+  // Interactions
+  buttons[0].click();
+  
+  // Return results
+  return JSON.stringify({ data, buttonCount: buttons.length });
+})()
+```
+
+### Batch Interactions
+
+**Don't** make separate calls for each click. **Do** batch them:
+
+```javascript
+(function() {
+  const actions = ["btn1", "btn2", "btn3"];
+  actions.forEach(id => document.getElementById(id).click());
+  return "Done";
+})()
+```
+
+### Typing/Input Sequences
+
+```javascript
+(function() {
+  const text = "HELLO";
+  for (const char of text) {
+    document.getElementById("key-" + char).click();
+  }
+  document.getElementById("submit").click();
+  return "Submitted: " + text;
+})()
+```
+
+### Reading App/Game State
+
+Extract structured state in one call:
+
+```javascript
+(function() {
+  const state = {
+    score: document.querySelector('.score')?.textContent,
+    status: document.querySelector('.status')?.className,
+    items: Array.from(document.querySelectorAll('.item')).map(el => ({
+      text: el.textContent,
+      active: el.classList.contains('active')
+    }))
+  };
+  return JSON.stringify(state, null, 2);
+})()
+```
+
+### Waiting for Updates
+
+If DOM updates after actions, add a small delay with bash:
+
+```bash
+sleep 0.5 && {baseDir}/browser-eval.js '...'
+```
+
+### Investigate Before Interacting
+
+Always start by understanding the page structure:
+
+```javascript
+(function() {
+  return {
+    title: document.title,
+    forms: document.forms.length,
+    buttons: document.querySelectorAll('button').length,
+    inputs: document.querySelectorAll('input').length,
+    mainContent: document.body.innerHTML.slice(0, 3000)
+  };
+})()
+```
+
+Then target specific elements based on what you find.

package/skills/browser-tools/browser-content.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import puppeteer from "puppeteer-core";
+import { Readability } from "@mozilla/readability";
+import { JSDOM } from "jsdom";
+import TurndownService from "turndown";
+import { gfm } from "turndown-plugin-gfm";
+
+// Global timeout - exit if script takes too long
+const TIMEOUT = 30000;
+const timeoutId = setTimeout(() => {
+	console.error("✗ Timeout after 30s");
+	process.exit(1);
+}, TIMEOUT).unref();
+
+const url = process.argv[2];
+
+if (!url) {
+	console.log("Usage: browser-content.js <url>");
+	console.log("\nExtracts readable content from a URL as markdown.");
+	console.log("\nExamples:");
+	console.log("  browser-content.js https://example.com");
+	console.log("  browser-content.js https://en.wikipedia.org/wiki/Rust_(programming_language)");
+	process.exit(1);
+}
+
+const b = await Promise.race([
+	puppeteer.connect({
+		browserURL: "http://localhost:9222",
+		defaultViewport: null,
+	}),
+	new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), 5000)),
+]).catch((e) => {
+	console.error("✗ Could not connect to browser:", e.message);
+	console.error("  Run: browser-start.js");
+	process.exit(1);
+});
+
+const p = (await b.pages()).at(-1);
+if (!p) {
+	console.error("✗ No active tab found");
+	process.exit(1);
+}
+
+await Promise.race([
+	p.goto(url, { waitUntil: "networkidle2" }),
+	new Promise((r) => setTimeout(r, 10000)),
+]).catch(() => {});
+
+// Get HTML via CDP (works even with TrustedScriptURL restrictions)
+const client = await p.createCDPSession();
+const { root } = await client.send("DOM.getDocument", { depth: -1, pierce: true });
+const { outerHTML } = await client.send("DOM.getOuterHTML", { nodeId: root.nodeId });
+await client.detach();
+
+const finalUrl = p.url();
+
+// Extract with Readability
+const doc = new JSDOM(outerHTML, { url: finalUrl });
+const reader = new Readability(doc.window.document);
+const article = reader.parse();
+
+// Convert to markdown
+function htmlToMarkdown(html) {
+	const turndown = new TurndownService({ headingStyle: "atx", codeBlockStyle: "fenced" });
+	turndown.use(gfm);
+	turndown.addRule("removeEmptyLinks", {
+		filter: (node) => node.nodeName === "A" && !node.textContent?.trim(),
+		replacement: () => "",
+	});
+	return turndown
+		.turndown(html)
+		.replace(/\[\\?\[\s*\\?\]\]\([^)]*\)/g, "")
+		.replace(/ +/g, " ")
+		.replace(/\s+,/g, ",")
+		.replace(/\s+\./g, ".")
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+}
+
+let content;
+if (article && article.content) {
+	content = htmlToMarkdown(article.content);
+} else {
+	// Fallback
+	const fallbackDoc = new JSDOM(outerHTML, { url: finalUrl });
+	const fallbackBody = fallbackDoc.window.document;
+	fallbackBody.querySelectorAll("script, style, noscript, nav, header, footer, aside").forEach((el) => el.remove());
+	const main = fallbackBody.querySelector("main, article, [role='main'], .content, #content") || fallbackBody.body;
+	const fallbackHtml = main?.innerHTML || "";
+	if (fallbackHtml.trim().length > 100) {
+		content = htmlToMarkdown(fallbackHtml);
+	} else {
+		content = "(Could not extract content)";
+	}
+}
+
+console.log(`URL: ${finalUrl}`);
+if (article?.title) console.log(`Title: ${article.title}`);
+console.log("");
+console.log(content);
+
+process.exit(0);