@haposoft/cafekit 0.16.7 → 0.18.1

package/src/claude/settings/settings.json

@@ -14,10 +14,6 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/session.cjs\""
           },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/docs-sync.cjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state.cjs\""
@@ -58,18 +54,9 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/rules.cjs\""
           },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-authority.cjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-state.cjs\""
-          },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/usage.cjs\"",
-            "timeout": 30
           }
         ]
       }
@@ -87,15 +74,6 @@
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/inspect-block.cjs\""
           }
         ]
-      },
-      {
-        "matcher": "Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/task-scaffold-guard.cjs\""
-          }
-        ]
       }
     ],
     "PostToolUse": [
@@ -113,8 +91,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/usage.cjs\"",
-            "timeout": 30
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-state.cjs\""
           }
         ]
       }
@@ -126,10 +103,6 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-gate.cjs\""
           },
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-authority.cjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state.cjs\""
@@ -140,10 +113,6 @@
     "SubagentStop": [
       {
         "hooks": [
-          {
-            "type": "command",
-            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/semantic-review-authority.cjs\""
-          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state.cjs\""

package/src/claude/skills/agent-browser/SKILL.md

@@ -236,7 +236,7 @@ agent-browser snapshot -i
 agent-browser fill @e1 "user@example.com"
 agent-browser fill @e2 "password123"
 agent-browser click @e3  # Submit button
-agent-browser wait url "/dashboard"
+agent-browser wait --url "/dashboard"
 ```
 
 ### State Persistence (Auth)

package/src/claude/skills/{question → ask}/SKILL.md

@@ -24,6 +24,7 @@ metadata:
 
 <ANSWER-ONLY-GATE>
 Do NOT implement, scaffold, refactor, modify files, generate full specs, or make final architecture decisions.
+This holds even when the question itself asks for a change ("and fix it", "rồi đổi luôn cho tôi"): answer the cause with evidence, edit nothing, and point to `cf:fix` for the change, or to `cf:debug` when the cause is not yet known.
 The output is an answer, evidence, confidence, and a follow-up only when needed.
 </ANSWER-ONLY-GATE>
 
@@ -43,10 +44,7 @@ Do not use it when:
 - The user asks to implement, fix, debug, test, commit, or publish.
 - The user wants ideation/tradeoff exploration; use `cf:brainstorm`.
 - The user wants a formal spec; use `cf:specs`.
-- The user wants full legacy documentation reconstruction: use
-  `cf:docs --reconstruct` when the optional document bundle is installed;
-  otherwise use `cf:scout` plus source evidence, or explain how to install the
-  bundle with `npx @haposoft/cafekit --with-document-skills`.
+- The user wants full legacy documentation reconstruction: use `cf:docs --reconstruct` when the optional document bundle is installed; otherwise use `cf:scout` plus source evidence, or explain how to install the bundle with `npx @haposoft/cafekit --with-document-skills`.
 - The user wants root-cause diagnosis for a failure; use `cf:debug`.
 
 ## Modes
@@ -60,50 +58,19 @@ Do not use it when:
 
 If modes conflict, prefer the most explicit source mode in this order: `--both`, `--repo`, `--web`, then default. Apply `--brief` or `--deep` as output depth modifiers.
 
-## Workflow
+## Standards
 
-### 1. Classify The Question
+**Unclear questions.** If `unclear`, ask one focused follow-up with the minimum choices needed.
 
-Pick one primary answer type:
+**Repo evidence priority:** `README.md`, `AGENTS.md`, `CLAUDE.md`; then relevant `docs/`, `specs/`, `.claude/`; then source files, tests, scripts, package manifests, config files; git history only when the question asks about changes or provenance. Use focused search (`rg`, targeted file reads) instead of broad scans. Use `cf:scout` when the user asks where something lives or the source surface is unclear.
 
-```text
-source-code behavior | config/version | spec/docs consistency | dependency/library | workflow/process | external/current knowledge | unclear
-```
-
-If `unclear`, ask one focused follow-up with the minimum choices needed.
-
-### 2. Gather Evidence
-
-Repo evidence priority:
-1. `README.md`, `AGENTS.md`, `CLAUDE.md`
-2. relevant `docs/`, `specs/`, `.claude/`
-3. source files, tests, scripts, package manifests, config files
-4. git history only when the question asks about changes or provenance
-
-Use focused search (`rg`, targeted file reads) instead of broad scans. Use `cf:scout` when the user asks where something lives or the source surface is unclear.
-
-External evidence:
-- Use external/current docs when repo evidence is absent, stale, or not authoritative.
-- Prefer official docs, standards, source repositories, or primary vendor docs.
-- State clearly when an answer is inferred from external docs rather than confirmed in the repo.
+**External evidence.** Use external/current docs when repo evidence is absent, stale, or not authoritative. Prefer official docs, standards, source repositories, or primary vendor docs. State clearly when an answer is inferred from external docs rather than confirmed in the repo.
 
-### 3. Decide Whether To Answer Or Ask Back
+**Broad questions.** When the question names no aspect or target — "Is this system stable?", "Is the code good?" — ask back before gathering evidence, offering 2-3 aspects (for example code and tests, runtime reliability, deploy readiness), even when a cautious answer would be possible.
 
-Answer directly when at least one of these is true:
-- repo evidence answers the question,
-- external/current evidence answers the non-project part,
-- a cautious answer can separate known facts from inference.
+**Answer or ask back.** Answer directly when at least one of these is true: repo evidence answers the question, external/current evidence answers the non-project part, or a cautious answer can separate known facts from inference. Ask back when the target system/module is not named and multiple targets are plausible, the needed file/source is blocked or private, the question requires business/domain judgment not present in source, the answer would require guessing customer intent, or the question bundles multiple unrelated topics. Ask only one follow-up question. Include 2-3 concrete options if helpful.
 
-Ask back when:
-- the target system/module is not named and multiple targets are plausible,
-- the needed file/source is blocked or private,
-- the question requires business/domain judgment not present in source,
-- the answer would require guessing customer intent,
-- the question bundles multiple unrelated topics.
-
-Ask only one follow-up question. Include 2-3 concrete options if helpful.
-
-### 4. Output Contract
+## Output Contract
 
 Default output:
 
@@ -135,36 +102,3 @@ Use `templates/question.md` when the user asks to save or document the answer.
 - Keep the answer proportional: concise for simple questions, structured for complex ones.
 - If external sources were used, include source links or names.
 - If no evidence exists, say "no evidence found in the current source" and explain what was checked.
-
-## Examples
-
-### Source Question
-
-```text
-/cf:ask "In this system, which file does cafekit use to toggle skill routing?"
-```
-
-Expected behavior:
-- read runtime/config/install files,
-- answer with exact config file and relevant keys,
-- say whether it is runtime-driven or hard-coded.
-
-### Mixed Source + Web Question
-
-```text
-/cf:ask "Which React version does this project use, and does that version still match current best practice?" --both
-```
-
-Expected behavior:
-- read `package.json` or lockfile,
-- check current React docs/release info if needed,
-- separate local version from external recommendation.
-
-### Ask Back
-
-```text
-/cf:ask "Is this system stable?"
-```
-
-Expected behavior:
-- ask one narrowing question because "stable" could mean architecture, security, performance, UX, tests, or deploy readiness.

package/src/claude/skills/brainstorm/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: cf:brainstorm
-description: "Turn unresolved product or architecture intent into a bounded decision contract, with proportional routing, evidence, and safe handoff."
+description: "Shape an unsettled piece of work into a decided one before anyone builds it. Use when the outcome is already agreed but two or more approaches would each satisfy it with meaningfully different consequences — setup cost, migration, failure behaviour, who carries the work afterwards; use it too when an idea still wants exploring, or when only one approach is viable but the contract and the candidate design still need a decision. It weighs viable approaches against a bounded contract of Outcome, Constraints, Non-goals and Acceptance, records what was chosen and what was rejected and why, and stops there; it writes no code and carries nothing onward by itself. Skip it for a direct factual answer, skip it for a bug or failure that still needs its root cause, and skip it when the request needs a plan and its tasks rather than a choice between designs."
 user-invocable: true
-when_to_use: "Use when material product, scope, or architecture choices remain; skip direct factual answers and already-concrete Specs work."
+when_to_use: "Use when an outcome is agreed and designs compete, an idea wants exploring, or a candidate needs a decision; skip direct factual answers, undiagnosed bugs, and requests that need a plan and its tasks."
 category: utilities
 keywords: [ideation, tradeoffs, decisions, scope]
 argument-hint: "<idea_or_problem>"
@@ -12,9 +12,7 @@ metadata:
 ---
 # Brainstorm — proportional pre-delivery design
 
-Turn unresolved intent into a bounded contract without turning clear work into
-an interview. `cf:brainstorm` owns the workflow; `brainstormer` is an optional
-specialist for real architectural trade-offs.
+Turn unresolved intent into a bounded contract without turning clear work into an interview. `cf:brainstorm` owns the workflow; `brainstormer` is an optional specialist for real architectural trade-offs.
 
 <HARD-GATE>
 Brainstorm never writes implementation, invokes Develop, or treats approval as
@@ -24,64 +22,32 @@ for a new explicit `cf:specs` invocation; it never starts Specs implicitly.
 
 ## Control flags
 
-Parse controls only from the leading consecutive token segment. Accept
-`--deep`, `--visual`, and `--advice` in any order, each at most once. `--` ends
-the control segment. After it or the first content token, every token is user
-content. An unknown or duplicate `--*` inside the leading segment returns usage
-and performs no scout, question, tool call, write, or workflow action.
+Parse controls only from the leading consecutive token segment. Accept `--deep`, `--visual`, and `--advice` in any order, each at most once. `--` ends the control segment. After it or the first content token, every token is user content. An unknown or duplicate `--*` inside the leading segment returns usage and performs no scout, question, tool call, write, or workflow action.
 
-Parsing identifies controls but does not apply them. Route Direct first, then
-apply controls only to requests that remain in Brainstorm. `--deep` may raise
-non-direct analysis depth but never lower a gate; `--visual` changes presentation
-only; and no control grants persistence, approval, dispatch, or implementation
-authority. Use `-- --dry-run` when literal flag-like content leads the prompt.
+Parsing identifies controls but does not apply them. Route Direct first, then apply controls only to requests that remain in Brainstorm. `--deep` may raise non-direct analysis depth but never lower a gate; `--visual` changes presentation only; and no control grants persistence, approval, dispatch, or implementation authority. Use `-- --dry-run` when literal flag-like content leads the prompt.
 
 ## Front-door routing — before scout or questions
 
 Classify intent first. This routing never waives safety or permission rules.
 
-1. **Direct request:** for a factual answer, a specific command, or an explicitly
-   different workflow, leave Brainstorm before scout, questions, approval, or
-   persistence. Read-only product or architecture exploration is not direct merely
-   because it writes no files.
-2. **Hydrate the contract, then keep routing:** for every request that remains,
-   reuse accepted Outcome, Constraints, Non-goals, and Acceptance field by field
-   only when current user text or an approved artifact binds them to the same
-   target and revision. Preserve current non-conflicting fields; treat missing,
-   stale, or conflicting fields as gaps. Never infer approval. Hydration is not a
-   terminal route; continue to exactly one intent route below.
-3. **Bug or failure:** before diagnosis, capture the repaired-behavior Outcome,
-   Constraints, Non-goals, and Acceptance evidence. Then use `cf:debug` until
-   root cause is evidenced. Do not brainstorm fixes from a symptom. If at least
-   two cause-aligned remedies remain, compare 2–3 here. Hand off to `cf:fix`
-   only when the user explicitly requested a fix; diagnosis-only work returns the
-   root-cause report and stops.
-4. **Non-bug exploration only:** inspect enough evidence, give a chat
-   recommendation, and stop. Do not request design approval, persist a report, or
-   invoke another workflow without a new explicit request.
-5. **Feature or documentation delivery:** continue through the design workflow.
+1. **Direct request:** for a factual answer, a specific command, or an explicitly different workflow, leave Brainstorm before scout, questions, approval, or persistence. Read-only product or architecture exploration is not direct merely because it writes no files.
+2. **Plan-and-tasks request:** when the user asks for a plan, a task list, or work split into tasks rather than a choice between designs, leave Brainstorm before scout or questions: say in one or two sentences that Specs owns plans and tasks, and ask the user to invoke `cf:specs` in a new request. Do not interview, compare options, write the list, or start Specs. Open this answer with `Route: plan-and-tasks · Depth: Standard`.
+3. **Hydrate the contract, then keep routing:** for every request that remains, reuse accepted Outcome, Constraints, Non-goals, and Acceptance field by field only when current user text or an approved artifact binds them to the same target and revision. Preserve current non-conflicting fields; treat missing, stale, or conflicting fields as gaps. Never infer approval. Hydration is not a terminal route; continue to exactly one intent route below.
+4. **Bug or failure:** before diagnosis, capture the repaired-behavior Outcome, Constraints, Non-goals, and Acceptance evidence. Then use `cf:debug` until root cause is evidenced. Do not brainstorm fixes from a symptom. If at least two cause-aligned remedies remain, compare 2–3 here. Hand off to `cf:fix` only when the user explicitly requested a fix; diagnosis-only work returns the root-cause report and stops.
+5. **Non-bug exploration only:** inspect enough evidence, give a chat recommendation, and stop. Do not request design approval, persist a report, or invoke another workflow without a new explicit request.
+6. **Feature or documentation delivery:** continue through the design workflow.
 
 ## Adaptive analysis depth
 
-For every non-direct request, choose the smallest adequate depth from current
-evidence and material risk:
+For every non-direct request, choose the smallest adequate depth from current evidence and material risk:
 
 - **Standard:** bounded single-surface work with no material risk signal.
-- **Deep:** critical safety/security risk; public compatibility or data migration;
-  cross-service state or concurrency; costly or irreversible rollback; or
-  unresolved feasibility at a material boundary.
-- With no Deep signal, use Standard. `--deep` raises Standard to Deep. If three
-  or more subsystems are independently deliverable, split them instead of using
-  Deep as a monolithic substitute.
-
-Deep is selective, not a checklist. Apply a lens only when its trigger is
-present and otherwise record `skipped: <reason>`: feasibility for an unresolved
-material boundary; stakeholders for externally affected roles; system boundaries
-for cross-component state; failure isolation for partial or cascading failure
-across boundaries; reversibility and recovery for costly or irreversible failure;
-operability for runtime ownership; migration/rollback for data or public
-compatibility; testability for a material proof gap; and second-order effects
-for downstream behavior or incentives.
+- **Deep:** critical safety/security risk; public compatibility or data migration; cross-service state or concurrency; costly or irreversible rollback; or unresolved feasibility at a material boundary.
+- With no Deep signal, use Standard. `--deep` raises Standard to Deep. If three or more subsystems are independently deliverable, split them instead of using Deep as a monolithic substitute.
+
+Open every non-direct answer with one line naming its route and depth, for example `Route: feature delivery · Depth: Standard`. When the answer is a `cf:debug` report, that report's heading comes first and this line follows it.
+
+Deep is selective, not a checklist. Apply a lens only when its trigger is present and otherwise record `skipped: <reason>`: feasibility for an unresolved material boundary; stakeholders for externally affected roles; system boundaries for cross-component state; failure isolation for partial or cascading failure across boundaries; reversibility and recovery for costly or irreversible failure; operability for runtime ownership; migration/rollback for data or public compatibility; testability for a material proof gap; and second-order effects for downstream behavior or incentives.
 
 ## Contract and evidence
 
@@ -92,118 +58,64 @@ For feature/docs delivery and every bug/failure, resolve four user-owned fields:
 - **Non-goals:** nearby work excluded from this delivery.
 - **Acceptance:** observable evidence that proves completion.
 
-After front-door routing, run `cf:scout` or a narrow equivalent before
-technical design. Inspect relevant modules, patterns, docs/plans, contracts, and
-runtime constraints; summarize only useful findings in 3–6 bullets.
+After front-door routing, run `cf:scout` or a narrow equivalent before technical design. Inspect relevant modules, patterns, docs/plans, contracts, and runtime constraints; summarize only useful findings in 3–6 bullets.
 
-For supplied images, video, PDFs, or mockups, use `cf:ai-multimodal` when the
-optional document bundle is installed; otherwise use the runtime's available
-multimodal capability or report the evidence gap. Add a diagram only when it
-clarifies a material choice or flow.
+For supplied images, video, PDFs, or mockups, use `cf:ai-multimodal` when the optional document bundle is installed; otherwise use the runtime's available multimodal capability or report the evidence gap. Add a diagram only when it clarifies a material choice or flow.
 
-Derive technical touchpoints from repository evidence. Ask the user about a
-touchpoint only when its ownership or scope boundary is a product decision that
-cannot be discovered. Keep intent separate from current-state evidence.
+Derive technical touchpoints from repository evidence. Ask the user about a touchpoint only when its ownership or scope boundary is a product decision that cannot be discovered. Keep intent separate from current-state evidence.
 
-On every route, keep feasibility (`confirmed | plausible | unknown |
-infeasible`), confidence (`high | medium | low`), and disposition (`chosen |
-rejected | deferred`) separate and cite evidence or basis. Missing evidence
-forces feasibility `unknown` and confidence `low`. A numeric estimate requires
-range, unit, basis, evidence, and assumptions; otherwise report `unknown`.
+On every route, keep feasibility (`confirmed | plausible | unknown | infeasible`), confidence (`high | medium | low`), and disposition (`chosen | rejected | deferred`) separate and cite evidence or basis. Missing evidence forces feasibility `unknown` and confidence `low`. A numeric estimate requires range, unit, basis, evidence, and assumptions; otherwise report `unknown`.
 
-If the request spans three or more independently deliverable subsystems, split
-it. A subsystem is independent only when its outcome, boundary, and verification
-or deployment path can move through the lifecycle separately.
+If the request spans three or more independently deliverable subsystems, split it. A subsystem is independent only when its outcome, boundary, and verification or deployment path can move through the lifecycle separately.
 
 ## Discovery Question Framework
 
-Load `references/question-framework.md` before the first discovery question.
-Generate questions from scout evidence, user intent, contract gaps, applicable
-domain guidance, and risk surfaces. Never ask the user for a technical fact that
-code, docs, or trusted current research can answer.
+Load `references/question-framework.md` before the first discovery question. Generate questions from scout evidence, user intent, contract gaps, applicable domain guidance, and risk surfaces. Never ask the user for a technical fact that code, docs, or trusted current research can answer.
+
+Use the runtime's native structured user-input tool when available. Ask one highest-impact question by default; batch at most three independent questions only when none depends on an earlier answer. Record confirmed decisions, assumptions, and open questions separately in the decision register.
 
-Use the runtime's native structured user-input tool when available. Ask one
-highest-impact question by default; batch at most three independent questions
-only when none depends on an earlier answer. Record confirmed decisions,
-assumptions, and open questions separately in the decision register.
+Stop asking when remaining details have safe implementation defaults. Do not force questions merely to consume a budget.
 
-Stop asking when remaining details have safe implementation defaults. Do not
-force questions merely to consume a budget.
+When the user delegates a choice ("pick whichever is fastest"), choose from the recorded evidence, say that you chose on the user's behalf and why, record it in the Decision register as a delegated choice, and ask only for the approvals its route requires.
 
 ## Options and specialist use
 
-A material design choice exists only when at least two viable paths would satisfy
-the contract with meaningfully different consequences.
+A material design choice exists only when at least two viable paths would satisfy the contract with meaningfully different consequences.
 
-- For a material choice, compare 2–3 mechanically distinct viable approaches by
-  setup cost, runtime complexity, maintenance, UX/DX, compatibility/migration,
-  risk, and time-to-value.
-- With one viable path, present it and explain briefly why alternatives would be
-  artificial or fail the contract. Never create strawman options.
+- For a material choice, compare 2–3 mechanically distinct viable approaches by setup cost, runtime complexity, maintenance, UX/DX, compatibility/migration, risk, and time-to-value.
+- With one viable path, present it and explain briefly why alternatives would be artificial or fail the contract. Never create strawman options.
 - Recommend the smallest path that satisfies the contract.
 
-Call `brainstormer` only for a material architectural choice that benefits from
-deeper pressure-testing. Use researcher only for current external facts the
-repository cannot establish. The controller remains responsible for questions,
-approval, persistence, and handoff.
+Unless the user names `brainstormer`, call it only for a material architectural choice that benefits from deeper pressure-testing. When the user names `brainstormer`, call it; tell it which route applies; the routes are feature delivery; an explicitly authorized fix; diagnosis-only bug work; non-bug exploration. Pass the contract with it; it may return a single-path conclusion. Use researcher only for current external facts the repository cannot establish. The controller remains responsible for questions, approval, persistence, and handoff.
 
-`--visual` may present inline Mermaid or ASCII for any non-direct analysis and
-falls back to equivalent text when rendering is unavailable. Durable or external
-rendering requires explicit user authority before invocation. `--advice` invokes
-`brainstormer` only after the material-choice gate; if advice is unavailable or
-fails, label it unavailable and continue with controller analysis. Before an
-external visual tool or adviser handoff, minimize context and redact secrets,
-credentials, private keys, access tokens, and unnecessary PII. Neither overlay
-writes, approves, persists, dispatches, or completes work.
+`--visual` may present inline Mermaid or ASCII for any non-direct analysis and falls back to equivalent text when rendering is unavailable. Durable or external rendering requires explicit user authority before invocation. `--advice` invokes `brainstormer` only after the material-choice gate; if advice is unavailable or fails, label it unavailable and continue with controller analysis. Before an external visual tool or adviser handoff, minimize context and redact secrets, credentials, private keys, access tokens, and unnecessary PII. Neither overlay writes, approves, persists, dispatches, or completes work.
 
 ## Delivery design and approval
 
 For feature or documentation delivery:
 
-1. Draft one coherent candidate scaled to the work: architecture, data flow,
-   interfaces/UX, error behavior, verification, and rollout only when material.
+1. Draft one coherent candidate scaled to the work: architecture, data flow, interfaces/UX, error behavior, verification, and rollout only when material.
 2. Run the internal 4-point review before presentation:
    - remove placeholders and vague instructions;
    - reconcile contradictory behavior;
    - remove scope creep;
    - make observable behavior and proof concrete.
 3. Present the reviewed candidate.
-4. Before final approval, require a separate explicit section decision when
-   the design changes auth/secrets/privacy, destructive or irreversible behavior
-   or data-loss risk, money/privilege/safety, or production-state mutation.
-5. After critical section decisions and revisions, request one final approval by
-   default.
+4. Before final approval, require a separate explicit section decision when the design changes auth/secrets/privacy, destructive or irreversible behavior or data-loss risk, money/privilege/safety, or production-state mutation.
+5. After critical section decisions and revisions, request one final approval by default.
 
-Revise material disagreement before handoff. An already accepted, current
-contract is not re-approved unless new evidence changes it.
+Revise material disagreement before handoff. An already accepted, current contract is not re-approved unless new evidence changes it.
 
 ## Persistence and handoff
 
-Persist only approved decisions and semantics, only with user authority, and
-only when they must survive the session or feed Specs. Use the repository's
-configured report path and naming convention. Do not create a report merely to
-satisfy this skill. Before writing, redact live secrets, credentials, private
-keys, access tokens, and unnecessary PII; preserve exact approved meaning with a
-safe placeholder and ownership reference instead of copying the sensitive value.
-
-The default handoff stays in chat Markdown. Use these exact headings:
-`Target and evidence freshness`, `Outcome`, `Constraints`, `Non-goals`,
-`Acceptance`, `Touchpoints`, `Direction and alternatives`, `Relevant impacts
-and failure behavior`, `Rollout and recovery`, `Proof mapping`, `Decision
-register`, `Assumptions`, and `Open questions`. The first section records target
-identity, current source revision and worktree state or `[UNVERIFIED]`, an
-evidence-as-of value, and what change invalidates the brief. Durable file output
-requires explicit authority and creates no readiness, approval, proof, or
-execution state.
-
-- Feature/docs delivery: provide the approved summary and ask the user to invoke
-  `cf:specs` explicitly in a new request.
+Persist only approved decisions and semantics, only with user authority, and only when they must survive the session or feed Specs. Use the repository's configured report path and naming convention. Do not create a report merely to satisfy this skill. Before writing, redact live secrets, credentials, private keys, access tokens, and unnecessary PII; preserve exact approved meaning with a safe placeholder and ownership reference instead of copying the sensitive value.
+
+The default handoff stays in chat Markdown. Use these exact headings: `Target and evidence freshness`, `Outcome`, `Constraints`, `Non-goals`, `Acceptance`, `Touchpoints`, `Direction and alternatives`, `Relevant impacts and failure behavior`, `Rollout and recovery`, `Proof mapping`, `Decision register`, `Assumptions`, and `Open questions`. The first section records target identity, current source revision and worktree state or `[UNVERIFIED]`, an evidence-as-of value, and what change invalidates the brief. Durable file output requires explicit authority and creates no readiness, approval, proof, or execution state.
+
+- Feature/docs delivery: provide the approved summary and ask the user to invoke `cf:specs` explicitly in a new request.
 - Diagnosed bug: follow the fix-authority rule in front-door routing.
 - Non-bug exploration: recommendation already returned in chat; stop.
 
 ## Completion bar
 
-Brainstorm is complete when the selected route is explicit, current evidence is
-separated from intent, every material user-owned gap is resolved or named, and
-the route-specific output has been returned without unauthorized persistence or
-implementation. Never claim live behavior from this written contract alone.
+Brainstorm is complete when the selected route is explicit, current evidence is separated from intent, every material user-owned gap is resolved or named, and the route-specific output has been returned without unauthorized persistence or implementation. Never claim live behavior from this written contract alone.

package/src/claude/skills/chrome-devtools/SKILL.md

@@ -52,8 +52,7 @@ Browser visibility is resolved automatically by `resolveHeadless()` in `lib/brow
 
 Override with `--headless true` or `--headless false` on any script.
 
-- Run multiple scripts/sessions in parallel to simulate real user interactions.
-- Run multiple scripts/sessions in parallel to simulate different device types (mobile, tablet, desktop).
+Scripts share one browser and its first tab through `.browser-session.json`, so run them one at a time; parallel runs drive the same page.
 
 ## ARIA Snapshot (Element Discovery)
 
@@ -104,7 +103,6 @@ node "$SKILL_DIR/aria-snapshot.js" --url https://example.com --output ./packages
 
 ### Interact by Ref
 
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
 Use `select-ref.js` to interact with elements by their ref:
 
 ```bash
@@ -129,7 +127,6 @@ node "$SKILL_DIR/select-ref.js" --ref e5 --action hover
 
 ### Store Snapshots
 
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
 Store snapshots for analysis in `<project>/packages/spec/src/claude/chrome-devtools/snapshots/`:
 
 ```bash
@@ -162,7 +159,6 @@ node "$SKILL_DIR/aria-snapshot.js" --url https://example.com --output packages/s
 
 ## Local HTML Files
 
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
 **IMPORTANT**: Never browse local HTML files via `file://` protocol. Always serve via local server:
 **Why**: `file://` protocol blocks many browser features (CORS, ES modules, fetch API, service workers). Local server ensures proper HTTP behavior.
 
@@ -176,7 +172,7 @@ python -m http.server 3000 --directory ./dist &
 node "$SKILL_DIR/navigate.js" --url http://localhost:3000
 ```
 
-**Note**: when port 3000 is busy, find an available port with `lsof -i :3000` and use a different one.
+**Note**: when port 3000 is busy, find its owner with `lsof -i :3000`; stop it if you started it, otherwise ask the user. Do not move to another port (`rules/process-management.md`).
 
 ## Quick Start
 
@@ -207,11 +203,10 @@ chrome-devtools auto-detects Chrome at standard OS paths and uses it automatical
 
 ### Manual Configuration
 
-To force a specific Chrome installation, copy `.env.example` to `.env` and set `CHROME_EXECUTABLE_PATH`:
+To force a specific Chrome installation, export `CHROME_EXECUTABLE_PATH` (or `PUPPETEER_EXECUTABLE_PATH`) in the shell that runs the scripts; they read the environment, not a `.env` file:
 
 ```bash
-cp "$SKILL_DIR/.env.example" "$SKILL_DIR/.env"
-# Edit .env and set CHROME_EXECUTABLE_PATH to your Chrome executable
+export CHROME_EXECUTABLE_PATH="/path/to/chrome"
 ```
 
 ### Skip Chromium Download
@@ -249,7 +244,6 @@ node "$SKILL_DIR/navigate.js" --url about:blank --close true
 
 ## Available Scripts
 
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
 All in `packages/spec/src/claude/skills/chrome-devtools/scripts/`:
 
 | Script | Purpose |
@@ -281,15 +275,14 @@ All in `packages/spec/src/claude/skills/chrome-devtools/scripts/`:
 
 ## Writing Custom Test Scripts
 
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
-For complex automation, write scripts to `<project>/packages/spec/src/claude/chrome-devtools/tmp/`:
+For complex automation, write scripts to `$SKILL_DIR/../tmp/` (beside `scripts/`, so the `../scripts/lib/browser.js` import resolves):
 
 ```bash
 # Create tmp directory for test scripts
-mkdir -p $SKILL_DIR/packages/spec/src/claude/chrome-devtools/tmp
+mkdir -p "$SKILL_DIR/../tmp"
 
 # Write a test script
-cat > $SKILL_DIR/packages/spec/src/claude/chrome-devtools/tmp/login-test.js << 'EOF'
+cat > "$SKILL_DIR/../tmp/login-test.js" << 'EOF'
 import { getBrowser, getPage, disconnectBrowser, outputJSON } from '../scripts/lib/browser.js';
 
 async function loginTest() {
@@ -315,7 +308,7 @@ loginTest();
 EOF
 
 # Run the test
-node $SKILL_DIR/packages/spec/src/claude/chrome-devtools/tmp/login-test.js
+node "$SKILL_DIR/../tmp/login-test.js"
 ```
 
 **Key principles for custom scripts**:
@@ -327,11 +320,7 @@ node $SKILL_DIR/packages/spec/src/claude/chrome-devtools/tmp/login-test.js
 
 ## Screenshots
 
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
-
-**IMPORTANT:** Store browser artifacts in a project-local screenshots or reports folder and include exact output paths in the final report.
-
-Store screenshots for analysis in `<project>/packages/spec/src/claude/chrome-devtools/screenshots/`:
+Store screenshots in `<project>/packages/spec/src/claude/chrome-devtools/screenshots/` and give their exact output paths in the final report:
 
 ```bash
 # Basic screenshot
@@ -356,15 +345,13 @@ node "$SKILL_DIR/screenshot.js" --url https://example.com --output ./packages/sp
 node "$SKILL_DIR/screenshot.js" --url https://example.com --output ./packages/spec/src/claude/chrome-devtools/screenshots/page.png --max-size 3
 
 # Disable compression
-node "$SKILL_DIR/screenshot.js" --url https://example.com --output ./packages/spec/src/claude/chrome-devtools/screenshots/page.png --no-compress
+node "$SKILL_DIR/screenshot.js" --url https://example.com --output ./packages/spec/src/claude/chrome-devtools/screenshots/page.png --no-compress true
 ```
 
 Store screenshots for analysis in `<project>/packages/spec/src/claude/chrome-devtools/screenshots/`.
 
 ## Console Log Collection & Analysis
 
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
-
 ### Capture Logs
 
 ```bash
@@ -407,7 +394,6 @@ node "$SKILL_DIR/console.js" --url https://example.com --types error --duration
 
 ## Finding Elements
 
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
 Use `snapshot.js` to discover selectors before interacting:
 
 ```bash
@@ -423,12 +409,11 @@ node "$SKILL_DIR/snapshot.js" --url https://example.com | jq '.elements[] | sele
 
 ## Error Recovery
 
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
 If script fails:
 
 ```bash
 # 1. Capture current state (without navigating to preserve state)
-node "$SKILL_DIR/screenshot.js" --output ./packages/spec/src/claude/skills/chrome-devtools/screenshots/debug.png
+node "$SKILL_DIR/screenshot.js" --output ./packages/spec/src/claude/chrome-devtools/screenshots/debug.png
 
 # 2. Get console errors
 node "$SKILL_DIR/console.js" --url about:blank --types error --duration 1000
@@ -469,22 +454,20 @@ node "$SKILL_DIR/performance.js" --url https://example.com | jq '.vitals'
 All scripts support:
 - `--headless true/false` - Override auto-detected headless mode (default: auto by OS)
 - `--close true` - Close browser completely (default: stay running)
-- `--timeout 30000` - Set timeout (ms)
-- `--wait-until networkidle2` - Wait strategy
+- `--wait-until networkidle2` - Wait strategy when the script loads `--url`
+- `--timeout <ms>` - read by the scripts that load a page or wait for one (`navigate.js`, `click.js`, `fill.js`, `connect-chrome.js`, `import-cookies.js`, `inject-auth.js`)
 
 `navigate.js` additionally supports:
 - `--wait-for-login <pattern>` - Interactive login: open headed, wait for URL regex match
 - `--login-timeout <ms>` - Max wait for login completion (default: 300000 = 5 min)
 
 ## Troubleshooting
-Skills can exist in **project-scope** or **user-scope**. Priority: project-scope > user-scope.
-
 | Error | Solution |
 |-------|----------|
 | `Cannot find package 'puppeteer'` | Run `npm install` in scripts directory |
 | `libnss3.so` missing (Linux) | Run `./install-deps.sh` |
 | Element not found | Use `snapshot.js` to find correct selector |
-| Script hangs | Use `--timeout 60000` or `--wait-until load` |
+| Script hangs | Use `--wait-until load`, or `--timeout 60000` on a script that reads it |
 | Screenshot >5MB | Auto-compressed; use `--max-size 3` for lower |
 | Session stale | Delete `.browser-session.json` and retry |