@vpxa/aikit 0.1.307 → 0.1.309

package/scaffold/dist/definitions/skills/brainstorming.mjs

@@ -14,44 +14,51 @@ argument-hint: "Feature, component, or behavior to design"
 
 # Brainstorming Ideas Into Designs
 
-## Quick Reference
+Use before implementation when multiple viable approaches exist, architecture/product tradeoffs matter, or user asks for guidance. Skip for mechanical changes and code-agent execution.
 
-**Purpose:** Explore requirements and design space before implementation starts.
+## Guardrail
 
-**Use this skill when:** there are multiple viable approaches, architecture trade-offs matter, or the user is asking for guidance rather than code.
+No code/scaffold handoff until design is clear enough for implementation. Planning agents use this; implementation agents request context instead.
 
-**Skip this skill when:** the work is already decided, the change is mechanical, or only one reasonable path exists.
+## Flow
 
-**HARD GATE:** Do NOT write code, scaffold files, or hand off to implementation until a design is presented and approved.
+1. Frame problem: goal, users, constraints, non-goals, success signal.
+2. Ask Why? and Simpler? unless already answered.
+3. Generate 2-4 distinct options with tradeoffs.
+4. Stress test: risks, dependencies, unknowns, reversibility, cost.
+5. Recommend one path with confidence and first step.
+6. Hand off concise design to Planner/Orchestrator.
 
-**Expected output:** a short design or spec with constraints, alternatives, recommendation, risks, and acceptance criteria.
+## Option Shape
 
-<HARD-GATE>
-Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
-</HARD-GATE>
+Each option includes:
+- Name.
+- How it works.
+- Best fit.
+- Costs/risks.
+- What must be true.
+- Verification path.
 
-## When Brainstorming Is Appropriate
+## Quality Bar
 
-Use brainstorming when at least one of these is true:
+Good brainstorming narrows choices. Avoid idea dumps. Surface disagreement, hidden constraints, and cheaper alternatives. If requirements are too vague, load requirements-clarity and score before design.
 
-- Multiple valid approaches exist and the choice changes cost, risk, or UX
-- The work introduces or changes boundaries: service, module, API, workflow, ownership
-- The user is asking for options, strategy, trade-offs, or "best way" guidance
-- Constraints are real but incomplete: performance, timeline, migration cost, reversibility, team familiarity
+## References
 
-Do not use brainstorming when the path is already obvious:
+Load on demand:
+- references/mode-selection.md — Simple vs Full mode selection criteria and examples.
+- references/decision-protocol.md — Multi-Researcher and Single-Agent decision protocol details.
+- references/design-quality.md — Review checklist, quality signals, and output contract formats.
+- references/spec-document-reviewer-prompt.md — Prompt template for dispatching spec document review.
 
-- Fixing a typo, renaming a variable, or updating a pinned dependency
-- Implementing an already-approved spec or ADR
-- Mechanical migrations where the desired end state is predetermined
+## Output
 
----
-
-## Mode Selection
+Use short sections: Problem, Constraints, Options, Recommendation, Open Questions, Handoff Notes. Include decision confidence: low/medium/high.
+`},{file:`references/mode-selection.md`,content:`# Mode Selection
 
-This skill operates in two modes. You choose the mode from the problem shape; do not ask the user which mode they want.
+The brainstorming skill operates in two modes. Choose the mode from the problem shape; do not ask the user which mode they want.
 
-### Simple Mode
+## Simple Mode
 
 Use when **all** of these are true:
 - Affects ≤3 files
@@ -62,7 +69,9 @@ Use when **all** of these are true:
 
 Examples: config change, utility function, bug fix with design ambiguity, small feature in existing component.
 
-### Full Mode
+Output: concise design note with Goal, Constraints, Options, Recommendation, Risks.
+
+## Full Mode
 
 Use when **any** of these are true:
 - Affects >3 files or crosses service boundaries
