diff --git a/.agents/skills/kane-cli/SKILL.md b/.agents/skills/kane-cli/SKILL.md
index 32231a7..5399e4d 100644
--- a/.agents/skills/kane-cli/SKILL.md
+++ b/.agents/skills/kane-cli/SKILL.md
@@ -5,7 +5,7 @@ description: Browser automation + AI test authoring via kane-cli - run browser o
 
 # Kane CLI — Browser Automation Skill
 
-Use `kane-cli` for **any task that requires a real browser**: navigating websites, clicking elements, filling forms, searching, testing web UI, taking screenshots, or verifying deployments. Do NOT use Playwright, Puppeteer, or Selenium directly. Always run with `--agent` so output is structured NDJSON you can parse.
+Use `kane-cli` for **any task that requires a real browser**: navigating websites, clicking elements, filling forms, searching, testing web UI, taking screenshots, or verifying deployments. Do NOT use Playwright, Puppeteer, or Selenium directly. Use `--agent` for `run`, `testmd run`, and `generate`. `testrun run` has no `--agent`: it emits NDJSON when **stdin** is not a TTY (use `< /dev/null` for terminal automation). Assurance conversational commands use `--mode agent`.
 
 **Authoring test cases or scenarios?** Never write them by hand — kane-cli has two authoring pipelines, and the routing matters:
 
@@ -36,7 +36,7 @@ After that, run kane-cli normally — the variable is inherited:
 kane-cli run "<objective>" --agent <other-flags>
 ```
 
-Bash blocks until kane-cli exits, then hands you the complete stdout. Parse it, summarize what happened, and present the results table. Same pattern for `kane-cli testmd run` and `kane-cli generate`.
+Bash blocks until kane-cli exits, then hands you the complete stdout. Parse it, summarize what happened, and present the results table. Wait for process completion on `testmd run` and `generate` too, but parse their own completion events: `test_md_done` and `generate_done`, respectively. An intermediate `run_end` does not finish a saved test.
 
 Set a generous timeout (up to 600000ms) since browser runs can take a while.
 
@@ -100,7 +100,7 @@ The terminal event has `type: "run_end"` and stable fields: `status`, `summary`,
 | 🟢 **Result** | Passed |
 | 🎯 **Task** | <one_liner> |
 | ⏱️ **Duration** | <duration>s |
-| 👣 **Steps taken** | <count of progress events> |
+| 👣 **Steps taken** | <count of completed progress events (done/failed), retaining child/execution context> |
 | 📝 **What happened** | <summary> |
 | 🔗 **View details** | [Open in KaneAI Dashboard](<test_url>) |
 ```
@@ -184,7 +184,7 @@ kane-cli run "<objective>" --agent [options]
 | `--variables <json>` | Inline variables JSON (for `{{key}}` in objective) | None |
 | `--variables-file <path>` | Load variables from a JSON file | None |
 | `--ws-endpoint <url>` | Remote browser (LambdaTest grid) | Local Chrome |
-| `--code-export` | Generate code export after upload | Off |
+| `--code-export` | Generate code export after upload | config (`true` by default) |
 | `--bug-detection <mode>` | Flag suspected product bugs while authoring: `off`/`stop`/`continue` (`stop` halts on a confirmed bug; `continue` records and keeps going) | config value (`off`) |
 
 Other flags (`--global-context`, `--local-context`, `--cdp-endpoint`, `--allow-missing-url`) and the full variables precedence chain live in `references/setup-and-config.md`.
@@ -222,11 +222,11 @@ How you phrase the objective string determines what the agent does. Four pattern
 | 🎯 **Action** | "go to", "click", "type", "search", "fill" | Performs browser actions |
 | ✅ **Assertion** | "assert", "verify", "confirm", "check that" | Pass/fail check on a condition |
 | 📦 **Extraction** | "store X as 'name'" | Persists a value into `run_end.final_state` |
-| 🔌 **API call** | "call", "POST/GET a URL", a pasted `curl` | The agent makes the HTTP request itself; "save the response as X", then assert/reference `{{X.status}}` / `{{X.response_body…}}` |
+| 🔌 **API call** | "call", "POST/GET a URL", a pasted `curl` | The agent makes the HTTP request itself; "save the response as X", then assert on it in plain English: "assert the response status is 200", "store the id from the response body as 'order_id'" |
 
 ### Two rules that make an objective replayable
 
-1. **End every flow in a terminal assertion.** Close with a check of the resulting page state (`verify the cart shows 1 item`), not a bare `submit` or `confirm the dialog`. A run only earns a replayable pass/fail from a verify/assert — a pure-action objective (`add a laptop to the cart`) gets none. If the objective has several phases, each ends in its own check. Two traps: `confirm the dialog` is an action, not a check; and `verify the Submit button is visible` fails exactly when the action worked (the control disappears on success) — assert the outcome, not the trigger.
+1. **End every flow in a terminal assertion.** Close with a check of the resulting page state (`verify the cart shows 1 item`), not a bare `submit` or `confirm the dialog`. A run only earns a replayable pass/fail from a verify/assert — a pure-action objective (`add a laptop to the cart`) gets none. If the objective has several phases, each ends in its own check. Phrase the closing check as what is on screen once the last action completes, so it verifies with no further click or navigation; if the evidence is elsewhere, make getting there an explicit action (`place the order, open Order History, then verify the newest order shows "Processing"`), never `verify the order succeeded by checking Order History`. Two traps: `confirm the dialog` is an action, not a check; and `verify the Submit button is visible` fails exactly when the action worked (the control disappears on success) — assert the outcome, not the trigger.
 2. **Intent for the actions, literal for the data.** Phrase actions as goals (`Log in with {{user}}`) so the run absorbs layout drift; keep exact values literal or in `{{variables}}`. An expected-optional branch (a sometimes-there cookie banner) goes in an `if/else`, not assumed away.
 
 **Shape:** an intent action carrying literal data, then a verify of an observable end state — `Search for "{{query}}" and open the first result, then verify the title contains "{{query}}"`. Full grammar in `references/objectives-cookbook.md §1`.
@@ -238,7 +238,7 @@ Vague phrasing like "read", "tell me", "report" does NOT reliably extract data 
 ❌ `"go to example.com and read the page title"`
 ✅ `"go to example.com, store the page title as 'page_title'"`
 
-Stored values appear in `run_end.final_state` and become the second results table per §1.4.
+Stored values appear in `run_end.final_state` and become the second results table per §1.4. Refer back to a stored value in plain English (`the stored price value`), never as `{{price}}`; `{{name}}` is for global variables and secrets only.
 
 ### Calling APIs directly
 
@@ -246,10 +246,10 @@ The agent can make API calls itself — not just observe the page's traffic. Phr
 
 ```text
 "Call POST https://api.example.com/login with body {...}, save the response as login,
- assert {{login.status}} is 200"
+ assert the response status is 200"
 ```
 
-Reference the saved response as `{{login.status}}`, `{{login.response_body}}`, or `{{login.response_body.<field>}}`; a pasted `curl` works too. Full grammar in `references/objectives-cookbook.md` §3.5.
+Use the response in plain English: `the response status`, `store the id from the response body as 'order_id'`, and later `the stored order_id value`. Never `{{login.status}}`: `{{name}}` is reserved for global variables and secrets. A pasted `curl` works too. Full grammar in `references/objectives-cookbook.md` §3.5.
 
 ### Chaining
 
@@ -269,18 +269,19 @@ Action → extraction → assertion in one objective:
 | Specific: "click the 'Add to Cart' button" | Vague: "add the item" |
 | Name extractions: "store X as 'price'" | Hope for values: "tell me the price" |
 | `{{variables}}` for credentials/URLs | Hardcode secrets in the objective |
+| Plain English for values the run produces: "the stored price value", "the response status" | `{{price}}` / `{{login.status}}` for a stored value or an API response |
 | Always include starting URL | Assume the agent knows where to start |
 | Split mega-objectives (>15 steps) into multiple runs | Cram everything into one |
 
 ---
 
-## 5. Parsing `--agent` output — essentials
+## 5. Parsing one-shot `run --agent` output — essentials
 
 > Internal reference only. Never expose these field names to the user — translate them per §1.
 
 Stdout is NDJSON, one event per line. There are two shapes:
 
-- **Progress events** (most events) have `step` (1-based), `status` (`passed`/`failed`), `remark` — and **no `type` field**.
+- **Progress events** (most events) have `step` (1-based), `status` (`running` at start, `done`/`failed` at completion), `remark` — and **no `type` field**.
 - **Typed events** have a `type` field: `project_folder_auto_defaulted` (run-startup gate, fires before any progress when no project/folder is configured), `bifurcation`, `child_agent_start`, `child_agent_end`, `ask_user`, `error` (an `error` with `code: "unresolved_variables"` is a pre-run refusal and the **only** line — no `run_end` follows; handle per §3), and finally `run_end`.
 
 Parsing strategy:
@@ -292,7 +293,7 @@ for each line:
   else if obj.step exists    → progress event → summarize per §1.3
 ```
 
-`run_end` is the only event with a stable cross-version schema — build all post-run logic on it.
+For one-shot `run`, build post-run logic on `run_end` and process exit. Saved tests and suites use their own completion events (see Command-specific completion below).
 
 For full event schemas (`bifurcation` flow fields, `child_agent_*`, `ask_user` semantics, `cancel`/`user_response` outbound events, complete `run_end` field list), Read `references/parsing.md`.
 
@@ -363,3 +364,12 @@ Internal event/field names (`generate_snapshot`, `request_id`, …) are for pars
 | Browse / create projects or folders, or parse the auto-default event | `references/test-manager.md` |
 | First-time install, auth, or full config | `references/setup-and-config.md` |
 | Compare / evaluate / benchmark kane-cli vs another tool or approach (cost, tokens, effort, ROI) | `references/fair-evaluation.md` |
+
+## Command-specific completion
+
+The `run_end` parsing strategy applies to one-shot `run` only. For `testmd run`, collect `test_md_done.overall_status`, `duration_s`, `session_id`, and optional `share_url`; embedded `run_end` events can finish individual steps. Local suites emit `testrun_done`; dispatched remote suites then emit `remote_done` (retain `status`, `exit`, `sessions_path`). `generate` emits `generate_done`. Assurance conversational agent streams end in `done`; review/read verbs have their own contracts. Always check process exit too: early refusal, invalid plan or dry-run can exit without the normal completion event.
+
+Progress is for live display: count only `done`/`failed` completions, retaining child and execution context when step indices repeat.
+
+
+For assertion mode, optional final validation, current-page `--analyzer-only` checks, streaming-network capture, and code-export defaults, read [Execution controls](references/execution-controls.md).
diff --git a/.agents/skills/kane-cli/references/assurance.md b/.agents/skills/kane-cli/references/assurance.md
index 24f994e..cab6a28 100644
--- a/.agents/skills/kane-cli/references/assurance.md
+++ b/.agents/skills/kane-cli/references/assurance.md
@@ -229,3 +229,13 @@ Never `context ingest` the new version first — reconcile does its own re-inges
 - **One stream.** The re-extract child's events ride the reconcile stream itself, stamped `verb: "reconcile"` — parse per `references/assurance-parsing.md`.
 
 For staleness that arrived outside a reconcile, `kane-cli maintain evolve` re-designs a use-case — it is interactive-only (the blast-radius confirmation is the point); suggest the user run it in a terminal rather than scripting around it.
+
+## Sharing a context store
+
+For location setup, sync, pull, push, clone and rebase recovery, see [Sharing the context store](context-sync.md).
+
+## Lifecycle automation contracts
+
+`context name`, `context retire`, and `context revert` accept `--mode agent` and emit an envelope ending in `done`. Destructive agent-mode operations require `--yes` even when stdin is a TTY. Other modes retain human output. Read commands use their documented `--json` flags; do not assume they all accept `--mode`.
+
+`context review --mode agent` / `--json` returns review outcome rows on success rather than the conversational `done` contract. Early agent-mode errors may emit `error` plus `done`; check command-specific output and process exit.
diff --git a/.agents/skills/kane-cli/references/evidence.md b/.agents/skills/kane-cli/references/evidence.md
index f11b229..e299539 100644
--- a/.agents/skills/kane-cli/references/evidence.md
+++ b/.agents/skills/kane-cli/references/evidence.md
@@ -73,3 +73,9 @@ Combines packs (execution ids or paths, order-significant) into one, sealed by d
 ## Debugging with a pack
 
 The pack is the first place to look on a failure: the failed step's **failure record** (error + page state), its **console/network slice** (4xx/5xx or JS errors usually explain it), and the **annotated screenshot** (what the agent actually acted on). Full failure workflow: `references/debug.md`.
+
+## Evidence merge identity
+
+For ordinary runs, default merge identity distinguishes the test and commit (`external_id.test_id`, `external_id.commit_id`) and the environment (`environment.os`, `environment.os_version`, `environment.browser`, `environment.browser_version`). Re-runs with the same identity nest as attempts; a different environment produces a separate sibling.
+
+Explicit collision policies can change grouping; a custom `--rules` file replaces the default rules rather than extending them. Check the selected identity rules before interpreting two runs as retries of the same test.
diff --git a/.agents/skills/kane-cli/references/execution-controls.md b/.agents/skills/kane-cli/references/execution-controls.md
new file mode 100644
index 0000000..5cae455
--- /dev/null
+++ b/.agents/skills/kane-cli/references/execution-controls.md
@@ -0,0 +1,11 @@
+# Execution controls
+
+## Assertion controls and current-page analysis
+
+`run` and `testmd run` support `--assertion-mode dom|visual` (default `dom` with vision fallback) and `--final-validation on|off` (default off). Persist with `config set-assertion-mode` and `config set-final-validation`. Final validation controls the synthesized `cp_final` checkpoint independently of action/testing mode; keep explicit terminal assertions in objectives.
+
+`run --analyzer-only --condition "<condition>"` checks the current desktop browser page without an objective, action steps or saved test. Repeat `--condition` for multiple checks. Use `--agent` or non-TTY input. Results contain `condition_results: boolean[]`; exit `0` means all conditions were judged, **not** that all are true. Exit `1` means a result was missing, and `3` means cancelled. This mode rejects mobile target/app/device options and code-export/name options.
+
+Experimental `run --network-ws` and `run --network-sse` enable WebSocket and SSE capture; both default off. Persist with `config set-network-ws on|off` and `config set-network-sse on|off`. SSE capture is Chromium-only. Do not copy these run-only flags onto `testmd` or `testrun` commands.
+
+Code export defaults to enabled, subject to saved configuration, and supports `python` (default) or `javascript`. `run`/`testmd run` use `--code-language`; `testmd export` uses `--language`. Upload eligibility is independent of action/testing mode.
\ No newline at end of file
diff --git a/.agents/skills/kane-cli/references/fair-evaluation.md b/.agents/skills/kane-cli/references/fair-evaluation.md
index 5eced3f..2b8f1e6 100644
--- a/.agents/skills/kane-cli/references/fair-evaluation.md
+++ b/.agents/skills/kane-cli/references/fair-evaluation.md
@@ -17,7 +17,7 @@ The most common evaluation error is pitting kane-cli **authoring** against the o
 |---|---|---|
 | **Create the test** | AI authoring — tokens, one-time | Agent/human **generates** the script — tokens and/or engineer hours, one-time |
 | **Run the test** | Replay from cache — ~0 LLM | Execute the script — ~0 LLM |
-| **UI changes / locator breaks** | Re-author only the failing step + downstream (`--retry` shrinking window); cost ∝ change | Human/agent finds & fixes broken selectors; debug the script |
+| **UI changes / locator breaks** | Re-author only the failing step + downstream (default adaptive healing); cost ∝ change | Human/agent finds & fixes broken selectors; debug the script |
 | **Ongoing maintenance** | Edit plain-English Markdown; cascade re-authors only forward; shared `@import` helpers fix once | Edit code; flaky-wait/fixture upkeep; selector churn |
 | **Verify pass/fail** | Deterministic asserts (URL/title/DOM/network/console/cookies); AI vision only for ~10% visual checks | Code assertions; or a separate LLM judge if the check is semantic/visual |
 
diff --git a/.agents/skills/kane-cli/references/mobile.md b/.agents/skills/kane-cli/references/mobile.md
index d434ec3..222a8c4 100644
--- a/.agents/skills/kane-cli/references/mobile.md
+++ b/.agents/skills/kane-cli/references/mobile.md
@@ -144,8 +144,8 @@ What to present after `testrun_done`/`remote_done`: the suite rollup (per `refer
 
 The **same natural-language objective grammar** applies (`references/objectives-cookbook.md`): action verbs, assertions, extractions ("store as"), if/else, chaining, and variables all carry over. A mobile run just drives an app instead of a page.
 
-The exception is **browser/DevTools-only checkpoints**, which are **web-only** and do not apply to a mobile run:
-
-- Network (HTTP traffic), Console, DOM/selectors, Cookies, localStorage, Core Web Vitals (LCP/CLS/INP/FCP/TTFB).
+Mobile capability depends on the platform and app. The implementation includes native network operations and Android cookie/storage access for visible Chrome or debuggable WebViews. This does not establish full desktop DevTools parity, general native DOM support, or equivalent iOS support. Verify device/app prerequisites and the specific checkpoint before relying on it; live platform parity remains unverified.
 
 Write mobile objectives around what the app shows and does (open a screen, tap, type, assert visible text/state, store a value). And never point a mobile run at a URL: a mobile run drives an app, not a website.
+
+In the interactive TUI, `/mobile` and `/desktop` can switch targets before the first dispatch. The target locks after dispatch; use `/new` to start a new session before switching.
diff --git a/.agents/skills/kane-cli/references/objectives-cookbook.md b/.agents/skills/kane-cli/references/objectives-cookbook.md
index 920745d..be6b2a9 100644
--- a/.agents/skills/kane-cli/references/objectives-cookbook.md
+++ b/.agents/skills/kane-cli/references/objectives-cookbook.md
@@ -4,7 +4,7 @@
 
 Read this whenever you're constructing the prose objective for `kane-cli run "<objective>"` or the body of a `## Step` in a `_test.md` file. Both surfaces feed the same agent and accept the same grammar.
 
-> **Mobile runs** (`--target emulator|simulator`, macOS Apple Silicon) share this same objective grammar, but the browser/DevTools-only checkpoints below (Network, Console, DOM/selectors, Cookies, localStorage, Core Web Vitals) are **web-only** and do not apply. Read `references/mobile.md`.
+> **Mobile runs** (`--target emulator|simulator`) share this objective grammar. Checkpoint support depends on platform and app: native network and Android Chrome/debuggable-WebView storage paths exist, but desktop parity and iOS equivalents must be verified. Read `references/mobile.md` for the capability boundary and local/cloud prerequisites.
 
 ---
 
@@ -38,6 +38,15 @@ Close each objective with a claim about the resulting **page state** — not a b
 
 If an objective has several phases (log in, then search, then check out), **each phase ends in its own assertion** — an intermediate phase with no check runs unverified, and a replay can't tell you which phase drifted.
 
+**The closing assertion is a look, not a trip.** Phrase it as a claim about what is on screen once the last action completes, so the agent verifies it without clicking, navigating, scrolling, or typing anywhere else. If the evidence lives somewhere else (Order History, the cart, a details drawer), add the action that gets there as its own step, then assert.
+
+```text
+❌ Place the order, then verify it succeeded by checking that it appears in Order History
+✅ Place the order, open Order History, then verify the newest order shows "Processing"
+```
+
+The ❌ version hides an action inside a check. The agent has to find its own way to Order History on every run, so the route can differ between runs and is never a step you can read or fix. The ✅ version keeps the route in the actions and leaves the assertion a pure observation of the page it lands on.
+
 Two things look like assertions but are not:
 
 - **A UI-commit "confirm" is an action, not a check.** `confirm the dialog` / `click OK to confirm` presses a control; it verifies nothing about the outcome. Follow it with a real check: `… then verify the confirmation reads "Order placed"`.
@@ -277,19 +286,22 @@ A pasted `curl` works too and is kept verbatim (method, headers, body, auth):
 curl -X POST https://api.example.com/login -H 'Content-Type: application/json' -d '{"u":"a","p":"b"}', save the response as login
 ```
 
-Once saved, reference the response by name:
+Once the call is made, use the response in plain English. `{{name}}` is reserved for global variables and secrets (§6); a value the run produces is never written that way.
 
-| Reference | Resolves to |
+| To use | Say |
 |---|---|
-| `{{order.status}}` | the HTTP status code (e.g. `201`) |
-| `{{order.response_body}}` | the whole response body |
-| `{{order.response_body.<field>}}` | a field from the JSON response body |
+| the HTTP status code | `assert the response status is 201` |
+| a field from the JSON body | `store the id from the response body as 'order_id'` |
+| the whole body | `store the response body as 'order_body'` |
+| a value later in the run | `the stored order_id value` |
+
+When one objective makes several calls, name each response (`save the response as order`) and say which one you mean: `assert the order response status is 201`.
 
 Then assert or chain on it — API calls and browser actions mix freely in one objective:
 
 ```text
 Call POST https://api.example.com/login with body {"u": "{{user}}", "p": "{{password}}"}, save the response as login,
-assert {{login.status}} is 200,
+assert the response status is 200,
 then open https://app.example.com and verify the dashboard loads
 ```
 
@@ -322,6 +334,8 @@ For DevTools extractions, the same rule applies — use "store" or "extract":
 
 Stored values land in `run_end.final_state` and feed the second results table per `SKILL.md §1.4`.
 
+Refer back to a stored value in plain English (`the stored price value`, `the same version as the stored api_tag value`), never as `{{price}}`. The `{{name}}` form is for global variables and secrets only (§6).
+
 ---
 
 ## 5. Chaining — action → extraction → assertion
@@ -374,6 +388,7 @@ Use `{{name}}` syntax for values that should be parameterized:
 
 **Always parameterize:** credentials, API keys, tokens, environment-specific URLs.
 **OK to hardcode:** one-off URLs, static UI text, navigation paths.
+**Never `{{name}}`:** anything the run itself produces. A stored value or an API response is referenced in plain English (§3.5, §4): `the stored order_id value`, `the response status`.
 
 Mark credentials with `secret: true` in the variables JSON so they're masked in logs and routed to the secrets store:
 
@@ -430,6 +445,7 @@ Positional assertions check where something is on the page:
 | Cram 25 operations into one objective | Split at logical boundaries (login, navigate, action, verify) | Long runs drift and stall. |
 | "Check the page is fast" | "Assert LCP is under 2500ms and CLS is below 0.1" | Use the explicit web-vital metric, not a vague "fast." |
 | "Make sure no errors" | "Assert no console errors and no API calls returned 5xx" | Be explicit about which kind of error you're checking. |
+| "Place the order, then verify it succeeded by checking Order History" | "Place the order, open Order History, then verify the newest order shows 'Processing'" | A check that needs its own navigation is an action hiding inside an assertion. Put the route in the actions and keep the assertion a pure observation of the screen it lands on. |
 | "Use DevTools to intercept the response and issue a GET to the invoice endpoint" | "Open the invoice from the order page, then verify the request to `/api/orders/42/invoice` returned 200 with `content-disposition: attachment`" | Describe the user action and the observable outcome, not the mechanism — the agent picks the method, and a prescribed mechanism it cannot perform leaves it stuck. |
 
 ---
@@ -483,7 +499,7 @@ The step body is exactly the same grammar as `kane-cli run`. Everything in this
 ```text
 "Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1},
  save the response as order,
- assert {{order.status}} is 201,
+ assert the response status is 201,
  then open https://app.example.com/orders,
  assert an order for 'sku_42' is visible"
 ```
diff --git a/.agents/skills/kane-cli/references/parsing.md b/.agents/skills/kane-cli/references/parsing.md
index 9af3442..7622576 100644
--- a/.agents/skills/kane-cli/references/parsing.md
+++ b/.agents/skills/kane-cli/references/parsing.md
@@ -8,18 +8,19 @@ With `--agent`, kane-cli outputs one JSON object per line to **stdout**. Progres
 
 ## Event Types
 
-**Progress events** (bulk of the output — one per step):
+**Progress events** (a start and completion event per step):
 
 ```json
-{"step": 1, "status": "passed", "remark": "Navigated to amazon.in"}
-{"step": 2, "status": "passed", "remark": "Typed 'laptop' in search box"}
+{"step": 1, "status": "running", "remark": "Navigate to amazon.in"}
+{"step": 1, "status": "done", "remark": "Navigated to amazon.in"}
+{"step": 2, "status": "done", "remark": "Typed 'laptop' in search box"}
 {"step": 3, "status": "failed", "remark": "Could not find Add to Cart button"}
 ```
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `step` | number | Step index (1-based) |
-| `status` | string | `"passed"` or `"failed"` |
+| `status` | string | `"running"` at start; `"done"` or `"failed"` at completion |
 | `remark` | string | What the agent did or why it failed |
 
 These are **untyped** — they have no `type` field. Do **not** key on `event.type === 'step_start'` or `'step_end'`; those event types are not emitted.
@@ -38,7 +39,7 @@ These are **untyped** — they have no `type` field. Do **not** key on `event.ty
 | `test_md_bundle_sync` | `status: "ok"\|"failed"`, `commit_id`, `bytes?` (success) / `stage?` (failure) | `testmd run` / `testmd sync`: test bundle pushed to the cloud after an authored commit. Informational. |
 | `testrun_*` family | see `references/testrun.md` | Emitted only by `kane-cli testrun run`; terminal event is `testrun_done`, not `run_end`. |
 
-**Note:** There is no `run_start` event — the first line is either a `bifurcation` or a progress object.
+**Note:** The `run` stream has no `run_start` event; startup metadata or errors can precede progress.
 
 ### `error` with `code: "unresolved_variables"` (0.8.12+)
 
