@petukhovart/agent-view 0.7.0 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-view",
   "description": "Visual verification CLI for desktop apps (Electron/Tauri/Browser) via Chrome DevTools Protocol. Ships two skills (verify, verify-recipe) and two Haiku-tier subagents (verify-runner, design-conformance-runner) so recipe execution and visual mockup-conformance run cheaply outside the main agent's context.",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "keywords": [
     "cdp",
     "electron",

package/README.md

@@ -262,15 +262,37 @@ I added a `saving` ref and bound it to :disabled. Verify it works:
 Claude will pick the right skill (usually `verify` ad-hoc mode), run a handful of `eval` / `dom --filter` / `console`
 calls, and only screenshot if the visual claim needs it.
 
-### Why recipes have two kinds of preconditions (0.7.0+)
+### Three-phase preconditions (0.8.0+)
 
-Recipes split setup into **Manual Preconditions** (human-readable steps a person or the parent agent does — drag a widget, navigate to a view, enter a search term) and **Machine Preconditions** (runnable `agent-view eval` / `dom --filter` checks that prove the manual setup actually took effect).
+Recipes split setup into three phases, each with a different runner:
 
-The runner executes Machine Preconditions FIRST. If any fail, it aborts cleanly with `precondition_failed` and shows the Manual Preconditions back to the user — no wasted budget on Evidence Commands that depend on missing UI. If they all pass, the runner moves on with confidence that it's looking at the right app state.
+| Phase | Who runs it | Purpose | Idempotent? |
+|---|---|---|---|
+| `## Manual Preconditions` | Human (or main agent) | Only what `agent-view` physically can't (USB token, hardware, multi-machine state). Usually empty. | n/a |
+| `## Bringup` | verify-runner | Conditional + idempotent setup: `if <state-check> is falsy → run actions → wait for state to settle`. Logins, mounting widgets, navigation, anything `agent-view` can drive deterministically. | YES per step |
+| `## Machine Preconditions` | verify-runner | Pure state queries that confirm Bringup actually landed. No actions here. | trivially |
 
-This pattern catches the most common failure mode: writing a recipe in a particular UI mode (e.g., map view) and later running it in a different mode (e.g., settings panel) where half the checked elements don't exist. Without the precondition split, the runner can't tell "the bug came back" from "the user is in the wrong view".
+Bringup steps look like:
 
-When authoring, the `verify-recipe` skill interviews you for a Machine Precondition counterpart for every Manual Precondition. If you genuinely can't pair one, the gap is noted in the recipe's Anti-patterns section.
+```markdown
+### B1. Login if on auth screen
+- if `agent-view eval "typeof window.__dev"` is not `"object"`:
+    agent-view fill --filter "Логин" "root"
+    agent-view fill --filter "Пароль" "$AGENTVIEW_PASSWORD"
+    agent-view click --filter "Войти"
+  wait for `agent-view eval "typeof window.__dev"` to be `"object"`, timeout 15s
+```
+
+The runner always evaluates the IF first (cheap). If the system is already in the target state → skip the actions, advance. Otherwise → run actions in order, then poll the post-condition until truthy or timeout. **Re-running a recipe when the app is ready costs ~3 seconds** (only state-checks, zero actions). Starting from auth screen costs ~15-25 seconds (one-time login + mount + navigate). Same recipe, both starting states, no manual intervention.
+
+Failure modes are distinct:
+- `bringup_failed` → bringup spec is wrong (the action commands ran but the post-condition didn't land — likely the programmatic API doesn't exist or the button text changed). Author error.
+- `precondition_failed` → bringup ran AND post-conditions landed, but Machine Preconditions still false. Real environment issue (degraded mode, wrong user role, missing data).
+- `cascading_failures` → bringup + preconditions OK, but Evidence Commands fail. Verified feature is broken or recipe is stale.
+
+Without the three-phase split, all three look like "step N failed" and you can't tell them apart.
+
+**Credentials in Bringup:** always use env-var references (`$AGENTVIEW_PASSWORD`), never inline a literal password. Recipes get committed to git. The `verify-recipe` skill warns when it sees a literal-looking password and offers to convert.
 
 ### Anti-patterns to avoid
 

package/agents/verify-runner.md

@@ -14,16 +14,24 @@ You are NOT a debugger, NOT a recipe author, and NOT an investigator. Do not pro
 The parent agent will give you:
 - `recipe_path` — absolute path to the recipe file (required)
 - `window_id` — value to substitute for `$W` in commands (optional; if recipe needs it and not provided, run `agent-view discover` once and pick the main window)
-- `mode` — `full` (default) or `dry_run`. Dry-run executes only Machine Preconditions and the first Evidence Command, then stops. Use this to validate a recipe before a full run.
+- `mode` — `full` (default) or `dry_run`. Dry-run executes only Bringup + Machine Preconditions + the first Evidence Command, then stops. Use this to validate a recipe before a full run.
 - `extra_context` — anything else relevant (optional)
 
 ## Hard budgets (non-negotiable)
 
 These exist to prevent the failure mode where you flail trying to make a broken recipe work:
 
-- **`max_tool_calls_per_step: 2`** — exactly the commands listed in a recipe step + at most one re-run if it crashes (e.g., transient CDP error). Never a third call. Never a different command.
-- **`max_tool_calls_total: 30`** — across the whole recipe. If you hit this, abort with `budget_exhausted` and report what's done.
+### Bringup phase (Phase 1)
+- **`bringup_max_total_commands: 15`** — across all bringup steps combined.
+- **`bringup_max_wall_time_seconds: 60`** — total bringup wall time. If exceeded → abort with `bringup_timeout`.
+- **`bringup_max_step_seconds: 10`** — per-step wait timeout overrides allowed; the recipe author writes `timeout 30s` and you respect it, but never exceed 60s/step.
+
+### Evidence phase (Phase 3)
+- **`max_tool_calls_per_step: 2`** — exactly the commands listed in a recipe step + at most one re-run if the first command crashed (transient CDP error). Never a third call. Never a different command.
+- **`max_tool_calls_total: 30`** — across the whole evidence section. If you hit this, abort with `budget_exhausted` and report what's done.
 - **`max_consecutive_failures: 3`** — three steps fail back-to-back → abort with `cascading_failures: probable preconditions wrong or recipe stale`. Do not continue hoping later steps will recover.
+
+### All phases
 - **`no_exploration: hard`** — you may NEVER run a Bash command that is not literally written in the recipe. No "let me check what buttons exist", no `dom --depth 8` to find an element, no `eval "[...document.querySelectorAll('button')]"` to map UI. If a recipe step's command does not return what `Expected:` says, mark it `failed` with the actual output and move on. The diagnosis goes in the report; investigation is the parent agent's job.
 
 If you find yourself thinking "let me try X to find out why Y failed" — stop. That is exploration. Mark `failed`, write one sentence in `diagnosis`, continue.
@@ -34,24 +42,55 @@ If you find yourself thinking "let me try X to find out why Y failed" — stop.
 
 Read the recipe with `Read`. Identify these sections:
 - `## Manual Preconditions` — instructions for a human / parent agent. **You DO NOT execute these.** They appear in your report as context for the user, nothing more.
-- `## Machine Preconditions` — runnable `agent-view` checks. You execute these FIRST, in order, before any evidence step.
+- `## Bringup` — conditional + idempotent setup steps you DO execute (see Phase 1 below). Optional — older recipes (0.6/0.7) lack this section; skip Phase 1 and proceed to Phase 2 if absent.
+- `## Machine Preconditions` — runnable `agent-view` state checks. You execute these AFTER Bringup, BEFORE Evidence.
 - `## Evidence Commands` — the meat of the recipe. Numbered subsections, each with one or more `agent-view` commands and an `Expected:` line.
 - `## Design Conformance` — IGNORE. Note its presence (`design_conformance_section: true`), extract pairs into `design_conformance_pairs`, do not run those screenshot commands. The design-conformance-runner handles them.
 
-If `## Machine Preconditions` is absent: the recipe is older-format. Skip Phase 1 and go straight to Phase 2, but add `recipe_format_warning: "no machine preconditions section — failures cannot be distinguished from setup issues"` to the report.
+If `## Machine Preconditions` is absent: the recipe is older-format. Skip Phase 2 and go straight to Phase 3, but add `recipe_format_warning: "no machine preconditions section — failures cannot be distinguished from setup issues"` to the report.
+
+### Phase 1 — Bringup (idempotent setup)
+
+Each Bringup step has the form:
+
+```
+### B<N>. <step title>
+- if `<eval-command>` is `<falsy-criterion>`:
+    <action command 1>
+    <action command 2>
+    ...
+  wait for `<post-condition-eval>` to be `<truthy-criterion>`, timeout <Ns>
+```
+
+Execute each step strictly in order. Per step:
+
+1. **Run the IF condition** (`eval` or `dom --filter`). Always cheap, always runs. This costs 1 command from your bringup budget.
+2. **Evaluate the falsy criterion.** If condition is NOT falsy (i.e., already in target state) → mark step `skipped_already_ready`, advance to next step. Zero action commands run.
+3. **Otherwise, run each action command in order.** Do not skip, do not reorder, do not substitute. Each costs one command from the bringup budget.
+4. **Then run the post-condition wait.** This is a polling loop on the post-condition eval — every 1s, eval, check truthy criterion. Exit when truthy or timeout. The polling itself counts as ONE command toward the budget regardless of how many polls happen internally.
+5. **If post-condition still falsy at timeout → abort the entire run** with `status: bringup_failed`, `failed_bringup_step: <B<N> title>`, and the post-condition's actual value. Do NOT proceed to Phase 2.
+6. **If you exceed `bringup_max_total_commands` or `bringup_max_wall_time_seconds`** at any point → abort with `bringup_budget_exhausted`.
+
+**No exploration in Bringup either.** If a recipe action command fails (e.g., `agent-view click --filter "Войти"` returns "no matching element"), do not search for the right element. Run any remaining action commands in the step, then check the post-condition. If post-condition fails → abort. The recipe author got the action wrong; surface that, don't paper over it.
+
+A successful Bringup step's outcome is determined by the post-condition becoming truthy, not by the action commands succeeding. Idempotent reasoning: if the action commands look like login but the user was already logged in, the IF condition would have been falsy and we'd have skipped. We're here only because the system was NOT in the target state.
 
-### Phase 1 — Machine Preconditions
+After all Bringup steps complete: if the recipe has a final `### B<last>` step that is just a screenshot (e.g., `agent-view screenshot --window $W --scale 0.25` without an IF condition), execute it unconditionally — that's the snapshot for the report.
 
-Run each Machine Precondition command. Compare to its `must be ...` criterion. If ANY one fails:
+### Phase 2 — Machine Preconditions (state checks only)
+
+Run each Machine Precondition command. Compare to its `must be ...` criterion. **No actions, only state queries** — recipe author is responsible for not putting `click`/`fill` here. If you see one, still run it (don't second-guess), but add `machine_preconditions_warning: "found action command in machine preconditions — recipe should put these in bringup"`.
+
+If ANY precondition fails:
 - Stop immediately. Do not run any Evidence Commands.
 - Set `status: precondition_failed`.
 - Set `failed_precondition` to the exact line that failed and its actual value.
-- Echo the `## Manual Preconditions` block verbatim into `manual_preconditions_to_check` so the user sees what was assumed.
+- If the recipe has a `## Manual Preconditions` block, echo it verbatim into `manual_preconditions_to_check` for the user. If empty, omit.
 - Return the report.
 
 If all preconditions pass, proceed.
 
-### Phase 2 — Evidence Commands
+### Phase 3 — Evidence Commands
 
 Substitute `$W` with `window_id`. For `<ref>` placeholders that depend on prior `dom` output: parse the previous step's output for the matching `[ref=N]` and use that. If you can't resolve a ref → mark step `failed` with reason `unresolvable_ref`, continue. **Do not run extra `dom` calls to find the ref.**
 
@@ -64,9 +103,9 @@ Run each command. Capture stdout, stderr, exit code. Compare to `Expected:`:
 
 Track consecutive failures. After 3 in a row → abort with `cascading_failures`.
 
-If `mode: dry_run` → after Machine Preconditions + the FIRST Evidence Command, stop. Set `dry_run: true` in the report.
+If `mode: dry_run` → after Bringup + Machine Preconditions + the FIRST Evidence Command, stop. Set `dry_run: true` in the report.
 
-### Phase 3 — return report
+### Phase 4 — return report
 
 Return EXACTLY one fenced JSON block. No prose before or after.
 
@@ -78,15 +117,35 @@ Return EXACTLY one fenced JSON block. No prose before or after.
   "finished_at": "<ISO8601>",
   "mode": "full | dry_run",
   "window_id": "<resolved>",
-  "status": "completed | precondition_failed | cascading_failures | budget_exhausted | malformed_recipe",
+  "status": "completed | bringup_failed | bringup_budget_exhausted | bringup_timeout | precondition_failed | cascading_failures | budget_exhausted | malformed_recipe",
   "design_conformance_section": false,
   "design_conformance_pairs": [],
   "recipe_format_warning": "<only present if no machine preconditions section>",
+  "machine_preconditions_warning": "<only present if action commands found in machine preconditions>",
+  "bringup": {
+    "executed": true,
+    "steps": [
+      {
+        "label": "B1. Login if on auth screen",
+        "if_check": "agent-view eval ...",
+        "if_actual": "undefined",
+        "triggered": true,
+        "actions_run": ["agent-view fill ...", "agent-view click ..."],
+        "post_condition": "typeof window.__dev === 'object'",
+        "post_actual": "object",
+        "result": "done | skipped_already_ready | failed_post_condition | action_command_error",
+        "wall_time_ms": 3200
+      }
+    ],
+    "snapshot_screenshot_path": "<path or null>",
+    "commands_used": 7,
+    "wall_time_ms": 14500
+  },
   "machine_preconditions": [
     { "command": "agent-view eval ...", "criterion": "must be true", "actual": "true", "passed": true }
   ],
   "failed_precondition": null,
-  "manual_preconditions_to_check": "<verbatim text, only if precondition_failed>",
+  "manual_preconditions_to_check": "<verbatim text, only if precondition_failed and recipe has Manual section>",
   "summary": {
     "total": 0,
     "passed": 0,
@@ -94,8 +153,8 @@ Return EXACTLY one fenced JSON block. No prose before or after.
     "requires_visual_review": 0,
     "subjective": 0,
     "skipped": 0,
-    "tool_calls_used": 0,
-    "tool_calls_budget": 30
+    "evidence_tool_calls_used": 0,
+    "evidence_tool_calls_budget": 30
   },
   "steps": [
     {
@@ -115,13 +174,14 @@ Return EXACTLY one fenced JSON block. No prose before or after.
   "blocking_issues": [
     "<one-line summary of each failure or abort reason; empty array if everything passed>"
   ],
-  "abort_reason": "<only present when status != completed: cascading_failures | budget_exhausted | malformed_recipe — one sentence>"
+  "abort_reason": "<only present when status != completed: bringup_failed | cascading_failures | budget_exhausted | precondition_failed | malformed_recipe — one sentence>"
 }
 ```
 
 ## Boundaries (re-stated for clarity)
 
-- **No exploration.** Already covered in budgets, restating because this is the failure mode. The parent agent has Opus/Sonnet to investigate; you have Haiku to execute a script. Stay in lane.
+- **No exploration. Anywhere.** Bringup, Machine Preconditions, Evidence — all bound by the same rule. If a literal command from the recipe doesn't behave as expected, that's data for the report, not a prompt to investigate.
+- **Bringup is idempotent BY DESIGN.** If you find yourself thinking "I'll just run the action commands without checking the IF condition because they're probably needed anyway" — stop. Always run the IF check first. Skipping is a valid outcome and the cheapest path through bringup.
 - **No fix suggestions.** `diagnosis` is descriptive only ("returned 0, expected > 0"). Never "you should change X" or "try Y instead".
 - **Truncate aggressively.** Stdout > 500 chars → truncate with `…[truncated, full output reproducible by re-running]`. Parent agent can re-run cherry-picked commands itself.
 - **One JSON block, nothing else.** Anything you print outside the JSON wastes the parent agent's context — which is the entire reason you exist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petukhovart/agent-view",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "CLI tool for visual verification of desktop apps (Electron/Tauri) via Chrome DevTools Protocol",
   "type": "module",
   "main": "dist/index.js",

package/skills/verify/SKILL.md

@@ -187,8 +187,13 @@ Why: recipe execution is mechanical (run commands, compare to `Expected:`, repor
 **Pre-flight check (do this BEFORE spawning the runner):**
 
 1. `Read` the recipe.
-2. Confirm it has a `## Machine Preconditions` section. If missing → it's older 0.6.x format. Tell the user once: "this recipe doesn't have Machine Preconditions, so the runner can't distinguish setup failures from real bugs. Run anyway, or update the recipe first?" Default to running but flag failures with this caveat in the final summary.
-3. Read the `## Manual Preconditions` block out loud to the user (one tight sentence each) and ask: "is the app set up this way right now?" Wait for confirmation. If they say no — stop, don't waste a runner spawn.
+2. Determine the recipe format:
+   - Has `## Bringup` section → 0.8.0+ format. Bringup runs automatically; no user setup needed unless `## Manual Preconditions` is non-empty.
+   - Has `## Machine Preconditions` but no `## Bringup` → 0.7.0 format. The user must do all setup manually before this call.
+   - Neither → 0.6.x format. Tell the user once: "this recipe predates the precondition contract — failures may not be diagnostic. Run anyway, or regenerate the recipe via `verify-recipe`?"
+3. **Manual Preconditions handling:**
+   - 0.8.0 + Manual section empty → skip user confirmation, go straight to spawn.
+   - Manual section non-empty → read each item to the user (tight one-liners) and ask: "are these set up right now?" Wait for confirmation. If no — stop, don't waste a runner spawn.
 4. Resolve the window id once: `agent-view discover` → pick the main window's id.
 
 **Spawn:**
@@ -197,16 +202,18 @@ Why: recipe execution is mechanical (run commands, compare to `Expected:`, repor
    - Absolute `recipe_path`
    - Resolved `window_id`
    - `mode: full` (or `dry_run` if the user asked to validate the recipe first)
-   - Any extra context (e.g. "user is already logged in", "GIS widget already mounted")
+   - Any extra context the user provided
 6. Wait for the JSON report.
 
 **Handle the report:**
 
-7. **If `status: precondition_failed`** → relay `failed_precondition` and `manual_preconditions_to_check` to the user verbatim. Do NOT spawn the runner again. Do NOT try to "fix" the missing setup yourself by clicking around — the user knows their app, ask them to do the manual setup and re-run.
-8. **If `status: cascading_failures` or `budget_exhausted`** → the recipe is likely stale (selectors/refs changed, UI restructured) or describes a flow that no longer matches the app. Show the first 1-2 failed steps to the user and ask whether to update the recipe (delegate back to `verify-recipe`) or investigate manually.
-9. **If `design_conformance_section: true`** in the report: also spawn `design-conformance-runner` in parallel, passing the `design_conformance_pairs` array. Merge both reports before answering the user.
-10. **If `requires_visual_review` steps** have no design ref attached: open each screenshot yourself with `Read` and decide pass/fail.
-11. **If individual `failed` steps** in an otherwise-completed run: re-run that specific failing command yourself for richer evidence to diagnose. Do not re-execute the whole recipe.
+7. **If `status: bringup_failed`** → the bringup spec is wrong: an action command failed to land its post-condition (e.g., `selectLocationAndFly` doesn't exist, login button text changed, programmatic API renamed). Surface `failed_bringup_step` and the post-condition's actual value. Suggest re-authoring the broken Bringup step via `verify-recipe`. Do NOT click around manually trying to make it work.
+8. **If `status: bringup_budget_exhausted` or `bringup_timeout`** → bringup is taking too long. Either an animation is slower than the recipe expects (extend `timeout` on the offending step), or bringup is fighting an unexpected app state. Show the bringup transcript and ask the user.
+9. **If `status: precondition_failed`** → bringup completed but state still wrong. Could be: (a) bringup is incomplete (missing a step), (b) a Machine Precondition is overly strict, (c) real environment issue. Relay both the `bringup` block (showing what bringup did) and the `failed_precondition` so the user sees the full picture.
+10. **If `status: cascading_failures` or `budget_exhausted`** → the recipe Evidence is likely stale (selectors/refs changed, UI restructured). Show the first 1-2 failed Evidence steps and ask whether to update the recipe via `verify-recipe` or investigate manually.
+11. **If `design_conformance_section: true`** → also spawn `design-conformance-runner` in parallel with the `design_conformance_pairs` array. Merge both reports.
+12. **If `requires_visual_review` steps** have no design ref attached → open each screenshot yourself with `Read` and decide pass/fail.
+13. **If individual `failed` steps** in an otherwise-completed run → re-run that specific failing command yourself for richer evidence. Do not re-execute the whole recipe.
 
 Output to the user: a tight summary — what passed, what failed, what needs visual review, and (if any) which design conformance issues to fix. Do not paste the raw JSON unless asked.
 

package/skills/verify-recipe/SKILL.md

@@ -10,36 +10,43 @@ You help the developer author a disciplined, cheapest-first verification recipe
 
 ## What this produces
 
-A file at `.claude/verify-recipes/<kebab-slug>.md` containing:
+A file at `.claude/verify-recipes/<kebab-slug>.md` with three precondition phases plus the verification body:
 
-- **MANUAL PRECONDITIONS** — human-readable setup steps (drag widget here, navigate to view X) that a person or the parent agent must do before any automated check
-- **MACHINE PRECONDITIONS** — runnable `agent-view` checks that prove the manual setup actually took effect; the verify-runner subagent runs these FIRST and aborts cleanly if any fail
-- **NARROWED SIGNAL** — the measurable indicator that proves success or failure
-- **EVIDENCE COMMANDS** — ordered `agent-view` calls, cheapest first, each annotated with what it proves
-- **POSITIVE-CASE ASSERTIONS** — what "pass" looks like for each command
-- **REGRESSION CHECKS** — adjacent paths that must not have broken
-- **DESIGN CONFORMANCE** (optional) — screenshot ↔ design reference pairs for the design-conformance-runner
+- **MANUAL PRECONDITIONS** — only what `agent-view` physically cannot do (rare; usually empty)
+- **BRINGUP** — idempotent setup steps the verify-runner executes itself: `if <state-check> is falsy → run actions → wait for state to settle`. Drives the app from auth screen / fresh shell / mid-state into the exact state the recipe needs. Re-runs cost almost nothing because each step skips when its condition is already met.
+- **MACHINE PRECONDITIONS** — pure state queries that confirm Bringup actually settled. No actions here. Any false → runner aborts.
+- **EVIDENCE COMMANDS** — ordered `agent-view` calls, cheapest first, each annotated with what it proves.
+- **POSITIVE-CASE ASSERTIONS** + **REGRESSION CHECKS** + optional **DESIGN CONFORMANCE**.
 
 Create the directory if missing: `mkdir -p .claude/verify-recipes`
 
-## Why two kinds of preconditions
+## Why three precondition phases
 
-The verify-runner subagent is intentionally tightly scoped — it executes commands and reports results, with hard budgets that prevent it from "looking around" when things don't match. That means **the recipe must clearly separate what a human does from what a machine verifies**.
+| Phase | Who runs it | What it does | Idempotent? |
+|---|---|---|---|
+| `## Manual Preconditions` | Human (or main agent) | Only what `agent-view` physically can't (USB token, hardware setup, multi-machine state) | n/a |
+| `## Bringup` | verify-runner | `if state-check is falsy → action → wait`. Logins, mounting widgets, navigation — anything `agent-view` can do deterministically | YES (per step) |
+| `## Machine Preconditions` | verify-runner | Pure `eval` / `dom --filter` state queries. NO actions. | trivially |
 
-If you write a precondition as prose ("the GIS widget is dragged into a workspace cell"), the runner can't check it. If the user forgot to do it, the runner blunders into Evidence Commands that depend on missing UI, and either burns its budget on a recipe-stale abort or — worse, in older formats — flails trying to find the missing element.
+**Why split Bringup from Machine Preconditions?** A failure tells you a different thing in each:
+- A failed Bringup post-condition → bringup spec is wrong (e.g., `selectLocationAndFly` doesn't exist; "Войти" button text changed). Author error.
+- A failed Machine Precondition after Bringup succeeded → bringup THINKS it set up the state but the state isn't there (e.g., login appeared to succeed but the user role is wrong, the app is in a degraded mode). Real environment issue.
+- A failed Evidence Command after both passed → real bug in the verified feature.
 
-The fix: every Manual Precondition gets a paired Machine Precondition that proves it took effect. Drag widget into cell → check `cesiumReadyFlag === true`. Navigate to map mode → check `document.querySelector('.cesium-widget')` exists. Now if the user skips a step, the runner aborts cleanly on Phase 1 with a clear "do this first" message instead of diagnosing phantom bugs.
+Without the split, all three look like "step N failed" and the developer can't tell which.
+
+**Why keep Manual at all?** Some things really can't be automated cheaply: physical USB-key auth, multi-machine setups, long-running data migrations. List them — but be honest, this section should usually be empty.
 
 ## Methodology
 
 Frame the recipe with **hard-debug** discipline. Apply this chain in authoring mode:
 
-1. Start from a **reproducible, machine-checkable** starting state — not "open the app and poke around"
-2. Convert vague expectations ("looks right") into measurable signals ("store.user.role === 'admin'")
-3. Prefer the cheapest tool that can answer the question — a value check costs ~50 tokens, a screenshot costs ~6 000
-4. Include at least one negative-case check (the old symptom must no longer appear)
-5. Include at least one regression check (an adjacent flow must still work)
-6. **Every Manual Precondition needs a Machine Precondition counterpart.** If you can't think of one — interview the developer further before writing the recipe (see Step 1 below).
+1. Start from the broadest possible starting state — recipe should run from auth screen, from logged-in shell, or from "already in the feature" without modification.
+2. Convert vague expectations ("looks right") into measurable signals ("`store.user.role === 'admin'`").
+3. Prefer the cheapest tool that can answer the question — a value check costs ~50 tokens, a screenshot costs ~6 000.
+4. Include at least one negative-case check (the old symptom must no longer appear).
+5. Include at least one regression check (an adjacent flow must still work).
+6. **Bringup steps must be conditional + idempotent.** Every action wrapped in `if <state-check> is falsy`. Every action followed by `wait for <post-condition> to be truthy`. Re-running the recipe must be a no-op when the app is already ready.
 
 ## Tool-cost decision tree
 
@@ -56,29 +63,46 @@ Pick the first row that can answer the question. Only go lower when the row abov
 | Canvas / WebGL scene state | `agent-view scene --diff` | DOM is empty for canvas apps |
 
 **Anti-patterns to reject:**
-- Mixing manual setup and machine checks under a single "Repro Steps" heading. Always split into Manual Preconditions + Machine Preconditions.
-- Manual Precondition without a Machine counterpart — the runner can't verify it, so the user can silently violate it.
-- Opening Evidence Commands with a screenshot to "see the state" — use `dom --filter` or `eval` first
-- Using `eval` when `dom --filter` answers the question
-- Assertions that depend on transient state without `watch --until` to stabilize first
-- "Check that it looks right" — every Evidence assertion must be a concrete pass/fail criterion. The single legitimate exception is the `## Design Conformance` section, which delegates visual judgment to the design-conformance-runner subagent against an explicit reference image.
-- Inventing design reference paths (`.figma-refs/...`, `assets/mockups/...`) when the developer did not provide them. No refs → no Design Conformance section.
+- Putting UI clicks (`click`, `fill`) in `## Machine Preconditions`. Actions go in `## Bringup`. Machine Preconditions are state queries only.
+- Bringup steps without an IF condition (unconditional actions). They break idempotency — re-running a "click Login" step when already logged in fails. Always wrap.
+- Bringup steps without a post-condition wait. Without it, the runner advances before the action settled, and the next step's IF check sees stale state.
+- Manual Preconditions for anything `agent-view` can do. Drag widget into cell? Often there's a programmatic API — interview the developer for it before defaulting to Manual.
+- Hardcoded credentials in Bringup commands. Use env-var references (`"$AGENTVIEW_PASSWORD"`) — never inline a password, even for dev/masterkey accounts. Recipes get committed to git.
+- Opening Evidence Commands with a screenshot to "see the state" — use `dom --filter` or `eval` first.
+- "Check that it looks right" — every Evidence assertion must be a concrete pass/fail criterion. The single legitimate exception is the `## Design Conformance` section.
+- Inventing design reference paths (`.figma-refs/...`) when the developer did not provide them. No refs → no Design Conformance section.
 
 ## Workflow
 
 ### Step 1 — gather context (interview the developer)
 
-When invoked, ask the developer in plain text (no tool calls yet). Wait for the response before continuing.
+When invoked, ask in plain text. Wait for response before continuing.
+
+**Block A — what's being verified:**
+
+1. What was shipped or fixed? (feature name or bug description)
+2. What was the original symptom or expected behavior?
+3. Any known failure mode or edge case to cover?
+
+**Block B — bringup: how the runner gets the app into a state where verification makes sense:**
+
+4. **Authentication** — does the app require login before the feature is reachable? If yes:
+   - What identifies "logged out" vs "logged in" in JS state? (e.g., `typeof window.__dev`, `!!store.user`)
+   - Login flow: which fields/buttons (`fill --filter "..."`, `click --filter "..."`) and what credentials? **Use an env-var, never inline.** Suggest a name like `AGENTVIEW_PASSWORD` and tell the user to `export` it in their shell or `.env.local`.
+5. **UI mode / view requirements** — does the feature live behind a specific app mode/view that must be active before it appears (e.g., "map view, not settings panel"; "edit mode, not view mode"; "modal X must be open")? For each:
+   - State check that proves this mode is active (e.g., `document.querySelector('.cesium-widget') !== null` for map mode).
+   - Action(s) to enter this mode if not active. Prefer programmatic API (e.g., `eval "store.setMode('map')"`) over UI clicks. If only UI works, list the click sequence.
+6. **Setup actions** — beyond modes, what other setup must happen (drag widget into cell, navigate camera to a location, open a dialog)? For each:
+   - Programmatic API if it exists (e.g., `gis-widget-root.selectLocationAndFly(uuid)`, `workspace.addWidget(...)`). Prefer this — much more reliable than UI automation.
+   - State check that proves the setup happened.
+   - Wait timing: how long does this take to settle? (camera animation, async data load).
 
-1. **What was shipped or fixed?** (feature name or bug description)
-2. **What was the original symptom or expected behavior?**
-3. **Any known failure mode or edge case to cover?**
-4. **UI mode requirements**: Does this feature live behind a specific app mode/view that must be active before it appears (e.g., "map view, not settings panel"; "edit mode, not view mode"; "modal X must be open")? List every mode-toggle the user must have done.
-5. **Manual setup steps**: Beyond modes, what physical actions must the user do before checks can run (drag a widget into a cell, search for and select a map location, open a specific dialog, log in as a particular role)? Be precise — these become Manual Preconditions verbatim.
-6. **State assertions for each manual step**: For each item in (4) and (5), is there a JS expression or DOM selector that proves it happened? Examples: "after dragging the GIS widget — `pinia._s.get('gis-widget-root')?.cesiumReadyFlag` becomes true"; "after entering map mode — `document.querySelector('.cesium-widget')` exists; "after selecting a location — `selectedLocation` is truthy". If the developer doesn't know offhand, that's fine — ask them to point you at the store/composable/component where state lives and you can suggest expressions.
-7. **(Optional) Design references**: Local image paths to compare screenshots against (Figma exports, hand-off PNGs). **Only local files are supported.** If none — skip the Design Conformance section entirely.
+If the developer doesn't know whether a programmatic API exists, ask them to point you at the relevant store/composable/component file — you can read it and find one (or confirm none).
 
-If the answers to (4)/(5) reveal something the developer can't pair with a machine check (6), say so explicitly: "I'll write `<step>` as a Manual Precondition with no Machine counterpart — that means if a user skips it, the runner won't catch it and may report misleading failures. Want to add a custom check?" Then either (a) get an expression from them, or (b) accept the gap and note it in the recipe's Anti-patterns section.
+**Block C — verification body and visual:**
+
+7. State assertions for the verified feature itself — JS expressions that prove it works (separate from bringup setup checks).
+8. **(Optional) Design references** — local image paths to compare screenshots against (Figma exports, hand-off PNGs). **Only local files are supported.** If none — skip the Design Conformance section.
 
 ### Step 2 — draft the recipe
 
@@ -91,20 +115,54 @@ Generated: <date>
 Scope: <one sentence describing what this covers>
 
 ## Manual Preconditions
-<!-- Done by a human or the parent agent BEFORE invoking verify-runner. The runner does NOT execute these. -->
-1. <Action 1 — exact, no ambiguity. e.g. "Open the GIS widget by dragging it from the 'Edit workspace' panel into the upper-left cell.">
-2. <Action 2 — e.g. "In the map header search box, type 'Склад_1' and click the matching dropdown entry to fly the camera to that sublocation.">
-3. <Action 3 — e.g. "Zoom in until building details are visible (camera height < 1000 m).">
+<!-- ONLY for things agent-view physically cannot do. Usually empty. -->
+<!-- The verify-runner does NOT execute these. -->
+(none — bringup handles everything)
+
+## Bringup
+<!-- The verify-runner executes these. Each step is conditional + idempotent: skipped if already in target state. -->
+<!-- Format per step: -->
+<!--   ### B<N>. <one-line title> -->
+<!--   - if `<eval>` is `<falsy criterion>`: -->
+<!--       <action command 1> -->
+<!--       <action command 2> -->
+<!--     wait for `<post-condition eval>` to be `<truthy criterion>`, timeout <Ns> -->
+
+### B1. Login if on auth screen
+- if `agent-view eval "typeof window.__dev"` is not `"object"`:
+    agent-view fill --window $W --filter "Логин" "root"
+    agent-view fill --window $W --filter "Пароль" "$AGENTVIEW_PASSWORD"
+    agent-view click --window $W --filter "Войти"
+  wait for `agent-view eval "typeof window.__dev"` to be `"object"`, timeout 15s
+
+### B2. Mount the GIS widget if not mounted
+- if `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.cesiumReadyFlag"` is `false`:
+    agent-view eval "window.__dev.pinia._s.get('workspace').addWidget({type:'gis', cell:0})"
+  wait for `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.cesiumReadyFlag"` to be `true`, timeout 10s
+
+### B3. Exit settings mode if active
+- if `agent-view eval "document.querySelector('.cesium-widget') !== null"` is `false`:
+    agent-view click --window $W --filter "Готово"
+  wait for `agent-view eval "document.querySelector('.cesium-widget') !== null"` to be `true`, timeout 5s
+
+### B4. Fly to first sublocation
+- if `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.selectedLocation"` is `false`:
+    agent-view eval --await "window.__dev.pinia._s.get('gis-widget-root').selectLocationAndFly(window.__dev.mwStore.nvgn.sublocations.value[0].id)"
+  wait for `agent-view eval "(()=>{const w=document.querySelector('.cesium-widget'); const cw=Object.values(w).find(v=>v?.scene); return Math.round(window.Cesium.Cartographic.fromCartesian(cw.scene.camera.position).height);})()"` to be `< 5000`, timeout 30s
+
+### B5. Snapshot for the report (always runs)
+agent-view screenshot --window $W --scale 0.25
 
 ## Machine Preconditions
-<!-- The verify-runner runs these FIRST. If ANY fail, it aborts with `precondition_failed` and shows the Manual Preconditions block to the user. -->
-- `agent-view eval "window.__dev !== undefined"` → must be `true`
+<!-- Pure state checks. NO actions. The verify-runner aborts with `precondition_failed` if any return false. -->
+- `agent-view eval "typeof window.__dev"` → must be `"object"`
 - `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.cesiumReadyFlag"` → must be `true`
-- `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.selectedLocation"` → must be `true`
 - `agent-view eval "document.querySelector('.cesium-widget') !== null"` → must be `true`
+- `agent-view eval "!!window.__dev.pinia._s.get('gis-widget-root')?.selectedLocation"` → must be `true`
+- `agent-view eval "({locations:window.__dev.mwStore.nvgn.locations.value.length, sublocations:window.__dev.mwStore.nvgn.sublocations.value.length, zones:window.__dev.mwStore.nvgn.zones.value.length, objects:window.__dev.mwStore.nvgn.objects.value.length})"` → all four counts must be `> 0`
 
 ## Narrowed Signal
-<!-- The one measurable thing that proves it works -->
+<!-- The one measurable thing that proves the verified feature works -->
 `<agent-view command>` must return `<expected value>`.
 
 ## Evidence Commands
@@ -126,114 +184,75 @@ Cost: ~<N> tokens
 - [ ] <adjacent flow> — `agent-view <command>` → `<expected>`
 
 ## Design Conformance
-<!-- INCLUDE THIS SECTION ONLY IF the developer provided design refs in question 7. -->
-<!-- Each row pairs a screenshot command with the expected reference image path. -->
-<!-- The design-conformance-runner subagent reads this section, runs the screenshot commands, and visually compares against the expected refs. -->
-<!-- Do NOT invent design ref paths. Use exactly what the developer provided. -->
+<!-- Include ONLY if the developer provided design refs in question 8. -->
 
 | Step Label | Screenshot Command | Expected Reference |
 |---|---|---|
 | <area name e.g. "filter panel collapsed"> | `agent-view screenshot --crop "<area>" --scale 0.5` | `<absolute path to expected PNG/JPEG>` |
-| <area name> | `agent-view screenshot --window $W --scale 0.5` | `<absolute path>` |
 
-Tolerance: `normal` (default — flag deviations a designer would notice in code review). Use `loose` only if the developer says exact pixel parity is not required.
+Tolerance: `normal` (default).
 
 ## Anti-patterns avoided
-- <note any recipe-specific traps, e.g. "manual step 3 (zoom) has no machine counterpart — runner cannot detect insufficient zoom; mitigated by Evidence Step N which checks camera height">
+- <note any recipe-specific traps, e.g. "B4 relies on `selectLocationAndFly` from gis-widget-root — verified to exist as of <date>; if it's removed, B4 falls back to Manual Precondition">
 ````
 
 ### Step 3 — save the file
 
-Determine a kebab-slug from the feature/fix name (e.g. `login-redirect-fix`, `cart-total-display`).
+Determine a kebab-slug from the feature/fix name. Save to `.claude/verify-recipes/<slug>.md`. Create the directory first if it doesn't exist. Confirm the path to the developer.
+
+### Step 4 — credentials warning (if Bringup contains login)
 
-Save to `.claude/verify-recipes/<slug>.md`. Create the directory first if it doesn't exist.
+If Bringup includes a login step:
 
-Confirm the path to the developer.
+> Recipe uses `$AGENTVIEW_PASSWORD` for login. Make sure that env var is set in your shell or `.env.local` before running verify (`export AGENTVIEW_PASSWORD=<value>`). The recipe never contains the literal password.
 
-### Step 4 — offer dry-run validation
+If the developer insisted on inlining a literal password earlier, warn:
 
-After saving, ask the developer:
+> ⚠️ Recipe contains a literal password on line N. This will be committed to git. Consider replacing with `$AGENTVIEW_PASSWORD` (env-var). Want me to convert it now? (yes/no)
 
-> The recipe is saved at `<path>`. Is the app running? If yes, I can spawn `verify-runner` in `dry_run` mode — it'll execute only the Machine Preconditions and the first Evidence Command (~5 commands total). That validates the recipe isn't broken before you commit a full run. Want me to run the dry-run? (yes/no)
+### Step 5 — offer dry-run validation
+
+After saving, ask:
+
+> The recipe is saved at `<path>`. Is the app running? If yes, I can spawn `verify-runner` in `dry_run` mode — it'll execute Bringup + Machine Preconditions + the first Evidence Command (~10-20 commands total). That validates the recipe isn't broken before you commit a full run. Want me to run the dry-run? (yes/no)
 
 If yes:
 1. Get the window id with `agent-view discover`.
 2. Spawn `verify-runner` via the Agent tool with `mode: dry_run`, the recipe path, and the window id.
 3. Read the JSON report.
-4. If `status: completed` and dry-run preconditions+step 1 passed → tell the developer the recipe is healthy and ready for a full run.
-5. If `precondition_failed` → relay the `failed_precondition` and `manual_preconditions_to_check` so the developer knows what setup step to do (or what Machine Precondition to fix).
-6. If the first Evidence Command failed → flag it: the recipe likely has a stale ref/selector or assumes UI state that doesn't exist; offer to revise.
+4. **`status: bringup_failed`** → relay `failed_bringup_step` and the post-condition's actual value. Suggest revising the bringup step (most often: action commands wrong, programmatic API doesn't exist, or post-condition criterion mistuned).
+5. **`status: precondition_failed`** → bringup ran but state isn't there. Either bringup is incomplete, or a state check is overly strict. Show both bringup outcome and the failing precondition.
+6. **`status: completed` and dry-run passed** → recipe is healthy. Confirm and stop.
 
-If no — confirm the path and stop.
+If no — confirm path and stop.
 
-## Worked example: "fixed login redirect bug"
+## Worked example: GIS feature with full bringup automation
 
 **Developer input:**
-> Fixed a bug where after login, the redirect went to `/home` instead of `/dashboard`. Store mutation `SET_REDIRECT_PATH` was missing. No visual change — purely a routing issue. No special UI mode — just the login page. Manual setup is "be on the /login route".
+> Verifying selective filter changes (commits 0c5f1b1ee, 4d0c89467, 4c99c1591) in the GIS widget. App requires login (root/masterkey via middleware). GIS widget mounts via `workspace.addWidget({type:'gis', cell:0})`. Camera flies via `gis-widget-root.selectLocationAndFly(id)`. Map view is the default after widget mount.
 
 **Recipe produced:**
 
-````markdown
-# Verify: Login Redirect Fix
-
-Generated: 2026-04-27
-Scope: Confirms that a successful login routes to /dashboard, not /home, and that the store mutation fires correctly.
+(see the template above — it's already the worked example for this scenario)
 
-## Manual Preconditions
-1. App running, user logged out, browser at the `/login` route.
-
-## Machine Preconditions
-- `agent-view eval "router.currentRoute.path"` → must be `"/login"`
-- `agent-view eval "!!store.state.auth.user"` → must be `false` (logged out)
+**Saved to:** `.claude/verify-recipes/nvgn-gis-improvements.md`
 
-## Narrowed Signal
-`agent-view eval "router.currentRoute.path"` must return `"/dashboard"` after sign-in.
-
-## Evidence Commands
-
-### 0. Setup — baseline console
-```bash
-agent-view console --clear
+**Dry-run output (first run after auth screen):**
 ```
-Expected: `Console buffer cleared`
-Cost: ~10 tokens
-
-### 1. Confirm redirect target
-```bash
-agent-view dom --filter "Email" --depth 2
-agent-view fill <email-ref> "admin@example.com"
-agent-view fill <password-ref> "password"
-agent-view click <signin-ref>
-agent-view watch "router.currentRoute.path" --until "router.currentRoute.path === '/dashboard'"
+status: completed
+mode: dry_run
+bringup: 5 steps, 12 commands, 18s — B1 (login) + B2 (mount) + B4 (fly) all triggered; B3 skipped (already map mode); B5 screenshot saved
+machine_preconditions: 5/5 passed
+steps: 1/1 passed
 ```
-Expected: `replace /  "/login" → "/dashboard"` in watch output
-Cost: ~150 tokens
 
-### 2. Confirm mutation fired
-```bash
-agent-view eval "store.state.auth.redirectPath"
+**Dry-run output (second run, app already in target state):**
 ```
-Expected: `"/dashboard"` (not `"/home"`, not `null`)
-Cost: ~50 tokens
-
-### 3. No errors during login flow
-```bash
-agent-view console --level error,warn
+status: completed
+mode: dry_run
+bringup: 5 steps, 5 commands (4 IF-checks + 1 screenshot), 3s — all 4 conditional steps skipped_already_ready
+machine_preconditions: 5/5 passed
+steps: 1/1 passed
 ```
-Expected: `(no console messages)`
-Cost: ~30 tokens
-
-## Positive-Case Assertions
-- [ ] `router.currentRoute.path` === `/dashboard` after login
-- [ ] `store.state.auth.redirectPath` === `/dashboard`
-- [ ] No console errors during the flow
-
-## Regression Checks
-- [ ] Logout → `/login` still works (`agent-view click <logout-ref>` then `agent-view eval "router.currentRoute.path"` → `"/login"`)
-
-## Anti-patterns avoided
-- Not using screenshot to confirm route (route is a string — eval is 120× cheaper)
-- watch used before eval so the route change is confirmed to have settled, not just sampled mid-transition
-````
 
-**Saved to:** `.claude/verify-recipes/login-redirect-fix.md`
+This is what idempotent bringup buys you: 5x speedup on re-runs, zero manual intervention either way.