@@ -74,65 +83,38 @@ Use when **any** of these are true:
 
 Examples: new notification channel, new API service, platform redesign, multi-service feature, infrastructure changes.
 
----
-
-## NEVER
-
-- **NEVER skip divergent thinking to jump to solutions** - premature convergence is the most common brainstorming failure. Force at least 3 alternatives before evaluating.
-- **NEVER present options without trade-off analysis** - listing A/B/C without pros, cons, and context is noise. Each option needs: strength, weakness, best-when.
-- **NEVER conflate requirements with design** - "the user wants to log in" is a requirement; "use OAuth2 + JWT" is a design. Clarify the problem before exploring the solution space.
-- **NEVER evaluate during the divergent phase** - "that won't work" too early kills useful exploration. Generate first, judge second.
-- **NEVER propose more than 5 options** - too many options create analysis paralysis. 3-5 well-differentiated choices is enough.
-- **NEVER present the obvious choice as the only real option with strawman alternatives** - if one option clearly dominates before analysis, say brainstorming is unnecessary and recommend directly.
-- **NEVER use brainstorming for single-path decisions** - if there is only one credible path, execute or hand off; do not manufacture fake alternatives.
-- **NEVER hide the deciding constraint** - if compliance, migration cost, latency, or org ownership is driving the decision, state it explicitly.
-
-## Core Workflow
-
-| Stage | What you do | What good output looks like |
-|-------|-------------|-----------------------------|
-| Frame | State the problem, constraints, and success criteria | Clear decision question and explicit boundaries |
-| Clarify | Ask one question at a time until ambiguity drops | Requirements are separate from solutions |
-| Diverge | Generate 3 alternatives that differ in shape, not just labels | Options have meaningfully different trade-offs |
-| Evaluate | Compare options against criteria, constraints, reversibility, and delivery cost | Rejection reasons are explicit |
-| Recommend | Pick one option and explain why the others lost | Recommendation matches the stated constraints |
-| Confirm | Present the design, get approval, then hand off | Implementation can proceed without reopening core design questions |
-
-Simple Mode compresses the workflow into a short design note. Full Mode produces a fuller spec and spends more time on constraints, interfaces, migration, and rollout.
-
----
-
-## Decision Protocol
+Output: spec covering boundaries, interfaces, data flow, migration, error handling, test strategy.
 
-Use the heaviest process the problem actually needs. The protocol scales with decision complexity; it does not assume a giant agent swarm.
+## Large Project Decomposition
 
-### Multi-Researcher Mode
+Before asking detailed questions, assess scope. If the request includes multiple independent subsystems, decompose first. Do not brainstorm the whole platform as one blob. Break into sub-projects, define order, then brainstorm the first sub-project only.
+`},{file:`references/decision-protocol.md`,content:`# Decision Protocol
 
-Use this when the decision is high-impact and the Orchestrator can actually dispatch multiple research passes.
+Use the heaviest process the problem actually needs. The protocol scales with decision complexity.
 
-1. **Independent passes** - gather 2-4 perspectives if available. More is optional, not mandatory.
-2. **Cross-check blind spots** - compare where the perspectives agree, clash, and what each missed.
-3. **Structured verdict** - produce one recommendation with confidence, deciding constraints, rejected alternatives, and first implementation step.
+## Multi-Researcher Mode
 
-Do not block waiting for an 8-agent protocol. If capacity is limited, reduce the number of perspectives and keep the structure.
+Use when the decision is high-impact and you can dispatch multiple research passes.
 
-### Single-Agent Fallback
+1. **Independent passes** — gather 2-4 perspectives if available. More is optional, not mandatory.
+2. **Cross-check blind spots** — compare where the perspectives agree, clash, and what each missed.
+3. **Structured verdict** — produce one recommendation with confidence, deciding constraints, rejected alternatives, and first implementation step.
 
-When running as a single agent (no Orchestrator dispatching multi-model research), use this structured approach:
+Do not block waiting for an 8-agent protocol. If capacity is limited, reduce perspectives and keep the structure.
 