@@ -64,7 +65,7 @@ Terminal: do not re-run the same command. Supply values (`--variables`, or fill
 
 **Note:** `ask_user` is auto-disabled when stdin is not a TTY. Since agents typically run kane-cli as a subprocess, ask_user events will not be emitted. Write objectives that don't require interactive input.
 
-## Parsing Strategy
+## Parsing Strategy for one-shot `run`
 
 Since progress events lack a `type` field, distinguish them from typed events like this:
 
@@ -76,9 +77,9 @@ for each line of NDJSON:
   if obj.step exists           → progress event (step/status/remark)
 ```
 
-**Build automation on `run_end`** — it is the only event guaranteed to have a stable schema across versions. Use progress events for live status display only.
+For one-shot `run`, build automation on `run_end` and process exit; other commands use the completion events listed below. Use progress events for live status display only.
 
-**Terminal event** (always the last line):
+**One-shot `run` completion event** (early refusals may exit without it):
 
 ```json
 {
@@ -129,3 +130,9 @@ To cancel a run:
 ```json
 {"type": "cancel"}
 ```
+
+## Command-specific completion
+
+The `run_end` parsing strategy applies to one-shot `run` only. For `testmd run`, collect `test_md_done.overall_status`, `duration_s`, `session_id`, and optional `share_url`; embedded `run_end` events can finish individual steps. Local suites emit `testrun_done`; dispatched remote suites then emit `remote_done` (retain `status`, `exit`, `sessions_path`). `generate` emits `generate_done`. Assurance conversational agent streams end in `done`; review/read verbs have their own contracts. Always check process exit too: early refusal, invalid plan or dry-run can exit without the normal completion event.
+
+Progress is for live display: count only `done`/`failed` completions, retaining child and execution context when step indices repeat.
diff --git a/.agents/skills/kane-cli/references/testmd.md b/.agents/skills/kane-cli/references/testmd.md
index 4efdbe5..470cbb4 100644
--- a/.agents/skills/kane-cli/references/testmd.md
+++ b/.agents/skills/kane-cli/references/testmd.md
@@ -54,7 +54,7 @@ Four parts in order:
 
 1. **YAML frontmatter** — between `--- ... ---` at the very top.
 2. **`# Title`** — decorative; everything before the first `## ` is ignored.
-3. **`## H2` step headings** — one per step. The agent reads the step body, not the heading.
+3. **`## H2` step headings** — one per step. The agent reads the step body; the parser also interprets heading markers for replay-only steps, imports and structured control flow.
 4. **Step body** — either prose **or** a single `@import <path>` line. Never both. Prose bodies are objectives with the same grammar as `kane-cli run` — for the full pattern catalog (action verbs, assertion analyze methods, checkpoint types, chaining, worked examples), Read `references/objectives-cookbook.md`.
 
 Per-step `yaml` overrides go immediately under the heading, in a fenced block:
@@ -75,7 +75,7 @@ Click submit and verify the confirmation banner.
 | `mode` | root | `action` (halts on auth walls) or `testing` (default — pushes through so negative-test assertions can fire) |
 | `url` | root | Start URL for the first step (bare domains get `https://`). Overridden by `--url`; falls back to config `default_url`. |
 | `tags` | root | Labels for batch selection: YAML list, `[a, b]`, or bare `a, b`. Trimmed, lowercased, deduped. Selected with `testrun --tags` (`references/testrun.md`); shown by `testmd list`. Empty → parse error; per-step → parse error. |
-| `max_steps` | root + step | Max agent reasoning steps. Default `30`. |
+| `max_steps` | root + step | Max agent reasoning steps. Engine fallback `30`; CLI default `50` (step config overrides). |
 | `timeout` | root + step | Hard kill per step in seconds. |
 | `headless` | root | No browser window. |
 | `variables` | root + step | `{{name}}` params, same shape as §3, with `secret: true` for credentials. Counts as a value for the pre-run check (0.8.12+) — a `{{name}}` with no value anywhere refuses the run before it starts |
@@ -88,19 +88,19 @@ Files ending in `_test.md` are tests (valid entry points). Any other `.md` is a
 
 On the **first** run of a test, the agent authors each step and saves a recording. On **every later run**, each step replays from its recording — no agent, no LLM cost, much faster.
 
-A step replays only if **all** of these hold:
+An authorable step replays only if **all** of these hold (replay-only marked steps always require their recording):
 - A recording for that step exists,
 - Its prose is unchanged since the recording,
 - Its `yaml` block is unchanged,
 - No earlier step in the file invalidated it.
 
-**Editing step N re-authors step N AND every step after it in the same file.** Each step starts where the previous step left off (URL, login, tabs). When step 3 changes, step 4 cannot safely replay against state that no longer exists.
+**Editing step N re-authors authorable steps from N onwards in that file. Replay-only marked steps still replay.** Each step starts where the previous step left off (URL, login, tabs). When step 3 changes, step 4 cannot safely replay against state that no longer exists.
 
 Consequences when editing tests:
-- A one-line tweak at the top of a 20-step test re-authors all 20 steps on the next run.
+- A one-line tweak at the top of a 20-step test re-authors all authorable steps on the next run; replay-only steps keep their recordings.
 - To re-record only one step, edit only that step (or steps after it).
-- `--author` forces full authoring for one run (debugging only).
-- `rm -rf output-<stem>/` wipes the cache entirely.
+- `--author` forces authorable steps to re-author; replay-only marked steps still require their recordings.
+- Do not delete output recordings for replay-only marked steps; they cannot be recovered by re-authoring.
 
 ## `@import` for reusing flows
 
@@ -129,7 +129,7 @@ Editing a helper re-authors that step in **every test that imports it**, plus ev
 | `kane-cli testmd run <path> --agent [flags]` | Run a test |
 | `kane-cli testmd list` | List `*_test.md` files under cwd (NDJSON when non-TTY; records include `tags`) |
 | `kane-cli testmd status <path>` | Test Manager identity + local-sync state |
-| `kane-cli testmd export <path> [--code-language python\|javascript]` | Regenerate code export from existing recordings (no browser launch) |
+| `kane-cli testmd export <path> [--language python\|javascript]` | Regenerate code export from existing recordings (no browser launch) |
 | `kane-cli testmd delete <path>` | Local-only delete: removes source + `output-<stem>/`. Does NOT delete from Test Manager. |
 | `kane-cli testmd sync <path>` | Re-push the test bundle (test + imports + outputs) to the cloud. Rarely needed — it happens automatically after every authored commit; use only to recover a failed auto-sync. |
 
@@ -143,12 +143,11 @@ Editing a helper re-authors that step in **every test that imports it**, plus ev
 | `--allow-missing-url` | off | Non-TTY only: start from the browser's current page instead of failing when the first step has no start URL. |
 | `--name <name>` | none | Persist the run under this name. Regex `[a-zA-Z0-9_-]+`. |
 | `--on-lock-conflict <readonly\|fail\|wait>` | none | Behavior when another user holds the test's edit lock. `readonly` = replay-only / no upload, `fail` = exit 2, `wait` = block until released |
-| `--retry` | off | On replay failure, restart with a shrinking replay window |
-| `--retry-count <n>` | `3` | Max retry restarts before falling back to full re-author |
-| `--author` | off | Force authoring every step (skip replay decision) |
+| `--no-adaptive-heal` | healing enabled | Disable adaptive healing after replay failure |
+| `--author` | off | Force authorable steps to re-author; replay-only steps still replay |
 | `--bug-detection <off\|stop\|continue>` | config (`off`) | Flag suspected product bugs while **authoring** (`stop` halts on a confirmed bug; `continue` records it). Replay failures always investigate regardless. |
 
-All §3 `run` flags also apply (`--agent`, `--headless`, `--max-steps`, `--timeout`, `--variables`, etc.).
+Common flags include `--agent`, `--headless`, `--max-steps`, `--timeout`, and `--variables`. Command-specific flags differ; check `kane-cli testmd run --help`.
 
 Flag wins over frontmatter for everything **except** `variables` — the file owns variables; you can add new keys via flags but cannot override file-defined ones.
 
@@ -195,14 +194,13 @@ On exit, kane-cli writes `<cwd>/.testmuai/tests/amazon-search_test.md`. Move tha
 kane-cli testmd run ./tests/checkout_test.md \
   --agent \
   --headless \
-  --on-lock-conflict wait \
-  --retry
+  --on-lock-conflict wait
 ```
 
 - `--agent` — NDJSON to stdout (auto-enabled when stdin is not a TTY; pass explicitly anyway).
 - `--headless` — no window.
 - `--on-lock-conflict wait` — block instead of failing if a teammate is editing the same test.
-- `--retry` — automatically recover transient replay failures.
+- Adaptive healing recovers replay failures by default; `--no-adaptive-heal` opts out.
 
 In non-TTY runs, interactive `ask_user` prompts are disabled — a step that would wait for input fails cleanly instead of hanging forever. Write CI test steps that don't depend on mid-run prompts. (Likewise, supply a start URL via the objective, `url:` frontmatter, or `--url`; a non-TTY run with no resolvable start URL fails unless you pass `--allow-missing-url`.)
 
@@ -234,3 +232,13 @@ Parse errors abort **before** any browser launch with exit `2`. Common ones and
 | `auth/identity keys are CLI-only` | Pass `username` / `access_key` as CLI flags, not in frontmatter |
 
 When the user reports a parse error, fix the file before retrying — don't loop on the same error.
+
+## Replay policy and completion
+
+Adaptive healing is enabled by default: after a replay failure the runner tries up to three shrinking replay windows, then full re-authoring of authorable steps. `--no-adaptive-heal` disables this recovery. Retired `--retry` and `--retry-count` are accepted only to print a notice; they do not enable healing or change the fixed budget.
+
+Headings marked `@db`, `@api`, `@js`, `@smartui`, `@network_query`, or `@network_assertion` are replay-only. They still replay under `--author`, downstream divergence and adaptive healing. Missing recordings cannot be re-authored through these markers: restore the recording or recreate it through the originating workflow. Do not delete their tapes to force authoring; adding a marker does not create an operation.
+
+Structured control flow uses balanced heading markers: `@if`, `@elif`, `@else`, `@end-if`, `@while`, `@end-while`. An `@else` must be last in its conditional; end markers must match the opened block type. These are distinct from natural-language conditionals. Markers are excluded from the step body hash. Only one replay-only kind is allowed per step, and an import cannot also be marked replay-only.
+
+Under `--agent`, wait for `test_md_done` (file-level `overall_status`, `duration_s`, `session_id`, optional `share_url`) and process exit. Individual `run_end` events do not complete the file.
diff --git a/.agents/skills/kane-cli/references/testrun.md b/.agents/skills/kane-cli/references/testrun.md
index 3604258..6691f4c 100644
--- a/.agents/skills/kane-cli/references/testrun.md
+++ b/.agents/skills/kane-cli/references/testrun.md
@@ -15,7 +15,7 @@
 ## Command
 
 ```bash
-kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdout is piped — there is NO --agent flag on testrun
+kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdin is not a TTY (use < /dev/null in terminal automation) — there is NO --agent flag on testrun
 ```
 
 `[paths...]` is optional — omit it to auto-discover every `*_test.md` under the cwd. Explicit paths must end in `_test.md`.
@@ -24,11 +24,11 @@ kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdout is
 |---|---|---|
 | `--match <regex>` | Filter candidates by project-relative path regex | — |
 | `--tags <list>` | ANY-match on frontmatter `tags:` (repeatable or comma-separated, case-insensitive) | — |
-| `--parallel <n>` | Worker count; each worker gets an isolated Chrome with a fresh temp profile | `1` |
+| `--parallel <n>` | Worker count; each desktop worker gets an isolated Chrome with a fresh temp profile | `1` |
 | `--on-failure <mode>` | `continue` (run everything) \| `fail-fast` (stop dispatching new members after a failure) | `continue` |
 | `--name <label>` | Run title in the dashboard | derived |
 | `--dry-run` | Print the plan (members + preflight failures) and exit; runs nothing | off |
-| `--retry` / `--retry-count <n>` | Replay-failure restart with shrinking replay window / max attempts | off / `3` |
+| `--no-adaptive-heal` | Disable default adaptive healing after replay failure | healing enabled |
 | `--bug-detection <mode>` | `off`\|`stop`\|`continue`, passed through to authoring members | config (`off`) |
 | `--headless` | Headless Chrome — use in CI | off |
 | `--remote [backend]` | Dispatch the suite to the HyperExecute grid instead of local Chrome / local devices (default backend `hyper`); needs `kane-cli plugin install remote-execution` — §Remote | off |
@@ -61,7 +61,7 @@ kane-cli testrun run tests/ios/ --remote --device-name "iPhone 15" --os-version
 - **`--parallel N`** becomes the job's concurrency for web and device suites alike (members auto-split across N grid tasks; a device task gets its own VM and device). **Web suites**: `--headless` is unnecessary (always headless on the grid); there is no `remote_device` event. Overhead is ~15 s of setup plus the tests' own time; a mobile job adds a minute or more for device boot.
 - **One job = one runtime.** A selection that mixes web and device members, emulator and simulator members, or emulator members on several Android versions is refused with a split suggestion (`--match`/`--tags`). Simulator members may differ in iOS version as long as they land on one HyperExecute pool (`mobile_pool_split` otherwise).
 - **Mobile app on the grid**: a member's local build (`.apk` for emulator, `.zip` for simulator, anywhere on disk) is uploaded from the laptop at preflight and handed to the grid as `--app <id>` (one `remote_app` event per distinct build); an `APP…` id is used as-is. Nothing has to be inside the project or un-gitignored; `--dry-run` uploads nothing. Details and the preflight codes: `references/mobile.md` §Remote.
-- `--author`, `--no-adaptive-heal`, `--bug-detection`, `--name`, `--on-failure` are forwarded to the grid. Use a long Bash timeout (up to 600000 ms).
+- Grid member flags include `--author` and `--no-adaptive-heal`. `--name` labels suite metadata.
 - The dispatch writes `.hyperexecute/`, `hyperexecute-cli.log`, and `.updatedhyperexecute.yaml` into the cwd — suggest gitignoring them; they are not inputs.
 
 Remote preflight refusals arrive as one `remote_error` per reason (then `testrun_done` failed, exit 2):
@@ -83,7 +83,7 @@ Remote preflight refusals arrive as one `remote_error` per reason (then `testrun
 
 ## NDJSON events (agent mode)
 
-All typed; stdout; one JSON object per line. **Terminal event: `testrun_done` — stop parsing there.**
+All typed; stdout; one JSON object per line. **Local completion: `testrun_done`. With `--remote`, keep reading through `remote_done` and process exit; preflight refusals or dry runs may exit without that wrapper event.**
 
 | `type` | Payload | Notes |
 |---|---|---|
@@ -94,7 +94,7 @@ All typed; stdout; one JSON object per line. **Terminal event: `testrun_done` 
 | `testrun_investigations_wait` | `count` | Failed replays left investigations running; the coordinator waits before sealing. Narrate as "investigating N failures". |
 | `testrun_evidence_ingest` | `status: "ok"\|"failed"`, `evidence_id`, `stage?` | Pack published to the dashboard. Absent when publish is skipped. |
 | `testrun_summary` | `totals: {tests, passed, failed, broken, skipped}`, `duration_s`, `upload`, `cancelled` | Build the rollup table from this. |
-| `testrun_done` | `execution_id`, `overall_status: "passed"\|"failed"\|"cancelled"` | Terminal. |
+| `testrun_done` | `execution_id`, `overall_status: "passed"\|"failed"\|"cancelled"` | Local completion; remote runs continue through `remote_done`. |
 
 With `--remote`, the stream is wrapped in typed `remote_*` events (all on stdout):
 
@@ -115,7 +115,8 @@ Parsing strategy:
 
 ```text
 for each line:
-  if type === "testrun_done"          → terminal, stop
+  if type === "testrun_done"          → capture suite outcome; remote runs keep reading
+  if type === "remote_done"           → capture remote status, exit and sessions_path
   if type === "testrun_plan" && !valid → report offenders, expect exit 2
   if type === "testrun_member_end"    → note per-member outcome
   if type === "testrun_summary"       → capture totals for the rollup
@@ -124,7 +125,7 @@ for each line:
 
 ## Presenting results (same discipline as SKILL.md §1)
 
-Never expose event/field names. After `testrun_done`, always render a suite rollup:
+Never expose event/field names. After completion and process exit (`remote_done` for dispatched remote runs), render a suite rollup:
 
 ```markdown
 | | |
@@ -144,3 +145,17 @@ For failures, add one line per failed member only (path + duration + status) —
 ## Evidence & debugging
 
 The suite produces **one** sealed pack, created directly in `<cwd>/.testmuai/evidence/`. Offer it to the user per `references/evidence.md`. Members run silently by design; to see per-member output while debugging, set `KANE_TESTRUN_MEMBER_DEBUG=1` (routes member events to stderr, prefixed `[member]`).
+
+## Execution constraints
+
+Local suites containing any mobile member require `--parallel 1`; larger values are refused. Isolated Chrome workers apply to desktop members only. Remote suites support grid concurrency via `--parallel N`.
+
+Healing is enabled by default (three shrinking replay windows, then re-authoring of authorable steps). `--no-adaptive-heal` disables it. Retired `--retry`/`--retry-count` only print a notice and have no effect. Replay-only recorded steps retain their recordings even during healing.
+
+NDJSON selection uses stdin, not stdout: run `kane-cli testrun run <paths> < /dev/null` for automation launched from a terminal. Dry-run validates a plan, not runtime authentication or browser/device readiness. Always observe process exit, including paths without a normal completion event.
+
+### Remote behavior still requiring verification
+
+The audited dispatch does not forward `--bug-detection` to member commands and does not map `--on-failure` into the job template. Do not rely on these flags for remote bug-detection or fail-fast behavior until implementation owners confirm or fix the mapping. `--name` is suite metadata, not a forwarded member flag.
+
+For dispatched runs, read through `remote_done` and process exit after `testrun_done`; retain the remote status and session-log path. Preflight refusal and dry-run may terminate without `remote_done`.
diff --git a/.claude/skills/kane-cli/SKILL.md b/.claude/skills/kane-cli/SKILL.md
index 32231a7..5399e4d 100644
--- a/.claude/skills/kane-cli/SKILL.md
+++ b/.claude/skills/kane-cli/SKILL.md
@@ -5,7 +5,7 @@ description: Browser automation + AI test authoring via kane-cli - run browser o
 
 # Kane CLI — Browser Automation Skill
 
-Use `kane-cli` for **any task that requires a real browser**: navigating websites, clicking elements, filling forms, searching, testing web UI, taking screenshots, or verifying deployments. Do NOT use Playwright, Puppeteer, or Selenium directly. Always run with `--agent` so output is structured NDJSON you can parse.
+Use `kane-cli` for **any task that requires a real browser**: navigating websites, clicking elements, filling forms, searching, testing web UI, taking screenshots, or verifying deployments. Do NOT use Playwright, Puppeteer, or Selenium directly. Use `--agent` for `run`, `testmd run`, and `generate`. `testrun run` has no `--agent`: it emits NDJSON when **stdin** is not a TTY (use `< /dev/null` for terminal automation). Assurance conversational commands use `--mode agent`.
 
 **Authoring test cases or scenarios?** Never write them by hand — kane-cli has two authoring pipelines, and the routing matters:
 
@@ -36,7 +36,7 @@ After that, run kane-cli normally — the variable is inherited:
 kane-cli run "<objective>" --agent <other-flags>
 ```
 
-Bash blocks until kane-cli exits, then hands you the complete stdout. Parse it, summarize what happened, and present the results table. Same pattern for `kane-cli testmd run` and `kane-cli generate`.
+Bash blocks until kane-cli exits, then hands you the complete stdout. Parse it, summarize what happened, and present the results table. Wait for process completion on `testmd run` and `generate` too, but parse their own completion events: `test_md_done` and `generate_done`, respectively. An intermediate `run_end` does not finish a saved test.
 
 Set a generous timeout (up to 600000ms) since browser runs can take a while.
 
@@ -100,7 +100,7 @@ The terminal event has `type: "run_end"` and stable fields: `status`, `summary`,
 | 🟢 **Result** | Passed |
 | 🎯 **Task** | <one_liner> |
 | ⏱️ **Duration** | <duration>s |
-| 👣 **Steps taken** | <count of progress events> |
+| 👣 **Steps taken** | <count of completed progress events (done/failed), retaining child/execution context> |
 | 📝 **What happened** | <summary> |
 | 🔗 **View details** | [Open in KaneAI Dashboard](<test_url>) |
 ```
@@ -184,7 +184,7 @@ kane-cli run "<objective>" --agent [options]
 | `--variables <json>` | Inline variables JSON (for `{{key}}` in objective) | None |
 | `--variables-file <path>` | Load variables from a JSON file | None |
 | `--ws-endpoint <url>` | Remote browser (LambdaTest grid) | Local Chrome |
-| `--code-export` | Generate code export after upload | Off |
+| `--code-export` | Generate code export after upload | config (`true` by default) |
 | `--bug-detection <mode>` | Flag suspected product bugs while authoring: `off`/`stop`/`continue` (`stop` halts on a confirmed bug; `continue` records and keeps going) | config value (`off`) |
 
 Other flags (`--global-context`, `--local-context`, `--cdp-endpoint`, `--allow-missing-url`) and the full variables precedence chain live in `references/setup-and-config.md`.
@@ -222,11 +222,11 @@ How you phrase the objective string determines what the agent does. Four pattern
 | 🎯 **Action** | "go to", "click", "type", "search", "fill" | Performs browser actions |
 | ✅ **Assertion** | "assert", "verify", "confirm", "check that" | Pass/fail check on a condition |
 | 📦 **Extraction** | "store X as 'name'" | Persists a value into `run_end.final_state` |
-| 🔌 **API call** | "call", "POST/GET a URL", a pasted `curl` | The agent makes the HTTP request itself; "save the response as X", then assert/reference `{{X.status}}` / `{{X.response_body…}}` |
+| 🔌 **API call** | "call", "POST/GET a URL", a pasted `curl` | The agent makes the HTTP request itself; "save the response as X", then assert on it in plain English: "assert the response status is 200", "store the id from the response body as 'order_id'" |
 
 ### Two rules that make an objective replayable
 
-1. **End every flow in a terminal assertion.** Close with a check of the resulting page state (`verify the cart shows 1 item`), not a bare `submit` or `confirm the dialog`. A run only earns a replayable pass/fail from a verify/assert — a pure-action objective (`add a laptop to the cart`) gets none. If the objective has several phases, each ends in its own check. Two traps: `confirm the dialog` is an action, not a check; and `verify the Submit button is visible` fails exactly when the action worked (the control disappears on success) — assert the outcome, not the trigger.
+1. **End every flow in a terminal assertion.** Close with a check of the resulting page state (`verify the cart shows 1 item`), not a bare `submit` or `confirm the dialog`. A run only earns a replayable pass/fail from a verify/assert — a pure-action objective (`add a laptop to the cart`) gets none. If the objective has several phases, each ends in its own check. Phrase the closing check as what is on screen once the last action completes, so it verifies with no further click or navigation; if the evidence is elsewhere, make getting there an explicit action (`place the order, open Order History, then verify the newest order shows "Processing"`), never `verify the order succeeded by checking Order History`. Two traps: `confirm the dialog` is an action, not a check; and `verify the Submit button is visible` fails exactly when the action worked (the control disappears on success) — assert the outcome, not the trigger.
 2. **Intent for the actions, literal for the data.** Phrase actions as goals (`Log in with {{user}}`) so the run absorbs layout drift; keep exact values literal or in `{{variables}}`. An expected-optional branch (a sometimes-there cookie banner) goes in an `if/else`, not assumed away.
 
 **Shape:** an intent action carrying literal data, then a verify of an observable end state — `Search for "{{query}}" and open the first result, then verify the title contains "{{query}}"`. Full grammar in `references/objectives-cookbook.md §1`.
@@ -238,7 +238,7 @@ Vague phrasing like "read", "tell me", "report" does NOT reliably extract data 
 ❌ `"go to example.com and read the page title"`
 ✅ `"go to example.com, store the page title as 'page_title'"`
 
-Stored values appear in `run_end.final_state` and become the second results table per §1.4.
+Stored values appear in `run_end.final_state` and become the second results table per §1.4. Refer back to a stored value in plain English (`the stored price value`), never as `{{price}}`; `{{name}}` is for global variables and secrets only.
 
 ### Calling APIs directly
 
@@ -246,10 +246,10 @@ The agent can make API calls itself — not just observe the page's traffic. Phr
 
 ```text
 "Call POST https://api.example.com/login with body {...}, save the response as login,
- assert {{login.status}} is 200"
+ assert the response status is 200"
 ```
 
-Reference the saved response as `{{login.status}}`, `{{login.response_body}}`, or `{{login.response_body.<field>}}`; a pasted `curl` works too. Full grammar in `references/objectives-cookbook.md` §3.5.
+Use the response in plain English: `the response status`, `store the id from the response body as 'order_id'`, and later `the stored order_id value`. Never `{{login.status}}`: `{{name}}` is reserved for global variables and secrets. A pasted `curl` works too. Full grammar in `references/objectives-cookbook.md` §3.5.
 
 ### Chaining
 
@@ -269,18 +269,19 @@ Action → extraction → assertion in one objective:
 | Specific: "click the 'Add to Cart' button" | Vague: "add the item" |
 | Name extractions: "store X as 'price'" | Hope for values: "tell me the price" |
 | `{{variables}}` for credentials/URLs | Hardcode secrets in the objective |
+| Plain English for values the run produces: "the stored price value", "the response status" | `{{price}}` / `{{login.status}}` for a stored value or an API response |
 | Always include starting URL | Assume the agent knows where to start |
 | Split mega-objectives (>15 steps) into multiple runs | Cram everything into one |
 
 ---
 
-## 5. Parsing `--agent` output — essentials
+## 5. Parsing one-shot `run --agent` output — essentials
 
 > Internal reference only. Never expose these field names to the user — translate them per §1.
 
 Stdout is NDJSON, one event per line. There are two shapes:
 
-- **Progress events** (most events) have `step` (1-based), `status` (`passed`/`failed`), `remark` — and **no `type` field**.
+- **Progress events** (most events) have `step` (1-based), `status` (`running` at start, `done`/`failed` at completion), `remark` — and **no `type` field**.
 - **Typed events** have a `type` field: `project_folder_auto_defaulted` (run-startup gate, fires before any progress when no project/folder is configured), `bifurcation`, `child_agent_start`, `child_agent_end`, `ask_user`, `error` (an `error` with `code: "unresolved_variables"` is a pre-run refusal and the **only** line — no `run_end` follows; handle per §3), and finally `run_end`.
 
 Parsing strategy:
@@ -292,7 +293,7 @@ for each line:
   else if obj.step exists    → progress event → summarize per §1.3
 ```
 
-`run_end` is the only event with a stable cross-version schema — build all post-run logic on it.
+For one-shot `run`, build post-run logic on `run_end` and process exit. Saved tests and suites use their own completion events (see Command-specific completion below).
 
 For full event schemas (`bifurcation` flow fields, `child_agent_*`, `ask_user` semantics, `cancel`/`user_response` outbound events, complete `run_end` field list), Read `references/parsing.md`.
 
@@ -363,3 +364,12 @@ Internal event/field names (`generate_snapshot`, `request_id`, …) are for pars
 | Browse / create projects or folders, or parse the auto-default event | `references/test-manager.md` |
 | First-time install, auth, or full config | `references/setup-and-config.md` |
 | Compare / evaluate / benchmark kane-cli vs another tool or approach (cost, tokens, effort, ROI) | `references/fair-evaluation.md` |
+
+## Command-specific completion
+
+The `run_end` parsing strategy applies to one-shot `run` only. For `testmd run`, collect `test_md_done.overall_status`, `duration_s`, `session_id`, and optional `share_url`; embedded `run_end` events can finish individual steps. Local suites emit `testrun_done`; dispatched remote suites then emit `remote_done` (retain `status`, `exit`, `sessions_path`). `generate` emits `generate_done`. Assurance conversational agent streams end in `done`; review/read verbs have their own contracts. Always check process exit too: early refusal, invalid plan or dry-run can exit without the normal completion event.
+
+Progress is for live display: count only `done`/`failed` completions, retaining child and execution context when step indices repeat.
+
+
+For assertion mode, optional final validation, current-page `--analyzer-only` checks, streaming-network capture, and code-export defaults, read [Execution controls](references/execution-controls.md).
diff --git a/.claude/skills/kane-cli/references/assurance.md b/.claude/skills/kane-cli/references/assurance.md
index 24f994e..cab6a28 100644
--- a/.claude/skills/kane-cli/references/assurance.md
+++ b/.claude/skills/kane-cli/references/assurance.md
@@ -229,3 +229,13 @@ Never `context ingest` the new version first — reconcile does its own re-inges
 - **One stream.** The re-extract child's events ride the reconcile stream itself, stamped `verb: "reconcile"` — parse per `references/assurance-parsing.md`.
 
 For staleness that arrived outside a reconcile, `kane-cli maintain evolve` re-designs a use-case — it is interactive-only (the blast-radius confirmation is the point); suggest the user run it in a terminal rather than scripting around it.
+
+## Sharing a context store
+
+For location setup, sync, pull, push, clone and rebase recovery, see [Sharing the context store](context-sync.md).
+
+## Lifecycle automation contracts
+
+`context name`, `context retire`, and `context revert` accept `--mode agent` and emit an envelope ending in `done`. Destructive agent-mode operations require `--yes` even when stdin is a TTY. Other modes retain human output. Read commands use their documented `--json` flags; do not assume they all accept `--mode`.
+
+`context review --mode agent` / `--json` returns review outcome rows on success rather than the conversational `done` contract. Early agent-mode errors may emit `error` plus `done`; check command-specific output and process exit.
diff --git a/.claude/skills/kane-cli/references/evidence.md b/.claude/skills/kane-cli/references/evidence.md
index f11b229..e299539 100644
--- a/.claude/skills/kane-cli/references/evidence.md
+++ b/.claude/skills/kane-cli/references/evidence.md
@@ -73,3 +73,9 @@ Combines packs (execution ids or paths, order-significant) into one, sealed by d
 ## Debugging with a pack
 
 The pack is the first place to look on a failure: the failed step's **failure record** (error + page state), its **console/network slice** (4xx/5xx or JS errors usually explain it), and the **annotated screenshot** (what the agent actually acted on). Full failure workflow: `references/debug.md`.
+
+## Evidence merge identity
+
+For ordinary runs, default merge identity distinguishes the test and commit (`external_id.test_id`, `external_id.commit_id`) and the environment (`environment.os`, `environment.os_version`, `environment.browser`, `environment.browser_version`). Re-runs with the same identity nest as attempts; a different environment produces a separate sibling.
+
+Explicit collision policies can change grouping; a custom `--rules` file replaces the default rules rather than extending them. Check the selected identity rules before interpreting two runs as retries of the same test.
diff --git a/.claude/skills/kane-cli/references/execution-controls.md b/.claude/skills/kane-cli/references/execution-controls.md
new file mode 100644
index 0000000..5cae455
--- /dev/null
+++ b/.claude/skills/kane-cli/references/execution-controls.md
@@ -0,0 +1,11 @@
+# Execution controls
+
+## Assertion controls and current-page analysis
+
+`run` and `testmd run` support `--assertion-mode dom|visual` (default `dom` with vision fallback) and `--final-validation on|off` (default off). Persist with `config set-assertion-mode` and `config set-final-validation`. Final validation controls the synthesized `cp_final` checkpoint independently of action/testing mode; keep explicit terminal assertions in objectives.
+
+`run --analyzer-only --condition "<condition>"` checks the current desktop browser page without an objective, action steps or saved test. Repeat `--condition` for multiple checks. Use `--agent` or non-TTY input. Results contain `condition_results: boolean[]`; exit `0` means all conditions were judged, **not** that all are true. Exit `1` means a result was missing, and `3` means cancelled. This mode rejects mobile target/app/device options and code-export/name options.
+
+Experimental `run --network-ws` and `run --network-sse` enable WebSocket and SSE capture; both default off. Persist with `config set-network-ws on|off` and `config set-network-sse on|off`. SSE capture is Chromium-only. Do not copy these run-only flags onto `testmd` or `testrun` commands.
+
+Code export defaults to enabled, subject to saved configuration, and supports `python` (default) or `javascript`. `run`/`testmd run` use `--code-language`; `testmd export` uses `--language`. Upload eligibility is independent of action/testing mode.
\ No newline at end of file
diff --git a/.claude/skills/kane-cli/references/fair-evaluation.md b/.claude/skills/kane-cli/references/fair-evaluation.md
index 5eced3f..2b8f1e6 100644
--- a/.claude/skills/kane-cli/references/fair-evaluation.md
+++ b/.claude/skills/kane-cli/references/fair-evaluation.md
@@ -17,7 +17,7 @@ The most common evaluation error is pitting kane-cli **authoring** against the o
 |---|---|---|
 | **Create the test** | AI authoring — tokens, one-time | Agent/human **generates** the script — tokens and/or engineer hours, one-time |
 | **Run the test** | Replay from cache — ~0 LLM | Execute the script — ~0 LLM |
-| **UI changes / locator breaks** | Re-author only the failing step + downstream (`--retry` shrinking window); cost ∝ change | Human/agent finds & fixes broken selectors; debug the script |
+| **UI changes / locator breaks** | Re-author only the failing step + downstream (default adaptive healing); cost ∝ change | Human/agent finds & fixes broken selectors; debug the script |
 | **Ongoing maintenance** | Edit plain-English Markdown; cascade re-authors only forward; shared `@import` helpers fix once | Edit code; flaky-wait/fixture upkeep; selector churn |
 | **Verify pass/fail** | Deterministic asserts (URL/title/DOM/network/console/cookies); AI vision only for ~10% visual checks | Code assertions; or a separate LLM judge if the check is semantic/visual |
 
diff --git a/.claude/skills/kane-cli/references/mobile.md b/.claude/skills/kane-cli/references/mobile.md
index d434ec3..222a8c4 100644
--- a/.claude/skills/kane-cli/references/mobile.md
+++ b/.claude/skills/kane-cli/references/mobile.md
@@ -144,8 +144,8 @@ What to present after `testrun_done`/`remote_done`: the suite rollup (per `refer
 
 The **same natural-language objective grammar** applies (`references/objectives-cookbook.md`): action verbs, assertions, extractions ("store as"), if/else, chaining, and variables all carry over. A mobile run just drives an app instead of a page.
 
-The exception is **browser/DevTools-only checkpoints**, which are **web-only** and do not apply to a mobile run:
-
-- Network (HTTP traffic), Console, DOM/selectors, Cookies, localStorage, Core Web Vitals (LCP/CLS/INP/FCP/TTFB).
+Mobile capability depends on the platform and app. The implementation includes native network operations and Android cookie/storage access for visible Chrome or debuggable WebViews. This does not establish full desktop DevTools parity, general native DOM support, or equivalent iOS support. Verify device/app prerequisites and the specific checkpoint before relying on it; live platform parity remains unverified.
 
 Write mobile objectives around what the app shows and does (open a screen, tap, type, assert visible text/state, store a value). And never point a mobile run at a URL: a mobile run drives an app, not a website.
+
+In the interactive TUI, `/mobile` and `/desktop` can switch targets before the first dispatch. The target locks after dispatch; use `/new` to start a new session before switching.
diff --git a/.claude/skills/kane-cli/references/objectives-cookbook.md b/.claude/skills/kane-cli/references/objectives-cookbook.md
index 920745d..be6b2a9 100644
--- a/.claude/skills/kane-cli/references/objectives-cookbook.md
+++ b/.claude/skills/kane-cli/references/objectives-cookbook.md
@@ -4,7 +4,7 @@
 
 Read this whenever you're constructing the prose objective for `kane-cli run "<objective>"` or the body of a `## Step` in a `_test.md` file. Both surfaces feed the same agent and accept the same grammar.
 
-> **Mobile runs** (`--target emulator|simulator`, macOS Apple Silicon) share this same objective grammar, but the browser/DevTools-only checkpoints below (Network, Console, DOM/selectors, Cookies, localStorage, Core Web Vitals) are **web-only** and do not apply. Read `references/mobile.md`.
+> **Mobile runs** (`--target emulator|simulator`) share this objective grammar. Checkpoint support depends on platform and app: native network and Android Chrome/debuggable-WebView storage paths exist, but desktop parity and iOS equivalents must be verified. Read `references/mobile.md` for the capability boundary and local/cloud prerequisites.
 
 ---
 
@@ -38,6 +38,15 @@ Close each objective with a claim about the resulting **page state** — not a b
 
 If an objective has several phases (log in, then search, then check out), **each phase ends in its own assertion** — an intermediate phase with no check runs unverified, and a replay can't tell you which phase drifted.
 
+**The closing assertion is a look, not a trip.** Phrase it as a claim about what is on screen once the last action completes, so the agent verifies it without clicking, navigating, scrolling, or typing anywhere else. If the evidence lives somewhere else (Order History, the cart, a details drawer), add the action that gets there as its own step, then assert.
+
+```text
+❌ Place the order, then verify it succeeded by checking that it appears in Order History
+✅ Place the order, open Order History, then verify the newest order shows "Processing"
+```
+
+The ❌ version hides an action inside a check. The agent has to find its own way to Order History on every run, so the route can differ between runs and is never a step you can read or fix. The ✅ version keeps the route in the actions and leaves the assertion a pure observation of the page it lands on.
+
 Two things look like assertions but are not:
 
 - **A UI-commit "confirm" is an action, not a check.** `confirm the dialog` / `click OK to confirm` presses a control; it verifies nothing about the outcome. Follow it with a real check: `… then verify the confirmation reads "Order placed"`.
@@ -277,19 +286,22 @@ A pasted `curl` works too and is kept verbatim (method, headers, body, auth):
 curl -X POST https://api.example.com/login -H 'Content-Type: application/json' -d '{"u":"a","p":"b"}', save the response as login
 ```
 
-Once saved, reference the response by name:
+Once the call is made, use the response in plain English. `{{name}}` is reserved for global variables and secrets (§6); a value the run produces is never written that way.
 
-| Reference | Resolves to |
+| To use | Say |
 |---|---|
-| `{{order.status}}` | the HTTP status code (e.g. `201`) |
-| `{{order.response_body}}` | the whole response body |
-| `{{order.response_body.<field>}}` | a field from the JSON response body |
+| the HTTP status code | `assert the response status is 201` |
+| a field from the JSON body | `store the id from the response body as 'order_id'` |
+| the whole body | `store the response body as 'order_body'` |
+| a value later in the run | `the stored order_id value` |
+
+When one objective makes several calls, name each response (`save the response as order`) and say which one you mean: `assert the order response status is 201`.
 
 Then assert or chain on it — API calls and browser actions mix freely in one objective:
 
 ```text
 Call POST https://api.example.com/login with body {"u": "{{user}}", "p": "{{password}}"}, save the response as login,
-assert {{login.status}} is 200,
+assert the response status is 200,
 then open https://app.example.com and verify the dashboard loads
 ```
 
@@ -322,6 +334,8 @@ For DevTools extractions, the same rule applies — use "store" or "extract":
 
 Stored values land in `run_end.final_state` and feed the second results table per `SKILL.md §1.4`.
 
+Refer back to a stored value in plain English (`the stored price value`, `the same version as the stored api_tag value`), never as `{{price}}`. The `{{name}}` form is for global variables and secrets only (§6).
+
 ---
 
 ## 5. Chaining — action → extraction → assertion
@@ -374,6 +388,7 @@ Use `{{name}}` syntax for values that should be parameterized:
 
 **Always parameterize:** credentials, API keys, tokens, environment-specific URLs.
 **OK to hardcode:** one-off URLs, static UI text, navigation paths.
+**Never `{{name}}`:** anything the run itself produces. A stored value or an API response is referenced in plain English (§3.5, §4): `the stored order_id value`, `the response status`.
 
 Mark credentials with `secret: true` in the variables JSON so they're masked in logs and routed to the secrets store:
 
@@ -430,6 +445,7 @@ Positional assertions check where something is on the page:
 | Cram 25 operations into one objective | Split at logical boundaries (login, navigate, action, verify) | Long runs drift and stall. |
 | "Check the page is fast" | "Assert LCP is under 2500ms and CLS is below 0.1" | Use the explicit web-vital metric, not a vague "fast." |
 | "Make sure no errors" | "Assert no console errors and no API calls returned 5xx" | Be explicit about which kind of error you're checking. |
+| "Place the order, then verify it succeeded by checking Order History" | "Place the order, open Order History, then verify the newest order shows 'Processing'" | A check that needs its own navigation is an action hiding inside an assertion. Put the route in the actions and keep the assertion a pure observation of the screen it lands on. |
 | "Use DevTools to intercept the response and issue a GET to the invoice endpoint" | "Open the invoice from the order page, then verify the request to `/api/orders/42/invoice` returned 200 with `content-disposition: attachment`" | Describe the user action and the observable outcome, not the mechanism — the agent picks the method, and a prescribed mechanism it cannot perform leaves it stuck. |
 
 ---
@@ -483,7 +499,7 @@ The step body is exactly the same grammar as `kane-cli run`. Everything in this
 ```text
 "Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1},
  save the response as order,
- assert {{order.status}} is 201,
+ assert the response status is 201,
  then open https://app.example.com/orders,
  assert an order for 'sku_42' is visible"
 ```
diff --git a/.claude/skills/kane-cli/references/parsing.md b/.claude/skills/kane-cli/references/parsing.md
index 9af3442..7622576 100644
--- a/.claude/skills/kane-cli/references/parsing.md
+++ b/.claude/skills/kane-cli/references/parsing.md
@@ -8,18 +8,19 @@ With `--agent`, kane-cli outputs one JSON object per line to **stdout**. Progres
 
 ## Event Types
 
-**Progress events** (bulk of the output — one per step):
+**Progress events** (a start and completion event per step):
 
 ```json
-{"step": 1, "status": "passed", "remark": "Navigated to amazon.in"}
-{"step": 2, "status": "passed", "remark": "Typed 'laptop' in search box"}
+{"step": 1, "status": "running", "remark": "Navigate to amazon.in"}
+{"step": 1, "status": "done", "remark": "Navigated to amazon.in"}
+{"step": 2, "status": "done", "remark": "Typed 'laptop' in search box"}
 {"step": 3, "status": "failed", "remark": "Could not find Add to Cart button"}
 ```
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `step` | number | Step index (1-based) |
-| `status` | string | `"passed"` or `"failed"` |
+| `status` | string | `"running"` at start; `"done"` or `"failed"` at completion |
 | `remark` | string | What the agent did or why it failed |
 
 These are **untyped** — they have no `type` field. Do **not** key on `event.type === 'step_start'` or `'step_end'`; those event types are not emitted.
@@ -38,7 +39,7 @@ These are **untyped** — they have no `type` field. Do **not** key on `event.ty
 | `test_md_bundle_sync` | `status: "ok"\|"failed"`, `commit_id`, `bytes?` (success) / `stage?` (failure) | `testmd run` / `testmd sync`: test bundle pushed to the cloud after an authored commit. Informational. |
 | `testrun_*` family | see `references/testrun.md` | Emitted only by `kane-cli testrun run`; terminal event is `testrun_done`, not `run_end`. |
 
-**Note:** There is no `run_start` event — the first line is either a `bifurcation` or a progress object.
+**Note:** The `run` stream has no `run_start` event; startup metadata or errors can precede progress.
 
 ### `error` with `code: "unresolved_variables"` (0.8.12+)
 
@@ -64,7 +65,7 @@ Terminal: do not re-run the same command. Supply values (`--variables`, or fill
 
 **Note:** `ask_user` is auto-disabled when stdin is not a TTY. Since agents typically run kane-cli as a subprocess, ask_user events will not be emitted. Write objectives that don't require interactive input.
 
-## Parsing Strategy
+## Parsing Strategy for one-shot `run`
 
 Since progress events lack a `type` field, distinguish them from typed events like this:
 
@@ -76,9 +77,9 @@ for each line of NDJSON:
   if obj.step exists           → progress event (step/status/remark)
 ```
 
-**Build automation on `run_end`** — it is the only event guaranteed to have a stable schema across versions. Use progress events for live status display only.
+For one-shot `run`, build automation on `run_end` and process exit; other commands use the completion events listed below. Use progress events for live status display only.
 
-**Terminal event** (always the last line):
+**One-shot `run` completion event** (early refusals may exit without it):
 
 ```json
 {
@@ -129,3 +130,9 @@ To cancel a run:
 ```json
 {"type": "cancel"}
 ```
+
+## Command-specific completion
+
+The `run_end` parsing strategy applies to one-shot `run` only. For `testmd run`, collect `test_md_done.overall_status`, `duration_s`, `session_id`, and optional `share_url`; embedded `run_end` events can finish individual steps. Local suites emit `testrun_done`; dispatched remote suites then emit `remote_done` (retain `status`, `exit`, `sessions_path`). `generate` emits `generate_done`. Assurance conversational agent streams end in `done`; review/read verbs have their own contracts. Always check process exit too: early refusal, invalid plan or dry-run can exit without the normal completion event.
+
+Progress is for live display: count only `done`/`failed` completions, retaining child and execution context when step indices repeat.
diff --git a/.claude/skills/kane-cli/references/testmd.md b/.claude/skills/kane-cli/references/testmd.md
index 4efdbe5..470cbb4 100644
--- a/.claude/skills/kane-cli/references/testmd.md
+++ b/.claude/skills/kane-cli/references/testmd.md
@@ -54,7 +54,7 @@ Four parts in order:
 
 1. **YAML frontmatter** — between `--- ... ---` at the very top.
 2. **`# Title`** — decorative; everything before the first `## ` is ignored.
-3. **`## H2` step headings** — one per step. The agent reads the step body, not the heading.
+3. **`## H2` step headings** — one per step. The agent reads the step body; the parser also interprets heading markers for replay-only steps, imports and structured control flow.
 4. **Step body** — either prose **or** a single `@import <path>` line. Never both. Prose bodies are objectives with the same grammar as `kane-cli run` — for the full pattern catalog (action verbs, assertion analyze methods, checkpoint types, chaining, worked examples), Read `references/objectives-cookbook.md`.
 
 Per-step `yaml` overrides go immediately under the heading, in a fenced block:
@@ -75,7 +75,7 @@ Click submit and verify the confirmation banner.
 | `mode` | root | `action` (halts on auth walls) or `testing` (default — pushes through so negative-test assertions can fire) |
 | `url` | root | Start URL for the first step (bare domains get `https://`). Overridden by `--url`; falls back to config `default_url`. |
 | `tags` | root | Labels for batch selection: YAML list, `[a, b]`, or bare `a, b`. Trimmed, lowercased, deduped. Selected with `testrun --tags` (`references/testrun.md`); shown by `testmd list`. Empty → parse error; per-step → parse error. |
-| `max_steps` | root + step | Max agent reasoning steps. Default `30`. |
+| `max_steps` | root + step | Max agent reasoning steps. Engine fallback `30`; CLI default `50` (step config overrides). |
 | `timeout` | root + step | Hard kill per step in seconds. |
 | `headless` | root | No browser window. |
 | `variables` | root + step | `{{name}}` params, same shape as §3, with `secret: true` for credentials. Counts as a value for the pre-run check (0.8.12+) — a `{{name}}` with no value anywhere refuses the run before it starts |
@@ -88,19 +88,19 @@ Files ending in `_test.md` are tests (valid entry points). Any other `.md` is a
 
 On the **first** run of a test, the agent authors each step and saves a recording. On **every later run**, each step replays from its recording — no agent, no LLM cost, much faster.
 
-A step replays only if **all** of these hold:
+An authorable step replays only if **all** of these hold (replay-only marked steps always require their recording):
 - A recording for that step exists,
 - Its prose is unchanged since the recording,
 - Its `yaml` block is unchanged,
 - No earlier step in the file invalidated it.
 
-**Editing step N re-authors step N AND every step after it in the same file.** Each step starts where the previous step left off (URL, login, tabs). When step 3 changes, step 4 cannot safely replay against state that no longer exists.
+**Editing step N re-authors authorable steps from N onwards in that file. Replay-only marked steps still replay.** Each step starts where the previous step left off (URL, login, tabs). When step 3 changes, step 4 cannot safely replay against state that no longer exists.
 
 Consequences when editing tests:
-- A one-line tweak at the top of a 20-step test re-authors all 20 steps on the next run.
+- A one-line tweak at the top of a 20-step test re-authors all authorable steps on the next run; replay-only steps keep their recordings.
 - To re-record only one step, edit only that step (or steps after it).
-- `--author` forces full authoring for one run (debugging only).
-- `rm -rf output-<stem>/` wipes the cache entirely.
+- `--author` forces authorable steps to re-author; replay-only marked steps still require their recordings.
+- Do not delete output recordings for replay-only marked steps; they cannot be recovered by re-authoring.
 
 ## `@import` for reusing flows
 
@@ -129,7 +129,7 @@ Editing a helper re-authors that step in **every test that imports it**, plus ev
 | `kane-cli testmd run <path> --agent [flags]` | Run a test |
 | `kane-cli testmd list` | List `*_test.md` files under cwd (NDJSON when non-TTY; records include `tags`) |
 | `kane-cli testmd status <path>` | Test Manager identity + local-sync state |
-| `kane-cli testmd export <path> [--code-language python\|javascript]` | Regenerate code export from existing recordings (no browser launch) |
+| `kane-cli testmd export <path> [--language python\|javascript]` | Regenerate code export from existing recordings (no browser launch) |
 | `kane-cli testmd delete <path>` | Local-only delete: removes source + `output-<stem>/`. Does NOT delete from Test Manager. |
 | `kane-cli testmd sync <path>` | Re-push the test bundle (test + imports + outputs) to the cloud. Rarely needed — it happens automatically after every authored commit; use only to recover a failed auto-sync. |
 
@@ -143,12 +143,11 @@ Editing a helper re-authors that step in **every test that imports it**, plus ev
 | `--allow-missing-url` | off | Non-TTY only: start from the browser's current page instead of failing when the first step has no start URL. |
 | `--name <name>` | none | Persist the run under this name. Regex `[a-zA-Z0-9_-]+`. |
 | `--on-lock-conflict <readonly\|fail\|wait>` | none | Behavior when another user holds the test's edit lock. `readonly` = replay-only / no upload, `fail` = exit 2, `wait` = block until released |
-| `--retry` | off | On replay failure, restart with a shrinking replay window |
-| `--retry-count <n>` | `3` | Max retry restarts before falling back to full re-author |
-| `--author` | off | Force authoring every step (skip replay decision) |
+| `--no-adaptive-heal` | healing enabled | Disable adaptive healing after replay failure |
+| `--author` | off | Force authorable steps to re-author; replay-only steps still replay |
 | `--bug-detection <off\|stop\|continue>` | config (`off`) | Flag suspected product bugs while **authoring** (`stop` halts on a confirmed bug; `continue` records it). Replay failures always investigate regardless. |
 
-All §3 `run` flags also apply (`--agent`, `--headless`, `--max-steps`, `--timeout`, `--variables`, etc.).
+Common flags include `--agent`, `--headless`, `--max-steps`, `--timeout`, and `--variables`. Command-specific flags differ; check `kane-cli testmd run --help`.
 
 Flag wins over frontmatter for everything **except** `variables` — the file owns variables; you can add new keys via flags but cannot override file-defined ones.
 
@@ -195,14 +194,13 @@ On exit, kane-cli writes `<cwd>/.testmuai/tests/amazon-search_test.md`. Move tha
 kane-cli testmd run ./tests/checkout_test.md \
   --agent \
   --headless \
-  --on-lock-conflict wait \
-  --retry
+  --on-lock-conflict wait
 ```
 
 - `--agent` — NDJSON to stdout (auto-enabled when stdin is not a TTY; pass explicitly anyway).
 - `--headless` — no window.
 - `--on-lock-conflict wait` — block instead of failing if a teammate is editing the same test.
-- `--retry` — automatically recover transient replay failures.
+- Adaptive healing recovers replay failures by default; `--no-adaptive-heal` opts out.
 
 In non-TTY runs, interactive `ask_user` prompts are disabled — a step that would wait for input fails cleanly instead of hanging forever. Write CI test steps that don't depend on mid-run prompts. (Likewise, supply a start URL via the objective, `url:` frontmatter, or `--url`; a non-TTY run with no resolvable start URL fails unless you pass `--allow-missing-url`.)
 
@@ -234,3 +232,13 @@ Parse errors abort **before** any browser launch with exit `2`. Common ones and
 | `auth/identity keys are CLI-only` | Pass `username` / `access_key` as CLI flags, not in frontmatter |
 
 When the user reports a parse error, fix the file before retrying — don't loop on the same error.
+
+## Replay policy and completion
+
+Adaptive healing is enabled by default: after a replay failure the runner tries up to three shrinking replay windows, then full re-authoring of authorable steps. `--no-adaptive-heal` disables this recovery. Retired `--retry` and `--retry-count` are accepted only to print a notice; they do not enable healing or change the fixed budget.
+
+Headings marked `@db`, `@api`, `@js`, `@smartui`, `@network_query`, or `@network_assertion` are replay-only. They still replay under `--author`, downstream divergence and adaptive healing. Missing recordings cannot be re-authored through these markers: restore the recording or recreate it through the originating workflow. Do not delete their tapes to force authoring; adding a marker does not create an operation.
+
+Structured control flow uses balanced heading markers: `@if`, `@elif`, `@else`, `@end-if`, `@while`, `@end-while`. An `@else` must be last in its conditional; end markers must match the opened block type. These are distinct from natural-language conditionals. Markers are excluded from the step body hash. Only one replay-only kind is allowed per step, and an import cannot also be marked replay-only.
+
+Under `--agent`, wait for `test_md_done` (file-level `overall_status`, `duration_s`, `session_id`, optional `share_url`) and process exit. Individual `run_end` events do not complete the file.
diff --git a/.claude/skills/kane-cli/references/testrun.md b/.claude/skills/kane-cli/references/testrun.md
index 3604258..6691f4c 100644
--- a/.claude/skills/kane-cli/references/testrun.md
+++ b/.claude/skills/kane-cli/references/testrun.md
@@ -15,7 +15,7 @@
 ## Command
 
 ```bash
-kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdout is piped — there is NO --agent flag on testrun
+kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdin is not a TTY (use < /dev/null in terminal automation) — there is NO --agent flag on testrun
 ```
 
 `[paths...]` is optional — omit it to auto-discover every `*_test.md` under the cwd. Explicit paths must end in `_test.md`.
@@ -24,11 +24,11 @@ kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdout is
 |---|---|---|
 | `--match <regex>` | Filter candidates by project-relative path regex | — |
 | `--tags <list>` | ANY-match on frontmatter `tags:` (repeatable or comma-separated, case-insensitive) | — |
-| `--parallel <n>` | Worker count; each worker gets an isolated Chrome with a fresh temp profile | `1` |
+| `--parallel <n>` | Worker count; each desktop worker gets an isolated Chrome with a fresh temp profile | `1` |
 | `--on-failure <mode>` | `continue` (run everything) \| `fail-fast` (stop dispatching new members after a failure) | `continue` |
 | `--name <label>` | Run title in the dashboard | derived |
 | `--dry-run` | Print the plan (members + preflight failures) and exit; runs nothing | off |
-| `--retry` / `--retry-count <n>` | Replay-failure restart with shrinking replay window / max attempts | off / `3` |
+| `--no-adaptive-heal` | Disable default adaptive healing after replay failure | healing enabled |
 | `--bug-detection <mode>` | `off`\|`stop`\|`continue`, passed through to authoring members | config (`off`) |
 | `--headless` | Headless Chrome — use in CI | off |
 | `--remote [backend]` | Dispatch the suite to the HyperExecute grid instead of local Chrome / local devices (default backend `hyper`); needs `kane-cli plugin install remote-execution` — §Remote | off |
@@ -61,7 +61,7 @@ kane-cli testrun run tests/ios/ --remote --device-name "iPhone 15" --os-version
 - **`--parallel N`** becomes the job's concurrency for web and device suites alike (members auto-split across N grid tasks; a device task gets its own VM and device). **Web suites**: `--headless` is unnecessary (always headless on the grid); there is no `remote_device` event. Overhead is ~15 s of setup plus the tests' own time; a mobile job adds a minute or more for device boot.
 - **One job = one runtime.** A selection that mixes web and device members, emulator and simulator members, or emulator members on several Android versions is refused with a split suggestion (`--match`/`--tags`). Simulator members may differ in iOS version as long as they land on one HyperExecute pool (`mobile_pool_split` otherwise).
 - **Mobile app on the grid**: a member's local build (`.apk` for emulator, `.zip` for simulator, anywhere on disk) is uploaded from the laptop at preflight and handed to the grid as `--app <id>` (one `remote_app` event per distinct build); an `APP…` id is used as-is. Nothing has to be inside the project or un-gitignored; `--dry-run` uploads nothing. Details and the preflight codes: `references/mobile.md` §Remote.
-- `--author`, `--no-adaptive-heal`, `--bug-detection`, `--name`, `--on-failure` are forwarded to the grid. Use a long Bash timeout (up to 600000 ms).
+- Grid member flags include `--author` and `--no-adaptive-heal`. `--name` labels suite metadata.
 - The dispatch writes `.hyperexecute/`, `hyperexecute-cli.log`, and `.updatedhyperexecute.yaml` into the cwd — suggest gitignoring them; they are not inputs.
 
 Remote preflight refusals arrive as one `remote_error` per reason (then `testrun_done` failed, exit 2):
@@ -83,7 +83,7 @@ Remote preflight refusals arrive as one `remote_error` per reason (then `testrun
 
 ## NDJSON events (agent mode)
 
-All typed; stdout; one JSON object per line. **Terminal event: `testrun_done` — stop parsing there.**
+All typed; stdout; one JSON object per line. **Local completion: `testrun_done`. With `--remote`, keep reading through `remote_done` and process exit; preflight refusals or dry runs may exit without that wrapper event.**
 
 | `type` | Payload | Notes |
 |---|---|---|
@@ -94,7 +94,7 @@ All typed; stdout; one JSON object per line. **Terminal event: `testrun_done` 
 | `testrun_investigations_wait` | `count` | Failed replays left investigations running; the coordinator waits before sealing. Narrate as "investigating N failures". |
 | `testrun_evidence_ingest` | `status: "ok"\|"failed"`, `evidence_id`, `stage?` | Pack published to the dashboard. Absent when publish is skipped. |
 | `testrun_summary` | `totals: {tests, passed, failed, broken, skipped}`, `duration_s`, `upload`, `cancelled` | Build the rollup table from this. |
-| `testrun_done` | `execution_id`, `overall_status: "passed"\|"failed"\|"cancelled"` | Terminal. |
+| `testrun_done` | `execution_id`, `overall_status: "passed"\|"failed"\|"cancelled"` | Local completion; remote runs continue through `remote_done`. |
 
 With `--remote`, the stream is wrapped in typed `remote_*` events (all on stdout):
 
@@ -115,7 +115,8 @@ Parsing strategy:
 
 ```text
 for each line:
-  if type === "testrun_done"          → terminal, stop
+  if type === "testrun_done"          → capture suite outcome; remote runs keep reading
+  if type === "remote_done"           → capture remote status, exit and sessions_path
   if type === "testrun_plan" && !valid → report offenders, expect exit 2
   if type === "testrun_member_end"    → note per-member outcome
   if type === "testrun_summary"       → capture totals for the rollup
@@ -124,7 +125,7 @@ for each line:
 
 ## Presenting results (same discipline as SKILL.md §1)
 
-Never expose event/field names. After `testrun_done`, always render a suite rollup:
+Never expose event/field names. After completion and process exit (`remote_done` for dispatched remote runs), render a suite rollup:
 
 ```markdown
 | | |
@@ -144,3 +145,17 @@ For failures, add one line per failed member only (path + duration + status) —
 ## Evidence & debugging
 
 The suite produces **one** sealed pack, created directly in `<cwd>/.testmuai/evidence/`. Offer it to the user per `references/evidence.md`. Members run silently by design; to see per-member output while debugging, set `KANE_TESTRUN_MEMBER_DEBUG=1` (routes member events to stderr, prefixed `[member]`).
+
+## Execution constraints
+
+Local suites containing any mobile member require `--parallel 1`; larger values are refused. Isolated Chrome workers apply to desktop members only. Remote suites support grid concurrency via `--parallel N`.
+
+Healing is enabled by default (three shrinking replay windows, then re-authoring of authorable steps). `--no-adaptive-heal` disables it. Retired `--retry`/`--retry-count` only print a notice and have no effect. Replay-only recorded steps retain their recordings even during healing.
+
+NDJSON selection uses stdin, not stdout: run `kane-cli testrun run <paths> < /dev/null` for automation launched from a terminal. Dry-run validates a plan, not runtime authentication or browser/device readiness. Always observe process exit, including paths without a normal completion event.
+
+### Remote behavior still requiring verification
+
+The audited dispatch does not forward `--bug-detection` to member commands and does not map `--on-failure` into the job template. Do not rely on these flags for remote bug-detection or fail-fast behavior until implementation owners confirm or fix the mapping. `--name` is suite metadata, not a forwarded member flag.
+
+For dispatched runs, read through `remote_done` and process exit after `testrun_done`; retain the remote status and session-log path. Preflight refusal and dry-run may terminate without `remote_done`.
diff --git a/README.md b/README.md
index 0d8ea5c..913eefe 100644
--- a/README.md
+++ b/README.md
@@ -201,7 +201,7 @@ kane-cli run "<one-sentence objective starting with 'Go to <url> and …'>" --ag
 
 Three rules:
 
-1. **Always use `--agent`** — gives you structured NDJSON to parse. Build automation on the `run_end` event; it's the only one with a stable schema.
+1. Use `--agent` for `run`, `testmd run`, and `generate`. `testrun run` has no `--agent`: it emits NDJSON when **stdin** is not a TTY (use `< /dev/null` for terminal automation). Assurance conversational commands use `--mode agent`. Parse command-specific completion events and process exit.
 2. **Use the "store as" pattern** for extraction. `"go to example.com, store the page title as 'page_title'"` — never `"read the page title"`.
 3. **One objective = one task.** If a flow has more than ~15 steps, split it into multiple `kane-cli run` calls and run them in parallel.
 
@@ -300,7 +300,7 @@ TUI slash commands (`/run`, `/mobile`, `/desktop`, `/doctor`, `/login`, `/logout
 | --------------------------- | ------------------------------------- | ----------------------------------------------------------------------- |
 | `--agent`                   | off                                   | Emit NDJSON to stdout. **Required for any scripted use.**               |
 | `--headless`                | off                                   | Run Chrome with no visible window. Required in CI.                      |
-| `--max-steps <n>`           | `30`                                  | Cap on agent reasoning steps.                                           |
+| `--max-steps <n>`           | `50`                                  | Cap on agent reasoning steps.                                           |
 | `--timeout <s>`             | none                                  | Hard kill the run after N seconds.                                      |
 | `--url <url>`               | config `default_url`                  | Start URL for the run. Overrides the configured default; bare domains get `https://`. |
 | `--allow-missing-url`       | off                                   | Non-TTY only: proceed from the browser's current page instead of failing when no start URL resolves. |
@@ -319,8 +319,8 @@ TUI slash commands (`/run`, `/mobile`, `/desktop`, `/doctor`, `/login`, `/logout
 | `--local-context <file>`    | `.testmuai/context.md` (cwd)          | Override project-local agent context.                                   |
 | `--username <user>`         | none                                  | Basic auth username (skips OAuth).                                      |
 | `--access-key <key>`        | none                                  | Basic auth access key (skips OAuth).                                    |
-| `--code-export`             | off                                   | Generate a code export of the run after upload.                         |
-| `--code-language <lang>`    | `python`                              | Code-export language (only `python` supported today).                   |
+| `--code-export`             | config (`true` by default) | Generate a code export of the run after upload.                         |
+| `--code-language <lang>`    | `python`                              | Code-export language (`python` or `javascript` supported today).                   |
 | `--skip-code-validation`    | on                                    | Skip post-codegen worker-side validation.                               |
 | `--no-skip-code-validation` | off                                   | Force post-codegen worker-side validation.                              |
 
@@ -345,19 +345,20 @@ With `--agent`, `kane-cli` writes **one JSON object per line** to stdout. The pr
 
 There are two shapes of event:
 
-### Progress events (one per step)
+### Progress events (start and completion per step)
 
 These are **untyped** — they have no `type` field. Identify them by the presence of `step`.
 
 ```json
-{"step": 1, "status": "passed", "remark": "Navigated to amazon.in"}
+{"step": 1, "status": "running", "remark": "Navigate to amazon.in"}
+{"step": 1, "status": "done", "remark": "Navigated to amazon.in"}
 {"step": 2, "status": "failed", "remark": "Could not find Add to Cart button"}
 ```
 
 | Field    | Type   | Description                          |
 | -------- | ------ | ------------------------------------ |
 | `step`   | number | 1-based step index                   |
-| `status` | string | `"passed"` or `"failed"`             |
+| `status` | string | `"running"` at start; `"done"` or `"failed"` at completion |
 | `remark` | string | What the agent did, or why it failed |
 
 ### `run_end` (the one event you should script against)
diff --git a/docs/user-guide/assurance/context.md b/docs/user-guide/assurance/context.md
index 0034650..a5de8a6 100644
--- a/docs/user-guide/assurance/context.md
+++ b/docs/user-guide/assurance/context.md
@@ -286,3 +286,13 @@ Headless extraction (`--mode agent|ci|override`), the NDJSON event stream, exit
 - [Maintaining the suite](./maintain.md) — what to do when a source changes.
 - [Sharing the context graph with your team](./sharing.md) — one location; publishing, taking your teammates' records, cloning, and what happens when two people change the same thing.
 - [Automation](./automation.md) — the headless contract.
+
+## Sharing a context store
+
+For location setup, sync, pull, push, clone and rebase recovery, see [Sharing the context store](./sharing.md).
+
+## Lifecycle automation contracts
+
+`context name`, `context retire`, and `context revert` accept `--mode agent` and emit an envelope ending in `done`. Destructive agent-mode operations require `--yes` even when stdin is a TTY. Other modes retain human output. Read commands use their documented `--json` flags; do not assume they all accept `--mode`.
+
+`context review --mode agent` / `--json` returns review outcome rows on success rather than the conversational `done` contract. Early agent-mode errors may emit `error` plus `done`; check command-specific output and process exit.
diff --git a/docs/user-guide/assurance/design.md b/docs/user-guide/assurance/design.md
index 9c8df49..09a873f 100644
--- a/docs/user-guide/assurance/design.md
+++ b/docs/user-guide/assurance/design.md
@@ -39,7 +39,7 @@ Between phases the session parks on a **check-in panel** — the same panel surf
 
 **Questions that need a typed value.** When an answer is a concrete value (a URL, a fixture id), the question either offers an input-bearing option row — selecting it opens an inline editor so the answer carries the pick and your value together *(0.7.1)* — or tells you to type the value directly. A plain option row sends only its label, so plain options on such questions are the genuine alternatives (use a placeholder, reduce scope, skip). If a needed value doesn't arrive, the agent re-asks once and then proceeds on its stated fallback — announced in the narrative, never silently.
 
-Headless modes run all phases without parking; a high-risk question pauses an `agent`-mode run (resumable) and fails a `ci`-mode run closed. Each phase still commits and reports as it completes on the event stream. See [Automation](./automation.md).
+Headless phases report their progress; every question pauses an `agent`-mode run (resumable); a high-risk question fails a `ci`-mode run closed. Each phase still commits and reports as it completes on the event stream. See [Automation](./automation.md).
 
 ## What you get
 
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
index 3d06b6d..2f89fa1 100644
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -57,8 +57,8 @@ Every field in `tui-config.json`:
 | `folder_name` | string \| null | `null` | Display name of the selected folder (set automatically by the picker) | set by `kane-cli config folder` |
 | `mode` | `"action"` \| `"testing"` | `"testing"` | Agent behaviour when the run hits an authentication wall, blocked page, or error page. See below. | `kane-cli config set-mode <action\|testing>` |
 | `bug_detection` | `"off"` \| `"stop"` \| `"continue"` | `"off"` | Whether the agent flags suspected product bugs while authoring. See [Bug detection](#bug-detection). | `kane-cli config set-bug-detection <mode>`, or per-run `--bug-detection` |
-| `code_export.enabled` | boolean | `false` | Whether to generate a code export after the upload pipeline completes (requires a TMS upload). | TUI menu, or per-run `--code-export` flag |
-| `code_export.language` | `"python"` | `"python"` | Output language for the generated code. Only `python` is supported today. | per-run `--code-language <lang>` |
+| `code_export.enabled` | boolean | `true` | Whether to generate a code export after the upload pipeline completes (requires a TMS upload). | TUI menu, or per-run `--code-export` flag |
+| `code_export.language` | `"python"` \| `"javascript"` | `"python"` | Output language for the generated code. | per-run `--code-language <lang>` |
 | `code_export.skip_validation` | boolean | `true` | Skip the post-codegen worker-side validation step. | TUI menu, or per-run `--skip-code-validation` / `--no-skip-code-validation` |
 
 ## Updating settings
@@ -185,10 +185,10 @@ The `code_export` block enables and configures generated code output that is pro
 - **The TUI** — open the config menu, choose Code Export, and toggle the `enabled` and `skip_validation` switches. The TUI writes the change back to `tui-config.json`.
 - **Per-run flags** on `kane-cli run`:
   - `--code-export` to enable for this run only.
-  - `--code-language <lang>` to pick the output language (only `python` is supported today).
+  - `--code-language <lang>` to pick the output language (`python` or `javascript`; default `python`).
   - `--skip-code-validation` / `--no-skip-code-validation` to control post-codegen worker-side validation.
 
-Code export requires a TMS upload to run, so it is only meaningful when `mode` is `testing` and a project/folder are configured (or auto-defaulted). See [test-manager-integration.md](./test-manager-integration.md) for the full upload pipeline.
+Code export requires a TMS upload to run, and a configured or auto-defaulted project/folder. Upload is not gated by `mode`: action/testing controls agent behavior. See [test-manager-integration.md](./test-manager-integration.md) for the full upload pipeline.
 
 ## Chrome management
 
@@ -275,3 +275,11 @@ kane-cli will recreate the file with defaults the next time it writes a setting.
 - Variables under `~/.testmuai/kaneai/variables/` and `.testmuai/variables/`.
 - Chrome profiles under `~/.testmuai/kaneai/chrome-profiles/`.
 - Context sync credentials and caches under `~/.testmuai/kaneai/context-sync/` (use `kane-cli context sync remove <name>` to delete a location's keys).
+
+### Assertion and capture controls
+
+- `kane-cli config set-assertion-mode dom|visual`: default `dom`, with vision fallback. Override with `--assertion-mode dom|visual` on `run` or `testmd run`.
+- `kane-cli config set-final-validation on|off`: default off. Override with `--final-validation on|off` on `run` or `testmd run`. Controls the synthesized final checkpoint (`cp_final`) independently of action/testing mode; continue writing explicit terminal assertions.
+- `kane-cli config set-network-ws on|off` and `set-network-sse on|off`: experimental capture, both off by default. `run` also exposes `--network-ws` and `--network-sse`; SSE capture is Chromium-only. These flags are not registered on `testmd run` or `testrun run`.
+
+Code export is enabled by default; existing saved configuration can override this. The 0.2.11 migration enabled it for migrated profiles. Both Python and JavaScript exports are supported.
diff --git a/docs/user-guide/evidence.md b/docs/user-guide/evidence.md
index 6fc0ceb..3543b1e 100644
--- a/docs/user-guide/evidence.md
+++ b/docs/user-guide/evidence.md
@@ -196,3 +196,9 @@ Runs that upload to Test Manager attach their sealed pack automatically. Replaye
 - [Batch runs with testrun](./testrun.md) — many tests, one execution, one pack.
 - [Running test.md files](./testmd/running.md) — the testmd command family.
 - [Troubleshooting](./troubleshooting.md) — debugging flows and escape hatches.
+
+## Evidence merge identity
+
+For ordinary runs, default merge identity distinguishes the test and commit (`external_id.test_id`, `external_id.commit_id`) and the environment (`environment.os`, `environment.os_version`, `environment.browser`, `environment.browser_version`). Re-runs with the same identity nest as attempts; a different environment produces a separate sibling.
+
+Explicit collision policies can change grouping; a custom `--rules` file replaces the default rules rather than extending them. Check the selected identity rules before interpreting two runs as retries of the same test.
diff --git a/docs/user-guide/features/api-calls.md b/docs/user-guide/features/api-calls.md
index 72415dd..597a6ac 100644
--- a/docs/user-guide/features/api-calls.md
+++ b/docs/user-guide/features/api-calls.md
@@ -20,25 +20,28 @@ curl -X POST https://api.example.com/login -H 'Content-Type: application/json' -
 
 ## Using the response
 
-Once you've saved a response under a name, reference it elsewhere in the objective:
+Use the response in plain English. The `{{name}}` form is reserved for global variables and secrets (see [Variables and Context](../variables-and-context.md)); a value the run produces is never written that way.
 
-| Reference | Resolves to |
-|-----------|-------------|
-| `{{order.status}}` | the HTTP status code (e.g. `201`) |
-| `{{order.response_body}}` | the whole response body |
-| `{{order.response_body.<field>}}` | a field from the JSON response body |
+| To use | Say |
+|---|---|
+| the HTTP status code | `assert the response status is 201` |
+| a field from the JSON body | `store the id from the response body as 'order_id'` |
+| the whole body | `store the response body as 'order_body'` |
+| a value later in the run | `the stored order_id value` |
+
+When one objective makes several calls, name each response (`save the response as order`) and say which one you mean: `assert the order response status is 201`.
 
 Assert on it, or feed it into later actions — API calls and browser actions mix freely in one objective:
 
 ```
 Call POST https://api.example.com/login with body {"u": "{{user}}", "p": "{{password}}"}, save the response as login,
-assert {{login.status}} is 200,
+assert the response status is 200,
 then open https://app.example.com and verify the dashboard loads
 ```
 
 ```
 Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1}, save the response as order,
-assert {{order.status}} is 201,
+assert the response status is 201,
 then open https://app.example.com/orders and verify an order for "sku_42" is visible
 ```
 
diff --git a/docs/user-guide/features/checkpoints/devtools/network.md b/docs/user-guide/features/checkpoints/devtools/network.md
index fc66499..3dba683 100644
--- a/docs/user-guide/features/checkpoints/devtools/network.md
+++ b/docs/user-guide/features/checkpoints/devtools/network.md
@@ -65,3 +65,5 @@ Store all API request URLs
 ```
 If the /api/auth returned 200 then proceed to dashboard, else show error message
 ```
+
+Experimental WebSocket and SSE capture is available through `run --network-ws` and `run --network-sse`, both off by default; SSE is Chromium-only. Persist via `config set-network-ws on|off` or `config set-network-sse on|off`. These flags are not registered on `testmd run` or `testrun run`.
diff --git a/docs/user-guide/features/checkpoints/visual.md b/docs/user-guide/features/checkpoints/visual.md
index 5ca9a70..d2f74ba 100644
--- a/docs/user-guide/features/checkpoints/visual.md
+++ b/docs/user-guide/features/checkpoints/visual.md
@@ -1,6 +1,6 @@
 # Visual Assertions
 
-Visual assertions verify what's visible on screen by analyzing the current screenshot. This is the default method — when in doubt, KaneAI uses visual analysis.
+Visual assertions verify what's visible on screen by analyzing the current screenshot. The default assertion mode is `dom`, with vision fallback. Set `--assertion-mode visual` to request visual assertions explicitly.
 
 ## When It's Used
 
diff --git a/docs/user-guide/remote-execution.md b/docs/user-guide/remote-execution.md
index 3c1a9f1..f0c4a10 100644
--- a/docs/user-guide/remote-execution.md
+++ b/docs/user-guide/remote-execution.md
@@ -58,7 +58,7 @@ job 24fc58b2-… dispatched → https://hyperexecute.lambdatest.com/hyperexecute
 |---|---|
 | `--parallel <n>` | Becomes the job's concurrency: the members are auto-split across `n` grid runners, each running its share one member at a time. Device suites parallelize the same way — every task has its own VM and device |
 | `--headless` | Not needed — every member runs headless on the grid |
-| `--on-failure`, `--name`, `--bug-detection`, `--author`, `--no-adaptive-heal` | Forwarded to the members on the grid |
+| `--author`, `--no-adaptive-heal` | Forwarded to grid member runs |
 | `--username`, `--access-key` | Used for the grid login and the Test Manager upload |
 
 ## Web suites on the grid
@@ -67,7 +67,7 @@ A web suite needs nothing beyond the prerequisites: the grid runner has Chrome,
 
 ```bash
 kane-cli plugin install remote-execution
-kane-cli testrun run tests/web/ --remote --parallel 4 --on-failure fail-fast
+kane-cli testrun run tests/web/ --remote --parallel 4
 ```
 
 What you see back is a normal `testrun` summary; the only extra lines are the dispatch and the job link. A member that authors on the grid comes back with its `output-<stem>/` recordings, so the next run — local or remote — replays them. Commit those recordings as you would after a local run.
@@ -155,12 +155,12 @@ kane-cli plugin install remote-execution
 
 # a web suite
 kane-cli testrun run tests/web/ --remote --parallel 4 \
-  --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY" --on-failure fail-fast
+  --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY"
 
 # a mobile suite
 kane-cli testrun run tests/app/ --remote \
   --device-name "Pixel 7" --os-version 14 \
-  --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY" --on-failure fail-fast
+  --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY"
 ```
 
 Archive `.testmuai/evidence/*.evidence` as the build artifact. More pipeline shapes: [CI/CD recipes](./cicd.md).
@@ -189,3 +189,9 @@ In agent / non-TTY mode a remote run adds typed events around the normal `testru
 - [Writing test.md files](./testmd/overview.md#mobile-target) — `target:`, `app:`, `device_name:`, `os_version:`.
 - [Evidence packs](./evidence.md) — what comes back and how to view it.
 - [CI/CD recipes](./cicd.md) — pipeline patterns, including runners with no Chrome.
+
+### Remote behavior still requiring verification
+
+The audited dispatch does not forward `--bug-detection` to member commands and does not map `--on-failure` into the job template. Do not rely on these flags for remote bug-detection or fail-fast behavior until implementation owners confirm or fix the mapping. `--name` is suite metadata, not a forwarded member flag.
+
+For dispatched runs, read through `remote_done` and process exit after `testrun_done`; retain the remote status and session-log path. Preflight refusal and dry-run may terminate without `remote_done`.
diff --git a/docs/user-guide/running-tests.md b/docs/user-guide/running-tests.md
index 71da1a7..a777fdd 100644
--- a/docs/user-guide/running-tests.md
+++ b/docs/user-guide/running-tests.md
@@ -14,7 +14,7 @@ What makes a good objective:
 
 Two habits make an objective reliable enough to save and replay.
 
-**End every flow in a check of the result.** Close with an assertion about the resulting page state — `verify the cart shows 1 item` — not a bare `submit` or `confirm the dialog`. Without a closing check, "done" only means the agent believed it finished; with one, the run passes or fails on the real end state. Name the outcome, never the control that triggered it: `verify the Submit button is visible` fails exactly when the action worked, because the button disappears on success. If an objective has several phases (log in, then search, then check out), each phase ends in its own check.
+**End every flow in a check of the result.** Close with an assertion about the resulting page state — `verify the cart shows 1 item` — not a bare `submit` or `confirm the dialog`. Without a closing check, "done" only means the agent believed it finished; with one, the run passes or fails on the real end state. Name the outcome, never the control that triggered it: `verify the Submit button is visible` fails exactly when the action worked, because the button disappears on success. If an objective has several phases (log in, then search, then check out), each phase ends in its own check. Make the closing check something the agent can see on the screen the last action leaves it on, with no further click or navigation. If the proof lives on another page, get there with an explicit action first: `place the order, open Order History, then verify the newest order shows "Processing"`, not `verify the order succeeded by checking Order History`. A check that has to find its own way to the evidence is an action hiding inside an assertion, and the route it improvises can differ from run to run.
 
 **Say the goal, not the clicks.** Phrase actions as goals — `Log in as {{tester}}`, `Complete checkout with the saved card` — so a run absorbs a reordered form or a new popup instead of breaking on it. Keep exact values such as credentials, prices, and URLs literal or in `{{variables}}`. For a step that only sometimes appears, such as a cookie banner, write it as a condition (`if a cookie banner appears, dismiss it`) rather than assuming it away.
 
@@ -172,7 +172,7 @@ The customer-facing flags accepted by `kane-cli run`:
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--headless` | Run Chrome in headless mode. | Off |
-| `--max-steps <n>` | Maximum agent steps. | `30` |
+| `--max-steps <n>` | Maximum agent steps. | `50` |
 | `--timeout <seconds>` | Kill the run after N seconds. | None |
 | `--url <url>` | Start URL for the run. Overrides the configured `default_url`; bare domains are normalized to `https://`. See [Default start URL](./configuration.md#default-start-url). | Config `default_url` |
 | `--allow-missing-url` | Non-TTY only: proceed from the browser's current page instead of failing when no start URL resolves (a provided `--url` is still used). | Off |
@@ -188,7 +188,7 @@ The customer-facing flags accepted by `kane-cli run`:
 | `--mode <name>` | Run mode: `action` (strict) or `testing` (lenient). | Config value, otherwise `testing` |
 | `--bug-detection <mode>` | Detect product bugs while authoring: `off`, `stop` (halt the run on a confirmed bug), or `continue` (record it and keep going). Overrides `config set-bug-detection`. See [Configuration](./configuration.md#bug-detection). | Config value, otherwise `off` |
 | `--agent` | Plain NDJSON output, no colors or UI. | Off |
-| `--code-export` | Generate code export after upload. | Off |
+| `--code-export` | Generate code export after upload. | config (`true` by default) |
 | `--code-language <lang>` | Code export language (currently `python`). | `python` |
 | `--skip-code-validation` | Skip post-codegen worker-side validation. | On |
 | `--no-skip-code-validation` | Force post-codegen worker-side validation. | Off |
@@ -226,7 +226,7 @@ The mobile run flags:
 - `--device-name <name>` + `--os-version <version>`: pick a device as `kane-cli devices list --target emulator|simulator` prints it (a name needs a version; a version alone matches any device on it). In the TUI/TTY, omitting them opens a one-time picker and the choice is saved; in non-interactive runs a device must already be set (via the flags or `kane-cli config set-device-name` / `set-os-version`) or the run exits with the fix spelled out.
 - `--app <path|APPid>`: the app under test, required for every mobile run. Pass a build (emulator: `.apk`, simulator: `.zip`) or an uploaded app id (`APP` followed by six or more digits; `kane-cli apps list --target <kind>` lists yours). On the `desktop` target, the device flags and `--app` are ignored.
 
-In the interactive TUI, a first run offers a Desktop / Emulator / Simulator chooser, and you can switch targets at any time with `/mobile` and `/desktop`. Run `/doctor` to check mobile tooling and devices.
+In the interactive TUI, a first run offers a Desktop / Emulator / Simulator chooser, and you can switch targets with `/mobile` and `/desktop` before the first dispatch; afterwards use `/new` before switching. Run `/doctor` to check mobile tooling and devices.
 
 For setup (Xcode or Android Studio, `kane-cli login`, and `kane-cli doctor --target emulator|simulator --install`) and the app formats each target accepts, see [Mobile testing](./mobile/overview.md).
 
@@ -286,3 +286,22 @@ The run is also captured as a sealed [evidence pack](./evidence.md) — screensh
 ## Feedback prompt
 
 After the result and links print, kane-cli prompts you to rate the session with thumbs up or thumbs down. Use the left and right arrow keys to choose, Enter to submit, or Esc to skip. The rating is sent to TestmuAI TMS for the active test case; see [./test-manager-integration.md](./test-manager-integration.md) for what is recorded.
+
+## Command-specific completion
+
+The `run_end` parsing strategy applies to one-shot `run` only. For `testmd run`, collect `test_md_done.overall_status`, `duration_s`, `session_id`, and optional `share_url`; embedded `run_end` events can finish individual steps. Local suites emit `testrun_done`; dispatched remote suites then emit `remote_done` (retain `status`, `exit`, `sessions_path`). `generate` emits `generate_done`. Assurance conversational agent streams end in `done`; review/read verbs have their own contracts. Always check process exit too: early refusal, invalid plan or dry-run can exit without the normal completion event.
+
+Progress is for live display: count only `done`/`failed` completions, retaining child and execution context when step indices repeat.
+
+In the interactive TUI, `/mobile` and `/desktop` can switch targets before the first dispatch. The target locks after dispatch; use `/new` to start a new session before switching.
+
+
+## Assertion controls and current-page analysis
+
+`run` and `testmd run` support `--assertion-mode dom|visual` (default `dom` with vision fallback) and `--final-validation on|off` (default off). Persist with `config set-assertion-mode` and `config set-final-validation`. Final validation controls the synthesized `cp_final` checkpoint independently of action/testing mode; keep explicit terminal assertions in objectives.
+
+`run --analyzer-only --condition "<condition>"` checks the current desktop browser page without an objective, action steps or saved test. Repeat `--condition` for multiple checks. Use `--agent` or non-TTY input. Results contain `condition_results: boolean[]`; exit `0` means all conditions were judged, **not** that all are true. Exit `1` means a result was missing, and `3` means cancelled. This mode rejects mobile target/app/device options and code-export/name options.
+
+Experimental `run --network-ws` and `run --network-sse` enable WebSocket and SSE capture; both default off. Persist with `config set-network-ws on|off` and `config set-network-sse on|off`. SSE capture is Chromium-only. Do not copy these run-only flags onto `testmd` or `testrun` commands.
+
+Code export defaults to enabled, subject to saved configuration, and supports `python` (default) or `javascript`. `run`/`testmd run` use `--code-language`; `testmd export` uses `--language`. Upload eligibility is independent of action/testing mode.
diff --git a/docs/user-guide/test-manager-integration.md b/docs/user-guide/test-manager-integration.md
index 4773c2c..dc14219 100644
--- a/docs/user-guide/test-manager-integration.md
+++ b/docs/user-guide/test-manager-integration.md
@@ -95,7 +95,7 @@ Code export runs server-side after the test case is finalised. kane-cli polls Te
 
 ### Enabling code export
 
-Code export is **off by default**. Turn it on either in your stored config or per-run on the CLI.
+Code export is **enabled by default**; stored configuration can override it. `--code-export` enables it for a run.
 
 In `~/.testmuai/kaneai/tui-config.json`, set the `code_export` block:
 
@@ -120,7 +120,7 @@ kane-cli run "Add an item to the cart" \
   --skip-code-validation
 ```
 
-`--no-skip-code-validation` forces validation on for that run. `--code-language` only accepts `python`.
+`--no-skip-code-validation` forces validation on for that run. `--code-language` accepts `python` (default) or `javascript`.
 
 ### Where to find the output
 
diff --git a/docs/user-guide/testmd/overview.md b/docs/user-guide/testmd/overview.md
index b812896..eb647ee 100644
--- a/docs/user-guide/testmd/overview.md
+++ b/docs/user-guide/testmd/overview.md
@@ -81,14 +81,14 @@ Frontmatter is YAML inside `---` fences at the top of the file. Every key is opt
 | `mode` | `"action"` \| `"testing"` | root only | How the agent reacts to auth walls, blocked pages, and error pages. `testing` (default) pushes through so negative-test assertions can run; `action` halts so you can intervene. See [Run mode](./running.md#run-mode). |
 | `url` | string | root only | Start URL for the test's first step. Bare domains are normalized to `https://`. Overridden by the `--url` flag; falls back to the configured `default_url`. See [Default start URL](../configuration.md#default-start-url). |
 | `tags` | list or string | root only | Labels for selecting tests in batch runs. Accepts a YAML list, a bracketed inline list (`tags: [smoke, checkout]`), or a bare comma string (`tags: smoke, checkout`). Tags are trimmed, lowercased, and de-duplicated. Shown by `kane-cli testmd list` and the interactive picker; selected with [`testrun --tags`](../testrun.md#selecting-tests); recorded in the run's [evidence pack](../evidence.md). |
-| `max_steps` | integer | root + per-step | Maximum agent reasoning steps for the run or step. Default is `30`. |
+| `max_steps` | integer | root + per-step | Maximum agent reasoning steps for the run or step. Engine fallback is `30` when neither step config nor CLI supplies a value; CLI default is `50`. |
 | `timeout` | integer (seconds) | root + per-step | Hard kill timer applied per step. No default. |
 | `global_context` | string (Markdown text) or file path | root + per-step | Standing instructions inlined into the agent's context. See [variables-and-context.md](../variables-and-context.md). |
 | `local_context` | string or file path | root + per-step | Project-scoped guidance. Same shape as `global_context`. |
 | `variables` | object | root + per-step | Named values usable as `{{name}}` in objectives. See [Variables](#variables). |
 | `session_context` | `{ prior_runs: [...] }` | root + per-step | Pre-loaded prior-run context for the agent. |
 | `target` | `"chrome"` \| `"cdp"` \| `"ws"` \| `"emulator"` \| `"simulator"` | root only | Where the test runs: a browser transport (default `chrome`) or a mobile target (a virtual Android or iOS device — locally on macOS Apple Silicon, or on the cloud grid with `testrun run --remote`). See [Mobile target](#mobile-target). |
-| `app` | string | root only | Mobile only: the app under test — a build path (emulator `.apk`, simulator `.zip`) or an uploaded `APP…` id. Required with `target: emulator\|simulator`, rejected with a browser target. On the grid a simulator test needs the `APP…` id. |
+| `app` | string | root only | Mobile only: the app under test — a build path (emulator `.apk`, simulator `.zip`) or an uploaded `APP…` id. Required with `target: emulator\|simulator`, rejected with a browser target. On the grid, simulator `.zip` builds are uploaded from this machine during a real run; an existing `APP…` id is also accepted. Dry-run does not upload. |
 | `no_reset` | boolean | root only | Mobile only: keep the app's existing state between runs instead of resetting it. |
 | `device_name` | string | root only | Mobile only: the default device for this test, as `kane-cli devices list --target <kind>` (add `--remote` for the grid catalog) prints it. Overridden by `--device-name`. |
 | `os_version` | string | root only | Mobile only: the device's OS version (`14`, `17.5`). Overridden by `--os-version`. Required alongside `device_name`. |
@@ -123,7 +123,7 @@ no_reset: false              # optional
 
 The nested form (`target: {platform, app}`) is not accepted — the parser refuses it and spells out the flat shape above.
 
-Mobile tests run with `kane-cli testmd run` and in batch with [`testrun`](../testrun.md#mobile-members). Locally that needs macOS Apple Silicon — setup is covered in [Mobile testing](../mobile/overview.md); with [`testrun run --remote`](../remote-execution.md) the suite runs on a grid emulator or simulator from any machine (a simulator member then needs an `APP…` id in `app:`).
+Mobile tests run with `kane-cli testmd run` and in batch with [`testrun`](../testrun.md#mobile-members). Locally that needs macOS Apple Silicon — setup is covered in [Mobile testing](../mobile/overview.md); with [`testrun run --remote`](../remote-execution.md) the suite runs on a grid emulator or simulator from any machine (simulator members accept a local `.zip` build or an `APP…` id in `app:`).
 
 ### Root-only vs root-or-per-step
 
@@ -329,3 +329,6 @@ Parse errors abort the run before any browser launch, auth call, or upload. The
 - [Batch runs with testrun](../testrun.md) — run many tests at once, selected by path or `tags:`.
 - [Composition with @import](./composition.md) — break a long test into reusable helpers.
 - [Variables and context](../variables-and-context.md) — the full variables pipeline.
+
+
+For replay-only heading markers and balanced structured control flow (`@if`/`@end-if`, `@while`/`@end-while`), see [Replay policy and completion](./running.md#replay-policy-and-completion).
diff --git a/docs/user-guide/testmd/running.md b/docs/user-guide/testmd/running.md
index c0a68da..c3e3e77 100644
--- a/docs/user-guide/testmd/running.md
+++ b/docs/user-guide/testmd/running.md
@@ -41,7 +41,7 @@ Every flag accepted by `kane-cli testmd run`:
 | Flag | Type | Default | Description |
 |---|---|---|---|
 | `--headless` | flag | off | Launch Chrome without a visible window. Per-run; no persistent setting. Equivalent to `headless: true` in frontmatter. |
-| `--max-steps <n>` | integer | `30` | Maximum agent reasoning steps per test step. |
+| `--max-steps <n>` | integer | `50` | Maximum agent reasoning steps per test step. |
 | `--timeout <s>` | integer | none | Hard kill timer per step, in seconds. |
 | `--url <url>` | string | frontmatter `url:` / config `default_url` | Start URL for the first step. Overrides the frontmatter `url:` key and the configured `default_url`; bare domains are normalized to `https://`. |
 | `--allow-missing-url` | flag | off | Non-TTY only: proceed from the browser's current page instead of failing when the first step has no start URL (`url:` / `--url` are still used if present). |
@@ -56,16 +56,15 @@ Every flag accepted by `kane-cli testmd run`:
 | `--access-key <key>` | string | profile | Basic-auth access key. Skips OAuth for this run. |
 | `--mode <name>` | `action` \| `testing` | profile or `testing` | Agent behaviour on auth walls and error pages. See [Run mode](#run-mode). |
 | `--agent` | flag | auto when stdin not TTY | Plain NDJSON output; no TUI. Use this in CI. |
-| `--code-export` | flag | off | Generate Playwright code after the run. See [Code export](#code-export). |
+| `--code-export` | flag | config (`true` by default) | Generate Playwright code after the run. See [Code export](#code-export). |
 | `--code-language <lang>` | `python` \| `javascript` | `python` | Code-export target language. |
 | `--skip-code-validation` | flag | on | Skip the post-codegen validation pass. |
 | `--no-skip-code-validation` | flag | off | Force the post-codegen validation pass. |
 | `--name <name>` | string | none | Persist a session name. Must match `[a-zA-Z0-9_-]+`. |
 | `--on-lock-conflict <mode>` | `readonly` \| `fail` \| `wait` | none | Policy when another user holds the lock. See [Lock conflicts](#lock-conflicts). |
 | `--push` | flag | off | Always commit at the end of the run. |
-| `--retry` | flag | off | On replay failure, restart the run with a shrinking replay window. |
-| `--retry-count <n>` | integer | `3` | Maximum replay restart attempts before falling back to a full re-author. |
-| `--author` | flag | off | Skip the replay decision and author every step from scratch. |
+| `--no-adaptive-heal` | flag | healing enabled | Disable adaptive healing after replay failure |
+| `--author` | flag | off | Re-author authorable steps; replay-only marked steps still replay. |
 | `--bug-detection <mode>` | `off` \| `stop` \| `continue` | config value (`off`) | Detect product bugs while authoring: `stop` halts the run on a confirmed bug; `continue` records it and keeps going. Overrides `config set-bug-detection`. Authoring steps only — replay failures always investigate. See [Configuration](../configuration.md#bug-detection). |
 
 Most flags have a frontmatter counterpart with the same name (with underscores). Where both are set, the CLI flag wins — except for `variables`, which the file owns; see [overview.md](./overview.md#variables).
@@ -87,7 +86,7 @@ Each step launches its own runner subprocess. The browser is shared across steps
 
 The first time you run a `_test.md`, every step is **authored**: the agent works out how to satisfy the objective and a recording is saved next to the test. On every subsequent run, kane-cli tries to **replay** the saved recording for each step — no agent involved, no LLM cost, much faster.
 
-A step replays if and only if all of the following are true:
+For authorable steps, replay requires all of the following (replay-only marked steps are exempt from this authoring decision):
 
 - A recording exists for it on disk.
 - The step's objective text has not changed since the recording.
@@ -98,23 +97,22 @@ If any of those fail, the step authors again.
 
 ### Edits cascade to the rest of the file
 
-Editing one step does not just re-record that step — it re-records that step **and every step after it in the same file**. The reason: each step starts where the previous step left off (same browser, same URL, same logged-in state). When you change step 3, the state step 4 expected to find may no longer be there, so it is not safe to replay step 4 from cache.
+Editing one step does not just re-record that step — it re-records that step **and every authorable step after it in the same file**; replay-only marked steps still replay. The reason: each step starts where the previous step left off (same browser, same URL, same logged-in state). When you change step 3, the state step 4 expected to find may no longer be there, so it is not safe to replay step 4 from cache.
 
-In practice this means: an isolated text fix at the top of a test can re-author the whole file. If you are iterating on a test and want only the last step to re-record, edit that last step.
+In practice this means: an isolated text fix at the top of a test can re-author all authorable steps in the file. If you are iterating on a test and want only the last step to re-record, edit that last step.
 
 ### Forcing a fresh recording
 
 Two ways to author everything:
 
-- **`--author`** — bypasses the replay decision for one run. Every step authors.
-- **Delete the output directory** — `rm -rf output-<stem>/` resets the cache for the next run.
+- **`--author`** — bypasses the replay decision for one run. Every authorable step authors; replay-only marked steps still replay.
+- Preserve output recordings for replay-only marked steps; deleting them cannot force fresh authoring.
 
 ### Handling replay failures
 
-A replay can fail if the site changed under you — a button moved, the page is slower than expected, an extra modal appears. Two flags help:
+A replay can fail if the site changed under you — a button moved, the page is slower than expected, an extra modal appears. Recovery is controlled by the healing policy:
 
-- **`--retry`** — on replay failure, kane-cli restarts the run with a smaller replay window: it authors the failing step and replays fewer earlier steps. This often recovers transient issues without a full re-author.
-- **`--retry-count <n>`** — maximum restart attempts. Default `3`. After this many retries, kane-cli falls back to a full re-author.
+- **Adaptive healing** — enabled by default: three shrinking replay windows, then re-author authorable steps. Use `--no-adaptive-heal` to disable it.
 
 Every failed replay is also **investigated automatically**: a failure record — the error, the page state at failure, and pointers into the step's console/network logs — is written into the run's [evidence pack](../evidence.md#debugging-a-failed-run-from-its-pack), so you can see *why* the replay broke, not just that it did.
 
@@ -241,14 +239,13 @@ A CI-friendly invocation:
 kane-cli testmd run ./tests/checkout_test.md \
   --agent \
   --headless \
-  --on-lock-conflict wait \
-  --retry
+  --on-lock-conflict wait
 ```
 
 - `--agent` — plain NDJSON to stdout, no TUI redraws. Auto-enabled when stdin is not a TTY, but pass it explicitly for clarity.
 - `--headless` — Chrome runs without a window.
 - `--on-lock-conflict wait` — block instead of failing if a teammate is editing the same test.
-- `--retry` — recover transient replay failures automatically.
+- Adaptive healing recovers replay failures by default; `--no-adaptive-heal` opts out.
 
 In a non-interactive run (stdin is not a TTY), there is no one to answer an interactive `ask_user` prompt, so kane-cli disables it: a step that would otherwise wait for input fails cleanly instead of blocking forever. Write test steps that do not depend on mid-run prompts when running in CI.
 
@@ -307,7 +304,7 @@ This is a local-only delete — it does not remove the test from Test Manager. U
 Regenerates the code export from existing recordings without re-running the test:
 
 ```bash
-kane-cli testmd export amazon_test.md --code-language python
+kane-cli testmd export amazon_test.md --language python
 ```
 
 This is faster than a full run because the browser is not launched; it reuses what was recorded last time.
@@ -335,3 +332,13 @@ You rarely need to run this by hand: after every successful authored commit, kan
 - [Composition with @import](./composition.md) — reusable helpers across tests.
 - [Configuration](../configuration.md) — persistent settings: Chrome profile, window size, code export defaults.
 - [Test Manager integration](../test-manager-integration.md) — what happens during the upload.
+
+## Replay policy and completion
+
+Adaptive healing is enabled by default: after a replay failure the runner tries up to three shrinking replay windows, then full re-authoring of authorable steps. `--no-adaptive-heal` disables this recovery. Retired `--retry` and `--retry-count` are accepted only to print a notice; they do not enable healing or change the fixed budget.
+
+Headings marked `@db`, `@api`, `@js`, `@smartui`, `@network_query`, or `@network_assertion` are replay-only. They still replay under `--author`, downstream divergence and adaptive healing. Missing recordings cannot be re-authored through these markers: restore the recording or recreate it through the originating workflow. Do not delete their tapes to force authoring; adding a marker does not create an operation.
+
+Structured control flow uses balanced heading markers: `@if`, `@elif`, `@else`, `@end-if`, `@while`, `@end-while`. An `@else` must be last in its conditional; end markers must match the opened block type. These are distinct from natural-language conditionals. Markers are excluded from the step body hash. Only one replay-only kind is allowed per step, and an import cannot also be marked replay-only.
+
+Under `--agent`, wait for `test_md_done` (file-level `overall_status`, `duration_s`, `session_id`, optional `share_url`) and process exit. Individual `run_end` events do not complete the file.
diff --git a/docs/user-guide/testrun.md b/docs/user-guide/testrun.md
index e529fa9..69c8d17 100644
--- a/docs/user-guide/testrun.md
+++ b/docs/user-guide/testrun.md
@@ -85,8 +85,7 @@ kane-cli testrun run tests/app/ --remote --device-name "Pixel 7" --os-version 14
 | `--on-failure <mode>` | `continue` \| `fail-fast` | `continue` |
 | `--name <label>` | Run title | derived from the selection |
 | `--dry-run` | Plan + validate only, execute nothing | off |
-| `--retry` | On replay failure, restart with a shrinking replay window | off |
-| `--retry-count <n>` | Max replay restart attempts before a full re-author | `3` |
+| `--no-adaptive-heal` | Disable default adaptive healing after replay failure | healing enabled |
 | `--bug-detection <mode>` | `off` \| `stop` \| `continue` — see [Configuration](./configuration.md#bug-detection) | config value |
 | `--headless` | Run Chrome without a visible window | off |
 | `--remote [backend]` | Dispatch the suite to the cloud grid instead of local Chrome / local devices (default backend: `hyper`). Needs `kane-cli plugin install remote-execution`. See [Remote runs](./remote-execution.md) | off |
@@ -94,7 +93,7 @@ kane-cli testrun run tests/app/ --remote --device-name "Pixel 7" --os-version 14
 | `--os-version <version>` | OS version for the mobile members (`14`, `17.5`); alone = any device on that version | member's `os_version:` |
 | `--username <user>` / `--access-key <key>` | Basic auth (skips OAuth) | — |
 
-Each worker gets its **own isolated Chrome** with a fresh temporary profile, so parallel members never share cookies, logins, or tabs — and never fight over your real browser profile.
+Each desktop worker gets its **own isolated Chrome** with a fresh temporary profile, so parallel members never share cookies, logins, or tabs — and never fight over your real browser profile.
 
 `--on-failure` controls what a failed member does to the rest of the suite:
 
@@ -111,7 +110,7 @@ Each worker gets its **own isolated Chrome** with a fresh temporary profile, so
 kane-cli testrun run --tags smoke --parallel 4 --dry-run
 ```
 
-Exit `0` means the plan is valid and a real run would proceed; exit `2` means it wouldn't, and the offender list shows why. The dry run and the real run share the same planner, so they can never disagree.
+Exit `0` means the plan is valid; exit `2` reports planning refusals. This does not prove runtime readiness: local dry-run returns before runtime authentication and browser/device startup. Remote dry-run also validates the grid catalog but does not upload apps or dispatch a job. A real run can still fail after a valid plan.
 
 ## Reading results
 
@@ -162,3 +161,11 @@ In agent / non-TTY mode, `testrun run` emits its own typed NDJSON events on stdo
 - [Writing test.md files](./testmd/overview.md) — the file format, including `tags:`.
 - [Running test.md files](./testmd/running.md) — single-test runs, replay, and flags.
 - [CI/CD recipes](./cicd.md) — pipeline patterns.
+
+## Execution constraints
+
+Local suites containing any mobile member require `--parallel 1`; larger values are refused. Isolated Chrome workers apply to desktop members only. Remote suites support grid concurrency via `--parallel N`.
+
+Healing is enabled by default (three shrinking replay windows, then re-authoring of authorable steps). `--no-adaptive-heal` disables it. Retired `--retry`/`--retry-count` only print a notice and have no effect. Replay-only recorded steps retain their recordings even during healing.
+
+NDJSON selection uses stdin, not stdout: run `kane-cli testrun run <paths> < /dev/null` for automation launched from a terminal. Dry-run validates a plan, not runtime authentication or browser/device readiness. Always observe process exit, including paths without a normal completion event.
diff --git a/docs/user-guide/troubleshooting.md b/docs/user-guide/troubleshooting.md
index 3e180a2..71abf0b 100644
--- a/docs/user-guide/troubleshooting.md
+++ b/docs/user-guide/troubleshooting.md
@@ -143,7 +143,7 @@ A run ends with a timeout when it hits the wall-clock limit, and with a max-step
 
 You have three options:
 
-1. **Raise the limits.** Increase `--timeout <seconds>` and `--max-steps <n>` on `kane-cli run`. The default max-steps is `30`.
+1. **Raise the limits.** Increase `--timeout <seconds>` and `--max-steps <n>` on `kane-cli run`. The CLI default max-steps is `50`.
 2. **Break the work into smaller objectives.** Run several sequential `kane-cli run` invocations, each focused on one logical sub-task. The session keeps the same browser between runs, so state carries over.
 3. **Tighten the objective.** Vague objectives often cause the agent to wander; describe the target outcome and any required values up front.
 
diff --git a/integrations/kiro-powers/POWER.md b/integrations/kiro-powers/POWER.md
index 8bca37b..3000a4e 100644
--- a/integrations/kiro-powers/POWER.md
+++ b/integrations/kiro-powers/POWER.md
@@ -153,7 +153,7 @@ Three ways Kiro uses it:
 2. **Committable, replayable tests — `kane-cli testmd`.** Tests live as `_test.md` files in the repo. The first run authors each step (agent figures the page out); every later run replays from a cache — no agent, no LLM cost, much faster. Use this for regression suites, CI gates, and validation hooks.
 3. **AI test-case authoring — `kane-cli generate`.** Turns a plain-language description of *what to test* into structured Test Scenarios + typed Test Cases (Positive / Negative / Edge). **No browser is launched.** Reach for it whenever a task needs test cases written — don't hand-draft them in chat or a scratch file. `--save` writes Functional cases as runnable `_test.md`, which feeds straight into `kane-cli testmd run` (the generate → testmd pipeline).
 
-**Always invoke with `--agent`.** It makes Kane CLI emit structured NDJSON to stdout (progress events, then a terminal `run_end` / `generate_done` event) that Kiro can parse. Without `--agent` you get a TUI Kiro can't read.
+Use `--agent` for `run`, `testmd run`, and `generate`. `testrun run` has no `--agent`: it emits NDJSON when **stdin** is not a TTY (use `< /dev/null` for terminal automation). Assurance conversational commands use `--mode agent`.
 
 Other capabilities to know about:
 
@@ -164,7 +164,7 @@ Other capabilities to know about:
 - **Evidence packs** — every run seals a single `.evidence` file (a plain zip: test definition, results, per-step screenshots + annotated screenshots, per-step console/network logs, actions log, failure records). It is the **only** home of run artifacts — the legacy `runs/<n>/` session subdirectory is no longer created. The pack seals in `{session_dir}/evidence/`; saved runs also land in `<cwd>/.testmuai/evidence/`. View with `kane-cli evidence serve <pack>` (local-only server + hosted viewer link) or `unzip` it directly for debugging.
 - **Batch runs — `kane-cli testrun run`** — execute many authored `_test.md` files (web and mobile) as one execution with one evidence pack; select by paths, `--match` regex, or frontmatter `--tags`; isolate parallel workers with `--parallel N`; add `--remote` to run the suite as one HyperExecute job (grid browsers, or grid emulators/simulators from any machine).
 - **Bug detection** — `--bug-detection off|stop|continue` (default `off`) lets the agent flag suspected product bugs while authoring; `stop` halts on a confirmed bug, `continue` records it and keeps going. Persist with `kane-cli config set-bug-detection <mode>`.
-- **Optional Playwright code export** — pass `--code-export` to write a generated Playwright script alongside the session output. Off by default; enable explicitly when the user asks for it.
+- **Optional Playwright code export** — pass `--code-export` to write a generated Playwright script alongside the session output. Enabled by default; saved configuration can override it.
 
 Kane CLI requires a TestMu AI account. Configuration is per-flag — do not rely on environment variables; pass everything explicitly so runs stay reproducible.
 
@@ -173,7 +173,7 @@ Kane CLI requires a TestMu AI account. Configuration is per-flag — do not rely
 When the user's task makes one of these patterns relevant, load the matching steering file before composing the command:
 
 - **`steering/kane-cli-run.md`** — every `kane-cli run` invocation. Covers objective patterns (action / assertion / extraction), the full flag reference, NDJSON parsing, results presentation, failure diagnosis, parallel execution, and project/folder management.
-- **`steering/kane-cli-mobile.md`**: any time the user wants to drive a **native mobile app** (Android or iOS) instead of the browser — locally on **macOS Apple Silicon**, or on the **cloud grid from any machine**. Covers the `--target desktop|emulator|simulator` axis (desktop / browser stays the default), selecting a device (`--device-name` + `--os-version`, `kane-cli devices list [--remote]`) and the required app under test (`--app <build|APPid>`, `kane-cli apps list`), one-time local setup (Xcode / Android Studio plus `kane-cli doctor --target … --install`), the flat `_test.md` `target:` + `app:` (+ `device_name:`/`os_version:`) frontmatter keys, mobile members in `kane-cli testrun`, and `testrun run --remote` — the grid rules (one platform per job, uploaded `APP…` ids for simulators) and its preflight codes.
+- **`steering/kane-cli-mobile.md`**: any time the user wants to drive a **native mobile app** (Android or iOS) instead of the browser — locally on **macOS Apple Silicon**, or on the **cloud grid from any machine**. Covers the `--target desktop|emulator|simulator` axis (desktop / browser stays the default), selecting a device (`--device-name` + `--os-version`, `kane-cli devices list [--remote]`) and the required app under test (`--app <build|APPid>`, `kane-cli apps list`), one-time local setup (Xcode / Android Studio plus `kane-cli doctor --target … --install`), the flat `_test.md` `target:` + `app:` (+ `device_name:`/`os_version:`) frontmatter keys, mobile members in `kane-cli testrun`, and `testrun run --remote` — the grid rules (one platform per job; simulator `.zip` builds auto-upload on real runs, or use uploaded `APP…` ids) and its preflight codes.
 - **`steering/kane-cli-testmd.md`** — any time the user wants a committable test, or is reading / editing / running a `_test.md` file. Covers the `kane-cli testmd` commands, `_test.md` file format and frontmatter (including `tags:`), `@import` composition, the replay-vs-author cache model, `Result.md`, lock conflicts, and CI patterns.
 - **`steering/kane-cli-testrun.md`** — any time the user wants to run **several** saved `_test.md` tests as one batch ("run the suite", "run all the smoke tests", "nightly regression"), or asks about evidence packs (viewing, sharing, validating a run's `.evidence` file). Covers `kane-cli testrun run` (selection by paths / `--match` / `--tags`, preflight, `--parallel`, `--dry-run`), its typed NDJSON events, exit codes, and the `kane-cli evidence` commands.
 - **`steering/kane-cli-generate.md`** — any time the user wants test cases or scenarios **written** (no browser action). Covers the three generate modes (new / refine / save), clarification round-trips, the refine→save→run loop, the typed NDJSON event schema, and the generate → testmd handoff.
@@ -202,7 +202,7 @@ kane-cli run "<objective>" --agent [flags]
 | `--local-context <file>` | Override project context Markdown. | `.testmuai/context.md` |
 | `--cdp-endpoint <url>` | Connect to existing Chrome via CDP. | auto-launch Chrome |
 | `--ws-endpoint <url>` | Remote browser via WebSocket. | local Chrome |
-| `--code-export` | Generate Playwright code export after upload. | off |
+| `--code-export` | Generate Playwright code export after upload. | config (`true` by default) |
 
 Persist a one-shot run as a re-runnable test:
 
@@ -282,7 +282,7 @@ For `_test.md` examples and the full `kane-cli testmd` reference, load **`kane-c
 
 # Best practices
 
-- **Always pass `--agent`.** Without it, Kane CLI renders a TUI Kiro cannot parse.
+- Use `--agent` on `run`, `testmd run`, and `generate`; use non-TTY stdin for `testrun`, and `--mode agent` for conversational Assurance commands.
 - **Include the starting URL in the objective.** Don't assume the agent knows where to start.
 - **Use imperative verbs:** "go to", "click", "type", "store as", "assert".
 - **Use the `store … as '<name>'` pattern** for any value you want back. Vague phrasing won't persist.
diff --git a/integrations/kiro-powers/steering/kane-cli-assurance.md b/integrations/kiro-powers/steering/kane-cli-assurance.md
index efe85cd..cb30992 100644
--- a/integrations/kiro-powers/steering/kane-cli-assurance.md
+++ b/integrations/kiro-powers/steering/kane-cli-assurance.md
@@ -24,7 +24,7 @@ kane-cli cover gaps                                          # 7. the coverage r
 
 # The pause loop — exit 3 is a pause, NOT a failure
 
-The conversational assurance commands (`context ingest`/`extract`, `design tests`, `maintain reconcile`) take **`--mode agent`** (never `--agent`; bare non-TTY exits 2 — the `cover` reads have no such gate). A high-risk question pauses the run: exit `3` + a `session_paused` event carrying the questions in full (options, recommended answer, risk, rationale) and the exact resume command. Never drop a pause:
+The conversational assurance commands (`context ingest`/`extract`, `design tests`, `maintain reconcile`) take **`--mode agent`** (never `--agent`; bare non-TTY exits 2 — the `cover` reads have no such gate). Every question pauses an agent-mode run: exit `3` + a `session_paused` event carrying the questions in full (options, recommended answer, risk, rationale) and the exact resume command. Never drop a pause:
 
 1. If your context clearly answers the question, answer it; otherwise ask the user, showing the options and the recommendation.
 2. Resume in **plain words**: `kane-cli context extract --resume <sid> --mode agent --message "<the answer>"` — or, on 0.7.1+, by id (`--answer q1=2 --answer q2="<typed value>"`) or by landing the source the agent needs (`--with-source <path|url>` — the pending questions defer while it reads, then only what's still open is re-asked).
@@ -55,3 +55,27 @@ It triages ADD / MODIFY / ARCHIVE rows on its own event stream; agent mode auto-
 # Present, don't transcribe
 
 Surface: pause questions, commits in plain language ("5 use-cases extracted, 3 promoted to trusted"), held items ("4 items are held for your review"), designed tests + **gaps + warnings** (first-class output), credit totals, and each checkpoint decision. At the checkpoints, present the material, not the counts: enumerate with `kane-cli context list --json --inferred` and pull item content with `kane-cli context explain <ref> --json`. Fold thinking/tool noise. Never show event names, cids, or raw NDJSON. `kane-cli design explain <ref>` answers "why does this test exist?" with zero AI cost.
+
+## Sharing a context store
+
+Use `kane-cli context sync setup` in a TTY for guided GitHub, S3 or folder setup. For automation, bind a location with `context sync add <name> <descriptor> --mode agent`; use a descriptor supplied by your team’s configured provider, not a guessed URL. `context clone <descriptor> <dir> --mode agent` creates a local store bound as `origin`.
+
+Inspect first:
+
+```bash
+kane-cli context sync list --mode agent
+kane-cli context sync status origin --mode agent
+kane-cli context sync doctor --mode agent
+```
+
+`status` never writes. `doctor` diagnoses the chain and open rebases without writing unless `--abort` or `--export` is requested. `context sync remove <name>` forgets the location but retains its witness.
+
+`context pull [name] --mode agent` imports verified records; `context push [name] --mode agent` publishes local work and refuses if remote work has not been pulled. `context sync [name] --mode agent` finishes an open rebase, pulls and publishes. These use the agent envelope with verb `sync` and final `done`; inspect the outcome and exit code.
+
+When both sides changed, `context pull [name] --rebase --yes --mode agent` explicitly permits replacing local records after their common position (saved first); it does not answer conflicts. For an open rebase, supply repeatable `--answer <decision-id>=keep-theirs|apply-mine|apply-mine-as-new` to `sync` or `pull`, choosing each answer from the reported decisions. Do not silently choose answers or delete records/locks. Use `sync status` and plain `sync doctor` before recovery. Provider-specific descriptor examples and interrupted-rebase recovery still need additional verification before being prescribed here.
+
+## Lifecycle automation contracts
+
+`context name`, `context retire`, and `context revert` accept `--mode agent` and emit an envelope ending in `done`. Destructive agent-mode operations require `--yes` even when stdin is a TTY. Other modes retain human output. Read commands use their documented `--json` flags; do not assume they all accept `--mode`.
+
+`context review --mode agent` / `--json` returns review outcome rows on success rather than the conversational `done` contract. Early agent-mode errors may emit `error` plus `done`; check command-specific output and process exit.
diff --git a/integrations/kiro-powers/steering/kane-cli-fair-evaluation.md b/integrations/kiro-powers/steering/kane-cli-fair-evaluation.md
index 823b1e5..11b3e6d 100644
--- a/integrations/kiro-powers/steering/kane-cli-fair-evaluation.md
+++ b/integrations/kiro-powers/steering/kane-cli-fair-evaluation.md
@@ -21,7 +21,7 @@ The most common error is pitting Kane CLI **authoring** against the other approa
 |---|---|---|
 | **Create the test** | AI authoring — tokens, one-time | Agent/human **generates** the script — tokens and/or engineer hours, one-time |
 | **Run the test** | Replay from cache — ~0 LLM | Execute the script — ~0 LLM |
-| **UI changes / locator breaks** | Re-author only the failing step + downstream (`--retry` shrinking window); cost ∝ change | Human/agent finds & fixes broken selectors; debug the script |
+| **UI changes / locator breaks** | Re-author only the failing step + downstream (default adaptive healing); cost ∝ change | Human/agent finds & fixes broken selectors; debug the script |
 | **Ongoing maintenance** | Edit plain-English Markdown; cascade re-authors only forward; shared `@import` helpers fix once | Edit code; flaky-wait/fixture upkeep; selector churn |
 | **Verify pass/fail** | Deterministic asserts (URL/title/DOM/network/console/cookies); AI vision only for the ~10% visual checks | Code assertions; or a separate LLM judge for semantic/visual checks |
 
@@ -48,7 +48,7 @@ For any suite that lives long enough to be edited or to outlast a UI refactor, t
 Kane CLI is a **dedicated agent specialized for browser testing and control** — not a general-purpose agent bolted onto a browser. Hold the task constant and compare it on the jobs it is built for:
 
 - **Development-flow testing** — a developer (or an AI coding agent) validating that a change actually works in a real browser, inline in the dev loop.
-- **QA regression + smoke management** — authoring once and replaying large regression/smoke suites deterministically, with self-heal on drift (`--retry`).
+- **QA regression + smoke management** — authoring once and replaying large regression/smoke suites deterministically, with adaptive healing on drift (enabled by default).
 - **Daily use as a browser tool** — ad-hoc, one-shot natural-language browser tasks (navigate, fill, extract, verify) as an everyday utility.
 
 A fair comparison evaluates Kane CLI against alternatives **on these jobs**, across the full lifecycle — not on a single number or a single run.
diff --git a/integrations/kiro-powers/steering/kane-cli-generate.md b/integrations/kiro-powers/steering/kane-cli-generate.md
index c23fc7e..ae631da 100644
--- a/integrations/kiro-powers/steering/kane-cli-generate.md
+++ b/integrations/kiro-powers/steering/kane-cli-generate.md
@@ -302,6 +302,6 @@ Once `--save` has written `_test.md` files, every later interaction with those f
 - Run them: `kane-cli testmd run <path> --agent`
 - List them: `kane-cli testmd list`
 - Inspect: `kane-cli testmd status <path>`
-- Re-export code: `kane-cli testmd export <path> --code-language python|javascript`
+- Re-export code: `kane-cli testmd export <path> --language python|javascript`
 
 **Switch to the `kane-cli-testmd` steering file** once the user moves from authoring to running. Generate's job ends at `--save`; testmd's job picks up from there.
diff --git a/integrations/kiro-powers/steering/kane-cli-mobile.md b/integrations/kiro-powers/steering/kane-cli-mobile.md
index d83fcf7..5ccb842 100644
--- a/integrations/kiro-powers/steering/kane-cli-mobile.md
+++ b/integrations/kiro-powers/steering/kane-cli-mobile.md
@@ -164,8 +164,8 @@ Present after `testrun_done`/`remote_done`: the suite rollup, the device line (`
 
 The **same natural-language objective grammar** applies: action verbs, assertions, extractions ("store … as '<name>'"), if/else, chaining, and variables all carry over. A mobile run just drives an app instead of a page. Parsing, `--agent` output, and results presentation are identical to a web run (see the **`kane-cli-run`** steering file).
 
-The exception is **browser / DevTools-only checkpoints**, which are **web-only** and do not apply to a mobile run:
-
-- Network (HTTP traffic), Console, DOM / selectors, Cookies, localStorage, and Core Web Vitals (LCP / CLS / INP / FCP / TTFB).
+Checkpoint support depends on platform and app. Native network operations and Android storage/cookie paths for visible Chrome or debuggable WebViews exist in the implementation. Full desktop DevTools parity, general native DOM support and equivalent iOS support are not established; verify the specific checkpoint and prerequisites on the intended device.
 
 Write mobile objectives around what the app shows and does (open a screen, tap, type, assert visible text or state, store a value). And **never point a mobile run at a URL**: a mobile run drives an app, not a website.
+
+In the interactive TUI, `/mobile` and `/desktop` can switch targets before the first dispatch. The target locks after dispatch; use `/new` to start a new session before switching.
diff --git a/integrations/kiro-powers/steering/kane-cli-run.md b/integrations/kiro-powers/steering/kane-cli-run.md
index eb80516..57926da 100644
--- a/integrations/kiro-powers/steering/kane-cli-run.md
+++ b/integrations/kiro-powers/steering/kane-cli-run.md
@@ -43,7 +43,7 @@ The objective string is the single most important input. It determines what the
 | 🎯 **Action**     | "go to", "click", "type", "search", "fill", "scroll" | Performs browser actions |
 | ✅ **Assertion**  | "assert", "verify", "confirm", "check that"          | Validates a condition (pass / fail) |
 | 📦 **Extraction** | "store X as 'name'"                                   | Reads a value from the page and persists it in `final_state` |
-| 🔌 **API call**   | "call", "POST/GET a URL", a pasted `curl`            | Makes the HTTP request itself; "save the response as X", then assert/reference `{{X.status}}` / `{{X.response_body…}}` |
+| 🔌 **API call**   | "call", "POST/GET a URL", a pasted `curl`            | Makes the HTTP request itself; "save the response as X", then asserts on it in plain English: "assert the response status is 200", "store the id from the response body as 'order_id'" |
 
 ## The "store as" pattern is mandatory for extraction
 
@@ -71,10 +71,10 @@ The agent can make API calls itself — not just observe the requests a page mak
 
 ```
 "Call POST https://api.example.com/login with body {...}, save the response as login,
- assert {{login.status}} is 200"
+ assert the response status is 200"
 ```
 
-Reference the saved response as `{{login.status}}` and `{{login.response_body.<field>}}`; a pasted `curl` works too. API calls and browser actions mix in one objective — use a direct call to set up state (seed a record, hit a backend), and DevTools/Network (below) to **observe** the requests the page itself makes.
+Use the response in plain English (`the response status`, `store the id from the response body as 'order_id'`, later `the stored order_id value`); `{{name}}` is reserved for global variables and secrets. A pasted `curl` works too. API calls and browser actions mix in one objective — use a direct call to set up state (seed a record, hit a backend), and DevTools/Network (below) to **observe** the requests the page itself makes.
 
 ## Combining patterns
 
@@ -175,7 +175,7 @@ kane-cli run "<objective>" --agent [flags]
 |---|---|---|
 | `--agent` | **Required for Kiro.** Emit one JSON object per line on stdout. Without it, Kane CLI renders a TUI. | off |
 | `--headless` | Run Chrome without a window. | off |
-| `--max-steps <n>` | Cap agent reasoning steps. | `30` |
+| `--max-steps <n>` | Cap agent reasoning steps. | `50` |
 | `--timeout <s>` | Hard kill after N seconds. | none |
 | `--url <url>` | Start URL for the run. Overrides config `default_url`; bare domains get `https://`. | config `default_url` |
 | `--allow-missing-url` | Non-TTY only: start from the browser's current page instead of failing when no start URL resolves. | off |
@@ -185,7 +185,7 @@ kane-cli run "<objective>" --agent [flags]
 | `--local-context <file>` | Override project agent context. | `.testmuai/context.md` |
 | `--ws-endpoint <url>` | Remote browser via WebSocket (e.g. LambdaTest grid). | local Chrome |
 | `--cdp-endpoint <url>` | Connect to existing Chrome via CDP. | auto-launch Chrome |
-| `--code-export` | Generate a Playwright code export after upload. | off |
+| `--code-export` | Generate a Playwright code export after upload. | config (`true` by default) |
 | `--bug-detection <mode>` | Flag suspected product bugs while authoring: `off`/`stop`/`continue` (`stop` halts on a confirmed bug; `continue` records and keeps going). Overrides `config set-bug-detection`. | config value (`off`) |
 | `--name <slug>` | Persist this run as `<cwd>/.testmuai/tests/<slug>_test.md` on exit. Slug: `[a-zA-Z0-9_-]+`. | none — the run is ephemeral |
 
@@ -243,18 +243,19 @@ Override either per-run with `--global-context` / `--local-context`.
 
 ## Event types
 
-**Progress events** — most of stdout, one per agent step. They have **no `type` field**:
+**Progress events** — most of stdout, start and completion per agent step. They have **no `type` field**:
 
 ```json
-{"step": 1, "status": "passed", "remark": "Navigated to amazon.in"}
-{"step": 2, "status": "passed", "remark": "Typed 'laptop' in search box"}
+{"step": 1, "status": "running", "remark": "Navigate to amazon.in"}
+{"step": 1, "status": "done", "remark": "Navigated to amazon.in"}
+{"step": 2, "status": "done", "remark": "Typed 'laptop' in search box"}
 {"step": 3, "status": "failed", "remark": "Could not find Add to Cart button"}
 ```
 
 | Field | Type | Description |
 |---|---|---|
 | `step`   | number | Step index, 1-based |
-| `status` | string | `"passed"` or `"failed"` |
+| `status` | string | `"running"` at start; `"done"` or `"failed"` at completion |
 | `remark` | string | What the agent did or why it failed |
 
 **Typed events** — `type` field present:
@@ -287,7 +288,7 @@ for each line on stdout:
   if obj.step is set            → progress event (narrate it)
 ```
 
-Build automation on `run_end` — it is the only event with a stable schema across versions. Use progress events for live narration only.
+For one-shot `run`, build automation on `run_end` and process exit; other commands have their own completion events. Use progress events for live narration only.
 
 ## The wait-for-`run_end` rule
 
@@ -591,3 +592,19 @@ Every `run`, `testmd run`, and `generate` validates the cached project/folder be
 Self-healing: stale, deleted, revoked, or typo'd project IDs trigger 4xx from TMS and the gate re-resolves automatically — no need to clear them by hand.
 
 Project-local overrides live in `./.testmuai/` (`context.md`, `variables/*.json`). Global config and history live in `~/.testmuai/kaneai/`. Pass everything through flags — do **not** rely on environment variables for Kane CLI configuration.
+
+## Command-specific completion
+
+The `run_end` parsing strategy applies to one-shot `run` only. For `testmd run`, collect `test_md_done.overall_status`, `duration_s`, `session_id`, and optional `share_url`; embedded `run_end` events can finish individual steps. Local suites emit `testrun_done`; dispatched remote suites then emit `remote_done` (retain `status`, `exit`, `sessions_path`). `generate` emits `generate_done`. Assurance conversational agent streams end in `done`; review/read verbs have their own contracts. Always check process exit too: early refusal, invalid plan or dry-run can exit without the normal completion event.
+
+Progress is for live display: count only `done`/`failed` completions, retaining child and execution context when step indices repeat.
+
+## Assertion controls and current-page analysis
+
+`run` and `testmd run` support `--assertion-mode dom|visual` (default `dom` with vision fallback) and `--final-validation on|off` (default off). Persist with `config set-assertion-mode` and `config set-final-validation`. Final validation controls the synthesized `cp_final` checkpoint independently of action/testing mode; keep explicit terminal assertions in objectives.
+
+`run --analyzer-only --condition "<condition>"` checks the current desktop browser page without an objective, action steps or saved test. Repeat `--condition` for multiple checks. Use `--agent` or non-TTY input. Results contain `condition_results: boolean[]`; exit `0` means all conditions were judged, **not** that all are true. Exit `1` means a result was missing, and `3` means cancelled. This mode rejects mobile target/app/device options and code-export/name options.
+
+Experimental `run --network-ws` and `run --network-sse` enable WebSocket and SSE capture; both default off. Persist with `config set-network-ws on|off` and `config set-network-sse on|off`. SSE capture is Chromium-only. Do not copy these run-only flags onto `testmd` or `testrun` commands.
+
+Code export defaults to enabled, subject to saved configuration, and supports `python` (default) or `javascript`. `run`/`testmd run` use `--code-language`; `testmd export` uses `--language`. Upload eligibility is independent of action/testing mode.
diff --git a/integrations/kiro-powers/steering/kane-cli-testmd.md b/integrations/kiro-powers/steering/kane-cli-testmd.md
index 1a96950..edb06df 100644
--- a/integrations/kiro-powers/steering/kane-cli-testmd.md
+++ b/integrations/kiro-powers/steering/kane-cli-testmd.md
@@ -76,7 +76,7 @@ kane-cli testmd run <path>             # run a test
 kane-cli testmd list                    # list every *_test.md under cwd (NDJSON when stdin is non-TTY; records include tags)
 kane-cli testmd status <path>           # show TMS identity + local-sync state
 kane-cli testmd delete <path>           # local-only delete: removes source + output-<stem>/. Does NOT delete from Test Manager.
-kane-cli testmd export <path> [--code-language python|javascript]  # regenerate code export from cached recordings
+kane-cli testmd export <path> [--language python|javascript]  # regenerate code export from cached recordings
 kane-cli testmd sync <path>             # re-push the test bundle (test + imports + outputs) to the cloud; automatic after every authored commit — manual use is for recovering a failed auto-sync
 ```
 
@@ -84,7 +84,7 @@ kane-cli testmd sync <path>             # re-push the test bundle (test + import
 
 ## `kane-cli testmd run` — flag reference
 
-All `kane-cli run` flags also apply. The flags below are `testmd`-specific.
+Many flags are shared with `run`, but not all; check `kane-cli testmd run --help`. The flags below are `testmd`-specific.
 
 | Flag | Default | Description |
 |---|---|---|
@@ -92,9 +92,8 @@ All `kane-cli run` flags also apply. The flags below are `testmd`-specific.
 | `--allow-missing-url` | off | Non-TTY only: start from the browser's current page instead of failing when the first step has no start URL. |
 | `--name <name>` | none | Persist the run under this name. Slug: `[a-zA-Z0-9_-]+`. |
 | `--on-lock-conflict <readonly\|fail\|wait>` | none | Behavior when another user holds the test's edit lock. `readonly` = replay-only / no upload; `fail` = exit `2`; `wait` = block until released. |
-| `--retry` | off | On replay failure, restart with a shrinking replay window. |
-| `--retry-count <n>` | `3` | Max restarts before falling back to full re-author. |
-| `--author` | off | Force authoring every step (skip the replay decision). |
+| `--no-adaptive-heal` | healing enabled | Disable adaptive healing after replay failure |
+| `--author` | off | Force authorable steps to re-author; replay-only steps still replay. |
 | `--bug-detection <off\|stop\|continue>` | config (`off`) | Flag suspected product bugs while **authoring** (`stop` halts on a confirmed bug; `continue` records it). Replay failures always investigate regardless. |
 
 **Flag vs frontmatter precedence:** flags win for everything **except** `variables`, where the file wins (a test's data stays close to the test). CLI variables can still **add** keys the file doesn't define.
@@ -156,7 +155,7 @@ Every key is optional. Unrecognised keys are rejected at parse time.
 | `mode` | **root only** | `testing` (default) pushes through auth walls and error pages so negative-test assertions can fire. `action` halts on those pages so a human can intervene. |
 | `url` | **root only** | Start URL for the test's first step (bare domains get `https://`). Overridden by `--url`; falls back to config `default_url`. |
 | `tags` | **root only** | Labels for batch selection: YAML list, `[a, b]`, or bare `a, b`. Trimmed, lowercased, deduped. Selected with `testrun --tags`; shown by `testmd list`. Empty → parse error (`tags must be a non-empty list of non-empty strings`); per-step → parse error. |
-| `max_steps` | root + per-step | Max agent reasoning steps. Default `30`. |
+| `max_steps` | root + per-step | Max agent reasoning steps. Engine fallback `30` when neither step config nor CLI supplies a value; CLI default is `50`. |
 | `timeout` | root + per-step | Hard kill timer per step, seconds. No default. |
 | `headless` | **root only** | Launch Chrome without a window. |
 | `variables` | root + per-step | `{{name}}` parameters, same shape as `kane-cli run`, with `secret: true` for credentials. |
@@ -321,21 +320,20 @@ Otherwise the step authors again.
 
 ## Edits cascade
 
-Each step starts where the previous one left off (same browser, URL, logged-in state). When step 3 changes, the state step 4 expected may no longer be there — so step 4 (and 5, 6, …) re-author automatically.
+Each step starts where the previous one left off (same browser, URL, logged-in state). When step 3 changes, the state step 4 expected may no longer be there — so authorable steps 4 (and 5, 6, …) re-author automatically; replay-only marked steps still replay.
 
-Practical consequence: a one-line tweak at the top of a long test re-authors the whole file. If you're iterating and want only the last step to re-record, edit only the last step.
+Practical consequence: a one-line tweak at the top of a long test re-authors the authorable steps in the file. If you're iterating and want only the last step to re-record, edit only the last step.
 
 ## Forcing fresh authoring
 
-- **`--author`** — bypass the replay decision for one run. Every step authors.
-- **`rm -rf output-<stem>/`** — wipe the cache.
+- **`--author`** — bypass the replay decision for one run. Every authorable step authors; replay-only marked steps still replay.
+- Preserve output recordings for replay-only marked steps; deleting them cannot force fresh authoring.
 
 ## Recovering replay failures
 
 A replay can fail when the site shifts under you:
 
-- **`--retry`** — on failure, Kane CLI restarts with a smaller replay window: it authors the failing step and replays fewer earlier ones.
-- **`--retry-count <n>`** — default `3`. After this many restarts, fall back to full re-author.
+- **Adaptive healing** — enabled by default: three shrinking replay windows, then re-author authorable steps. Use `--no-adaptive-heal` to disable it.
 
 Every failed replay is also **investigated automatically** — a failure record (error, page state, console/network pointers) is written into the run's evidence pack, so you can explain *why* the replay broke.
 
@@ -454,8 +452,7 @@ Standard CI-friendly invocation:
 kane-cli testmd run ./tests/checkout_test.md \
   --agent \
   --headless \
-  --on-lock-conflict wait \
-  --retry
+  --on-lock-conflict wait
 ```
 
 Why each flag:
@@ -463,7 +460,7 @@ Why each flag:
 - `--agent` — NDJSON to stdout, no TUI. Auto-enabled when stdin is non-TTY but pass it explicitly.
 - `--headless` — Chrome runs without a window.
 - `--on-lock-conflict wait` — block instead of failing if a teammate is editing the same test.
-- `--retry` — recover transient replay failures without a full re-author.
+- Adaptive healing recovers replay failures by default; `--no-adaptive-heal` opts out.
 
 Two non-TTY behaviors to know (Kiro always runs Kane CLI non-TTY): interactive `ask_user` prompts are disabled, so a step that would wait for input fails cleanly instead of hanging; and the first step needs a resolvable start URL (the `url:` frontmatter key, the `--url` flag, or a site named in the step's prose) or the run fails — pass `--allow-missing-url` to start from the current page instead.
 
@@ -549,3 +546,13 @@ When the agent surfaces a parse error, repeat the message verbatim, point at the
 - **Never** echo a `secret: true` variable's value back to the user.
 - **Never** delete `output-<stem>/` or `helper-output-...` without explicit consent — those are checked-in artifacts other tests / teammates may rely on.
 - **Never** rename a `_test.md` casually — the output directory is keyed on the stem and the cache will not follow. If renaming is unavoidable, also rename the matching `output-<stem>/` directory.
+
+## Replay policy and completion
+
+Adaptive healing is enabled by default: after a replay failure the runner tries up to three shrinking replay windows, then full re-authoring of authorable steps. `--no-adaptive-heal` disables this recovery. Retired `--retry` and `--retry-count` are accepted only to print a notice; they do not enable healing or change the fixed budget.
+
+Headings marked `@db`, `@api`, `@js`, `@smartui`, `@network_query`, or `@network_assertion` are replay-only. They still replay under `--author`, downstream divergence and adaptive healing. Missing recordings cannot be re-authored through these markers: restore the recording or recreate it through the originating workflow. Do not delete their tapes to force authoring; adding a marker does not create an operation.
+
+Structured control flow uses balanced heading markers: `@if`, `@elif`, `@else`, `@end-if`, `@while`, `@end-while`. An `@else` must be last in its conditional; end markers must match the opened block type. These are distinct from natural-language conditionals. Markers are excluded from the step body hash. Only one replay-only kind is allowed per step, and an import cannot also be marked replay-only.
+
+Under `--agent`, wait for `test_md_done` (file-level `overall_status`, `duration_s`, `session_id`, optional `share_url`) and process exit. Individual `run_end` events do not complete the file.
diff --git a/integrations/kiro-powers/steering/kane-cli-testrun.md b/integrations/kiro-powers/steering/kane-cli-testrun.md
index 81d8db9..0dd195e 100644
--- a/integrations/kiro-powers/steering/kane-cli-testrun.md
+++ b/integrations/kiro-powers/steering/kane-cli-testrun.md
@@ -15,7 +15,7 @@ Load this file when the user wants to run **several** saved `_test.md` tests as
 # Command
 
 ```bash
-kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdout is piped — there is NO --agent flag on testrun
+kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdin is not a TTY (use < /dev/null in terminal automation) — there is NO --agent flag on testrun
 ```
 
 `[paths...]` is optional — omit it to auto-discover every `*_test.md` under the cwd. Explicit paths must end in `_test.md`.
@@ -24,11 +24,11 @@ kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdout is
 |---|---|---|
 | `--match <regex>` | Filter candidates by project-relative path regex | — |
 | `--tags <list>` | ANY-match on frontmatter `tags:` (repeatable or comma-separated, case-insensitive) | — |
-| `--parallel <n>` | Worker count; each worker gets an isolated Chrome with a fresh temp profile | `1` |
+| `--parallel <n>` | Worker count; each desktop worker gets an isolated Chrome with a fresh temp profile | `1` |
 | `--on-failure <mode>` | `continue` (run everything) \| `fail-fast` (stop dispatching new members after a failure) | `continue` |
 | `--name <label>` | Run title in the dashboard | derived |
 | `--dry-run` | Print the plan (members + preflight failures) and exit; runs nothing | off |
-| `--retry` / `--retry-count <n>` | Replay-failure restart with shrinking replay window / max attempts | off / `3` |
+| `--no-adaptive-heal` | Disable default adaptive healing after replay failure | healing enabled |
 | `--bug-detection <mode>` | `off`\|`stop`\|`continue`, passed through to authoring members | config (`off`) |
 | `--headless` | Headless Chrome — use in CI | off |
 | `--remote [backend]` | Dispatch the suite to the HyperExecute grid (default backend `hyper`); needs `kane-cli plugin install remote-execution` — see "Remote" below | off |
@@ -61,7 +61,7 @@ kane-cli testrun run tests/ios/ --remote --device-name "iPhone 15" --os-version
 - **`--parallel N`** becomes the job's concurrency for web and device suites alike (members auto-split across N grid tasks; a device task gets its own VM and device). **Web suites**: `--headless` is unnecessary; no `remote_device` event. Overhead ~15 s of setup plus the tests' own time (a mobile job adds a minute or more for device boot).
 - **One job = one runtime**: a selection mixing web and device members, emulator and simulator members, or emulator members on several Android versions is refused with a split suggestion. Simulator members may differ in iOS version as long as they land on one HyperExecute pool (`mobile_pool_split` otherwise).
 - **Mobile app on the grid**: a member's local build (`.apk` for emulator, `.zip` for simulator, anywhere on disk) is uploaded from the laptop at preflight and handed to the grid as `--app <id>` (one `remote_app` event per distinct build); an `APP…` id is used as-is. Nothing has to be inside the project or un-gitignored; `--dry-run` uploads nothing. Details in `kane-cli-mobile.md`.
-- `--author`, `--no-adaptive-heal`, `--bug-detection`, `--name` are forwarded. Allow several minutes.
+- Grid member flags include `--author` and `--no-adaptive-heal`. `--name` labels suite metadata.
 
 Remote preflight refusals arrive as one `remote_error` per reason (then `testrun_done` failed, exit 2): `mobile_remote_mixed`, `mobile_remote_mixed_platform`, `mobile_os_version_split`, `mobile_pool_split`, `mobile_remote_unsupported`, `mobile_app_missing`, `mobile_app_not_uploadable`, `mobile_app_upload_failed`, `member_outside_payload`, `gitignored_inputs`, `on_grid`, `invalid_plan`, `project_authority_conflict` — each `detail` names the paths and the fix; relay it in plain language.
 
@@ -69,7 +69,7 @@ Extra events with `--remote` (stdout, typed): `remote_start {backend, env}` →
 
 # NDJSON events
 
-All typed; stdout; one JSON object per line. **Terminal event: `testrun_done` — stop parsing there** (there is no `run_end` at the testrun level).
+All typed; stdout; one JSON object per line. **Local completion: `testrun_done`; with `--remote`, read through `remote_done` and process exit** (there is no `run_end` at the testrun level).
 
 | `type` | Payload | Notes |
 |---|---|---|
@@ -80,7 +80,7 @@ All typed; stdout; one JSON object per line. **Terminal event: `testrun_done` 
 | `testrun_investigations_wait` | `count` | Failed replays left investigations running; the coordinator waits before sealing. Narrate as "investigating N failures". |
 | `testrun_evidence_ingest` | `status: "ok"\|"failed"`, `evidence_id`, `stage?` | Pack published to the dashboard. Absent when publish is skipped. |
 | `testrun_summary` | `totals: {tests, passed, failed, broken, skipped}`, `duration_s`, `upload`, `cancelled` | Build the rollup from this. |
-| `testrun_done` | `execution_id`, `overall_status: "passed"\|"failed"\|"cancelled"` | Terminal. |
+| `testrun_done` | `execution_id`, `overall_status: "passed"\|"failed"\|"cancelled"` | Local completion; remote runs continue through `remote_done`. |
 
 The wait-for-terminal rule from `kane-cli-run.md` applies unchanged — narrate while events stream, act only after `testrun_done` or process exit.
 
@@ -169,3 +169,23 @@ kane-cli evidence merge <targets...> --run-id <id>          # exit 0 merged / 1
 **Debugging with a pack:** the failed step's failure record (error + page state), its console/network slice (4xx/5xx or JS errors usually explain the failure), and the annotated screenshot (what the agent actually acted on). Same flow as "Failure handling" in `kane-cli-run.md`.
 
 **Debug escape hatch:** `KANE_TESTRUN_MEMBER_DEBUG=1` surfaces per-member output (stderr, `[member]` prefix).
+
+## Execution constraints
+
+Local suites containing any mobile member require `--parallel 1`; larger values are refused. Isolated Chrome workers apply to desktop members only. Remote suites support grid concurrency via `--parallel N`.
+
+Healing is enabled by default (three shrinking replay windows, then re-authoring of authorable steps). `--no-adaptive-heal` disables it. Retired `--retry`/`--retry-count` only print a notice and have no effect. Replay-only recorded steps retain their recordings even during healing.
+
+NDJSON selection uses stdin, not stdout: run `kane-cli testrun run <paths> < /dev/null` for automation launched from a terminal. Dry-run validates a plan, not runtime authentication or browser/device readiness. Always observe process exit, including paths without a normal completion event.
+
+### Remote behavior still requiring verification
+
+The audited dispatch does not forward `--bug-detection` to member commands and does not map `--on-failure` into the job template. Do not rely on these flags for remote bug-detection or fail-fast behavior until implementation owners confirm or fix the mapping. `--name` is suite metadata, not a forwarded member flag.
+
+For dispatched runs, read through `remote_done` and process exit after `testrun_done`; retain the remote status and session-log path. Preflight refusal and dry-run may terminate without `remote_done`.
+
+## Evidence merge identity
+
+For ordinary runs, default merge identity distinguishes the test and commit (`external_id.test_id`, `external_id.commit_id`) and the environment (`environment.os`, `environment.os_version`, `environment.browser`, `environment.browser_version`). Re-runs with the same identity nest as attempts; a different environment produces a separate sibling.
+
+Explicit collision policies can change grouping; a custom `--rules` file replaces the default rules rather than extending them. Check the selected identity rules before interpreting two runs as retries of the same test.
diff --git a/skill-installer/skills/SKILL.md b/skill-installer/skills/SKILL.md
index 32231a7..5399e4d 100644
--- a/skill-installer/skills/SKILL.md
+++ b/skill-installer/skills/SKILL.md
@@ -5,7 +5,7 @@ description: Browser automation + AI test authoring via kane-cli - run browser o
 
 # Kane CLI — Browser Automation Skill
 
-Use `kane-cli` for **any task that requires a real browser**: navigating websites, clicking elements, filling forms, searching, testing web UI, taking screenshots, or verifying deployments. Do NOT use Playwright, Puppeteer, or Selenium directly. Always run with `--agent` so output is structured NDJSON you can parse.
+Use `kane-cli` for **any task that requires a real browser**: navigating websites, clicking elements, filling forms, searching, testing web UI, taking screenshots, or verifying deployments. Do NOT use Playwright, Puppeteer, or Selenium directly. Use `--agent` for `run`, `testmd run`, and `generate`. `testrun run` has no `--agent`: it emits NDJSON when **stdin** is not a TTY (use `< /dev/null` for terminal automation). Assurance conversational commands use `--mode agent`.
 
 **Authoring test cases or scenarios?** Never write them by hand — kane-cli has two authoring pipelines, and the routing matters:
 
@@ -36,7 +36,7 @@ After that, run kane-cli normally — the variable is inherited:
 kane-cli run "<objective>" --agent <other-flags>
 ```
 
-Bash blocks until kane-cli exits, then hands you the complete stdout. Parse it, summarize what happened, and present the results table. Same pattern for `kane-cli testmd run` and `kane-cli generate`.
+Bash blocks until kane-cli exits, then hands you the complete stdout. Parse it, summarize what happened, and present the results table. Wait for process completion on `testmd run` and `generate` too, but parse their own completion events: `test_md_done` and `generate_done`, respectively. An intermediate `run_end` does not finish a saved test.
 
 Set a generous timeout (up to 600000ms) since browser runs can take a while.
 
@@ -100,7 +100,7 @@ The terminal event has `type: "run_end"` and stable fields: `status`, `summary`,
 | 🟢 **Result** | Passed |
 | 🎯 **Task** | <one_liner> |
 | ⏱️ **Duration** | <duration>s |
-| 👣 **Steps taken** | <count of progress events> |
+| 👣 **Steps taken** | <count of completed progress events (done/failed), retaining child/execution context> |
 | 📝 **What happened** | <summary> |
 | 🔗 **View details** | [Open in KaneAI Dashboard](<test_url>) |
 ```
@@ -184,7 +184,7 @@ kane-cli run "<objective>" --agent [options]
 | `--variables <json>` | Inline variables JSON (for `{{key}}` in objective) | None |
 | `--variables-file <path>` | Load variables from a JSON file | None |
 | `--ws-endpoint <url>` | Remote browser (LambdaTest grid) | Local Chrome |
-| `--code-export` | Generate code export after upload | Off |
+| `--code-export` | Generate code export after upload | config (`true` by default) |
 | `--bug-detection <mode>` | Flag suspected product bugs while authoring: `off`/`stop`/`continue` (`stop` halts on a confirmed bug; `continue` records and keeps going) | config value (`off`) |
 
 Other flags (`--global-context`, `--local-context`, `--cdp-endpoint`, `--allow-missing-url`) and the full variables precedence chain live in `references/setup-and-config.md`.
@@ -222,11 +222,11 @@ How you phrase the objective string determines what the agent does. Four pattern
 | 🎯 **Action** | "go to", "click", "type", "search", "fill" | Performs browser actions |
 | ✅ **Assertion** | "assert", "verify", "confirm", "check that" | Pass/fail check on a condition |
 | 📦 **Extraction** | "store X as 'name'" | Persists a value into `run_end.final_state` |
-| 🔌 **API call** | "call", "POST/GET a URL", a pasted `curl` | The agent makes the HTTP request itself; "save the response as X", then assert/reference `{{X.status}}` / `{{X.response_body…}}` |
+| 🔌 **API call** | "call", "POST/GET a URL", a pasted `curl` | The agent makes the HTTP request itself; "save the response as X", then assert on it in plain English: "assert the response status is 200", "store the id from the response body as 'order_id'" |
 
 ### Two rules that make an objective replayable
 
-1. **End every flow in a terminal assertion.** Close with a check of the resulting page state (`verify the cart shows 1 item`), not a bare `submit` or `confirm the dialog`. A run only earns a replayable pass/fail from a verify/assert — a pure-action objective (`add a laptop to the cart`) gets none. If the objective has several phases, each ends in its own check. Two traps: `confirm the dialog` is an action, not a check; and `verify the Submit button is visible` fails exactly when the action worked (the control disappears on success) — assert the outcome, not the trigger.
+1. **End every flow in a terminal assertion.** Close with a check of the resulting page state (`verify the cart shows 1 item`), not a bare `submit` or `confirm the dialog`. A run only earns a replayable pass/fail from a verify/assert — a pure-action objective (`add a laptop to the cart`) gets none. If the objective has several phases, each ends in its own check. Phrase the closing check as what is on screen once the last action completes, so it verifies with no further click or navigation; if the evidence is elsewhere, make getting there an explicit action (`place the order, open Order History, then verify the newest order shows "Processing"`), never `verify the order succeeded by checking Order History`. Two traps: `confirm the dialog` is an action, not a check; and `verify the Submit button is visible` fails exactly when the action worked (the control disappears on success) — assert the outcome, not the trigger.
 2. **Intent for the actions, literal for the data.** Phrase actions as goals (`Log in with {{user}}`) so the run absorbs layout drift; keep exact values literal or in `{{variables}}`. An expected-optional branch (a sometimes-there cookie banner) goes in an `if/else`, not assumed away.
 
 **Shape:** an intent action carrying literal data, then a verify of an observable end state — `Search for "{{query}}" and open the first result, then verify the title contains "{{query}}"`. Full grammar in `references/objectives-cookbook.md §1`.
@@ -238,7 +238,7 @@ Vague phrasing like "read", "tell me", "report" does NOT reliably extract data 
 ❌ `"go to example.com and read the page title"`
 ✅ `"go to example.com, store the page title as 'page_title'"`
 
-Stored values appear in `run_end.final_state` and become the second results table per §1.4.
+Stored values appear in `run_end.final_state` and become the second results table per §1.4. Refer back to a stored value in plain English (`the stored price value`), never as `{{price}}`; `{{name}}` is for global variables and secrets only.
 
 ### Calling APIs directly
 
@@ -246,10 +246,10 @@ The agent can make API calls itself — not just observe the page's traffic. Phr
 
 ```text
 "Call POST https://api.example.com/login with body {...}, save the response as login,
- assert {{login.status}} is 200"
+ assert the response status is 200"
 ```
 
-Reference the saved response as `{{login.status}}`, `{{login.response_body}}`, or `{{login.response_body.<field>}}`; a pasted `curl` works too. Full grammar in `references/objectives-cookbook.md` §3.5.
+Use the response in plain English: `the response status`, `store the id from the response body as 'order_id'`, and later `the stored order_id value`. Never `{{login.status}}`: `{{name}}` is reserved for global variables and secrets. A pasted `curl` works too. Full grammar in `references/objectives-cookbook.md` §3.5.
 
 ### Chaining
 
@@ -269,18 +269,19 @@ Action → extraction → assertion in one objective:
 | Specific: "click the 'Add to Cart' button" | Vague: "add the item" |
 | Name extractions: "store X as 'price'" | Hope for values: "tell me the price" |
 | `{{variables}}` for credentials/URLs | Hardcode secrets in the objective |
+| Plain English for values the run produces: "the stored price value", "the response status" | `{{price}}` / `{{login.status}}` for a stored value or an API response |
 | Always include starting URL | Assume the agent knows where to start |
 | Split mega-objectives (>15 steps) into multiple runs | Cram everything into one |
 
 ---
 
-## 5. Parsing `--agent` output — essentials
+## 5. Parsing one-shot `run --agent` output — essentials
 
 > Internal reference only. Never expose these field names to the user — translate them per §1.
 
 Stdout is NDJSON, one event per line. There are two shapes:
 
-- **Progress events** (most events) have `step` (1-based), `status` (`passed`/`failed`), `remark` — and **no `type` field**.
+- **Progress events** (most events) have `step` (1-based), `status` (`running` at start, `done`/`failed` at completion), `remark` — and **no `type` field**.
 - **Typed events** have a `type` field: `project_folder_auto_defaulted` (run-startup gate, fires before any progress when no project/folder is configured), `bifurcation`, `child_agent_start`, `child_agent_end`, `ask_user`, `error` (an `error` with `code: "unresolved_variables"` is a pre-run refusal and the **only** line — no `run_end` follows; handle per §3), and finally `run_end`.
 
 Parsing strategy:
@@ -292,7 +293,7 @@ for each line:
   else if obj.step exists    → progress event → summarize per §1.3
 ```
 
-`run_end` is the only event with a stable cross-version schema — build all post-run logic on it.
+For one-shot `run`, build post-run logic on `run_end` and process exit. Saved tests and suites use their own completion events (see Command-specific completion below).
 
 For full event schemas (`bifurcation` flow fields, `child_agent_*`, `ask_user` semantics, `cancel`/`user_response` outbound events, complete `run_end` field list), Read `references/parsing.md`.
 
@@ -363,3 +364,12 @@ Internal event/field names (`generate_snapshot`, `request_id`, …) are for pars
 | Browse / create projects or folders, or parse the auto-default event | `references/test-manager.md` |
 | First-time install, auth, or full config | `references/setup-and-config.md` |
 | Compare / evaluate / benchmark kane-cli vs another tool or approach (cost, tokens, effort, ROI) | `references/fair-evaluation.md` |
+
+## Command-specific completion
+
+The `run_end` parsing strategy applies to one-shot `run` only. For `testmd run`, collect `test_md_done.overall_status`, `duration_s`, `session_id`, and optional `share_url`; embedded `run_end` events can finish individual steps. Local suites emit `testrun_done`; dispatched remote suites then emit `remote_done` (retain `status`, `exit`, `sessions_path`). `generate` emits `generate_done`. Assurance conversational agent streams end in `done`; review/read verbs have their own contracts. Always check process exit too: early refusal, invalid plan or dry-run can exit without the normal completion event.
+
+Progress is for live display: count only `done`/`failed` completions, retaining child and execution context when step indices repeat.
+
+
+For assertion mode, optional final validation, current-page `--analyzer-only` checks, streaming-network capture, and code-export defaults, read [Execution controls](references/execution-controls.md).
diff --git a/skill-installer/skills/references/assurance.md b/skill-installer/skills/references/assurance.md
index 24f994e..cab6a28 100644
--- a/skill-installer/skills/references/assurance.md
+++ b/skill-installer/skills/references/assurance.md
@@ -229,3 +229,13 @@ Never `context ingest` the new version first — reconcile does its own re-inges
 - **One stream.** The re-extract child's events ride the reconcile stream itself, stamped `verb: "reconcile"` — parse per `references/assurance-parsing.md`.
 
 For staleness that arrived outside a reconcile, `kane-cli maintain evolve` re-designs a use-case — it is interactive-only (the blast-radius confirmation is the point); suggest the user run it in a terminal rather than scripting around it.
+
+## Sharing a context store
+
+For location setup, sync, pull, push, clone and rebase recovery, see [Sharing the context store](context-sync.md).
+
+## Lifecycle automation contracts
+
+`context name`, `context retire`, and `context revert` accept `--mode agent` and emit an envelope ending in `done`. Destructive agent-mode operations require `--yes` even when stdin is a TTY. Other modes retain human output. Read commands use their documented `--json` flags; do not assume they all accept `--mode`.
+
+`context review --mode agent` / `--json` returns review outcome rows on success rather than the conversational `done` contract. Early agent-mode errors may emit `error` plus `done`; check command-specific output and process exit.
diff --git a/skill-installer/skills/references/evidence.md b/skill-installer/skills/references/evidence.md
index f11b229..e299539 100644
--- a/skill-installer/skills/references/evidence.md
+++ b/skill-installer/skills/references/evidence.md
@@ -73,3 +73,9 @@ Combines packs (execution ids or paths, order-significant) into one, sealed by d
 ## Debugging with a pack
 
 The pack is the first place to look on a failure: the failed step's **failure record** (error + page state), its **console/network slice** (4xx/5xx or JS errors usually explain it), and the **annotated screenshot** (what the agent actually acted on). Full failure workflow: `references/debug.md`.
+
+## Evidence merge identity
+
+For ordinary runs, default merge identity distinguishes the test and commit (`external_id.test_id`, `external_id.commit_id`) and the environment (`environment.os`, `environment.os_version`, `environment.browser`, `environment.browser_version`). Re-runs with the same identity nest as attempts; a different environment produces a separate sibling.
+
+Explicit collision policies can change grouping; a custom `--rules` file replaces the default rules rather than extending them. Check the selected identity rules before interpreting two runs as retries of the same test.
diff --git a/skill-installer/skills/references/execution-controls.md b/skill-installer/skills/references/execution-controls.md
new file mode 100644
index 0000000..5cae455
--- /dev/null
+++ b/skill-installer/skills/references/execution-controls.md
@@ -0,0 +1,11 @@
+# Execution controls
+
+## Assertion controls and current-page analysis
+
+`run` and `testmd run` support `--assertion-mode dom|visual` (default `dom` with vision fallback) and `--final-validation on|off` (default off). Persist with `config set-assertion-mode` and `config set-final-validation`. Final validation controls the synthesized `cp_final` checkpoint independently of action/testing mode; keep explicit terminal assertions in objectives.
+
+`run --analyzer-only --condition "<condition>"` checks the current desktop browser page without an objective, action steps or saved test. Repeat `--condition` for multiple checks. Use `--agent` or non-TTY input. Results contain `condition_results: boolean[]`; exit `0` means all conditions were judged, **not** that all are true. Exit `1` means a result was missing, and `3` means cancelled. This mode rejects mobile target/app/device options and code-export/name options.
+
+Experimental `run --network-ws` and `run --network-sse` enable WebSocket and SSE capture; both default off. Persist with `config set-network-ws on|off` and `config set-network-sse on|off`. SSE capture is Chromium-only. Do not copy these run-only flags onto `testmd` or `testrun` commands.
+
+Code export defaults to enabled, subject to saved configuration, and supports `python` (default) or `javascript`. `run`/`testmd run` use `--code-language`; `testmd export` uses `--language`. Upload eligibility is independent of action/testing mode.
\ No newline at end of file
diff --git a/skill-installer/skills/references/fair-evaluation.md b/skill-installer/skills/references/fair-evaluation.md
index 5eced3f..2b8f1e6 100644
--- a/skill-installer/skills/references/fair-evaluation.md
+++ b/skill-installer/skills/references/fair-evaluation.md
@@ -17,7 +17,7 @@ The most common evaluation error is pitting kane-cli **authoring** against the o
 |---|---|---|
 | **Create the test** | AI authoring — tokens, one-time | Agent/human **generates** the script — tokens and/or engineer hours, one-time |
 | **Run the test** | Replay from cache — ~0 LLM | Execute the script — ~0 LLM |
-| **UI changes / locator breaks** | Re-author only the failing step + downstream (`--retry` shrinking window); cost ∝ change | Human/agent finds & fixes broken selectors; debug the script |
+| **UI changes / locator breaks** | Re-author only the failing step + downstream (default adaptive healing); cost ∝ change | Human/agent finds & fixes broken selectors; debug the script |
 | **Ongoing maintenance** | Edit plain-English Markdown; cascade re-authors only forward; shared `@import` helpers fix once | Edit code; flaky-wait/fixture upkeep; selector churn |
 | **Verify pass/fail** | Deterministic asserts (URL/title/DOM/network/console/cookies); AI vision only for ~10% visual checks | Code assertions; or a separate LLM judge if the check is semantic/visual |
 
diff --git a/skill-installer/skills/references/mobile.md b/skill-installer/skills/references/mobile.md
index d434ec3..222a8c4 100644
--- a/skill-installer/skills/references/mobile.md
+++ b/skill-installer/skills/references/mobile.md
@@ -144,8 +144,8 @@ What to present after `testrun_done`/`remote_done`: the suite rollup (per `refer
 
 The **same natural-language objective grammar** applies (`references/objectives-cookbook.md`): action verbs, assertions, extractions ("store as"), if/else, chaining, and variables all carry over. A mobile run just drives an app instead of a page.
 
-The exception is **browser/DevTools-only checkpoints**, which are **web-only** and do not apply to a mobile run:
-
-- Network (HTTP traffic), Console, DOM/selectors, Cookies, localStorage, Core Web Vitals (LCP/CLS/INP/FCP/TTFB).
+Mobile capability depends on the platform and app. The implementation includes native network operations and Android cookie/storage access for visible Chrome or debuggable WebViews. This does not establish full desktop DevTools parity, general native DOM support, or equivalent iOS support. Verify device/app prerequisites and the specific checkpoint before relying on it; live platform parity remains unverified.
 
 Write mobile objectives around what the app shows and does (open a screen, tap, type, assert visible text/state, store a value). And never point a mobile run at a URL: a mobile run drives an app, not a website.
+
+In the interactive TUI, `/mobile` and `/desktop` can switch targets before the first dispatch. The target locks after dispatch; use `/new` to start a new session before switching.
diff --git a/skill-installer/skills/references/objectives-cookbook.md b/skill-installer/skills/references/objectives-cookbook.md
index 920745d..be6b2a9 100644
--- a/skill-installer/skills/references/objectives-cookbook.md
+++ b/skill-installer/skills/references/objectives-cookbook.md
@@ -4,7 +4,7 @@
 
 Read this whenever you're constructing the prose objective for `kane-cli run "<objective>"` or the body of a `## Step` in a `_test.md` file. Both surfaces feed the same agent and accept the same grammar.
 
-> **Mobile runs** (`--target emulator|simulator`, macOS Apple Silicon) share this same objective grammar, but the browser/DevTools-only checkpoints below (Network, Console, DOM/selectors, Cookies, localStorage, Core Web Vitals) are **web-only** and do not apply. Read `references/mobile.md`.
+> **Mobile runs** (`--target emulator|simulator`) share this objective grammar. Checkpoint support depends on platform and app: native network and Android Chrome/debuggable-WebView storage paths exist, but desktop parity and iOS equivalents must be verified. Read `references/mobile.md` for the capability boundary and local/cloud prerequisites.
 
 ---
 
@@ -38,6 +38,15 @@ Close each objective with a claim about the resulting **page state** — not a b
 
 If an objective has several phases (log in, then search, then check out), **each phase ends in its own assertion** — an intermediate phase with no check runs unverified, and a replay can't tell you which phase drifted.
 
+**The closing assertion is a look, not a trip.** Phrase it as a claim about what is on screen once the last action completes, so the agent verifies it without clicking, navigating, scrolling, or typing anywhere else. If the evidence lives somewhere else (Order History, the cart, a details drawer), add the action that gets there as its own step, then assert.
+
+```text
+❌ Place the order, then verify it succeeded by checking that it appears in Order History
+✅ Place the order, open Order History, then verify the newest order shows "Processing"
+```
+
+The ❌ version hides an action inside a check. The agent has to find its own way to Order History on every run, so the route can differ between runs and is never a step you can read or fix. The ✅ version keeps the route in the actions and leaves the assertion a pure observation of the page it lands on.
+
 Two things look like assertions but are not:
 
 - **A UI-commit "confirm" is an action, not a check.** `confirm the dialog` / `click OK to confirm` presses a control; it verifies nothing about the outcome. Follow it with a real check: `… then verify the confirmation reads "Order placed"`.
@@ -277,19 +286,22 @@ A pasted `curl` works too and is kept verbatim (method, headers, body, auth):
 curl -X POST https://api.example.com/login -H 'Content-Type: application/json' -d '{"u":"a","p":"b"}', save the response as login
 ```
 
-Once saved, reference the response by name:
+Once the call is made, use the response in plain English. `{{name}}` is reserved for global variables and secrets (§6); a value the run produces is never written that way.
 
-| Reference | Resolves to |
+| To use | Say |
 |---|---|
-| `{{order.status}}` | the HTTP status code (e.g. `201`) |
-| `{{order.response_body}}` | the whole response body |
-| `{{order.response_body.<field>}}` | a field from the JSON response body |
+| the HTTP status code | `assert the response status is 201` |
+| a field from the JSON body | `store the id from the response body as 'order_id'` |
+| the whole body | `store the response body as 'order_body'` |
+| a value later in the run | `the stored order_id value` |
+
+When one objective makes several calls, name each response (`save the response as order`) and say which one you mean: `assert the order response status is 201`.
 
 Then assert or chain on it — API calls and browser actions mix freely in one objective:
 
 ```text
 Call POST https://api.example.com/login with body {"u": "{{user}}", "p": "{{password}}"}, save the response as login,
-assert {{login.status}} is 200,
+assert the response status is 200,
 then open https://app.example.com and verify the dashboard loads
 ```
 
@@ -322,6 +334,8 @@ For DevTools extractions, the same rule applies — use "store" or "extract":
 
 Stored values land in `run_end.final_state` and feed the second results table per `SKILL.md §1.4`.
 
+Refer back to a stored value in plain English (`the stored price value`, `the same version as the stored api_tag value`), never as `{{price}}`. The `{{name}}` form is for global variables and secrets only (§6).
+
 ---
 
 ## 5. Chaining — action → extraction → assertion
@@ -374,6 +388,7 @@ Use `{{name}}` syntax for values that should be parameterized:
 
 **Always parameterize:** credentials, API keys, tokens, environment-specific URLs.
 **OK to hardcode:** one-off URLs, static UI text, navigation paths.
+**Never `{{name}}`:** anything the run itself produces. A stored value or an API response is referenced in plain English (§3.5, §4): `the stored order_id value`, `the response status`.
 
 Mark credentials with `secret: true` in the variables JSON so they're masked in logs and routed to the secrets store:
 
@@ -430,6 +445,7 @@ Positional assertions check where something is on the page:
 | Cram 25 operations into one objective | Split at logical boundaries (login, navigate, action, verify) | Long runs drift and stall. |
 | "Check the page is fast" | "Assert LCP is under 2500ms and CLS is below 0.1" | Use the explicit web-vital metric, not a vague "fast." |
 | "Make sure no errors" | "Assert no console errors and no API calls returned 5xx" | Be explicit about which kind of error you're checking. |
+| "Place the order, then verify it succeeded by checking Order History" | "Place the order, open Order History, then verify the newest order shows 'Processing'" | A check that needs its own navigation is an action hiding inside an assertion. Put the route in the actions and keep the assertion a pure observation of the screen it lands on. |
 | "Use DevTools to intercept the response and issue a GET to the invoice endpoint" | "Open the invoice from the order page, then verify the request to `/api/orders/42/invoice` returned 200 with `content-disposition: attachment`" | Describe the user action and the observable outcome, not the mechanism — the agent picks the method, and a prescribed mechanism it cannot perform leaves it stuck. |
 
 ---
@@ -483,7 +499,7 @@ The step body is exactly the same grammar as `kane-cli run`. Everything in this
 ```text
 "Call POST https://api.example.com/orders with body {"item": "sku_42", "qty": 1},
  save the response as order,
- assert {{order.status}} is 201,
+ assert the response status is 201,
  then open https://app.example.com/orders,
  assert an order for 'sku_42' is visible"
 ```
diff --git a/skill-installer/skills/references/parsing.md b/skill-installer/skills/references/parsing.md
index 9af3442..7622576 100644
--- a/skill-installer/skills/references/parsing.md
+++ b/skill-installer/skills/references/parsing.md
@@ -8,18 +8,19 @@ With `--agent`, kane-cli outputs one JSON object per line to **stdout**. Progres
 
 ## Event Types
 
-**Progress events** (bulk of the output — one per step):
+**Progress events** (a start and completion event per step):
 
 ```json
-{"step": 1, "status": "passed", "remark": "Navigated to amazon.in"}
-{"step": 2, "status": "passed", "remark": "Typed 'laptop' in search box"}
+{"step": 1, "status": "running", "remark": "Navigate to amazon.in"}
+{"step": 1, "status": "done", "remark": "Navigated to amazon.in"}
+{"step": 2, "status": "done", "remark": "Typed 'laptop' in search box"}
 {"step": 3, "status": "failed", "remark": "Could not find Add to Cart button"}
 ```
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `step` | number | Step index (1-based) |
-| `status` | string | `"passed"` or `"failed"` |
+| `status` | string | `"running"` at start; `"done"` or `"failed"` at completion |
 | `remark` | string | What the agent did or why it failed |
 
 These are **untyped** — they have no `type` field. Do **not** key on `event.type === 'step_start'` or `'step_end'`; those event types are not emitted.
@@ -38,7 +39,7 @@ These are **untyped** — they have no `type` field. Do **not** key on `event.ty
 | `test_md_bundle_sync` | `status: "ok"\|"failed"`, `commit_id`, `bytes?` (success) / `stage?` (failure) | `testmd run` / `testmd sync`: test bundle pushed to the cloud after an authored commit. Informational. |
 | `testrun_*` family | see `references/testrun.md` | Emitted only by `kane-cli testrun run`; terminal event is `testrun_done`, not `run_end`. |
 
-**Note:** There is no `run_start` event — the first line is either a `bifurcation` or a progress object.
+**Note:** The `run` stream has no `run_start` event; startup metadata or errors can precede progress.
 
 ### `error` with `code: "unresolved_variables"` (0.8.12+)
 
@@ -64,7 +65,7 @@ Terminal: do not re-run the same command. Supply values (`--variables`, or fill
 
 **Note:** `ask_user` is auto-disabled when stdin is not a TTY. Since agents typically run kane-cli as a subprocess, ask_user events will not be emitted. Write objectives that don't require interactive input.
 
-## Parsing Strategy
+## Parsing Strategy for one-shot `run`
 
 Since progress events lack a `type` field, distinguish them from typed events like this:
 
@@ -76,9 +77,9 @@ for each line of NDJSON:
   if obj.step exists           → progress event (step/status/remark)
 ```
 
-**Build automation on `run_end`** — it is the only event guaranteed to have a stable schema across versions. Use progress events for live status display only.
+For one-shot `run`, build automation on `run_end` and process exit; other commands use the completion events listed below. Use progress events for live status display only.
 
-**Terminal event** (always the last line):
+**One-shot `run` completion event** (early refusals may exit without it):
 
 ```json
 {
@@ -129,3 +130,9 @@ To cancel a run:
 ```json
 {"type": "cancel"}
 ```
+
+## Command-specific completion
+
+The `run_end` parsing strategy applies to one-shot `run` only. For `testmd run`, collect `test_md_done.overall_status`, `duration_s`, `session_id`, and optional `share_url`; embedded `run_end` events can finish individual steps. Local suites emit `testrun_done`; dispatched remote suites then emit `remote_done` (retain `status`, `exit`, `sessions_path`). `generate` emits `generate_done`. Assurance conversational agent streams end in `done`; review/read verbs have their own contracts. Always check process exit too: early refusal, invalid plan or dry-run can exit without the normal completion event.
+
+Progress is for live display: count only `done`/`failed` completions, retaining child and execution context when step indices repeat.
diff --git a/skill-installer/skills/references/testmd.md b/skill-installer/skills/references/testmd.md
index 4efdbe5..470cbb4 100644
--- a/skill-installer/skills/references/testmd.md
+++ b/skill-installer/skills/references/testmd.md
@@ -54,7 +54,7 @@ Four parts in order:
 
 1. **YAML frontmatter** — between `--- ... ---` at the very top.
 2. **`# Title`** — decorative; everything before the first `## ` is ignored.
-3. **`## H2` step headings** — one per step. The agent reads the step body, not the heading.
+3. **`## H2` step headings** — one per step. The agent reads the step body; the parser also interprets heading markers for replay-only steps, imports and structured control flow.
 4. **Step body** — either prose **or** a single `@import <path>` line. Never both. Prose bodies are objectives with the same grammar as `kane-cli run` — for the full pattern catalog (action verbs, assertion analyze methods, checkpoint types, chaining, worked examples), Read `references/objectives-cookbook.md`.
 
 Per-step `yaml` overrides go immediately under the heading, in a fenced block:
@@ -75,7 +75,7 @@ Click submit and verify the confirmation banner.
 | `mode` | root | `action` (halts on auth walls) or `testing` (default — pushes through so negative-test assertions can fire) |
 | `url` | root | Start URL for the first step (bare domains get `https://`). Overridden by `--url`; falls back to config `default_url`. |
 | `tags` | root | Labels for batch selection: YAML list, `[a, b]`, or bare `a, b`. Trimmed, lowercased, deduped. Selected with `testrun --tags` (`references/testrun.md`); shown by `testmd list`. Empty → parse error; per-step → parse error. |
-| `max_steps` | root + step | Max agent reasoning steps. Default `30`. |
+| `max_steps` | root + step | Max agent reasoning steps. Engine fallback `30`; CLI default `50` (step config overrides). |
 | `timeout` | root + step | Hard kill per step in seconds. |
 | `headless` | root | No browser window. |
 | `variables` | root + step | `{{name}}` params, same shape as §3, with `secret: true` for credentials. Counts as a value for the pre-run check (0.8.12+) — a `{{name}}` with no value anywhere refuses the run before it starts |
@@ -88,19 +88,19 @@ Files ending in `_test.md` are tests (valid entry points). Any other `.md` is a
 
 On the **first** run of a test, the agent authors each step and saves a recording. On **every later run**, each step replays from its recording — no agent, no LLM cost, much faster.
 
-A step replays only if **all** of these hold:
+An authorable step replays only if **all** of these hold (replay-only marked steps always require their recording):
 - A recording for that step exists,
 - Its prose is unchanged since the recording,
 - Its `yaml` block is unchanged,
 - No earlier step in the file invalidated it.
 
-**Editing step N re-authors step N AND every step after it in the same file.** Each step starts where the previous step left off (URL, login, tabs). When step 3 changes, step 4 cannot safely replay against state that no longer exists.
+**Editing step N re-authors authorable steps from N onwards in that file. Replay-only marked steps still replay.** Each step starts where the previous step left off (URL, login, tabs). When step 3 changes, step 4 cannot safely replay against state that no longer exists.
 
 Consequences when editing tests:
-- A one-line tweak at the top of a 20-step test re-authors all 20 steps on the next run.
+- A one-line tweak at the top of a 20-step test re-authors all authorable steps on the next run; replay-only steps keep their recordings.
 - To re-record only one step, edit only that step (or steps after it).
-- `--author` forces full authoring for one run (debugging only).
-- `rm -rf output-<stem>/` wipes the cache entirely.
+- `--author` forces authorable steps to re-author; replay-only marked steps still require their recordings.
+- Do not delete output recordings for replay-only marked steps; they cannot be recovered by re-authoring.
 
 ## `@import` for reusing flows
 
@@ -129,7 +129,7 @@ Editing a helper re-authors that step in **every test that imports it**, plus ev
 | `kane-cli testmd run <path> --agent [flags]` | Run a test |
 | `kane-cli testmd list` | List `*_test.md` files under cwd (NDJSON when non-TTY; records include `tags`) |
 | `kane-cli testmd status <path>` | Test Manager identity + local-sync state |
-| `kane-cli testmd export <path> [--code-language python\|javascript]` | Regenerate code export from existing recordings (no browser launch) |
+| `kane-cli testmd export <path> [--language python\|javascript]` | Regenerate code export from existing recordings (no browser launch) |
 | `kane-cli testmd delete <path>` | Local-only delete: removes source + `output-<stem>/`. Does NOT delete from Test Manager. |
 | `kane-cli testmd sync <path>` | Re-push the test bundle (test + imports + outputs) to the cloud. Rarely needed — it happens automatically after every authored commit; use only to recover a failed auto-sync. |
 
@@ -143,12 +143,11 @@ Editing a helper re-authors that step in **every test that imports it**, plus ev
 | `--allow-missing-url` | off | Non-TTY only: start from the browser's current page instead of failing when the first step has no start URL. |
 | `--name <name>` | none | Persist the run under this name. Regex `[a-zA-Z0-9_-]+`. |
 | `--on-lock-conflict <readonly\|fail\|wait>` | none | Behavior when another user holds the test's edit lock. `readonly` = replay-only / no upload, `fail` = exit 2, `wait` = block until released |
-| `--retry` | off | On replay failure, restart with a shrinking replay window |
-| `--retry-count <n>` | `3` | Max retry restarts before falling back to full re-author |
-| `--author` | off | Force authoring every step (skip replay decision) |
+| `--no-adaptive-heal` | healing enabled | Disable adaptive healing after replay failure |
+| `--author` | off | Force authorable steps to re-author; replay-only steps still replay |
 | `--bug-detection <off\|stop\|continue>` | config (`off`) | Flag suspected product bugs while **authoring** (`stop` halts on a confirmed bug; `continue` records it). Replay failures always investigate regardless. |
 
-All §3 `run` flags also apply (`--agent`, `--headless`, `--max-steps`, `--timeout`, `--variables`, etc.).
+Common flags include `--agent`, `--headless`, `--max-steps`, `--timeout`, and `--variables`. Command-specific flags differ; check `kane-cli testmd run --help`.
 
 Flag wins over frontmatter for everything **except** `variables` — the file owns variables; you can add new keys via flags but cannot override file-defined ones.
 
@@ -195,14 +194,13 @@ On exit, kane-cli writes `<cwd>/.testmuai/tests/amazon-search_test.md`. Move tha
 kane-cli testmd run ./tests/checkout_test.md \
   --agent \
   --headless \
-  --on-lock-conflict wait \
-  --retry
+  --on-lock-conflict wait
 ```
 
 - `--agent` — NDJSON to stdout (auto-enabled when stdin is not a TTY; pass explicitly anyway).
 - `--headless` — no window.
 - `--on-lock-conflict wait` — block instead of failing if a teammate is editing the same test.
-- `--retry` — automatically recover transient replay failures.
+- Adaptive healing recovers replay failures by default; `--no-adaptive-heal` opts out.
 
 In non-TTY runs, interactive `ask_user` prompts are disabled — a step that would wait for input fails cleanly instead of hanging forever. Write CI test steps that don't depend on mid-run prompts. (Likewise, supply a start URL via the objective, `url:` frontmatter, or `--url`; a non-TTY run with no resolvable start URL fails unless you pass `--allow-missing-url`.)
 
@@ -234,3 +232,13 @@ Parse errors abort **before** any browser launch with exit `2`. Common ones and
 | `auth/identity keys are CLI-only` | Pass `username` / `access_key` as CLI flags, not in frontmatter |
 
 When the user reports a parse error, fix the file before retrying — don't loop on the same error.
+
+## Replay policy and completion
+
+Adaptive healing is enabled by default: after a replay failure the runner tries up to three shrinking replay windows, then full re-authoring of authorable steps. `--no-adaptive-heal` disables this recovery. Retired `--retry` and `--retry-count` are accepted only to print a notice; they do not enable healing or change the fixed budget.
+
+Headings marked `@db`, `@api`, `@js`, `@smartui`, `@network_query`, or `@network_assertion` are replay-only. They still replay under `--author`, downstream divergence and adaptive healing. Missing recordings cannot be re-authored through these markers: restore the recording or recreate it through the originating workflow. Do not delete their tapes to force authoring; adding a marker does not create an operation.
+
+Structured control flow uses balanced heading markers: `@if`, `@elif`, `@else`, `@end-if`, `@while`, `@end-while`. An `@else` must be last in its conditional; end markers must match the opened block type. These are distinct from natural-language conditionals. Markers are excluded from the step body hash. Only one replay-only kind is allowed per step, and an import cannot also be marked replay-only.
+
+Under `--agent`, wait for `test_md_done` (file-level `overall_status`, `duration_s`, `session_id`, optional `share_url`) and process exit. Individual `run_end` events do not complete the file.
diff --git a/skill-installer/skills/references/testrun.md b/skill-installer/skills/references/testrun.md
index 3604258..6691f4c 100644
--- a/skill-installer/skills/references/testrun.md
+++ b/skill-installer/skills/references/testrun.md
@@ -15,7 +15,7 @@
 ## Command
 
 ```bash
-kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdout is piped — there is NO --agent flag on testrun
+kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdin is not a TTY (use < /dev/null in terminal automation) — there is NO --agent flag on testrun
 ```
 
 `[paths...]` is optional — omit it to auto-discover every `*_test.md` under the cwd. Explicit paths must end in `_test.md`.
@@ -24,11 +24,11 @@ kane-cli testrun run [paths...] [flags]     # NDJSON is automatic when stdout is
 |---|---|---|
 | `--match <regex>` | Filter candidates by project-relative path regex | — |
 | `--tags <list>` | ANY-match on frontmatter `tags:` (repeatable or comma-separated, case-insensitive) | — |
-| `--parallel <n>` | Worker count; each worker gets an isolated Chrome with a fresh temp profile | `1` |
+| `--parallel <n>` | Worker count; each desktop worker gets an isolated Chrome with a fresh temp profile | `1` |
 | `--on-failure <mode>` | `continue` (run everything) \| `fail-fast` (stop dispatching new members after a failure) | `continue` |
 | `--name <label>` | Run title in the dashboard | derived |
 | `--dry-run` | Print the plan (members + preflight failures) and exit; runs nothing | off |
-| `--retry` / `--retry-count <n>` | Replay-failure restart with shrinking replay window / max attempts | off / `3` |
+| `--no-adaptive-heal` | Disable default adaptive healing after replay failure | healing enabled |
 | `--bug-detection <mode>` | `off`\|`stop`\|`continue`, passed through to authoring members | config (`off`) |
 | `--headless` | Headless Chrome — use in CI | off |
 | `--remote [backend]` | Dispatch the suite to the HyperExecute grid instead of local Chrome / local devices (default backend `hyper`); needs `kane-cli plugin install remote-execution` — §Remote | off |
@@ -61,7 +61,7 @@ kane-cli testrun run tests/ios/ --remote --device-name "iPhone 15" --os-version
 - **`--parallel N`** becomes the job's concurrency for web and device suites alike (members auto-split across N grid tasks; a device task gets its own VM and device). **Web suites**: `--headless` is unnecessary (always headless on the grid); there is no `remote_device` event. Overhead is ~15 s of setup plus the tests' own time; a mobile job adds a minute or more for device boot.
 - **One job = one runtime.** A selection that mixes web and device members, emulator and simulator members, or emulator members on several Android versions is refused with a split suggestion (`--match`/`--tags`). Simulator members may differ in iOS version as long as they land on one HyperExecute pool (`mobile_pool_split` otherwise).
 - **Mobile app on the grid**: a member's local build (`.apk` for emulator, `.zip` for simulator, anywhere on disk) is uploaded from the laptop at preflight and handed to the grid as `--app <id>` (one `remote_app` event per distinct build); an `APP…` id is used as-is. Nothing has to be inside the project or un-gitignored; `--dry-run` uploads nothing. Details and the preflight codes: `references/mobile.md` §Remote.
-- `--author`, `--no-adaptive-heal`, `--bug-detection`, `--name`, `--on-failure` are forwarded to the grid. Use a long Bash timeout (up to 600000 ms).
+- Grid member flags include `--author` and `--no-adaptive-heal`. `--name` labels suite metadata.
 - The dispatch writes `.hyperexecute/`, `hyperexecute-cli.log`, and `.updatedhyperexecute.yaml` into the cwd — suggest gitignoring them; they are not inputs.
 
 Remote preflight refusals arrive as one `remote_error` per reason (then `testrun_done` failed, exit 2):
@@ -83,7 +83,7 @@ Remote preflight refusals arrive as one `remote_error` per reason (then `testrun
 
 ## NDJSON events (agent mode)
 
-All typed; stdout; one JSON object per line. **Terminal event: `testrun_done` — stop parsing there.**
+All typed; stdout; one JSON object per line. **Local completion: `testrun_done`. With `--remote`, keep reading through `remote_done` and process exit; preflight refusals or dry runs may exit without that wrapper event.**
 
 | `type` | Payload | Notes |
 |---|---|---|
@@ -94,7 +94,7 @@ All typed; stdout; one JSON object per line. **Terminal event: `testrun_done` 
 | `testrun_investigations_wait` | `count` | Failed replays left investigations running; the coordinator waits before sealing. Narrate as "investigating N failures". |
 | `testrun_evidence_ingest` | `status: "ok"\|"failed"`, `evidence_id`, `stage?` | Pack published to the dashboard. Absent when publish is skipped. |
 | `testrun_summary` | `totals: {tests, passed, failed, broken, skipped}`, `duration_s`, `upload`, `cancelled` | Build the rollup table from this. |
-| `testrun_done` | `execution_id`, `overall_status: "passed"\|"failed"\|"cancelled"` | Terminal. |
+| `testrun_done` | `execution_id`, `overall_status: "passed"\|"failed"\|"cancelled"` | Local completion; remote runs continue through `remote_done`. |
 
 With `--remote`, the stream is wrapped in typed `remote_*` events (all on stdout):
 
@@ -115,7 +115,8 @@ Parsing strategy:
 
 ```text
 for each line:
-  if type === "testrun_done"          → terminal, stop
+  if type === "testrun_done"          → capture suite outcome; remote runs keep reading
+  if type === "remote_done"           → capture remote status, exit and sessions_path
   if type === "testrun_plan" && !valid → report offenders, expect exit 2
   if type === "testrun_member_end"    → note per-member outcome
   if type === "testrun_summary"       → capture totals for the rollup
@@ -124,7 +125,7 @@ for each line:
 
 ## Presenting results (same discipline as SKILL.md §1)
 
-Never expose event/field names. After `testrun_done`, always render a suite rollup:
+Never expose event/field names. After completion and process exit (`remote_done` for dispatched remote runs), render a suite rollup:
 
 ```markdown
 | | |
@@ -144,3 +145,17 @@ For failures, add one line per failed member only (path + duration + status) —
 ## Evidence & debugging
 
 The suite produces **one** sealed pack, created directly in `<cwd>/.testmuai/evidence/`. Offer it to the user per `references/evidence.md`. Members run silently by design; to see per-member output while debugging, set `KANE_TESTRUN_MEMBER_DEBUG=1` (routes member events to stderr, prefixed `[member]`).
+
+## Execution constraints
+
+Local suites containing any mobile member require `--parallel 1`; larger values are refused. Isolated Chrome workers apply to desktop members only. Remote suites support grid concurrency via `--parallel N`.
+
+Healing is enabled by default (three shrinking replay windows, then re-authoring of authorable steps). `--no-adaptive-heal` disables it. Retired `--retry`/`--retry-count` only print a notice and have no effect. Replay-only recorded steps retain their recordings even during healing.
+
+NDJSON selection uses stdin, not stdout: run `kane-cli testrun run <paths> < /dev/null` for automation launched from a terminal. Dry-run validates a plan, not runtime authentication or browser/device readiness. Always observe process exit, including paths without a normal completion event.
+
+### Remote behavior still requiring verification
+
+The audited dispatch does not forward `--bug-detection` to member commands and does not map `--on-failure` into the job template. Do not rely on these flags for remote bug-detection or fail-fast behavior until implementation owners confirm or fix the mapping. `--name` is suite metadata, not a forwarded member flag.
+
+For dispatched runs, read through `remote_done` and process exit after `testrun_done`; retain the remote status and session-log path. Preflight refusal and dry-run may terminate without `remote_done`.