-1. **Frame the decision space** - state the question, list constraints, define success criteria
-2. **Generate 3 alternatives** - force diversity by thinking from different lenses:
-  - Lens A: Simplest approach (minimum viable, least risk)
-  - Lens B: Best long-term approach (might be more work now, pays off later)
-  - Lens C: Unconventional approach (different framing, different trade-off)
-3. **Evaluate against criteria** - for each alternative, score against the stated success criteria
-4. **Recommend with rationale** - pick one, explain WHY, acknowledge what you're trading away
+## Single-Agent Fallback
 
-This replaces the full Multi-Model Decision Protocol when running solo.
+When running as a single agent (no multi-model research dispatch):
 
-### Verdict Format
+1. **Frame the decision space** — state the question, list constraints, define success criteria.
+2. **Generate 3 alternatives** — force diversity by thinking from different lenses:
+   - Lens A: Simplest approach (minimum viable, least risk)
+   - Lens B: Best long-term approach (more work now, pays off later)
+   - Lens C: Unconventional approach (different framing, different trade-off)
+3. **Evaluate against criteria** — for each alternative, score against the stated success criteria.
+4. **Recommend with rationale** — pick one, explain WHY, acknowledge what you are trading away.
 
-Express the result in structured text, not diagrams:
+## Verdict Format
 
 | Section | Required content |
 |---------|------------------|
@@ -143,30 +125,25 @@ Express the result in structured text, not diagrams:
 | Rejections | Why the other options lost |
 | Risks | What could fail and how reversible it is |
 | First Step | Smallest useful next move after approval |
-
-### Large Project Decomposition
-
-Before asking detailed questions, assess scope. If the request includes multiple independent subsystems, decompose first. Do not brainstorm the whole platform as one blob.
-
-If the project is too large for a single spec, break it into sub-projects, define the order, then brainstorm the first sub-project only.
+`},{file:`references/design-quality.md`,content:`# Design Quality
 
 ## Design Quality Signals
 
-- **Options are genuinely different** - if they only differ in naming, you have not explored the space.
-- **Trade-offs are real** - if one option dominates on all dimensions, the others are strawmen.
-- **Constraints are explicit** - "we chose X because of Y constraint" is good; "X is better" is lazy.
-- **Reversibility is assessed** - one-way doors need more analysis than two-way doors.
-- **You can explain why NOT the other options** - if you cannot articulate the rejection reason, the analysis is shallow.
+- **Options are genuinely different** — if they only differ in naming, you have not explored the space.
+- **Trade-offs are real** — if one option dominates on all dimensions, the others are strawmen.
+- **Constraints are explicit** — "we chose X because of Y constraint" is good; "X is better" is lazy.
+- **Reversibility is assessed** — one-way doors need more analysis than two-way doors.
+- **You can explain why NOT the other options** — if you cannot articulate the rejection reason, the analysis is shallow.
 
 ## Design Review Checklist
 
-Before presenting the design, verify these quality bars:
+Before presenting the design, verify:
 
-- **Completeness** - no TODOs, placeholders, or missing constraints that block planning.
-- **Consistency** - sections do not contradict each other.
-- **Precision** - two competent developers would implement compatible solutions from this spec.
-- **Scope control** - the design solves the asked problem and avoids unrequested extras.
-- **Canonical language** - names and domain terms match the codebase or are explicitly introduced.
+- **Completeness** — no TODOs, placeholders, or missing constraints that block planning.
+- **Consistency** — sections do not contradict each other.
+- **Precision** — two competent developers would implement compatible solutions from this spec.
+- **Scope control** — the design solves the asked problem and avoids unrequested extras.
+- **Canonical language** — names and domain terms match the codebase or are explicitly introduced.
 
 Fix serious issues before handoff. Minor wording changes are advisory, not blockers.
 
@@ -178,28 +155,13 @@ Fix serious issues before handoff. Minor wording changes are advisory, not block
 - Separate divergent generation from evaluation.
 - Lead with your recommendation once the option space is explored.
 - Stay concrete: boundaries, interfaces, data flow, failure modes, rollout.
-
-## Output Contract
-
-For Simple Mode, produce a concise design note with:
-
-- Goal
-- Constraints
-- 3 options
-- Recommendation
-- Risks and acceptance criteria
-
-For Full Mode, produce a spec that also covers:
-
-- Boundaries and component responsibilities
-- Interfaces and data flow
-- Migration or rollout strategy
-- Error handling and operational risks
-- Test and acceptance strategy
-
-When useful, save the approved design to \`docs/plans/YYYY-MM-DD-<topic>-design.md\` before handing off to implementation planning.
-
-`},{file:`spec-document-reviewer-prompt.md`,content:`# Spec Document Reviewer Prompt Template
+- NEVER skip divergent thinking to jump to solutions. Force at least 3 alternatives before evaluating.
+- NEVER present options without trade-off analysis.
+- NEVER conflate requirements with design.
+- NEVER evaluate during the divergent phase.
+- NEVER propose more than 5 options (3-5 is enough).
+- NEVER hide the deciding constraint.
+`},{file:`references/spec-document-reviewer-prompt.md`,content:`# Spec Document Reviewer Prompt Template
 
 Use this template when dispatching a spec document reviewer subagent.
 

package/scaffold/dist/definitions/skills/browser-use.mjs

@@ -1,6 +1,6 @@
 var e=[{file:`SKILL.md`,content:`---
 name: browser-use
-description: "Browser automation for AI agents using AI Kit's owned \`browser\` MCP tool. Triggered when: (1) repo-access exhausts its Strategy Ladder and auth requires browser interaction, (2) \`web_fetch\` returns login page HTML, SAML redirect, or CAPTCHA instead of content, (3) user needs to interact with web applications (fill forms, click buttons, extract data), (4) a site requires JavaScript rendering that \`web_fetch\` cannot handle, (5) user asks to browse, scrape, test, or automate a website, or (6) another skill needs a standard recipe format for browser-driven workflows. Uses AI Kit's owned Chromium runtime and recipe patterns for domain-specific automation skills — no external MCP server dependency."
+description: "Browser automation for AI agents using AI Kit's owned browser MCP tool. Triggered when repo-access exhausts its Strategy Ladder and auth requires browser interaction; web_fetch returns login page HTML, SAML redirect, or CAPTCHA; user needs web app interaction; site requires JavaScript rendering; user asks to browse, scrape, test, or automate a website; or another skill needs browser recipes. Uses AI Kit's owned Chromium runtime."
 metadata:
   category: cross-cutting
   domain: general
@@ -12,204 +12,59 @@ metadata:
 argument-hint: "URL or browser task description"
 ---
 
-# Browser Automation for AI Agents
+# Browser Automation
 
-Use AI Kit's \`browser\` MCP tool for authentication barriers, data extraction, form interactions, network capture, and web automation. Single tool, action-based dispatch, owned Chromium runtime.
+Use AI Kit browser for JS-rendered pages, auth barriers, forms, screenshots, network capture, storage/cookies, and web app verification.
 
-## Runtime Preference
+## Tool Choice
 
-- Always use AI Kit's controlled Chromium when the agent needs to inspect, verify, or interact with a page.
-- Use \`mode: 'headless'\` by default. Switch to \`mode: 'ui'\` only for user-visible auth or visual debugging.
-- Never use system browser commands for agent work. They provide no programmatic feedback.
+Start with web_fetch/http for static content. Use browser when:
+- Page needs JS rendering or interaction.
+- Auth/SSO/CAPTCHA/login wall blocks fetch.
+- User asks to fill forms, click, scrape, inspect, or test UI.
+- Need screenshot/canvas/visual verification.
 
-## Quick Reference
-
-| I need to... | Action | Key params |
-|---|---|---|
-| Open a page | \`open\` | url, mode (ui/headless) |
-| Read page content | \`read\` | readMode: snapshot/dom/markdown/text |
-| Click/type/interact | \`act\` | kind: click/type/press/hover/select |
-| Wait for something | \`navigate\` | type: waitFor, selector |
-| Check network calls | \`network\` | subAction: enable → get |
-| Get cookies/storage | \`session\` | sessionAction: cookies/get-storage |
-| Take screenshot | \`screenshot\` | fullPage, selector |
-| Compare changes | \`diff\` | (compares to previous snapshot) |
-
-For full parameter details: \`describe_tool('browser')\`
-
-## Principles
-
-- **Prefer \`read\` over \`screenshot\`** — snapshots are structured (ARIA tree), searchable, and token-efficient. Screenshots are opaque blobs. Use screenshots only for visual verification.
-- **Prefer \`headless\` over \`ui\`** — faster, no window management. Use \`ui\` only when: user needs to see the browser, auth requires manual interaction, or debugging visual issues.
-- **Always \`read\` after \`act\`** — actions don't return page state. You need to verify the result.
-- **Use \`diff\` instead of re-reading** — after an action, \`diff\` shows only what changed. Much more efficient than full \`read\`.
-- **Network capture BEFORE navigation** — enable network capture THEN navigate. Captures start from enable time, not retroactively.
-- **One page = one task** — don't reuse pages across unrelated tasks. Fresh pages avoid state contamination.
-- **Read snapshot before targeting** — ARIA refs are more stable than guessing CSS selectors or text matches.
-- **Use page-context fetch for authenticated APIs** — if the browser session already has cookies and CSRF state, \`fetch\` is usually simpler than exporting cookies.
-
-## NEVER
-
-- **NEVER use \`file:///\` URLs** — the browser blocks local file access for security. Serve locally instead: \`npx -y serve <dir>\` then open \`http://localhost:<port>\`.
-- **NEVER interact without reading first** — you need the ARIA tree to know what elements exist. Blind clicks fail.
-- **NEVER send passwords via \`act({ kind: 'type' })\`** — tell the user to type credentials manually. Agent should never handle secrets.
-- **NEVER use \`screenshot\` as primary information source** — screenshots waste tokens and can't be searched. Use \`read\` with appropriate readMode.
-- **NEVER open system browser (\`Start-Process\`, \`open\`, \`xdg-open\`)** — provides zero feedback to the agent. Always use the owned browser.
-- **NEVER leave pages open** — close pages when done: \`session({ sessionAction: 'close', pageId })\`. Leaked pages consume resources.
-- **NEVER scrape without rate limiting** — rapid page loads trigger bot detection. Add reasonable delays between navigations.
-- **NEVER enable network capture after the event you care about** — you can't recover missed requests.
-
-## Activation Signals
-
-- Activate when \`web_fetch\` returns login HTML, SAML redirects, CAPTCHA pages, or JS-heavy shells with no readable content.
-- Activate when \`http\` returns 401/403/407 and browser auth is a plausible recovery path.
-- Activate when the task requires interaction, screenshots, network capture, authenticated browser-session fetches, or previewing a locally served HTML file.
-- Skip it when \`web_fetch\` or \`http\` already gives the answer.
-- The \`browser\` tool is always callable directly. This skill exists for recipes and operating discipline, not for basic availability.
-
-## Workflows
-
-**Two modes:**
-- **Script Mode** — direct sequential \`browser()\` calls for one-off tasks, debugging, and authenticated API capture.
-- **Recipe Mode** — reusable labeled step sequences for domain-specific automation.
-
-### Script Mode (Default — Imperative)
-
-Direct sequential \`browser()\` calls. Best for one-off tasks, testing, API capture.
-
-~~~text
-// Open → Read → Act → Read loop
-browser({ action: 'open', url: 'https://app.example.com', mode: 'ui' })
-browser({ action: 'read', pageId })
-browser({ action: 'act', pageId, kind: 'click', ref: '@login-button' })
-browser({ action: 'read', pageId })  // verify state changed
-~~~
-
-**Network Intelligence pattern:**
-
-~~~text
-browser({ action: 'network', pageId, subAction: 'enable', filter: { resourceTypes: ['xhr', 'fetch'] } })
-// ... navigate/interact to trigger API calls ...
-browser({ action: 'network', pageId, subAction: 'get' })
-browser({ action: 'network', pageId, subAction: 'export-har' })
-~~~
-
-**Authenticated API calls (using page cookies/session):**
-
-~~~text
-browser({ action: 'fetch', pageId, fetchUrl: 'https://app.example.com/api/data', fetchMethod: 'GET' })
-~~~
-
-Executes \`fetch()\` in the page, so cookies, session state, and CSRF tokens are reused automatically.
-
-**Console capture:**
-
-~~~text
-browser({ action: 'console', pageId, consoleSubAction: 'enable' })
-// ... trigger page actions ...
-browser({ action: 'console', pageId, consoleSubAction: 'get', level: 'error' })
-~~~
-
-### Recipe Mode (Declarative)
-
-Structured step-by-step format for reusable workflows and domain skills. Each step declares Action, Verify, On Failure, and Extract fields.
-
-Load [references/recipes.md](references/recipes.md) for full recipe templates and the recipe format specification.
-
-Brief recipe format:
-
-~~~text
-Step N: <description>
-  Action: browser({ ... })
-  Verify: <condition to check after action>
-  On Failure: <recovery strategy>
-  Extract: <data to capture for next steps>
-~~~
-
-### Element Targeting Priority
-
-1. **\`ref\`** (e.g., \`@F12\`) — From \`read(snapshot)\` ARIA tree. Most reliable.
-2. **\`selector\`** (e.g., \`input[name='q']\`) — Playwright CSS/attribute selector. Precise.
-3. **\`element\`** (e.g., \`'Submit'\`) — Text matching via \`text=\` locator. **Picks first DOM match regardless of visibility.** Fragile for complex widgets (comboboxes, ARIA roles). Last resort.
-
-**Always \`read(snapshot)\` first** to get refs before interacting.
-
-If a selector times out, assume visibility ambiguity first: narrow the selector, add \`:visible\`, or switch to a snapshot ref.
-
-## Network Intelligence
-
-Use browser-native capture when you need to learn how a web app really talks to its backend:
-
-- **\`network\`** for passive capture of XHR/fetch traffic, timing, and HAR export.
-- **\`console\`** for browser-side errors after UI actions.
-- **\`fetch\`** for replaying authenticated requests from page context without manually exporting cookies.
-
-Headers are redacted by default. Use sensitive output only when the task explicitly requires it and never echo secrets back to the user.
+Use headless by default. Use UI only for user-visible auth or visual debugging. Do not use system browser for agent-visible evidence.
 
-**Workflow — Reverse-engineer API:**
+## Recipes
 
-~~~text
-1. open target page
-2. network enable (filter: xhr, fetch)
-3. interact with the page (click buttons, submit forms)
-4. network get → see API endpoints, methods, headers
-5. fetch → replay API calls using page session
-~~~
+Open/read:
+1. browser open with url and waitUntil.
+2. browser read snapshot/text/markdown.
+3. Use eval only for data unavailable through accessibility/DOM reads.
 
-## Session Management
+Interact:
+1. Read snapshot.
+2. Act by stable role/name/ref/selector.
+3. Re-read or diff.
+4. Capture screenshot when visual result matters.
 
-- Cookie read/write actions require explicit confirmation.
-- Prefer \`fetch\` over cookie export when the goal is an authenticated API call.
-- Use labels for long flows, but close the page when the task ends.
+Auth:
+1. Detect login/SSO/CAPTCHA.
+2. Ask user only for secrets/actions that cannot be automated safely.
+3. Export cookies/session only when needed for same task.
+4. Never print tokens/passwords.
 
-## Security Model
+Network:
+1. Enable network capture before action.
+2. Perform action.
+3. Inspect filtered requests/responses.
+4. Include status, URL pattern, and relevant body snippets only.
 
-**Hard gates — NEVER bypass:**
-- Credentials go via terminal input (NEVER through tool params or chat)
-- CAPTCHA/MFA: pause and ask user
-- Never store tokens in conversation
-- Close pages containing sensitive data when done
-- Verify page URL before entering credentials (phishing prevention)
-- Use \`headless\` mode for automated non-interactive tasks; \`ui\` for user-supervised auth
+## Safety
 
-**Cookie safety gate:** All cookie read/write session actions (\`cookies\`, \`set-cookie\`, \`delete-cookie\`, \`clear-cookies\`) require \`confirm: true\` as an explicit acknowledgment. Without it, the tool returns an error.
-
-## Local File Preview
+- No destructive web actions without explicit confirmation.
+- No credential exfiltration or secret logging.
+- Respect robots/ToS for scraping; prefer official APIs when available.
+- For payments/admin/delete/send actions, ask clearly and wait.
 
-The browser tool blocks \`file:///\` URLs for security. To preview local HTML files, serve them via a local HTTP server first.
+## References
 
-**Pattern:**
-
-~~~text
-// 1. Start local server (pick an unused port)
-//    Terminal: npx -y serve <directory> -l <port>
-//    Example: npx -y serve ./dist -l 3847
-
-// 2. Open in browser
-browser({ action: 'open', url: 'http://localhost:3847/my-file.html', mode: 'ui' })
+Load references/recipes.md for detailed browser flows. Load references/auth-patterns.md for SSO/login/cookie handling. Load references/workflows.md for quick reference table, element targeting, script mode, session management, and local file preview.
 
-// 3. Read content or take screenshot
-browser({ action: 'read', pageId, readMode: 'markdown' })
-browser({ action: 'screenshot', pageId, fullPage: true })
-
-// 4. Clean up — kill the server terminal when done
-~~~
-
-**Use cases:**
-- Preview generated HTML (viewers, reports, docs)
-- Visual regression testing of local builds
-- Inspect single-file HTML applications
-- Screenshot local pages for review
-
-**Important:** Always use \`mode: 'ui'\` for visual preview so the user can also see and interact with the page.
-
-## High-Value Patterns
+## Output
 
-- **Dialogs:** register \`dialog\` before the action that triggers it. Prompt dialogs also need \`promptText\`.
-- **Labels:** assign a \`label\` on open for long-running flows so later calls stay readable.
-- **Batch:** use \`batch\` to reduce round-trips, but only when the needed \`pageId\` is already known.
-- **Diff:** first call establishes baseline, second call shows the delta.
-- **Preview local HTML:** serve the directory first, then open the localhost URL in the owned browser.
+Report URL, actions taken, evidence, extracted data, screenshots/paths if any, blockers, and next step.
 `},{file:`references/recipes.md`,content:`# Browser Recipes & Domain Skills
 
 Reference file for reusable browser automation patterns. Load this when building domain-specific browser workflows.
@@ -560,4 +415,93 @@ browser({ action: 'eval', pageId, code: 'localStorage.getItem("authToken")' })
 4. Or use \`navigate\` to move between pages — cookies persist
 
 **Important:** The browser auto-closes after idle timeout. For long-running tasks, interact periodically to reset the idle timer.
+`},{file:`references/workflows.md`,content:`# Browser Workflows Reference
+
+## Quick Reference
+
+| Need | Action | Key params |
+|---|---|---|
+| Open a page | \`open\` | url, mode (ui/headless) |
+| Read page content | \`read\` | readMode: snapshot/dom/markdown/text |
+| Click/type/interact | \`act\` | kind: click/type/press/hover/select |
+| Wait for something | \`navigate\` | type: waitFor, selector |
+| Check network calls | \`network\` | subAction: enable -> get |
+| Get cookies/storage | \`session\` | sessionAction: cookies/get-storage |
+| Take screenshot | \`screenshot\` | fullPage, selector |
+| Compare changes | \`diff\` | (compares to previous snapshot) |
+
+For full parameter details: \`describe_tool('browser')\`
+
+## Principles
+
+- Prefer \`read\` over \`screenshot\` — snapshots are structured (ARIA tree), searchable, token-efficient.
+- Always \`read\` after \`act\` — actions don't return page state.
+- Use \`diff\` instead of re-reading after an action — shows only what changed.
+- Network capture BEFORE navigation — enable then navigate. Captures start from enable time.
+- One page = one task — fresh pages avoid state contamination.
+- Read snapshot before targeting — ARIA refs are more stable than guessing CSS selectors.
+
+## Element Targeting Priority
+
+1. **\`ref\`** (e.g., \`@F12\`) — From read(snapshot) ARIA tree. Most reliable.
+2. **\`selector\`** (e.g., \`input[name='q']\`) — Playwright CSS/attribute selector. Precise.
+3. **\`element** (e.g., \`'Submit'\`) — Text matching via text= locator. Picks first DOM match regardless of visibility. Fragile for complex widgets. Last resort.
+
+Always read(snapshot) first to get refs before interacting.
+
+## Script Mode (Imperative)
+
+Direct sequential browser() calls for one-off tasks and debugging:
+
+\`\`\`
+// Open -> Read -> Act -> Read loop
+browser({ action: 'open', url, mode: 'headless' })
+browser({ action: 'read', pageId })
+browser({ action: 'act', pageId, kind: 'click', ref: '@login-button' })
+browser({ action: 'read', pageId })  // verify state changed
+\`\`\`
+
+**Network Intelligence pattern:**
+\`\`\`
+browser({ action: 'network', pageId, subAction: 'enable', filter: { resourceTypes: ['xhr', 'fetch'] } })
+// ... navigate/interact ...
+browser({ action: 'network', pageId, subAction: 'get' })
+browser({ action: 'network', pageId, subAction: 'export-har' })
+\`\`\`
+
+**Console capture:**
+\`\`\`
+browser({ action: 'console', pageId, consoleSubAction: 'enable' })
+// ... trigger page actions ...
+browser({ action: 'console', pageId, consoleSubAction: 'get', level: 'error' })
+\`\`\`
+
+## Session Management
+
+- Cookie read/write requires explicit \`confirm: true\`.
+- Prefer \`fetch\` action over cookie export when the goal is an authenticated API call — reuse page cookies/session directly.
+- Use labels for long flows; close the page when the task ends.
+- Never store extracted cookies in code, commits, or logs. Warn user cookies are auth tokens that expire.
+
+## Local File Preview
+
+The browser tool blocks \`file:///\` URLs. Serve local HTML first:
+
+\`\`\`
+// 1. Start local server
+// Terminal: npx -y serve <directory> -l <port>
+// 2. Open in browser
+browser({ action: 'open', url: 'http://localhost:<port>/my-file.html', mode: 'ui' })
+// 3. Read content or screenshot
+browser({ action: 'read', pageId, readMode: 'markdown' })
+// 4. Clean up — kill the server terminal when done
+\`\`\`
+
+## High-Value Patterns
+
+- **Dialogs:** Register \`dialog\` before the action that triggers it. Prompt dialogs also need \`promptText\`.
+- **Labels:** Assign a \`label\` on open for long-running flows.
+- **Batch:** Use \`batch\` to reduce round-trips, but only when \`pageId\` is already known.
+- **Diff:** First call establishes baseline, second call shows the delta.
+- **Security:** Never send passwords via \`act({ kind: 'type' })\`. Ask user to type credentials manually. Never use \`file:///\` URLs.
 `}];export{e as default};