diff --git a/.agents/skills/annotask-apply/A11Y_RULES.md b/.agents/skills/annotask-apply/A11Y_RULES.md
new file mode 100644
index 0000000..8062295
--- /dev/null
+++ b/.agents/skills/annotask-apply/A11Y_RULES.md
@@ -0,0 +1,77 @@
+# A11Y Rules
+
+Read this file for `a11y_fix` tasks. If you are applying a batch of a11y tasks, read it once for the batch, not once per task.
+
+## Task context
+
+The `a11y_fix` task `context` contains:
+
+- `rule`: axe rule ID, or Annotask's synthetic `tab-order` rule
+- `impact`, `help`, `helpUrl`
+- `elements[]`: offending elements with `html`, `selector`, `fix`, source `file` / `line` / `component`
+- `elements[i].a11y`: computed accessibility metadata for the specific element
+
+```text
+elements[i].a11y = {
+  accessible_name, name_source,
+  role, role_source,
+  tabindex, focusable,
+  focus_indicator,
+  contrast,
+  aria_attrs,
+}
+```
+
+If `screenshot_meta` is present, retrieve it via `annotask_get_screenshot` before proposing visual changes such as contrast or focus-ring fixes.
+
+## Rule playbook
+
+Match on `context.rule`.
+
+| Rule(s) | Fix layer | What to do |
+|---|---|---|
+| `color-contrast`, `color-contrast-enhanced` | Design tokens first | See **Color contrast playbook** below. |
+| `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` that points at visible text. If `name_source === 'placeholder'`, the input still has no real label. |
+| `button-name`, `link-name`, `input-button-name` | Markup | Add visible text or `aria-label`. For icon-only buttons, add a visually hidden label (`sr-only` or the project equivalent). Do not rely on `title`. |
+| `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | Use `alt=""` for decorative imagery and descriptive `alt` for informational imagery. For SVG icons paired with visible text, use `aria-hidden="true"`. |
+| `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These usually live in layout/root files, not leaf components. |
+| `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert or promote `<h1>`, then renumber subsequent heading levels so the outline is contiguous. Usually a layout or section change. |
+| `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what is set. Use `helpUrl` to confirm the role's allowed and required attributes, then remove or add attributes accordingly. |
+| `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Remove `aria-hidden`, move the focusable elements out, or make them unfocusable with `tabindex="-1"` if appropriate. |
+| `tabindex`, `tab-order` | Markup | Remove positive `tabindex`; use `0` for normal DOM-order focus or `-1` for programmatic focus only. For synthetic `tab-order`, inspect `context.tab_order.flag` (`positive`, `unreachable`, `reorder`) and make DOM order match visual order. |
+| `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Fix the framework's document-level source of truth: `index.html`, `app/layout.tsx`, `src/routes/+layout.svelte`, or the equivalent root document. |
+| `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>` or `<span>`. Do not nest interactive elements. |
+| `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element in the layout. Use the project's visually-hidden pattern that becomes visible on `:focus`. |
+| `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="..."` values and rename one. If the id is generated, make the generation key unique per instance. |
+| `frame-title`, `iframe-title` | Markup | Add `title="..."` describing the iframe's purpose. |
+
+## Color contrast playbook
+
+Use this when `context.rule` is `color-contrast` or `color-contrast-enhanced`. The goal is to land **one token-level edit** that fixes the violation on the first try, without spraying inline overrides or hardcoded hex into component CSS.
+
+1. **Read the structured contrast block first.** `elements[i].a11y.contrast` gives you `foreground`, `background`, and `ratio` as actual computed hex. Treat these as facts; do not re-derive from screenshots.
+2. **Open the source at `elements[i].file:line` and locate the failing CSS rule.** Identify how `color` and `background`/`background-color` are set:
+   - `var(--token-name)` → token-level fix (preferred).
+   - hardcoded hex / `rgb()` / `hsl()` → component-level fix.
+   - inline `style={…}` / `style="…"` → component-level fix on that one instance.
+   - Tailwind / utility class (e.g. `bg-blue-500 text-white`) → swap utility classes or extend the project's theme config; do not add ad-hoc inline overrides.
+3. **For the token path** — the common case in design-system playgrounds:
+   - Find the variable's definition (typically a `:root` / `:root[data-theme="*"]` block in `tokens.css`, `globals.css`, `theme.css`, or equivalent). Use `grep` for `--token-name:` if you have to.
+   - Edit the variable **at its definition**, inside the theme block that matches the current `color_scheme` on the task (`dark` vs `light`). Do not redefine the variable on the component selector — that bypasses the design system and breaks every other consumer.
+   - If both themes look like they fail, fix the variable in each theme block separately, computing per-theme.
+4. **Pick which token to move.** When both `color` and `background` are tokens, default to:
+   - **Brand background + white/near-white text (`--accent` + `--text-on-accent`):** keep the white text token, darken the brand token. Brand tokens earn their lightness; light text on brand is almost always the intended pattern, and darkening the brand by ~10–20% luminance is usually the smallest visible change.
+   - **Muted text on neutral surface (`--text-muted`, `--text-subtle` on `--surface*`):** lighten the text token, do not darken the surface. Surface tokens drive layout perception and many components consume them.
+   - **Disabled/placeholder text:** if the project intentionally uses a low-contrast token, keep the rule failure scoped to that pattern and fix only the offending public-facing instance, not the token.
+5. **Choose the new value by luminance, not by eye.** For text vs. opaque background, target ≥4.5:1 (normal text) or ≥3:1 (large/bold ≥18pt or 14pt+700). Move the token in **one direction only** (darken bg *or* lighten fg) — do not split the fix across both ends. After editing, the diff should be one line in the tokens file.
+6. **Sanity-check sibling tokens.** If you darken `--accent`, glance at `--accent-strong` (the hover/pressed variant) and `--accent-soft` (low-opacity surfaces). If `--accent-strong` is already darker than your new `--accent` value, leave it. If it's now lighter, slide it darker by the same delta so the brand ramp stays monotonic.
+7. **Do not touch the component CSS.** A clean token fix has no edits in the component file. If you find yourself opening the component to override the variable, stop — you are about to re-introduce the instance-level pattern the playbook is trying to prevent.
+
+The agent should also confirm the re-render passes after applying: the user's a11y panel re-scans automatically once the file saves, and the violation should drop off. If it doesn't, the wrong token was moved or the change landed in the wrong theme block.
+
+## General rules
+
+- Prefer pattern fixes over instance fixes. If many entries point at the same file or component, fix the source component once.
+- For synthetic `tab-order`, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no axe `helpUrl`; use the WCAG page in `context.helpUrl`.
+- When `a11y.accessible_name` is empty and `a11y.focusable` is true, naming is usually the highest-priority fix.
+- Layout and document-head rules usually belong in root or layout files, not the selected leaf component.
diff --git a/.agents/skills/annotask-apply/ERROR_FIX.md b/.agents/skills/annotask-apply/ERROR_FIX.md
new file mode 100644
index 0000000..d6b598c
--- /dev/null
+++ b/.agents/skills/annotask-apply/ERROR_FIX.md
@@ -0,0 +1,40 @@
+# Error fix tasks
+
+`error_fix` tasks come from the Errors tab in the Annotask shell. Each task
+captures one or more console errors with their stack traces, the route where
+they happened, and the number of occurrences.
+
+## Read order
+
+1. **`task.context.level`** — `'error'` or `'warn'`. Errors block; warnings
+   often don't. Don't suppress warnings into errors and don't downgrade
+   errors into warnings just to make the panel quieter.
+2. **`task.context.errorId`** — stable hash. Use it to confirm you're
+   fixing what the user saw, not a sibling error from the same file.
+3. **`task.context.occurrences`** — when this is high (>50), the error is
+   firing on every render or interaction. Prioritize root-cause fixes over
+   try/catch wrappers.
+4. **Stack trace** — read the top frame to locate the throw, but read the
+   second and third frames to understand who called it. The fix usually
+   lives at the caller, not the throw site.
+
+## Fix patterns
+
+- **Undefined property access** (`Cannot read properties of undefined`) —
+  fix the producer, not the consumer. Adding `?.` everywhere hides the
+  real defect.
+- **Hydration mismatch** (React/Vue/Svelte SSR) — the server and client
+  rendered different output. Find the divergent branch (often
+  `typeof window !== 'undefined'`) and align them.
+- **Network errors** — surface to the user; don't swallow with a generic
+  toast unless the user explicitly asked for one.
+
+## Don't
+
+- Don't add `try/catch` around the call site just to silence the error.
+- Don't add `console.error` suppressions or noise filters.
+- Don't change the error to a warning to clear the panel.
+
+When you finish, set `status: 'review'` with a one-line resolution that
+states (a) the root cause and (b) the file you touched. The user will
+verify in the Errors tab that the count stays at zero.
diff --git a/.agents/skills/annotask-apply/PERF_FIX.md b/.agents/skills/annotask-apply/PERF_FIX.md
new file mode 100644
index 0000000..fd2259f
--- /dev/null
+++ b/.agents/skills/annotask-apply/PERF_FIX.md
@@ -0,0 +1,57 @@
+# Performance fix tasks
+
+`perf_fix` tasks come from the Perf tab. Each task points at one finding:
+a Web Vital that regressed, a heavy resource group, a heavy bundle
+package, or long main-thread tasks captured during a recording.
+
+## Read order
+
+1. **`task.context.category`** — what kind of finding this is:
+   `'vital' | 'resource' | 'long-task' | 'bundle'`. The fix surface
+   varies dramatically by category; don't apply a vitals recipe to a
+   bundle task.
+2. **`task.context.metric`** — present **only on `vital` findings**: the
+   uppercase Web Vital name (`'LCP'`, `'CLS'`, `'INP'`, `'TTFB'`,
+   `'FCP'`). Non-vital findings have no `metric`; key off `category`
+   and `findingId` instead.
+3. **`task.context.findingId`** — stable id that also encodes the
+   offender: `vital:LCP`, `resource:heavy-script`,
+   `bundle:lodash`, `blocking:long-tasks`.
+4. **`task.context.value`** + **`unit`** — the observed value (`'ms'`
+   for vitals and long tasks, `'bytes'` for resource/bundle findings,
+   empty unit for CLS which is unitless). Use this to verify your fix
+   in the Perf tab post-edit.
+5. **`task.context.severity`** — the Web Vitals rating scale:
+   `'good' | 'needs-improvement' | 'poor'`. `poor` CLS (>0.25) usually
+   means a single layout shift you can squash; `needs-improvement` may
+   be unfixable without redesign.
+6. **`task.context.detail`** / **`resources`** — human-readable summary,
+   and (on `resource` findings) the offending URLs with sizes and
+   durations. `context.metrics` carries the full snapshot when one was
+   captured.
+
+## Fix patterns
+
+- **LCP** — defer or preload the largest contentful element. Drop hero
+  images to the right format/size; preconnect to the right origins.
+- **CLS** — explicit dimensions on images, reserved space for async
+  content (banners, ads, late-loaded fonts).
+- **INP** — break long tasks, debounce input handlers, move work off the
+  main thread. `blocking:long-tasks` findings give you Total Blocking
+  Time and pair naturally with INP work.
+- **Resource / bundle size** — confirm the offender lives in user code,
+  not a vendor chunk. Tree-shake or lazy-load instead of swapping
+  libraries; the `bundle:<package>` finding's detail may already
+  suggest a lighter alternative.
+
+## Don't
+
+- Don't suppress the metric by changing what gets counted (e.g. excluding
+  a route from RUM).
+- Don't ship a "fix" that improves the metric in dev but regresses in
+  prod (e.g. removing `import.meta.hot` blocks).
+- Don't refactor unrelated code in a perf task.
+
+Set `status: 'review'` with a resolution that names the finding and the
+post-fix expected value (`'CLS dropped from 0.31 to ~0.05 — reserved space
+for hero image'`). The user re-runs the Perf scan to confirm.
diff --git a/.agents/skills/annotask-apply/SKILL.md b/.agents/skills/annotask-apply/SKILL.md
index 820d735..49bca89 100644
--- a/.agents/skills/annotask-apply/SKILL.md
+++ b/.agents/skills/annotask-apply/SKILL.md
@@ -1,7 +1,14 @@
+---
+name: annotask-apply
+description: Apply pending Annotask design tasks to the source code. Use when the user asks to apply Annotask changes, apply design changes, sync Annotask, or runs /annotask-apply.
+---
+
 # annotask-apply
 
 Apply pending Annotask design tasks to the source code.
 
+> **For editor agents (Claude Code, Cursor, Windsurf).** Annotask's built-in agent runs apply directly through the shell — the user runs a task from the Conversation tab and the local-CLI provider edits files in place. This skill exists when the user prefers to drive apply from their own editor agent instead.
+
 ## When to use
 
 Use this skill when the user says:
@@ -12,7 +19,7 @@ Use this skill when the user says:
 
 ## How it works
 
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
+Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, and text highlights (sections are wireframe sketch material — they arrive as `wireframe_apply` add directions, not Annotate tasks). These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
 
 ## MCP preference
 
@@ -96,166 +103,93 @@ npx annotask update-task TASK_ID --status=in_progress --mcp
 
 #### b. Reference the design spec for consistency
 
-Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
+Use the design spec when the task changes visual design, layout tokens, typography, spacing, or introduces new UI that should match the existing system.
 
-**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
+**MCP:** `annotask_get_design_spec()`
 
 ```bash
 npx annotask design-spec --mcp
 ```
 
-Response example:
-```json
-{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
-```
-
-For detailed tokens in a specific category:
+For one category only:
 
 ```bash
 npx annotask design-spec --category=colors --mcp
 ```
 
-**When to use:**
-- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
-- **Typography changes** — Reference the font scale and families from the spec
-- **Responsive design** — Use detected breakpoints when adding media queries
-- **New components** — Match the design system when creating new UI
-
-**How to apply:**
-- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
-- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
-- For responsive design, use the detected breakpoints
-- Document the token reference in your resolution note (e.g., "Applied primary color token")
-
-#### c. Find relevant components (required when adding any UI element)
-
-If the task asks you to add, insert, or create a UI element of any kind — a table, button, card, modal, input, dropdown, form, list, nav, etc. — you **must** search the component library first before writing HTML from scratch. This applies to all task types: `section_request`, `annotation` with actions like `add_column`/`add_row`/`wrap_container`, and free-text `annotation` notes whose `description` implies new UI.
-
-**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
-
-```bash
-npx annotask components "button" --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
-```
-
-For a specific component, get its full prop signature:
+Apply it narrowly:
+- Prefer existing tokens over hardcoded values
+- Use the project's spacing and breakpoint scale
+- Reuse the detected styling conventions instead of introducing a new pattern
 
-```bash
-npx annotask component Button --mcp
-```
+#### c. Gather only the extra context this task needs
 
-For **in-repo usage examples** (real prop combinations + import path this project actually uses), call `annotask_get_component_examples(name: "Button")` — or `npx annotask component-examples Button --mcp`. Prefer the example's import path and prop shape over reinventing: the examples show how *this* codebase uses the component, not just what the library exposes.
+Start with the task summary. Pull more context only when it changes the implementation.
 
-#### c-ter. Find the data source (required for any task that adds or modifies data-driven UI)
+**Re-anchor stale tasks**
 
-Before writing UI that renders data, check what's already wired. If the task's summary contains `data_context_summary` (e.g. `"hook:useUserQuery"` or `"store:useCounterStore"`), that's the primary data source powering the selected element. For the full picture:
-
-**MCP:** `annotask_get_data_context(task_id: "TASK_ID")` — returns the complete `DataContext`: every data reference in the enclosing file (`sources`, sorted with the primary source at index 0 — closest to `task.line`, tie-broken by kind precedence), `rendered_identifiers` from the template/JSX (CSV), and `route_bindings` (CSV).
+For **denied** tasks, old `in_progress` tasks, or any task whose `file`/`line` may have drifted, call `annotask_get_code_context(task_id)` before editing.
 
 ```bash
-npx annotask data-context TASK_ID --mcp
-```
-
-To browse the project's catalog of hooks, stores, and fetch wrappers (sorted by `used_count` — most load-bearing first):
-
-**MCP:** `annotask_get_data_sources(used_only: true)` — filter to entries actually used elsewhere in the codebase.
-
-```bash
-npx annotask data-sources --used-only --mcp
+npx annotask code-context TASK_ID --mcp
 ```
 
-To see **real in-repo usages** of a specific data source (destructuring patterns, parameter shape, common wrappers — parallel to `annotask_get_component_examples`):
+Use `symbol` + `excerpt` to locate the edit target. Treat `excerpt_hash` as a cheap drift check across retries.
 
-**MCP:** `annotask_get_data_source_examples(name: "useUserQuery", kind: "composable")`
+**If the task adds UI, find components first**
 
-```bash
-npx annotask data-source-examples useUserQuery --kind=composable --mcp
-```
+If the task asks you to add, insert, or create UI of any kind — table, button, card, modal, input, dropdown, form, list, nav, layout wrapper — search the component library before writing custom HTML. This applies to `section_request`, structural `annotation` actions like `add_row` or `wrap_container`, and free-text notes that clearly imply new UI.
 
-To see **what shape comes back** from an API — cross-reference declared schemas (OpenAPI, GraphQL, tRPC) so you don't guess field names:
-
-**MCP:** `annotask_resolve_endpoint(url: "/api/cats")` → returns the best-match operation with a confidence score.
+**MCP:** `annotask_get_components(search: "button")`
 
 ```bash
-npx annotask resolve-endpoint /api/cats --mcp
-```
-
-**MCP:** `annotask_get_api_operation(path: "/api/cats", method: "GET")` — full request / response schema for a known path pattern.
-
-```bash
-npx annotask api-operation /api/cats --method=GET --mcp
+npx annotask components "button" --mcp
 ```
 
-**MCP:** `annotask_get_api_schemas(detail: true)` — browse every discovered schema source up front.
+If a candidate looks right, inspect the exact API and project usage:
 
 ```bash
-npx annotask api-schemas --detail --mcp
+npx annotask component Button --mcp
+npx annotask component-examples Button --mcp
 ```
 
-If a task summary shows `response_schema_ref: "Cat[]"`, the agent already knows a declared shape exists — `annotask_get_api_operation` or `annotask_resolve_endpoint` will surface the full JSON schema.
-
-**When to use:**
-- Any task where the user's description mentions adding, replacing, or rewiring data — "show the current user", "list orders", "filter by status", "fetch from the API".
-- Denied tasks where feedback mentions wrong or fake data.
-- Section requests that need to render real information.
-
-**How to apply:**
-- Prefer reusing a hook/store from `data_context.sources` or `data-sources` catalog over writing new fetch code.
-- Copy the import path and call-site shape from `data-source-examples`, not from library docs.
-- If `sources[0]` doesn't match the user's description (e.g. task says "user name" but `sources[0]` is `useOrdersQuery`), check the rest of the `sources` list — the right hook is usually there.
+Prefer the import path and prop shape from `annotask_get_component_examples` over inventing a fresh usage.
 
-**When to use:**
-- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
-- **UI additions** — Check if a table, button, card, modal, input, form, list, or nav component already exists before writing custom HTML
-- **Styling consistency** — Using library components ensures your changes match the design system
+**If the task binds or changes data, inspect the existing data path**
 
-**How to apply:**
-- Search for components matching the intent (e.g., "table" if adding tabular data, "dropdown" if adding a select menu)
-- Read the props to understand customization options (variant, size, disabled, etc.)
-- Call `annotask_get_component_examples` to see how the component is already used in this codebase; copy the import path and prop patterns from there
-- Use the component in your JSX/Vue/Svelte code with appropriate props
-- Document the component reference in your resolution note
+Do this only for data-driven work: showing real data, rewiring an existing hook/store, changing filters or queries, or fixing a denied task that used fake or wrong data.
 
-#### c-bis. Re-anchor older or retried tasks
-
-For **denied** tasks, tasks that have been sitting in the queue while you edited other files, or any task whose `file`/`line` you suspect has drifted: call `annotask_get_code_context(task_id)` before editing.
+Start with what the task already tells you:
+- If the summary has `data_context_summary`, use that as the first candidate source
+- If that is not enough, call `annotask_get_data_context(task_id)` to inspect nearby sources in the current file
 
 ```bash
-npx annotask code-context TASK_ID --mcp
-```
-
-Response:
-```json
-{"file":"src/components/Header.vue","line":42,"symbol":"Header","excerpt_start_line":27,"excerpt_end_line":57,"excerpt":"...","imports":["import ..."],"excerpt_hash":"ab12cd34ef56..."}
+npx annotask data-context TASK_ID --mcp
 ```
 
-Use `symbol` + `excerpt` to locate the edit target; the `excerpt_hash` is a cheap drift check on subsequent retries (if the hash changes between attempts, the surrounding code moved). Skip this step for fresh pending tasks where `file`/`line` are known good.
+Only expand further when needed:
+- `annotask_get_data_sources(used_only: true)` / `npx annotask data-sources --used-only --mcp` when you need to find a reused project-level source
+- `annotask_get_data_source_examples(name)` / `npx annotask data-source-examples NAME --kind=composable --mcp` when you need the real import path or call-site shape
+- `annotask_resolve_endpoint(url)` or `annotask_get_api_operation(path, method)` when you need response field names or schema details
+- `annotask_get_api_schemas(detail: true)` only as a last resort when you still do not know which schema owns the endpoint
 
-#### c-quater. Retrieve interaction history or rendered HTML on demand
+Prefer reusing an existing hook/store/fetch wrapper over writing new data plumbing.
 
-Annotask always captures two richer context streams per task — but keeps them out of the default task payload so lists stay lean:
-- **Interaction history** — the user's recent navigation + click trace (up to ~20 events around task creation)
-- **Rendered HTML** — the post-render `outerHTML` of the selected element (bindings resolved, capped at 200 KB)
+**If the task references a flow or rendered structure, pull it on demand**
 
-The "Embed …" toggles in the Annotask UI only decide whether each rides in the task payload. When the payload doesn't contain them, pull on demand:
-
-**MCP:** `annotask_get_interaction_history(task_id: "TASK_ID")` — useful when the task description references a flow or sequence ("after I click submit…", "on the orders page…").
+Use interaction history when the task depends on the user's path through the app:
 
 ```bash
 npx annotask interaction-history TASK_ID --mcp
 ```
 
-**MCP:** `annotask_get_rendered_html(task_id: "TASK_ID")` — useful when the task references visual structure that's hard to reconstruct from source alone ("the three spans in the header", "this button's icon wrapper").
+Use rendered HTML when the task refers to post-render structure that is easier to inspect from the DOM than from source:
 
 ```bash
 npx annotask rendered-html TASK_ID --mcp
 ```
 
-Both tools prefer the embedded copy on the task when present (`source: "embedded"`), fall back to the per-task sidecar under `.annotask/` (`source: "sidecar"`), and return `not_captured: true` when neither exists (rare — only when no selection was attached at task creation).
+Both tools prefer embedded task payloads when present and otherwise fall back to the per-task sidecar under `.annotask/`.
 
 #### d. Apply the change
 
@@ -263,121 +197,26 @@ Read the task type and apply accordingly:
 
 - **`annotation` with `action: "text_edit"`**: The `description` field says what text to change. Find the text in the source file and apply the edit.
 
-- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run step c first.
+- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run the component lookup in step c first.
 
-- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run step c (component library search) before writing HTML.**
+- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run the component lookup in step c before writing HTML.**
 
 - **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
 
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
-
-- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID, or the synthetic `tab-order` rule from Annotask's tab-order overlay), `impact`, `help`, `helpUrl`, and `elements` array with `html`, `selector`, `fix`, source `file`/`line`/`component`, and a per-element `a11y` block with computed accessibility metadata:
-
-  ```
-  elements[i].a11y = {
-    accessible_name, name_source,   // "Sign in", source: aria-label | labelledby | label | alt | text | placeholder | none
-    role, role_source,              // "button", source: explicit | implicit | none
-    tabindex, focusable,            // null | number, true/false
-    focus_indicator,                // "visible" | "none" | "unknown"
-    contrast,                       // { foreground, background, ratio, aa_normal, aa_large, ... } only when element has text
-    aria_attrs,                     // [{ name: "aria-expanded", value: "false" }, ...]
-  }
-  ```
-
-  If `screenshot_meta` is present (the user manually attached one with the snip tool), retrieve it via `annotask_get_screenshot` before proposing visual changes (color-contrast, focus rings).
-
-  **Per-rule playbook.** Most rules fall into one of these patterns — match by `context.rule`:
-
-  | Rule(s) | Fix layer | What to do |
-  |---|---|---|
-  | `color-contrast`, `color-contrast-enhanced` | Design tokens first | Read `elements[i].a11y.contrast` for the actual fg/bg hex + ratio. If the colors come from theme tokens (check `cssVar` lookups in the source), adjust the token. If the contrast comes from a one-off inline style or hardcoded class, fix the component, not the token (you'd regress every other consumer). |
-  | `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` referencing visible text. `a11y.accessible_name` shows what (if anything) the input currently exposes — when `name_source === 'placeholder'`, the input has no real label. |
-  | `button-name`, `link-name`, `input-button-name` | Markup | Add visible text content or `aria-label`. For icon-only buttons add a visually hidden `<span class="sr-only">` (or your project's equivalent). Don't add `title` — it's not reliable for SR users. |
-  | `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | `alt=""` for decorative imagery, descriptive `alt` for informational. For `<img>` that conveys text, use the text. For SVG icons that pair with visible text, use `aria-hidden="true"`. |
-  | `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These almost always live in a layout component (e.g. `App.vue`, `_layout.tsx`, `RootLayout`), not in leaf components. |
-  | `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert/promote `<h1>`; renumber subsequent levels so the outline is contiguous. Usually a layout/section component change, not a leaf change. |
-  | `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what's set. Reference the WAI-ARIA roles spec (`helpUrl`) for the role's allowed attributes. Remove disallowed attrs; add required ones. |
-  | `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Either remove `aria-hidden`, or move the focusable elements outside (or set `tabindex="-1"` and ensure they're never the focus target). |
-  | `tabindex`, **synthetic** `tab-order` | Markup | Remove positive `tabindex`; use 0 (focusable in DOM order) or -1 (programmatically focusable, not in tab order). For the synthetic `tab-order` rule, `context.tab_order.flag` is one of `positive` / `unreachable` / `reorder` — fix the source markup so DOM order matches visual order. |
-  | `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Single source of truth — usually `index.html` (Vite/CRA), `app/layout.tsx` (Next), `src/routes/+layout.svelte` (SvelteKit), or the framework's root document. |
-  | `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>`/`<span>`. Don't nest interactive elements (e.g. `<button>` inside `<a>`). |
-  | `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element of the layout. Style it with the visually-hidden pattern that becomes visible on `:focus`. |
-  | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="…"` and rename one. If the id is dynamic, ensure the generation key is unique per instance. |
-  | `frame-title`, `iframe-title` | Markup | Add `title="…"` describing the iframe's purpose. |
-
-  **General rules:**
-  - Prefer **pattern fixes** over instance fixes. When `elements` contains many entries that share the same `file`/`component`, change the source component once — don't paste the same fix N times.
-  - For the synthetic `tab-order` rule, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no `helpUrl` from axe — use the linked WCAG focus-order page in `context.helpUrl`.
-  - When `a11y.accessible_name` is empty and `a11y.focusable` is true, the element is unreachable for screen readers — naming is the highest-priority fix.
-
-- **`theme_update`**: One or more design token value changes committed together from the Theme page. A single task now covers every edit the user made in one Commit click — do not expect one task per token. The `context` object contains:
-  - `edits`: array of token edits. Each entry has:
-    - `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
-    - `role`: semantic role name (e.g. `primary`, `background`, `heading`)
-    - `cssVar`: CSS variable name if backed by one (e.g. `--color-primary`), or `null`
-    - `theme_variant`: the theme id this edit targets (e.g. `light`, `dark`)
-    - `theme_selector`: how that variant is activated in the DOM — `{kind:'default'}`, `{kind:'attribute',host,name,value}`, `{kind:'class',host,name}`, or `{kind:'media',media}` — tells you which CSS block owns this variable (`:root`, `:root[data-theme="dark"]`, `.dark`, `@media (prefers-color-scheme: dark)`)
-    - `before`: old value (`null` for new tokens)
-    - `after`: new value
-    - `sourceFile` / `sourceLine`: where the current declaration lives (both `null` for new tokens — you pick the location)
-    - `isNew`: `true` if this token didn't exist before
-  - `styling`: array of project styling methods (e.g. `["tailwind", "scoped-css"]`)
-  - `specFile`: relative path to the design spec (typically `.annotask/design-spec.json`)
-
-  **How to apply:**
-  1. **Group `context.edits` by `sourceFile`.** For each file (skipping `null`/`isNew` for now), open it once, apply every edit against its file in a single Edit-batch, save. Use `theme_selector` + `cssVar` to locate the right declaration block — e.g. an edit with `theme_selector: {kind:'attribute',host:'html',name:'data-theme',value:'dark'}` belongs inside `:root[data-theme="dark"] { … }`, a `{kind:'default'}` edit belongs in the base `:root { … }` block.
-  2. **Tailwind config edits:** if `cssVar` is `null` and `sourceFile` references `tailwind.config.*`, update the corresponding key. If edits span both Tailwind and raw CSS, handle each file independently.
-  3. **New tokens (`isNew: true`):** add the CSS variable to the declaration block matching `theme_selector`. If no block exists for that variant yet, create one (e.g. add `:root[data-theme="dark"] { --new-var: …; }` at the end of the main tokens file). After writing, remember the final file path and line for step 4.
-  4. **Patch `.annotask/design-spec.json` once at the end.** Resolve `context.specFile` against the MFE root (the directory containing `.annotask/`). For each edit:
-     - Existing token: find `spec.<category>` — note dotted categories like `typography.families` map to nested paths — locate the entry by `role`, then set `values[theme_variant] = after`.
-     - New token: append a token object with `role`, `values: { [theme_variant]: after }`, `cssVar`, and fresh `sourceFile` / `sourceLine` pointing at where you added the declaration in step 3.
-     - When writing, keep the existing JSON formatting (same indentation, trailing newline) so the file watcher's next broadcast is clean.
-  5. The server watches `design-spec.json`; saving it fires a `designspec:updated` push and the Theme page refetches automatically.
-
-  **Worked example:** `context.edits = [{ category:'colors', role:'background', cssVar:'--stress-bg', theme_variant:'light', theme_selector:{kind:'default'}, before:'#f4f7fb', after:'#ff00ff', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:12, isNew:false }, { category:'colors', role:'text', cssVar:'--stress-text', theme_variant:'dark', theme_selector:{kind:'attribute',host:'html',name:'data-theme',value:'dark'}, before:'#e7eefb', after:'#ffeb3b', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:65, isNew:false }]` → open `tokens.css` once, update `--stress-bg` in the `:root` block and `--stress-text` in the `:root[data-theme="dark"]` block, save. Then open `.annotask/design-spec.json`, set `colors[?role=='background'].values.light = '#ff00ff'` and `colors[?role=='text'].values.dark = '#ffeb3b'`, save. Mark the task `review` with resolution `"Updated 2 color tokens in tokens.css and design-spec.json"`.
-
-- **`api_update`**: In-repo backend-contract edit. Created from the shell's Data view when the user selects an internal data source (`schema_in_repo === true`) and fills in a desired change. Only valid for in-repo schemas — external APIs cannot be edited from Annotask and should be marked `blocked` with an explanation if a request implies one.
-
-  The `context` object carries:
-  - `data_source_name`: hook/store/query identifier (e.g. `useCatsQuery`)
-  - `data_source_kind`: one of `composable | signal | store | fetch | graphql | loader | rpc`
-  - `schema_location`: path to the schema file (e.g. `openapi.yaml`, `src/trpc/router.ts`)
-  - `schema_kind`: `openapi | graphql | trpc | jsonschema`
-  - `endpoint`: literal endpoint / query key when the source used one
-  - `operation`: `{ method, path }` from the matched schema operation, when a match exists
-  - `desired_change`: user's description of the needed contract change
-  - `rationale`: optional "why"
-
-  **How to apply:**
-  - Open the schema file at `context.schema_location`. Read the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`) and make the change described in `desired_change`.
-  - Update the handler / backend implementation that serves that operation (typical pairs: OpenAPI routes ↔ the framework-specific handler file, tRPC router ↔ its procedure body).
-  - Update the frontend data source at `file:line` if the shape change affects the consumer (e.g. return type, destructured fields).
-  - If the change is additive (new optional field), you usually don't need to change existing callers. If it's breaking (required field, renamed field), search for all usages with `annotask_get_data_source_examples` and update them.
-  - Record what you changed in the resolution note — mention which schema location, which operation, and any frontend call sites touched.
-
-- **`annotation` with cross-boundary API edits**: An annotation task may turn out to require an in-repo API change (e.g. "show expiration date on the tier badge" when the `Cat` schema does not currently return `expires_at`).
-
-  **Rule**: do **not** silently edit the backend. Ask the user first via a `needs_info` question:
-  > This change requires updating the internal API route `GET /api/cats` to add an `expires_at` field on the `Cat` response. Proceed with both frontend and backend edits? (yes / no)
-
-  If the user approves, continue the same task (do **not** spawn a separate `api_update` task). Record each API edit structurally in `task.context.api_edits[]`:
-  ```json
-  {
-    "api_edits": [
-      {
-        "schema_location": "openapi.yaml",
-        "schema_kind": "openapi",
-        "operation": { "method": "GET", "path": "/api/cats" },
-        "change_summary": "Added nullable expires_at: string (ISO date) to the Cat response schema and handler."
-      }
-    ]
-  }
-  ```
-  Annotask's summary lifting will surface `api_edits_count` on the triage view so the user sees this task crossed the frontend/backend line.
-
-  If the user denies, do the frontend-only thing you can, or mark the task `blocked` with an explanation pointing at the missing backend support.
-
-  If the data source is external (`schema_in_repo === false`) and the task requires a contract change, mark the task `blocked` immediately — Annotask cannot edit APIs outside the repo.
+  The same `context.changes` array may also carry these three **legacy** types — the current UI no longer emits them, but apply them per these rules when they appear in older tasks:
+  - `{"type": "component_prop_update", "element", "prop", "before", "after", "binding", "prop_type"?, "file", "line"}` — one prop value change at a component **usage site** (`file:line` is where `<Element …>` is written). Respect `binding`: `"literal"` means rewrite the plain attribute value (`label="Reset"` → `label="Clear"`); `"expression-literal"` means the literal is written through binding syntax — **keep the syntax** (`:count="3"` → `:count="4"`, `count={3}` → `count={4}`); `"new"` means the prop isn't present at the usage site — add it using the framework's idiomatic form for `prop_type`. Bound expressions never appear here (the UI refuses them) — if `before` doesn't match what you find in source, re-anchor via `annotask_get_code_context` instead of guessing, and never rewrite an expression that references variables.
+  - `{"type": "text_update", "element", "before", "after", "file", "line"}` — a literal text-content change. The element at `file:line` has a single literal text run equal to `before`; replace it with `after`. If the text there is an interpolation/expression or doesn't match `before`, the source drifted — re-anchor or ask, never overwrite a binding.
+  - `{"type": "component_move", "element": {"tag", "component"?, "from_file", "from_line"}, "move_to": {"target_file", "target_line", "position"}}` — relocate the element's source block from `from_file:from_line` to the given position (`before`/`after`/`append`/`prepend`) relative to `target_file:target_line`. Move the markup intact (including its bindings and children); adjust imports only if the move crosses files.
+
+- **`section_request`** (**legacy** — the current UI no longer emits these; sections now arrive as `wireframe_apply` `add` directions with an `md` body. Apply this rule when older task files carry one): Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and the relevant step-c lookups before writing custom HTML.
+
+- **`a11y_fix`**: Fix an accessibility violation. Read `A11Y_RULES.md` in this skill directory before applying the change. If you are working through multiple a11y tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: prefer pattern fixes over instance fixes, expect layout/head rules to live in root or layout files, and fetch the screenshot first when the issue is visual (contrast, focus ring, hidden text, similar).
+
+- **`theme_update`**: Apply batched design-token edits from the Theme page. Read `THEME_UPDATE.md` in this skill directory before applying the change. If you are working through multiple theme tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: one task may include many edits, update source files before `.annotask/design-spec.json`, and land `theme_update` before dependent `style_update` tasks.
+
+- **`wireframe_apply`**: Implement the user's wireframe — snapshot-sketch directions (`context.session` entries with `change.type: 'wireframe_direction'`) and/or palette placements (`context.wireframe.instances[]`) — in real source. Read `WIREFRAME_APPLY.md` in this skill directory before applying the change. If you are working through multiple wireframe tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: pixel geometry is a hint and the direction's `relations` are the contract (implement intent with idiomatic layout, never absolute positioning); placements/directions carry durable `anchor`s (`file`/`line`) — resolve component imports via `annotask_get_component_examples` rather than guessing; and never fabricate handlers/children/data — placeholders stay visibly placeholders.
+
+- **`annotation` with cross-boundary API edits**: Some frontend requests turn out to depend on backend work (for example, a field is not returned by the current response schema). Do **not** edit the backend and do **not** ask for permission to do so. If there is a meaningful frontend-only fallback, apply it and explain the missing backend support in the resolution note. Otherwise, mark the task `blocked` and tell the user which API/schema change would be required.
 
 #### e. Ask for clarification (only when stuck)
 
diff --git a/.agents/skills/annotask-apply/THEME_UPDATE.md b/.agents/skills/annotask-apply/THEME_UPDATE.md
new file mode 100644
index 0000000..b56494b
--- /dev/null
+++ b/.agents/skills/annotask-apply/THEME_UPDATE.md
@@ -0,0 +1,46 @@
+# Theme Update
+
+Read this file for `theme_update` tasks. If you are applying a batch of theme tasks, read it once for the batch, not once per task.
+
+## Task context
+
+`theme_update` batches every token edit from one Theme-page commit into a single task.
+
+The `context` object contains:
+
+- `edits[]`: token edits
+- `styling[]`: project styling methods such as `tailwind` or `scoped-css`
+- `specFile`: relative path to `.annotask/design-spec.json`
+
+Each edit contains:
+
+- `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
+- `role`: semantic token role such as `primary` or `background`
+- `cssVar`: CSS variable name when present, otherwise `null`
+- `theme_variant`: variant id such as `light` or `dark`
+- `theme_selector`: selector metadata describing which declaration block owns the value
+- `before`, `after`
+- `sourceFile`, `sourceLine`
+- `isNew`
+
+## Apply flow
+
+1. Group `context.edits` by `sourceFile`.
+2. For each existing source file, open it once and apply every edit in one pass.
+3. Use `theme_selector` + `cssVar` to locate the correct block:
+   - `{kind:'default'}` -> base `:root`
+   - `{kind:'attribute', ...}` -> matching attribute-scoped block such as `:root[data-theme="dark"]`
+   - `{kind:'class', ...}` -> matching class-scoped block such as `.dark`
+   - `{kind:'media', ...}` -> matching media-query block
+4. If `cssVar` is `null` and the file is `tailwind.config.*`, update the matching config key instead of searching CSS.
+5. For `isNew: true`, add the token to the correct variant block. Create the block if it does not exist yet.
+6. Patch `.annotask/design-spec.json` once at the end:
+   - existing token -> update `values[theme_variant]`
+   - new token -> append a token entry with `role`, `values`, `cssVar`, `sourceFile`, and `sourceLine`
+7. Keep the existing JSON formatting so the file watcher emits a clean update.
+
+## Defaults
+
+- One `theme_update` task may touch multiple files.
+- Edit source files before patching `.annotask/design-spec.json`.
+- `theme_update` should land before any dependent `style_update` in the same apply run.
diff --git a/.agents/skills/annotask-apply/WIREFRAME_APPLY.md b/.agents/skills/annotask-apply/WIREFRAME_APPLY.md
new file mode 100644
index 0000000..dfbc207
--- /dev/null
+++ b/.agents/skills/annotask-apply/WIREFRAME_APPLY.md
@@ -0,0 +1,121 @@
+# Wireframe Apply
+
+Read this file for `wireframe_apply` tasks. If you are applying a batch, read it once for the batch, not once per instance.
+
+A `wireframe_apply` task arrives two ways:
+
+1. **"Implement this wireframe"** — the user froze a route into a snapshot sketch (per-block images of the real render), rearranged it freely, and asked you to implement the intent. The task carries **wireframe directions** in `context.session.entries[]` (`change.type === 'wireframe_direction'`) plus a labeled before/after composite screenshot.
+2. **"Build this route" / "Apply now"** — palette placements in `context.wireframe.instances[]` and/or design-session edits in `context.session.entries[]` (style/class/move/insert change types).
+
+A task may carry both halves. Handle directions with the rules below; handle placements and other session entries with the later sections.
+
+## Wireframe directions (`change.type: 'wireframe_direction'`)
+
+The user rearranged a SKETCH — images of the rendered page, not the live app. The server diffed the sketch against the original capture into one direction per changed block:
+
+- `op`: `move` | `resize` | `delete` | `add` | `note`.
+- `block`: `{ label, component?, tag? }` — the block's identity as captured. Tool-derived, never invented.
+- `file`/`line` (top level): the block's captured source anchor — or, for `add`, the nearest anchored NEIGHBOR block (see `added.position`).
+- `measured`: TOOL-MEASURED geometry. `before`/`after` rects, `dx`/`dy`, `wPct`/`hPct` (percent of original), and `relations[]` — order-flip / full-width / alignment facts computed from box geometry (e.g. `"now above the filters (was below)"`).
+- `added` (op `add` only): `kind` `component` (a real palette component — `componentName`/`library`/`module`/`props` are REAL scanner output) | `placeholder` (a user-drawn labeled box) | `duplicate` (another copy of a captured block's markup). `position` (`before`/`after`/`append`) is relative to the anchored neighbor. May carry `md` (the user's VERBATIM markdown spec for a drawn section) and/or `data` (a binding to a REAL catalog data source — see *Data bindings on adds* below).
+- `note`: the user's VERBATIM words for that block. `measured` is what the tool measured; `note` is what the user said — never conflate them, and never present a measured relation as a user request.
+
+### Intent over pixels
+
+**Pixel geometry is a hint; the relations are the contract.** `"now above the filters (was below)"` IS the instruction; `y 480→180` is evidence. Implement with idiomatic layout — reorder siblings, change flex/grid order, adjust column spans, use design tokens (`annotask_get_design_spec`) for sizes — never absolute positioning to hit coordinates. A resize of `+50% w` on a card grid usually means "fewer, larger columns", not `width: 1200px`.
+
+### Use the visuals
+
+The task screenshot (`annotask_get_screenshot`) is a labeled composite: **left = the captured render (truth at capture time); right = the user's sketch — rearranged images, not real UI.** Numbered badges on the right pane map 1:1 to the numbered directions in the task description. Look at it before writing code: spatial intent (what ended up next to what) is often clearer in the image than in prose.
+
+### Per-op rules
+
+- **move** — relocate the block's anchored markup to satisfy the relations. Apply per-file edits bottom-up (descending line); re-ground drifted anchors with `annotask_get_source_excerpt`. A loop-rendered block moves as the loop, not one iteration. An exploded container appears as both a container block and separate child blocks (each with finer anchors): directions on children mean restructuring INSIDE the container; a direction on the container means moving the whole thing, children included. (Explode-to-children is deferred this release — `WIREFRAME_EXPLODE_ENABLED=false` — so new tasks won't carry exploded child blocks; this guidance applies to legacy task files that already do.)
+- **resize** — prefer tokens/utility classes/grid-template changes over raw px. Say in the resolution what you chose and why.
+- **delete** — remove the anchored markup. Remove now-dead local bindings only when provably unused; never delete shared code.
+- **add / component** — resolve the real import via `annotask_get_component_examples` (proven specifier + export kind). No in-repo examples → fall back to `library`/`module` and say so. Apply `added.props` primitives only; never fabricate handlers, bindings, or children. When `added.data` is present, wire the REAL source per *Data bindings on adds* below — never sample data.
+- **add / placeholder** (bare — no `md`) — emit a *visibly labeled* placeholder element (e.g. `<div class="placeholder">pagination here</div>` styled per project conventions) or the minimal honest scaffold the label names. **Never fabricate data or content.**
+- **add / placeholder with `added.md` (a drawn SECTION)** — the markdown is the user's verbatim spec for the region: build what it describes per project conventions (component-library-first — run the SKILL.md step-c lookups before writing custom HTML; design tokens for styling). Use `added.data` for any data the section shows. Data-driven content with NO binding → visible placeholder slots or `needs_info` — **never fabricate data or fields.**
+- **add / duplicate** — duplicate the anchored block's markup. If it's loop-rendered, the user probably wants another ITEM or a second instance of the section — read the note/screenshot, ask via `needs_info` when ambiguous.
+- **note** — implement the user's verbatim ask. Ambiguous → `needs_info`, never guess silently.
+
+Before rewriting any expression or bound markup you encounter mid-edit, re-classify it against CURRENT source: `annotask_get_binding_classification` (CLI: `annotask binding-classify`). Never rewrite an expression that references variables.
+
+### Data bindings on adds (`added.data`)
+
+> **Gated off this release.** Wireframe data binding is DEFERRED (`WIREFRAME_DATA_BINDING_ENABLED=false` in `src/shell/wireframeFeatures.ts`), so new `wireframe_apply` tasks won't carry `added.data`. This section applies to legacy/older task files that already contain a binding — when one is present, wire it per the rules below.
+
+`added.data` means "wire THIS source" — it is REAL scanner-catalog identity, never invented:
+
+- `kind`/`name`/`module`/`endpoint`: the source as the project defines it (`module` is its defining file). `path` drills into the response shape (`planets[]` = the list; `data.user` = an object); `fields` are the keys the element should display.
+- `shape_source` is the honesty tag for where the drill-down shape came from:
+  - `api-schema` — a real API contract matched the source's endpoint; the path/fields were picked off the actual response schema. Trust the shape; `annotask_get_api_operation` returns the full operation when you need more.
+  - `source-details` — regex-inferred return-type hints only (no confidence score is carried — the tag is the only signal). Re-verify against the real definition before relying on field names.
+  - `none` — the user typed the path/fields blind. Ground them yourself before wiring.
+- **Re-grounding protocol (always):** call `annotask_get_data_source_details` for the definition and `annotask_get_data_source_examples` for the proven import + call pattern — wire the source the way the project already wires it (same import specifier, same destructuring, loops/`v-for` over the `path` collection, render the `fields`).
+- The binding contradicts current source (source renamed, field gone, shape changed)? → `needs_info` with what you found. **Never invent fields**; runtime endpoints carry no response shapes — don't pretend otherwise.
+
+### Verification & status
+
+Directions are spatial — the server does NOT verify them against source. When you set `review`, direction entries flip `written` on trust (bindings included — their wiring rides the trusted resolution); **your resolution is the only record of what actually landed**, so make it specific and honest per direction: which file(s), what structural change, for bindings the imported source + call site + rendered fields, any file you created (name new files explicitly — in git projects the server nets newly-created files into the undo batch, but your resolution is still the human-readable record). `blocked_reason` when a direction is impossible; `needs_info` for ambiguity; denied → read `feedback` and re-apply the same task.
+
+## Placements (`context.wireframe`)
+
+`context.wireframe` contains:
+
+- `route`: the iframe route the placements were made on (e.g. `/planets`).
+- `instances[]`: one entry per placement.
+
+Each instance contains:
+
+- `id`: stable placement id.
+- `kind`: `component` | `html` | `layout-preset`.
+- `anchor`: where it goes — `{ file, line, position, component, targetTag }`.
+  - `file`, `line`: the drop target's source location (`data-annotask-file` / `-line`). `line` is the target's **opening-tag** line.
+  - `position`: `before` | `after` | `append` | `prepend` — placement relative to the target element.
+  - `component`: the target's owning component (context).
+- `inserted`: what to add — `{ tag, componentName?, library?, props?, classes?, text_content? }`. `inserted.props` are the REAL props.
+- `previewProps` (optional): the display-only sample props the user actually saw rendered on the canvas (e.g. `{ label: "Button" }`). Use them as **hints** for sensible prop values and label text when `inserted.props` is empty or sparse — they show what the user previewed and approved. They are still samples: never lift fabricated event handlers, data bindings, or children from them.
+- `fidelity`: how faithfully it previewed — `live` (rendered in real context), `isolated-preview` (rendered detached, no provider tree), `placeholder` (could not render). Lower fidelity is a hint that the component needs context/props you may have to wire by hand; it is not a blocker.
+- `mounted`: whether the live preview produced output.
+- `status` / `taskId`: lifecycle bookkeeping (`building` + the owning task id while you work). Read-only for you — see the lifecycle section below.
+
+### Apply flow for placements
+
+1. Group `context.wireframe.instances` by `anchor.file`. Open each file once and apply all its placements in one pass, **bottom-up** (descending `anchor.line`): every insertion shifts the lines below it, so applying the highest line number first keeps the remaining anchors' line numbers valid without re-counting.
+2. Locate the anchor element at `anchor.line` in that file. Insert the new markup relative to it per `anchor.position` (`before`/`after` = sibling; `append`/`prepend` = first/last child of the target). Match the file's framework (read `annotask_get_design_spec` for `framework` once) and the surrounding indentation.
+3. Emit markup per `kind`:
+   - **html** → the raw element: `<tag class="…">text_content</tag>` using `inserted.classes` / `inserted.text_content`. Omit empty attributes.
+   - **layout-preset** → a styled wrapper (`<div class="…">` / `<section class="…">`) with `inserted.classes`. It has **no children** — leave it empty for the user to fill. Never fabricate children.
+   - **component** → resolve the real import first, then emit `<ComponentName …props />` (or framework equivalent) at the anchor and add the import if the file does not already import it.
+4. For a `component`, call `annotask_get_component_examples` with `inserted.componentName` (and `inserted.library`) to get the **proven** import specifier + export kind (named vs default) from real in-repo usage. Use that exact import path. If there are no in-repo examples, fall back to `inserted.library` / the scanner `module`, and say so in your resolution — do **not** invent an import path.
+5. Apply props from `inserted.props`, but only primitives that differ from the component's documented defaults. **Never fabricate** event handlers, data bindings, children, or named slots — if a component clearly needs them, note it in the resolution (or use `needs_info`).
+6. After all placements land, set status to `review` with a per-instance resolution (what you inserted, where, and any import you had to guess).
+
+## Other design-session edits (`context.session`)
+
+`context.session` may also carry non-direction entries — the user's design-session edits:
+
+- `session_id`: bookkeeping. The server owns `.annotask/design-session.json`, `.annotask/wireframe.json` (which also carries the canvas sketch), and `.annotask/file-snapshots.json` — **never edit, rewrite, or clean up those files yourself**. Apply through source code only; the server verifies your work and updates the session when you set `review`.
+- `entries[]`: each is `{ id, change, anchor, evidence?, instance_id? }`.
+  - `change` is one of the structured change types (`style_update`, `class_update`, `component_insert`, legacy `component_prop_update`/`text_update`/`component_move`, …) — apply each per the change-type rules in SKILL.md step d.
+  - `anchor` (`{ file, line, targetTag? }`) is where the edit was recorded. Your own earlier edits in the same run shift lines — apply **bottom-up per file** like placements, and re-ground via `annotask_get_source_excerpt` when an anchor doesn't match.
+  - `evidence.classification` (legacy `component_prop_update`/`text_update` entries only) is the round-trip-honesty proof from when the user made the edit: `literal` edits rewrite a plain literal in place; `expression-literal` edits keep the binding syntax (`:count="3"` → `:count="4"`); `bound` edits never appear (the UI refused them). If what you find at the anchor contradicts the evidence, the source drifted — re-anchor or ask via `needs_info`, never rewrite an expression.
+- Prefer idiomatic placement over literal transcription: if a `style_update` matches a design token (`token_role` present, or an obvious token in `annotask_get_design_spec`), apply the token/class rather than a raw value, and say so in the resolution.
+- After you set `review`, the server re-reads the source per entry and marks each `written` or `failed` (directions are trusted — see above) — a `failed` badge in the user's panel means your edit wasn't found where expected, so make resolutions specific about what landed where.
+
+## Lifecycle (do NOT edit .annotask files)
+
+- When the user **accepts** your task, the server removes its instances and the implemented canvas sketch from `wireframe.json` automatically.
+- When the user **deletes** the task, the server reverts instances to `placed` and unlocks the sketch (`building` → `sketch`) so the user can tweak and re-implement.
+- When the user **denies** the task, everything stays locked to your task — re-apply against the same task after reading `feedback`.
+
+## Edge cases
+
+- If an `anchor.file`/`line` no longer matches the described element (source drifted since the capture/placement), call `annotask_get_code_context` for the task to re-anchor; if you still can't place it, mark that instance/direction and use `needs_info`.
+- If a placement or direction requires data/state that doesn't exist yet (e.g. a list component with no data source on the route), use `blocked_reason` to explain what's missing rather than fabricating data.
+
+## Defaults
+
+- One `wireframe_apply` task may touch multiple files and multiple frameworks (MFEs) — handle each file independently.
+- The sketch is a wireframe, not a final design: prioritize correct structure, real imports, and the stated relations over pixel-perfect geometry.
diff --git a/.agents/skills/annotask-init/SKILL.md b/.agents/skills/annotask-init/SKILL.md
index 63df6c7..ac5d4e0 100644
--- a/.agents/skills/annotask-init/SKILL.md
+++ b/.agents/skills/annotask-init/SKILL.md
@@ -1,7 +1,14 @@
+---
+name: annotask-init
+description: Initialize Annotask for this project by scanning the codebase and generating .annotask/design-spec.json. Use when the user asks to initialize, set up, configure, or scan their project for Annotask, or runs /annotask-init.
+---
+
 # annotask-init
 
 Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
 
+> **For editor agents only.** Annotask's built-in agent runs init through the shell UI — open `http://localhost:5173/__annotask/` and the wizard walks the user through provider setup, project scan, and style guide. This skill exists for users who prefer their own editor agent (Claude Code, Cursor, Windsurf) to do the deeper token extraction the in-shell baseline doesn't cover.
+
 ## When to use
 
 Use this skill when the user says any of:
diff --git a/.claude/skills/annotask-apply/A11Y_RULES.md b/.claude/skills/annotask-apply/A11Y_RULES.md
new file mode 100644
index 0000000..8062295
--- /dev/null
+++ b/.claude/skills/annotask-apply/A11Y_RULES.md
@@ -0,0 +1,77 @@
+# A11Y Rules
+
+Read this file for `a11y_fix` tasks. If you are applying a batch of a11y tasks, read it once for the batch, not once per task.
+
+## Task context
+
+The `a11y_fix` task `context` contains:
+
+- `rule`: axe rule ID, or Annotask's synthetic `tab-order` rule
+- `impact`, `help`, `helpUrl`
+- `elements[]`: offending elements with `html`, `selector`, `fix`, source `file` / `line` / `component`
+- `elements[i].a11y`: computed accessibility metadata for the specific element
+
+```text
+elements[i].a11y = {
+  accessible_name, name_source,
+  role, role_source,
+  tabindex, focusable,
+  focus_indicator,
+  contrast,
+  aria_attrs,
+}
+```
+
+If `screenshot_meta` is present, retrieve it via `annotask_get_screenshot` before proposing visual changes such as contrast or focus-ring fixes.
+
+## Rule playbook
+
+Match on `context.rule`.
+
+| Rule(s) | Fix layer | What to do |
+|---|---|---|
+| `color-contrast`, `color-contrast-enhanced` | Design tokens first | See **Color contrast playbook** below. |
+| `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` that points at visible text. If `name_source === 'placeholder'`, the input still has no real label. |
+| `button-name`, `link-name`, `input-button-name` | Markup | Add visible text or `aria-label`. For icon-only buttons, add a visually hidden label (`sr-only` or the project equivalent). Do not rely on `title`. |
+| `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | Use `alt=""` for decorative imagery and descriptive `alt` for informational imagery. For SVG icons paired with visible text, use `aria-hidden="true"`. |
+| `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These usually live in layout/root files, not leaf components. |
+| `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert or promote `<h1>`, then renumber subsequent heading levels so the outline is contiguous. Usually a layout or section change. |
+| `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what is set. Use `helpUrl` to confirm the role's allowed and required attributes, then remove or add attributes accordingly. |
+| `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Remove `aria-hidden`, move the focusable elements out, or make them unfocusable with `tabindex="-1"` if appropriate. |
+| `tabindex`, `tab-order` | Markup | Remove positive `tabindex`; use `0` for normal DOM-order focus or `-1` for programmatic focus only. For synthetic `tab-order`, inspect `context.tab_order.flag` (`positive`, `unreachable`, `reorder`) and make DOM order match visual order. |
+| `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Fix the framework's document-level source of truth: `index.html`, `app/layout.tsx`, `src/routes/+layout.svelte`, or the equivalent root document. |
+| `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>` or `<span>`. Do not nest interactive elements. |
+| `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element in the layout. Use the project's visually-hidden pattern that becomes visible on `:focus`. |
+| `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="..."` values and rename one. If the id is generated, make the generation key unique per instance. |
+| `frame-title`, `iframe-title` | Markup | Add `title="..."` describing the iframe's purpose. |
+
+## Color contrast playbook
+
+Use this when `context.rule` is `color-contrast` or `color-contrast-enhanced`. The goal is to land **one token-level edit** that fixes the violation on the first try, without spraying inline overrides or hardcoded hex into component CSS.
+
+1. **Read the structured contrast block first.** `elements[i].a11y.contrast` gives you `foreground`, `background`, and `ratio` as actual computed hex. Treat these as facts; do not re-derive from screenshots.
+2. **Open the source at `elements[i].file:line` and locate the failing CSS rule.** Identify how `color` and `background`/`background-color` are set:
+   - `var(--token-name)` → token-level fix (preferred).
+   - hardcoded hex / `rgb()` / `hsl()` → component-level fix.
+   - inline `style={…}` / `style="…"` → component-level fix on that one instance.
+   - Tailwind / utility class (e.g. `bg-blue-500 text-white`) → swap utility classes or extend the project's theme config; do not add ad-hoc inline overrides.
+3. **For the token path** — the common case in design-system playgrounds:
+   - Find the variable's definition (typically a `:root` / `:root[data-theme="*"]` block in `tokens.css`, `globals.css`, `theme.css`, or equivalent). Use `grep` for `--token-name:` if you have to.
+   - Edit the variable **at its definition**, inside the theme block that matches the current `color_scheme` on the task (`dark` vs `light`). Do not redefine the variable on the component selector — that bypasses the design system and breaks every other consumer.
+   - If both themes look like they fail, fix the variable in each theme block separately, computing per-theme.
+4. **Pick which token to move.** When both `color` and `background` are tokens, default to:
+   - **Brand background + white/near-white text (`--accent` + `--text-on-accent`):** keep the white text token, darken the brand token. Brand tokens earn their lightness; light text on brand is almost always the intended pattern, and darkening the brand by ~10–20% luminance is usually the smallest visible change.
+   - **Muted text on neutral surface (`--text-muted`, `--text-subtle` on `--surface*`):** lighten the text token, do not darken the surface. Surface tokens drive layout perception and many components consume them.
+   - **Disabled/placeholder text:** if the project intentionally uses a low-contrast token, keep the rule failure scoped to that pattern and fix only the offending public-facing instance, not the token.
+5. **Choose the new value by luminance, not by eye.** For text vs. opaque background, target ≥4.5:1 (normal text) or ≥3:1 (large/bold ≥18pt or 14pt+700). Move the token in **one direction only** (darken bg *or* lighten fg) — do not split the fix across both ends. After editing, the diff should be one line in the tokens file.
+6. **Sanity-check sibling tokens.** If you darken `--accent`, glance at `--accent-strong` (the hover/pressed variant) and `--accent-soft` (low-opacity surfaces). If `--accent-strong` is already darker than your new `--accent` value, leave it. If it's now lighter, slide it darker by the same delta so the brand ramp stays monotonic.
+7. **Do not touch the component CSS.** A clean token fix has no edits in the component file. If you find yourself opening the component to override the variable, stop — you are about to re-introduce the instance-level pattern the playbook is trying to prevent.
+
+The agent should also confirm the re-render passes after applying: the user's a11y panel re-scans automatically once the file saves, and the violation should drop off. If it doesn't, the wrong token was moved or the change landed in the wrong theme block.
+
+## General rules
+
+- Prefer pattern fixes over instance fixes. If many entries point at the same file or component, fix the source component once.
+- For synthetic `tab-order`, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no axe `helpUrl`; use the WCAG page in `context.helpUrl`.
+- When `a11y.accessible_name` is empty and `a11y.focusable` is true, naming is usually the highest-priority fix.
+- Layout and document-head rules usually belong in root or layout files, not the selected leaf component.
diff --git a/.claude/skills/annotask-apply/ERROR_FIX.md b/.claude/skills/annotask-apply/ERROR_FIX.md
new file mode 100644
index 0000000..d6b598c
--- /dev/null
+++ b/.claude/skills/annotask-apply/ERROR_FIX.md
@@ -0,0 +1,40 @@
+# Error fix tasks
+
+`error_fix` tasks come from the Errors tab in the Annotask shell. Each task
+captures one or more console errors with their stack traces, the route where
+they happened, and the number of occurrences.
+
+## Read order
+
+1. **`task.context.level`** — `'error'` or `'warn'`. Errors block; warnings
+   often don't. Don't suppress warnings into errors and don't downgrade
+   errors into warnings just to make the panel quieter.
+2. **`task.context.errorId`** — stable hash. Use it to confirm you're
+   fixing what the user saw, not a sibling error from the same file.
+3. **`task.context.occurrences`** — when this is high (>50), the error is
+   firing on every render or interaction. Prioritize root-cause fixes over
+   try/catch wrappers.
+4. **Stack trace** — read the top frame to locate the throw, but read the
+   second and third frames to understand who called it. The fix usually
+   lives at the caller, not the throw site.
+
+## Fix patterns
+
+- **Undefined property access** (`Cannot read properties of undefined`) —
+  fix the producer, not the consumer. Adding `?.` everywhere hides the
+  real defect.
+- **Hydration mismatch** (React/Vue/Svelte SSR) — the server and client
+  rendered different output. Find the divergent branch (often
+  `typeof window !== 'undefined'`) and align them.
+- **Network errors** — surface to the user; don't swallow with a generic
+  toast unless the user explicitly asked for one.
+
+## Don't
+
+- Don't add `try/catch` around the call site just to silence the error.
+- Don't add `console.error` suppressions or noise filters.
+- Don't change the error to a warning to clear the panel.
+
+When you finish, set `status: 'review'` with a one-line resolution that
+states (a) the root cause and (b) the file you touched. The user will
+verify in the Errors tab that the count stays at zero.
diff --git a/.claude/skills/annotask-apply/PERF_FIX.md b/.claude/skills/annotask-apply/PERF_FIX.md
new file mode 100644
index 0000000..fd2259f
--- /dev/null
+++ b/.claude/skills/annotask-apply/PERF_FIX.md
@@ -0,0 +1,57 @@
+# Performance fix tasks
+
+`perf_fix` tasks come from the Perf tab. Each task points at one finding:
+a Web Vital that regressed, a heavy resource group, a heavy bundle
+package, or long main-thread tasks captured during a recording.
+
+## Read order
+
+1. **`task.context.category`** — what kind of finding this is:
+   `'vital' | 'resource' | 'long-task' | 'bundle'`. The fix surface
+   varies dramatically by category; don't apply a vitals recipe to a
+   bundle task.
+2. **`task.context.metric`** — present **only on `vital` findings**: the
+   uppercase Web Vital name (`'LCP'`, `'CLS'`, `'INP'`, `'TTFB'`,
+   `'FCP'`). Non-vital findings have no `metric`; key off `category`
+   and `findingId` instead.
+3. **`task.context.findingId`** — stable id that also encodes the
+   offender: `vital:LCP`, `resource:heavy-script`,
+   `bundle:lodash`, `blocking:long-tasks`.
+4. **`task.context.value`** + **`unit`** — the observed value (`'ms'`
+   for vitals and long tasks, `'bytes'` for resource/bundle findings,
+   empty unit for CLS which is unitless). Use this to verify your fix
+   in the Perf tab post-edit.
+5. **`task.context.severity`** — the Web Vitals rating scale:
+   `'good' | 'needs-improvement' | 'poor'`. `poor` CLS (>0.25) usually
+   means a single layout shift you can squash; `needs-improvement` may
+   be unfixable without redesign.
+6. **`task.context.detail`** / **`resources`** — human-readable summary,
+   and (on `resource` findings) the offending URLs with sizes and
+   durations. `context.metrics` carries the full snapshot when one was
+   captured.
+
+## Fix patterns
+
+- **LCP** — defer or preload the largest contentful element. Drop hero
+  images to the right format/size; preconnect to the right origins.
+- **CLS** — explicit dimensions on images, reserved space for async
+  content (banners, ads, late-loaded fonts).
+- **INP** — break long tasks, debounce input handlers, move work off the
+  main thread. `blocking:long-tasks` findings give you Total Blocking
+  Time and pair naturally with INP work.
+- **Resource / bundle size** — confirm the offender lives in user code,
+  not a vendor chunk. Tree-shake or lazy-load instead of swapping
+  libraries; the `bundle:<package>` finding's detail may already
+  suggest a lighter alternative.
+
+## Don't
+
+- Don't suppress the metric by changing what gets counted (e.g. excluding
+  a route from RUM).
+- Don't ship a "fix" that improves the metric in dev but regresses in
+  prod (e.g. removing `import.meta.hot` blocks).
+- Don't refactor unrelated code in a perf task.
+
+Set `status: 'review'` with a resolution that names the finding and the
+post-fix expected value (`'CLS dropped from 0.31 to ~0.05 — reserved space
+for hero image'`). The user re-runs the Perf scan to confirm.
diff --git a/.claude/skills/annotask-apply/SKILL.md b/.claude/skills/annotask-apply/SKILL.md
index 820d735..49bca89 100644
--- a/.claude/skills/annotask-apply/SKILL.md
+++ b/.claude/skills/annotask-apply/SKILL.md
@@ -1,7 +1,14 @@
+---
+name: annotask-apply
+description: Apply pending Annotask design tasks to the source code. Use when the user asks to apply Annotask changes, apply design changes, sync Annotask, or runs /annotask-apply.
+---
+
 # annotask-apply
 
 Apply pending Annotask design tasks to the source code.
 
+> **For editor agents (Claude Code, Cursor, Windsurf).** Annotask's built-in agent runs apply directly through the shell — the user runs a task from the Conversation tab and the local-CLI provider edits files in place. This skill exists when the user prefers to drive apply from their own editor agent instead.
+
 ## When to use
 
 Use this skill when the user says:
@@ -12,7 +19,7 @@ Use this skill when the user says:
 
 ## How it works
 
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
+Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, and text highlights (sections are wireframe sketch material — they arrive as `wireframe_apply` add directions, not Annotate tasks). These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
 
 ## MCP preference
 
@@ -96,166 +103,93 @@ npx annotask update-task TASK_ID --status=in_progress --mcp
 
 #### b. Reference the design spec for consistency
 
-Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
+Use the design spec when the task changes visual design, layout tokens, typography, spacing, or introduces new UI that should match the existing system.
 
-**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
+**MCP:** `annotask_get_design_spec()`
 
 ```bash
 npx annotask design-spec --mcp
 ```
 
-Response example:
-```json
-{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
-```
-
-For detailed tokens in a specific category:
+For one category only:
 
 ```bash
 npx annotask design-spec --category=colors --mcp
 ```
 
-**When to use:**
-- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
-- **Typography changes** — Reference the font scale and families from the spec
-- **Responsive design** — Use detected breakpoints when adding media queries
-- **New components** — Match the design system when creating new UI
-
-**How to apply:**
-- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
-- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
-- For responsive design, use the detected breakpoints
-- Document the token reference in your resolution note (e.g., "Applied primary color token")
-
-#### c. Find relevant components (required when adding any UI element)
-
-If the task asks you to add, insert, or create a UI element of any kind — a table, button, card, modal, input, dropdown, form, list, nav, etc. — you **must** search the component library first before writing HTML from scratch. This applies to all task types: `section_request`, `annotation` with actions like `add_column`/`add_row`/`wrap_container`, and free-text `annotation` notes whose `description` implies new UI.
-
-**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
-
-```bash
-npx annotask components "button" --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
-```
-
-For a specific component, get its full prop signature:
+Apply it narrowly:
+- Prefer existing tokens over hardcoded values
+- Use the project's spacing and breakpoint scale
+- Reuse the detected styling conventions instead of introducing a new pattern
 
-```bash
-npx annotask component Button --mcp
-```
+#### c. Gather only the extra context this task needs
 
-For **in-repo usage examples** (real prop combinations + import path this project actually uses), call `annotask_get_component_examples(name: "Button")` — or `npx annotask component-examples Button --mcp`. Prefer the example's import path and prop shape over reinventing: the examples show how *this* codebase uses the component, not just what the library exposes.
+Start with the task summary. Pull more context only when it changes the implementation.
 
-#### c-ter. Find the data source (required for any task that adds or modifies data-driven UI)
+**Re-anchor stale tasks**
 
-Before writing UI that renders data, check what's already wired. If the task's summary contains `data_context_summary` (e.g. `"hook:useUserQuery"` or `"store:useCounterStore"`), that's the primary data source powering the selected element. For the full picture:
-
-**MCP:** `annotask_get_data_context(task_id: "TASK_ID")` — returns the complete `DataContext`: every data reference in the enclosing file (`sources`, sorted with the primary source at index 0 — closest to `task.line`, tie-broken by kind precedence), `rendered_identifiers` from the template/JSX (CSV), and `route_bindings` (CSV).
+For **denied** tasks, old `in_progress` tasks, or any task whose `file`/`line` may have drifted, call `annotask_get_code_context(task_id)` before editing.
 
 ```bash
-npx annotask data-context TASK_ID --mcp
-```
-
-To browse the project's catalog of hooks, stores, and fetch wrappers (sorted by `used_count` — most load-bearing first):
-
-**MCP:** `annotask_get_data_sources(used_only: true)` — filter to entries actually used elsewhere in the codebase.
-
-```bash
-npx annotask data-sources --used-only --mcp
+npx annotask code-context TASK_ID --mcp
 ```
 
-To see **real in-repo usages** of a specific data source (destructuring patterns, parameter shape, common wrappers — parallel to `annotask_get_component_examples`):
+Use `symbol` + `excerpt` to locate the edit target. Treat `excerpt_hash` as a cheap drift check across retries.
 
-**MCP:** `annotask_get_data_source_examples(name: "useUserQuery", kind: "composable")`
+**If the task adds UI, find components first**
 
-```bash
-npx annotask data-source-examples useUserQuery --kind=composable --mcp
-```
+If the task asks you to add, insert, or create UI of any kind — table, button, card, modal, input, dropdown, form, list, nav, layout wrapper — search the component library before writing custom HTML. This applies to `section_request`, structural `annotation` actions like `add_row` or `wrap_container`, and free-text notes that clearly imply new UI.
 
-To see **what shape comes back** from an API — cross-reference declared schemas (OpenAPI, GraphQL, tRPC) so you don't guess field names:
-
-**MCP:** `annotask_resolve_endpoint(url: "/api/cats")` → returns the best-match operation with a confidence score.
+**MCP:** `annotask_get_components(search: "button")`
 
 ```bash
-npx annotask resolve-endpoint /api/cats --mcp
-```
-
-**MCP:** `annotask_get_api_operation(path: "/api/cats", method: "GET")` — full request / response schema for a known path pattern.
-
-```bash
-npx annotask api-operation /api/cats --method=GET --mcp
+npx annotask components "button" --mcp
 ```
 
-**MCP:** `annotask_get_api_schemas(detail: true)` — browse every discovered schema source up front.
+If a candidate looks right, inspect the exact API and project usage:
 
 ```bash
-npx annotask api-schemas --detail --mcp
+npx annotask component Button --mcp
+npx annotask component-examples Button --mcp
 ```
 
-If a task summary shows `response_schema_ref: "Cat[]"`, the agent already knows a declared shape exists — `annotask_get_api_operation` or `annotask_resolve_endpoint` will surface the full JSON schema.
-
-**When to use:**
-- Any task where the user's description mentions adding, replacing, or rewiring data — "show the current user", "list orders", "filter by status", "fetch from the API".
-- Denied tasks where feedback mentions wrong or fake data.
-- Section requests that need to render real information.
-
-**How to apply:**
-- Prefer reusing a hook/store from `data_context.sources` or `data-sources` catalog over writing new fetch code.
-- Copy the import path and call-site shape from `data-source-examples`, not from library docs.
-- If `sources[0]` doesn't match the user's description (e.g. task says "user name" but `sources[0]` is `useOrdersQuery`), check the rest of the `sources` list — the right hook is usually there.
+Prefer the import path and prop shape from `annotask_get_component_examples` over inventing a fresh usage.
 
-**When to use:**
-- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
-- **UI additions** — Check if a table, button, card, modal, input, form, list, or nav component already exists before writing custom HTML
-- **Styling consistency** — Using library components ensures your changes match the design system
+**If the task binds or changes data, inspect the existing data path**
 
-**How to apply:**
-- Search for components matching the intent (e.g., "table" if adding tabular data, "dropdown" if adding a select menu)
-- Read the props to understand customization options (variant, size, disabled, etc.)
-- Call `annotask_get_component_examples` to see how the component is already used in this codebase; copy the import path and prop patterns from there
-- Use the component in your JSX/Vue/Svelte code with appropriate props
-- Document the component reference in your resolution note
+Do this only for data-driven work: showing real data, rewiring an existing hook/store, changing filters or queries, or fixing a denied task that used fake or wrong data.
 
-#### c-bis. Re-anchor older or retried tasks
-
-For **denied** tasks, tasks that have been sitting in the queue while you edited other files, or any task whose `file`/`line` you suspect has drifted: call `annotask_get_code_context(task_id)` before editing.
+Start with what the task already tells you:
+- If the summary has `data_context_summary`, use that as the first candidate source
+- If that is not enough, call `annotask_get_data_context(task_id)` to inspect nearby sources in the current file
 
 ```bash
-npx annotask code-context TASK_ID --mcp
-```
-
-Response:
-```json
-{"file":"src/components/Header.vue","line":42,"symbol":"Header","excerpt_start_line":27,"excerpt_end_line":57,"excerpt":"...","imports":["import ..."],"excerpt_hash":"ab12cd34ef56..."}
+npx annotask data-context TASK_ID --mcp
 ```
 
-Use `symbol` + `excerpt` to locate the edit target; the `excerpt_hash` is a cheap drift check on subsequent retries (if the hash changes between attempts, the surrounding code moved). Skip this step for fresh pending tasks where `file`/`line` are known good.
+Only expand further when needed:
+- `annotask_get_data_sources(used_only: true)` / `npx annotask data-sources --used-only --mcp` when you need to find a reused project-level source
+- `annotask_get_data_source_examples(name)` / `npx annotask data-source-examples NAME --kind=composable --mcp` when you need the real import path or call-site shape
+- `annotask_resolve_endpoint(url)` or `annotask_get_api_operation(path, method)` when you need response field names or schema details
+- `annotask_get_api_schemas(detail: true)` only as a last resort when you still do not know which schema owns the endpoint
 
-#### c-quater. Retrieve interaction history or rendered HTML on demand
+Prefer reusing an existing hook/store/fetch wrapper over writing new data plumbing.
 
-Annotask always captures two richer context streams per task — but keeps them out of the default task payload so lists stay lean:
-- **Interaction history** — the user's recent navigation + click trace (up to ~20 events around task creation)
-- **Rendered HTML** — the post-render `outerHTML` of the selected element (bindings resolved, capped at 200 KB)
+**If the task references a flow or rendered structure, pull it on demand**
 
-The "Embed …" toggles in the Annotask UI only decide whether each rides in the task payload. When the payload doesn't contain them, pull on demand:
-
-**MCP:** `annotask_get_interaction_history(task_id: "TASK_ID")` — useful when the task description references a flow or sequence ("after I click submit…", "on the orders page…").
+Use interaction history when the task depends on the user's path through the app:
 
 ```bash
 npx annotask interaction-history TASK_ID --mcp
 ```
 
-**MCP:** `annotask_get_rendered_html(task_id: "TASK_ID")` — useful when the task references visual structure that's hard to reconstruct from source alone ("the three spans in the header", "this button's icon wrapper").
+Use rendered HTML when the task refers to post-render structure that is easier to inspect from the DOM than from source:
 
 ```bash
 npx annotask rendered-html TASK_ID --mcp
 ```
 
-Both tools prefer the embedded copy on the task when present (`source: "embedded"`), fall back to the per-task sidecar under `.annotask/` (`source: "sidecar"`), and return `not_captured: true` when neither exists (rare — only when no selection was attached at task creation).
+Both tools prefer embedded task payloads when present and otherwise fall back to the per-task sidecar under `.annotask/`.
 
 #### d. Apply the change
 
@@ -263,121 +197,26 @@ Read the task type and apply accordingly:
 
 - **`annotation` with `action: "text_edit"`**: The `description` field says what text to change. Find the text in the source file and apply the edit.
 
-- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run step c first.
+- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run the component lookup in step c first.
 
-- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run step c (component library search) before writing HTML.**
+- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run the component lookup in step c before writing HTML.**
 
 - **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
 
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
-
-- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID, or the synthetic `tab-order` rule from Annotask's tab-order overlay), `impact`, `help`, `helpUrl`, and `elements` array with `html`, `selector`, `fix`, source `file`/`line`/`component`, and a per-element `a11y` block with computed accessibility metadata:
-
-  ```
-  elements[i].a11y = {
-    accessible_name, name_source,   // "Sign in", source: aria-label | labelledby | label | alt | text | placeholder | none
-    role, role_source,              // "button", source: explicit | implicit | none
-    tabindex, focusable,            // null | number, true/false
-    focus_indicator,                // "visible" | "none" | "unknown"
-    contrast,                       // { foreground, background, ratio, aa_normal, aa_large, ... } only when element has text
-    aria_attrs,                     // [{ name: "aria-expanded", value: "false" }, ...]
-  }
-  ```
-
-  If `screenshot_meta` is present (the user manually attached one with the snip tool), retrieve it via `annotask_get_screenshot` before proposing visual changes (color-contrast, focus rings).
-
-  **Per-rule playbook.** Most rules fall into one of these patterns — match by `context.rule`:
-
-  | Rule(s) | Fix layer | What to do |
-  |---|---|---|
-  | `color-contrast`, `color-contrast-enhanced` | Design tokens first | Read `elements[i].a11y.contrast` for the actual fg/bg hex + ratio. If the colors come from theme tokens (check `cssVar` lookups in the source), adjust the token. If the contrast comes from a one-off inline style or hardcoded class, fix the component, not the token (you'd regress every other consumer). |
-  | `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` referencing visible text. `a11y.accessible_name` shows what (if anything) the input currently exposes — when `name_source === 'placeholder'`, the input has no real label. |
-  | `button-name`, `link-name`, `input-button-name` | Markup | Add visible text content or `aria-label`. For icon-only buttons add a visually hidden `<span class="sr-only">` (or your project's equivalent). Don't add `title` — it's not reliable for SR users. |
-  | `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | `alt=""` for decorative imagery, descriptive `alt` for informational. For `<img>` that conveys text, use the text. For SVG icons that pair with visible text, use `aria-hidden="true"`. |
-  | `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These almost always live in a layout component (e.g. `App.vue`, `_layout.tsx`, `RootLayout`), not in leaf components. |
-  | `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert/promote `<h1>`; renumber subsequent levels so the outline is contiguous. Usually a layout/section component change, not a leaf change. |
-  | `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what's set. Reference the WAI-ARIA roles spec (`helpUrl`) for the role's allowed attributes. Remove disallowed attrs; add required ones. |
-  | `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Either remove `aria-hidden`, or move the focusable elements outside (or set `tabindex="-1"` and ensure they're never the focus target). |
-  | `tabindex`, **synthetic** `tab-order` | Markup | Remove positive `tabindex`; use 0 (focusable in DOM order) or -1 (programmatically focusable, not in tab order). For the synthetic `tab-order` rule, `context.tab_order.flag` is one of `positive` / `unreachable` / `reorder` — fix the source markup so DOM order matches visual order. |
-  | `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Single source of truth — usually `index.html` (Vite/CRA), `app/layout.tsx` (Next), `src/routes/+layout.svelte` (SvelteKit), or the framework's root document. |
-  | `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>`/`<span>`. Don't nest interactive elements (e.g. `<button>` inside `<a>`). |
-  | `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element of the layout. Style it with the visually-hidden pattern that becomes visible on `:focus`. |
-  | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="…"` and rename one. If the id is dynamic, ensure the generation key is unique per instance. |
-  | `frame-title`, `iframe-title` | Markup | Add `title="…"` describing the iframe's purpose. |
-
-  **General rules:**
-  - Prefer **pattern fixes** over instance fixes. When `elements` contains many entries that share the same `file`/`component`, change the source component once — don't paste the same fix N times.
-  - For the synthetic `tab-order` rule, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no `helpUrl` from axe — use the linked WCAG focus-order page in `context.helpUrl`.
-  - When `a11y.accessible_name` is empty and `a11y.focusable` is true, the element is unreachable for screen readers — naming is the highest-priority fix.
-
-- **`theme_update`**: One or more design token value changes committed together from the Theme page. A single task now covers every edit the user made in one Commit click — do not expect one task per token. The `context` object contains:
-  - `edits`: array of token edits. Each entry has:
-    - `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
-    - `role`: semantic role name (e.g. `primary`, `background`, `heading`)
-    - `cssVar`: CSS variable name if backed by one (e.g. `--color-primary`), or `null`
-    - `theme_variant`: the theme id this edit targets (e.g. `light`, `dark`)
-    - `theme_selector`: how that variant is activated in the DOM — `{kind:'default'}`, `{kind:'attribute',host,name,value}`, `{kind:'class',host,name}`, or `{kind:'media',media}` — tells you which CSS block owns this variable (`:root`, `:root[data-theme="dark"]`, `.dark`, `@media (prefers-color-scheme: dark)`)
-    - `before`: old value (`null` for new tokens)
-    - `after`: new value
-    - `sourceFile` / `sourceLine`: where the current declaration lives (both `null` for new tokens — you pick the location)
-    - `isNew`: `true` if this token didn't exist before
-  - `styling`: array of project styling methods (e.g. `["tailwind", "scoped-css"]`)
-  - `specFile`: relative path to the design spec (typically `.annotask/design-spec.json`)
-
-  **How to apply:**
-  1. **Group `context.edits` by `sourceFile`.** For each file (skipping `null`/`isNew` for now), open it once, apply every edit against its file in a single Edit-batch, save. Use `theme_selector` + `cssVar` to locate the right declaration block — e.g. an edit with `theme_selector: {kind:'attribute',host:'html',name:'data-theme',value:'dark'}` belongs inside `:root[data-theme="dark"] { … }`, a `{kind:'default'}` edit belongs in the base `:root { … }` block.
-  2. **Tailwind config edits:** if `cssVar` is `null` and `sourceFile` references `tailwind.config.*`, update the corresponding key. If edits span both Tailwind and raw CSS, handle each file independently.
-  3. **New tokens (`isNew: true`):** add the CSS variable to the declaration block matching `theme_selector`. If no block exists for that variant yet, create one (e.g. add `:root[data-theme="dark"] { --new-var: …; }` at the end of the main tokens file). After writing, remember the final file path and line for step 4.
-  4. **Patch `.annotask/design-spec.json` once at the end.** Resolve `context.specFile` against the MFE root (the directory containing `.annotask/`). For each edit:
-     - Existing token: find `spec.<category>` — note dotted categories like `typography.families` map to nested paths — locate the entry by `role`, then set `values[theme_variant] = after`.
-     - New token: append a token object with `role`, `values: { [theme_variant]: after }`, `cssVar`, and fresh `sourceFile` / `sourceLine` pointing at where you added the declaration in step 3.
-     - When writing, keep the existing JSON formatting (same indentation, trailing newline) so the file watcher's next broadcast is clean.
-  5. The server watches `design-spec.json`; saving it fires a `designspec:updated` push and the Theme page refetches automatically.
-
-  **Worked example:** `context.edits = [{ category:'colors', role:'background', cssVar:'--stress-bg', theme_variant:'light', theme_selector:{kind:'default'}, before:'#f4f7fb', after:'#ff00ff', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:12, isNew:false }, { category:'colors', role:'text', cssVar:'--stress-text', theme_variant:'dark', theme_selector:{kind:'attribute',host:'html',name:'data-theme',value:'dark'}, before:'#e7eefb', after:'#ffeb3b', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:65, isNew:false }]` → open `tokens.css` once, update `--stress-bg` in the `:root` block and `--stress-text` in the `:root[data-theme="dark"]` block, save. Then open `.annotask/design-spec.json`, set `colors[?role=='background'].values.light = '#ff00ff'` and `colors[?role=='text'].values.dark = '#ffeb3b'`, save. Mark the task `review` with resolution `"Updated 2 color tokens in tokens.css and design-spec.json"`.
-
-- **`api_update`**: In-repo backend-contract edit. Created from the shell's Data view when the user selects an internal data source (`schema_in_repo === true`) and fills in a desired change. Only valid for in-repo schemas — external APIs cannot be edited from Annotask and should be marked `blocked` with an explanation if a request implies one.
-
-  The `context` object carries:
-  - `data_source_name`: hook/store/query identifier (e.g. `useCatsQuery`)
-  - `data_source_kind`: one of `composable | signal | store | fetch | graphql | loader | rpc`
-  - `schema_location`: path to the schema file (e.g. `openapi.yaml`, `src/trpc/router.ts`)
-  - `schema_kind`: `openapi | graphql | trpc | jsonschema`
-  - `endpoint`: literal endpoint / query key when the source used one
-  - `operation`: `{ method, path }` from the matched schema operation, when a match exists
-  - `desired_change`: user's description of the needed contract change
-  - `rationale`: optional "why"
-
-  **How to apply:**
-  - Open the schema file at `context.schema_location`. Read the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`) and make the change described in `desired_change`.
-  - Update the handler / backend implementation that serves that operation (typical pairs: OpenAPI routes ↔ the framework-specific handler file, tRPC router ↔ its procedure body).
-  - Update the frontend data source at `file:line` if the shape change affects the consumer (e.g. return type, destructured fields).
-  - If the change is additive (new optional field), you usually don't need to change existing callers. If it's breaking (required field, renamed field), search for all usages with `annotask_get_data_source_examples` and update them.
-  - Record what you changed in the resolution note — mention which schema location, which operation, and any frontend call sites touched.
-
-- **`annotation` with cross-boundary API edits**: An annotation task may turn out to require an in-repo API change (e.g. "show expiration date on the tier badge" when the `Cat` schema does not currently return `expires_at`).
-
-  **Rule**: do **not** silently edit the backend. Ask the user first via a `needs_info` question:
-  > This change requires updating the internal API route `GET /api/cats` to add an `expires_at` field on the `Cat` response. Proceed with both frontend and backend edits? (yes / no)
-
-  If the user approves, continue the same task (do **not** spawn a separate `api_update` task). Record each API edit structurally in `task.context.api_edits[]`:
-  ```json
-  {
-    "api_edits": [
-      {
-        "schema_location": "openapi.yaml",
-        "schema_kind": "openapi",
-        "operation": { "method": "GET", "path": "/api/cats" },
-        "change_summary": "Added nullable expires_at: string (ISO date) to the Cat response schema and handler."
-      }
-    ]
-  }
-  ```
-  Annotask's summary lifting will surface `api_edits_count` on the triage view so the user sees this task crossed the frontend/backend line.
-
-  If the user denies, do the frontend-only thing you can, or mark the task `blocked` with an explanation pointing at the missing backend support.
-
-  If the data source is external (`schema_in_repo === false`) and the task requires a contract change, mark the task `blocked` immediately — Annotask cannot edit APIs outside the repo.
+  The same `context.changes` array may also carry these three **legacy** types — the current UI no longer emits them, but apply them per these rules when they appear in older tasks:
+  - `{"type": "component_prop_update", "element", "prop", "before", "after", "binding", "prop_type"?, "file", "line"}` — one prop value change at a component **usage site** (`file:line` is where `<Element …>` is written). Respect `binding`: `"literal"` means rewrite the plain attribute value (`label="Reset"` → `label="Clear"`); `"expression-literal"` means the literal is written through binding syntax — **keep the syntax** (`:count="3"` → `:count="4"`, `count={3}` → `count={4}`); `"new"` means the prop isn't present at the usage site — add it using the framework's idiomatic form for `prop_type`. Bound expressions never appear here (the UI refuses them) — if `before` doesn't match what you find in source, re-anchor via `annotask_get_code_context` instead of guessing, and never rewrite an expression that references variables.
+  - `{"type": "text_update", "element", "before", "after", "file", "line"}` — a literal text-content change. The element at `file:line` has a single literal text run equal to `before`; replace it with `after`. If the text there is an interpolation/expression or doesn't match `before`, the source drifted — re-anchor or ask, never overwrite a binding.
+  - `{"type": "component_move", "element": {"tag", "component"?, "from_file", "from_line"}, "move_to": {"target_file", "target_line", "position"}}` — relocate the element's source block from `from_file:from_line` to the given position (`before`/`after`/`append`/`prepend`) relative to `target_file:target_line`. Move the markup intact (including its bindings and children); adjust imports only if the move crosses files.
+
+- **`section_request`** (**legacy** — the current UI no longer emits these; sections now arrive as `wireframe_apply` `add` directions with an `md` body. Apply this rule when older task files carry one): Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and the relevant step-c lookups before writing custom HTML.
+
+- **`a11y_fix`**: Fix an accessibility violation. Read `A11Y_RULES.md` in this skill directory before applying the change. If you are working through multiple a11y tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: prefer pattern fixes over instance fixes, expect layout/head rules to live in root or layout files, and fetch the screenshot first when the issue is visual (contrast, focus ring, hidden text, similar).
+
+- **`theme_update`**: Apply batched design-token edits from the Theme page. Read `THEME_UPDATE.md` in this skill directory before applying the change. If you are working through multiple theme tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: one task may include many edits, update source files before `.annotask/design-spec.json`, and land `theme_update` before dependent `style_update` tasks.
+
+- **`wireframe_apply`**: Implement the user's wireframe — snapshot-sketch directions (`context.session` entries with `change.type: 'wireframe_direction'`) and/or palette placements (`context.wireframe.instances[]`) — in real source. Read `WIREFRAME_APPLY.md` in this skill directory before applying the change. If you are working through multiple wireframe tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: pixel geometry is a hint and the direction's `relations` are the contract (implement intent with idiomatic layout, never absolute positioning); placements/directions carry durable `anchor`s (`file`/`line`) — resolve component imports via `annotask_get_component_examples` rather than guessing; and never fabricate handlers/children/data — placeholders stay visibly placeholders.
+
+- **`annotation` with cross-boundary API edits**: Some frontend requests turn out to depend on backend work (for example, a field is not returned by the current response schema). Do **not** edit the backend and do **not** ask for permission to do so. If there is a meaningful frontend-only fallback, apply it and explain the missing backend support in the resolution note. Otherwise, mark the task `blocked` and tell the user which API/schema change would be required.
 
 #### e. Ask for clarification (only when stuck)
 
diff --git a/.claude/skills/annotask-apply/THEME_UPDATE.md b/.claude/skills/annotask-apply/THEME_UPDATE.md
new file mode 100644
index 0000000..b56494b
--- /dev/null
+++ b/.claude/skills/annotask-apply/THEME_UPDATE.md
@@ -0,0 +1,46 @@
+# Theme Update
+
+Read this file for `theme_update` tasks. If you are applying a batch of theme tasks, read it once for the batch, not once per task.
+
+## Task context
+
+`theme_update` batches every token edit from one Theme-page commit into a single task.
+
+The `context` object contains:
+
+- `edits[]`: token edits
+- `styling[]`: project styling methods such as `tailwind` or `scoped-css`
+- `specFile`: relative path to `.annotask/design-spec.json`
+
+Each edit contains:
+
+- `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
+- `role`: semantic token role such as `primary` or `background`
+- `cssVar`: CSS variable name when present, otherwise `null`
+- `theme_variant`: variant id such as `light` or `dark`
+- `theme_selector`: selector metadata describing which declaration block owns the value
+- `before`, `after`
+- `sourceFile`, `sourceLine`
+- `isNew`
+
+## Apply flow
+
+1. Group `context.edits` by `sourceFile`.
+2. For each existing source file, open it once and apply every edit in one pass.
+3. Use `theme_selector` + `cssVar` to locate the correct block:
+   - `{kind:'default'}` -> base `:root`
+   - `{kind:'attribute', ...}` -> matching attribute-scoped block such as `:root[data-theme="dark"]`
+   - `{kind:'class', ...}` -> matching class-scoped block such as `.dark`
+   - `{kind:'media', ...}` -> matching media-query block
+4. If `cssVar` is `null` and the file is `tailwind.config.*`, update the matching config key instead of searching CSS.
+5. For `isNew: true`, add the token to the correct variant block. Create the block if it does not exist yet.
+6. Patch `.annotask/design-spec.json` once at the end:
+   - existing token -> update `values[theme_variant]`
+   - new token -> append a token entry with `role`, `values`, `cssVar`, `sourceFile`, and `sourceLine`
+7. Keep the existing JSON formatting so the file watcher emits a clean update.
+
+## Defaults
+
+- One `theme_update` task may touch multiple files.
+- Edit source files before patching `.annotask/design-spec.json`.
+- `theme_update` should land before any dependent `style_update` in the same apply run.
diff --git a/.claude/skills/annotask-apply/WIREFRAME_APPLY.md b/.claude/skills/annotask-apply/WIREFRAME_APPLY.md
new file mode 100644
index 0000000..dfbc207
--- /dev/null
+++ b/.claude/skills/annotask-apply/WIREFRAME_APPLY.md
@@ -0,0 +1,121 @@
+# Wireframe Apply
+
+Read this file for `wireframe_apply` tasks. If you are applying a batch, read it once for the batch, not once per instance.
+
+A `wireframe_apply` task arrives two ways:
+
+1. **"Implement this wireframe"** — the user froze a route into a snapshot sketch (per-block images of the real render), rearranged it freely, and asked you to implement the intent. The task carries **wireframe directions** in `context.session.entries[]` (`change.type === 'wireframe_direction'`) plus a labeled before/after composite screenshot.
+2. **"Build this route" / "Apply now"** — palette placements in `context.wireframe.instances[]` and/or design-session edits in `context.session.entries[]` (style/class/move/insert change types).
+
+A task may carry both halves. Handle directions with the rules below; handle placements and other session entries with the later sections.
+
+## Wireframe directions (`change.type: 'wireframe_direction'`)
+
+The user rearranged a SKETCH — images of the rendered page, not the live app. The server diffed the sketch against the original capture into one direction per changed block:
+
+- `op`: `move` | `resize` | `delete` | `add` | `note`.
+- `block`: `{ label, component?, tag? }` — the block's identity as captured. Tool-derived, never invented.
+- `file`/`line` (top level): the block's captured source anchor — or, for `add`, the nearest anchored NEIGHBOR block (see `added.position`).
+- `measured`: TOOL-MEASURED geometry. `before`/`after` rects, `dx`/`dy`, `wPct`/`hPct` (percent of original), and `relations[]` — order-flip / full-width / alignment facts computed from box geometry (e.g. `"now above the filters (was below)"`).
+- `added` (op `add` only): `kind` `component` (a real palette component — `componentName`/`library`/`module`/`props` are REAL scanner output) | `placeholder` (a user-drawn labeled box) | `duplicate` (another copy of a captured block's markup). `position` (`before`/`after`/`append`) is relative to the anchored neighbor. May carry `md` (the user's VERBATIM markdown spec for a drawn section) and/or `data` (a binding to a REAL catalog data source — see *Data bindings on adds* below).
+- `note`: the user's VERBATIM words for that block. `measured` is what the tool measured; `note` is what the user said — never conflate them, and never present a measured relation as a user request.
+
+### Intent over pixels
+
+**Pixel geometry is a hint; the relations are the contract.** `"now above the filters (was below)"` IS the instruction; `y 480→180` is evidence. Implement with idiomatic layout — reorder siblings, change flex/grid order, adjust column spans, use design tokens (`annotask_get_design_spec`) for sizes — never absolute positioning to hit coordinates. A resize of `+50% w` on a card grid usually means "fewer, larger columns", not `width: 1200px`.
+
+### Use the visuals
+
+The task screenshot (`annotask_get_screenshot`) is a labeled composite: **left = the captured render (truth at capture time); right = the user's sketch — rearranged images, not real UI.** Numbered badges on the right pane map 1:1 to the numbered directions in the task description. Look at it before writing code: spatial intent (what ended up next to what) is often clearer in the image than in prose.
+
+### Per-op rules
+
+- **move** — relocate the block's anchored markup to satisfy the relations. Apply per-file edits bottom-up (descending line); re-ground drifted anchors with `annotask_get_source_excerpt`. A loop-rendered block moves as the loop, not one iteration. An exploded container appears as both a container block and separate child blocks (each with finer anchors): directions on children mean restructuring INSIDE the container; a direction on the container means moving the whole thing, children included. (Explode-to-children is deferred this release — `WIREFRAME_EXPLODE_ENABLED=false` — so new tasks won't carry exploded child blocks; this guidance applies to legacy task files that already do.)
+- **resize** — prefer tokens/utility classes/grid-template changes over raw px. Say in the resolution what you chose and why.
+- **delete** — remove the anchored markup. Remove now-dead local bindings only when provably unused; never delete shared code.
+- **add / component** — resolve the real import via `annotask_get_component_examples` (proven specifier + export kind). No in-repo examples → fall back to `library`/`module` and say so. Apply `added.props` primitives only; never fabricate handlers, bindings, or children. When `added.data` is present, wire the REAL source per *Data bindings on adds* below — never sample data.
+- **add / placeholder** (bare — no `md`) — emit a *visibly labeled* placeholder element (e.g. `<div class="placeholder">pagination here</div>` styled per project conventions) or the minimal honest scaffold the label names. **Never fabricate data or content.**
+- **add / placeholder with `added.md` (a drawn SECTION)** — the markdown is the user's verbatim spec for the region: build what it describes per project conventions (component-library-first — run the SKILL.md step-c lookups before writing custom HTML; design tokens for styling). Use `added.data` for any data the section shows. Data-driven content with NO binding → visible placeholder slots or `needs_info` — **never fabricate data or fields.**
+- **add / duplicate** — duplicate the anchored block's markup. If it's loop-rendered, the user probably wants another ITEM or a second instance of the section — read the note/screenshot, ask via `needs_info` when ambiguous.
+- **note** — implement the user's verbatim ask. Ambiguous → `needs_info`, never guess silently.
+
+Before rewriting any expression or bound markup you encounter mid-edit, re-classify it against CURRENT source: `annotask_get_binding_classification` (CLI: `annotask binding-classify`). Never rewrite an expression that references variables.
+
+### Data bindings on adds (`added.data`)
+
+> **Gated off this release.** Wireframe data binding is DEFERRED (`WIREFRAME_DATA_BINDING_ENABLED=false` in `src/shell/wireframeFeatures.ts`), so new `wireframe_apply` tasks won't carry `added.data`. This section applies to legacy/older task files that already contain a binding — when one is present, wire it per the rules below.
+
+`added.data` means "wire THIS source" — it is REAL scanner-catalog identity, never invented:
+
+- `kind`/`name`/`module`/`endpoint`: the source as the project defines it (`module` is its defining file). `path` drills into the response shape (`planets[]` = the list; `data.user` = an object); `fields` are the keys the element should display.
+- `shape_source` is the honesty tag for where the drill-down shape came from:
+  - `api-schema` — a real API contract matched the source's endpoint; the path/fields were picked off the actual response schema. Trust the shape; `annotask_get_api_operation` returns the full operation when you need more.
+  - `source-details` — regex-inferred return-type hints only (no confidence score is carried — the tag is the only signal). Re-verify against the real definition before relying on field names.
+  - `none` — the user typed the path/fields blind. Ground them yourself before wiring.
+- **Re-grounding protocol (always):** call `annotask_get_data_source_details` for the definition and `annotask_get_data_source_examples` for the proven import + call pattern — wire the source the way the project already wires it (same import specifier, same destructuring, loops/`v-for` over the `path` collection, render the `fields`).
+- The binding contradicts current source (source renamed, field gone, shape changed)? → `needs_info` with what you found. **Never invent fields**; runtime endpoints carry no response shapes — don't pretend otherwise.
+
+### Verification & status
+
+Directions are spatial — the server does NOT verify them against source. When you set `review`, direction entries flip `written` on trust (bindings included — their wiring rides the trusted resolution); **your resolution is the only record of what actually landed**, so make it specific and honest per direction: which file(s), what structural change, for bindings the imported source + call site + rendered fields, any file you created (name new files explicitly — in git projects the server nets newly-created files into the undo batch, but your resolution is still the human-readable record). `blocked_reason` when a direction is impossible; `needs_info` for ambiguity; denied → read `feedback` and re-apply the same task.
+
+## Placements (`context.wireframe`)
+
+`context.wireframe` contains:
+
+- `route`: the iframe route the placements were made on (e.g. `/planets`).
+- `instances[]`: one entry per placement.
+
+Each instance contains:
+
+- `id`: stable placement id.
+- `kind`: `component` | `html` | `layout-preset`.
+- `anchor`: where it goes — `{ file, line, position, component, targetTag }`.
+  - `file`, `line`: the drop target's source location (`data-annotask-file` / `-line`). `line` is the target's **opening-tag** line.
+  - `position`: `before` | `after` | `append` | `prepend` — placement relative to the target element.
+  - `component`: the target's owning component (context).
+- `inserted`: what to add — `{ tag, componentName?, library?, props?, classes?, text_content? }`. `inserted.props` are the REAL props.
+- `previewProps` (optional): the display-only sample props the user actually saw rendered on the canvas (e.g. `{ label: "Button" }`). Use them as **hints** for sensible prop values and label text when `inserted.props` is empty or sparse — they show what the user previewed and approved. They are still samples: never lift fabricated event handlers, data bindings, or children from them.
+- `fidelity`: how faithfully it previewed — `live` (rendered in real context), `isolated-preview` (rendered detached, no provider tree), `placeholder` (could not render). Lower fidelity is a hint that the component needs context/props you may have to wire by hand; it is not a blocker.
+- `mounted`: whether the live preview produced output.
+- `status` / `taskId`: lifecycle bookkeeping (`building` + the owning task id while you work). Read-only for you — see the lifecycle section below.
+
+### Apply flow for placements
+
+1. Group `context.wireframe.instances` by `anchor.file`. Open each file once and apply all its placements in one pass, **bottom-up** (descending `anchor.line`): every insertion shifts the lines below it, so applying the highest line number first keeps the remaining anchors' line numbers valid without re-counting.
+2. Locate the anchor element at `anchor.line` in that file. Insert the new markup relative to it per `anchor.position` (`before`/`after` = sibling; `append`/`prepend` = first/last child of the target). Match the file's framework (read `annotask_get_design_spec` for `framework` once) and the surrounding indentation.
+3. Emit markup per `kind`:
+   - **html** → the raw element: `<tag class="…">text_content</tag>` using `inserted.classes` / `inserted.text_content`. Omit empty attributes.
+   - **layout-preset** → a styled wrapper (`<div class="…">` / `<section class="…">`) with `inserted.classes`. It has **no children** — leave it empty for the user to fill. Never fabricate children.
+   - **component** → resolve the real import first, then emit `<ComponentName …props />` (or framework equivalent) at the anchor and add the import if the file does not already import it.
+4. For a `component`, call `annotask_get_component_examples` with `inserted.componentName` (and `inserted.library`) to get the **proven** import specifier + export kind (named vs default) from real in-repo usage. Use that exact import path. If there are no in-repo examples, fall back to `inserted.library` / the scanner `module`, and say so in your resolution — do **not** invent an import path.
+5. Apply props from `inserted.props`, but only primitives that differ from the component's documented defaults. **Never fabricate** event handlers, data bindings, children, or named slots — if a component clearly needs them, note it in the resolution (or use `needs_info`).
+6. After all placements land, set status to `review` with a per-instance resolution (what you inserted, where, and any import you had to guess).
+
+## Other design-session edits (`context.session`)
+
+`context.session` may also carry non-direction entries — the user's design-session edits:
+
+- `session_id`: bookkeeping. The server owns `.annotask/design-session.json`, `.annotask/wireframe.json` (which also carries the canvas sketch), and `.annotask/file-snapshots.json` — **never edit, rewrite, or clean up those files yourself**. Apply through source code only; the server verifies your work and updates the session when you set `review`.
+- `entries[]`: each is `{ id, change, anchor, evidence?, instance_id? }`.
+  - `change` is one of the structured change types (`style_update`, `class_update`, `component_insert`, legacy `component_prop_update`/`text_update`/`component_move`, …) — apply each per the change-type rules in SKILL.md step d.
+  - `anchor` (`{ file, line, targetTag? }`) is where the edit was recorded. Your own earlier edits in the same run shift lines — apply **bottom-up per file** like placements, and re-ground via `annotask_get_source_excerpt` when an anchor doesn't match.
+  - `evidence.classification` (legacy `component_prop_update`/`text_update` entries only) is the round-trip-honesty proof from when the user made the edit: `literal` edits rewrite a plain literal in place; `expression-literal` edits keep the binding syntax (`:count="3"` → `:count="4"`); `bound` edits never appear (the UI refused them). If what you find at the anchor contradicts the evidence, the source drifted — re-anchor or ask via `needs_info`, never rewrite an expression.
+- Prefer idiomatic placement over literal transcription: if a `style_update` matches a design token (`token_role` present, or an obvious token in `annotask_get_design_spec`), apply the token/class rather than a raw value, and say so in the resolution.
+- After you set `review`, the server re-reads the source per entry and marks each `written` or `failed` (directions are trusted — see above) — a `failed` badge in the user's panel means your edit wasn't found where expected, so make resolutions specific about what landed where.
+
+## Lifecycle (do NOT edit .annotask files)
+
+- When the user **accepts** your task, the server removes its instances and the implemented canvas sketch from `wireframe.json` automatically.
+- When the user **deletes** the task, the server reverts instances to `placed` and unlocks the sketch (`building` → `sketch`) so the user can tweak and re-implement.
+- When the user **denies** the task, everything stays locked to your task — re-apply against the same task after reading `feedback`.
+
+## Edge cases
+
+- If an `anchor.file`/`line` no longer matches the described element (source drifted since the capture/placement), call `annotask_get_code_context` for the task to re-anchor; if you still can't place it, mark that instance/direction and use `needs_info`.
+- If a placement or direction requires data/state that doesn't exist yet (e.g. a list component with no data source on the route), use `blocked_reason` to explain what's missing rather than fabricating data.
+
+## Defaults
+
+- One `wireframe_apply` task may touch multiple files and multiple frameworks (MFEs) — handle each file independently.
+- The sketch is a wireframe, not a final design: prioritize correct structure, real imports, and the stated relations over pixel-perfect geometry.
diff --git a/.claude/skills/annotask-init/SKILL.md b/.claude/skills/annotask-init/SKILL.md
index 63df6c7..ac5d4e0 100644
--- a/.claude/skills/annotask-init/SKILL.md
+++ b/.claude/skills/annotask-init/SKILL.md
@@ -1,7 +1,14 @@
+---
+name: annotask-init
+description: Initialize Annotask for this project by scanning the codebase and generating .annotask/design-spec.json. Use when the user asks to initialize, set up, configure, or scan their project for Annotask, or runs /annotask-init.
+---
+
 # annotask-init
 
 Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
 
+> **For editor agents only.** Annotask's built-in agent runs init through the shell UI — open `http://localhost:5173/__annotask/` and the wizard walks the user through provider setup, project scan, and style guide. This skill exists for users who prefer their own editor agent (Claude Code, Cursor, Windsurf) to do the deeper token extraction the in-shell baseline doesn't cover.
+
 ## When to use
 
 Use this skill when the user says any of:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f7d338a..470ff84 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -5,6 +5,10 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  # Weekly slot for the secret-gated live-CLI job; also runnable on demand.
+  schedule:
+    - cron: '0 5 * * 1' # Monday 05:00 UTC
+  workflow_dispatch: {}
 
 jobs:
   build-and-test:
@@ -23,6 +27,10 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
+      # Skill mirrors (.claude/skills, .agents/skills, vue-webpack playground)
+      # must match the canonical skills/ tree — re-run sync and fail on drift.
+      - run: pnpm sync:skills && git diff --exit-code skills .claude/skills .agents/skills playgrounds/simple/vue-webpack/.claude/skills
+
       - run: pnpm audit --prod --audit-level=high
         continue-on-error: true
 
@@ -58,3 +66,40 @@ jobs:
       - run: npx playwright install --with-deps chromium
 
       - run: pnpm test:e2e --project=${{ matrix.project }}
+
+  # Live agent-apply loop against a REAL CLI. Gated on a repo secret so it only
+  # runs where credentials exist (fork PRs and unconfigured repos skip it); runs
+  # on the weekly schedule + manual dispatch, never per-PR (cost + auth). This is
+  # the only automated proof that the full apply→write→verify loop works end to
+  # end with a real provider; the per-PR suites cover the server lifecycle/undo
+  # logic deterministically without a CLI.
+  live-cli:
+    runs-on: ubuntu-latest
+    needs: build-and-test
+    if: ${{ (github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') && vars.ANNOTASK_RUN_LIVE_CLI == '1' }}
+    env:
+      ANNOTASK_LIVE_CLI: '1'
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm build
+
+      # Install the Claude CLI the live suite drives. Other providers can be
+      # added the same way once their CI auth story is sorted.
+      - run: npm install -g @anthropic-ai/claude-code
+
+      # The apply-session matrix + live providers self-skip without
+      # ANNOTASK_LIVE_CLI=1; here it's set, so they run against the real CLI.
+      - run: ANNOTASK_LIVE_ONLY=claude pnpm vitest run src/server/__tests__/apply-session-matrix.test.ts
diff --git a/.gitignore b/.gitignore
index af650a3..cba574f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,6 +8,9 @@ __pycache__
 # Annotask (generated)
 .annotask/
 
+# CLI matrix MDX reports
+/reports/
+
 
 # Astro (generated)
 .astro/
@@ -16,6 +19,11 @@ plan/
 # Local-only (references external repos)
 playgrounds/simple/antenna-vite/
 
+# Demo recording artifacts (large binaries)
+demo/segments/
+demo/voiceover/
+demo/final/
+
 # Claude Code session state
 .claude/worktrees/
 .claude/scheduled_tasks.lock
diff --git a/AGENTS.md b/AGENTS.md
index ae516ee..af0193c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,6 +29,13 @@ Annotask includes an MCP server that starts automatically with the dev server at
 | `annotask_get_api_schemas` | List discovered OpenAPI, GraphQL, tRPC, and JSON Schema sources |
 | `annotask_get_api_operation` | Fetch one API operation by path |
 | `annotask_resolve_endpoint` | Match a concrete URL to a known API operation |
+| `annotask_get_source_excerpt` | Direct source excerpt by file/line (no task required) |
+| `annotask_get_binding_classification` | Round-trip honesty classification of one element by file/line[/tag]: per-prop literal/bound/unknown, text kind, enclosing loop |
+| `annotask_get_playbook` | Fetch a task-type companion playbook (A11Y_RULES, THEME_UPDATE, ERROR_FIX, PERF_FIX, WIREFRAME_APPLY) |
+| `annotask_get_agent_directions` | Fetch per-persona project directions from `.annotask/agents.json` |
+| `annotask_conversation_read` | Read a task's conversation thread (optional `after_id` for cheap polling) |
+| `annotask_conversation_post` | Append a message to a task's conversation thread (role: user/assistant/system/tool) |
+| `annotask_conversation_subscribe` | Long-poll for new conversation messages after `after_id` |
 
 ### Applying tasks via MCP
 
@@ -70,6 +77,9 @@ annotask screenshot <id>     # Download a task's screenshot
 annotask components [search] # List components (add --mcp for JSON)
 annotask component <Name>    # Show component props
 annotask code-context <id>   # Ground task to current source excerpt
+annotask source-excerpt <file> <line>  # Direct source excerpt by file/line
+annotask playbook <task-type>  # Print a task-type companion playbook
+annotask agent-directions [persona]  # Per-persona project directions
 annotask component-examples Button # Real in-repo component usage examples
 annotask data-context <id>   # Resolve task data context
 annotask interaction-history <id>  # Pre-task user trace (always captured)
@@ -123,11 +133,41 @@ Options: `--port=N`, `--host=H`, `--server=URL` (override server.json),
 - `GET /__annotask/api/resolve-endpoint` — Resolve a concrete URL to a known operation
 - `GET|POST /__annotask/api/tasks/:id/interaction-history` — Per-task user-trace sidecar (always written on task create; embed toggle only gates inclusion in the task payload)
 - `GET|POST /__annotask/api/tasks/:id/rendered-html` — Per-task `outerHTML` sidecar (always written when a selection exists; 200 KB cap)
+- `GET /__annotask/api/agent-configs` — Per-persona project directions (`{ version, agents: { [personaId]: { projectDirections } } }`)
+- `PATCH /__annotask/api/agent-configs/:id` — Update one persona's `projectDirections`, `providerId`, `model`, or `effort`
+- `GET|PUT /__annotask/api/wireframe` — Multi-route wireframe document (`?route=PATH` slices one route; persists to `.annotask/wireframe.json`). Each route carries `instances[]` (palette placements) and an optional `canvas` (the snapshot-wireframe sketch: per-block captures with source anchors, transforms, notes, soft-deletes)
+- `POST /__annotask/api/wireframe-snapshots` — Upload a canvas block PNG (`{id, data}`; id-addressed, 4MB cap; persists to `.annotask/wireframe-snapshots/`)
+- `GET /__annotask/wireframe-snapshots/:filename` — Serve a canvas snapshot PNG (containment-guarded)
+- `DELETE /__annotask/api/wireframe-snapshots/:filename` — Drop a canvas snapshot PNG
+- `GET|PUT|DELETE /__annotask/api/design-session` — Design-session journal (ordered record of design-tool edits; CAS on `rev`, 409 on stale writes; persists to `.annotask/design-session.json`). DELETE = server-owned discard: clears the journal, removes session-created wireframe placements, and drops every route's canvas sketch (+ its snapshot PNGs)
+- `POST /__annotask/api/design-session/apply` — "Apply now" / "Implement this wireframe": snapshots the touched files, mints ONE `wireframe_apply` task (placements + design-session edits/directions in `context.session`; optional `screenshot` = the before/after composite), stamps statuses; the shell then runs the embedded agent on it. The agent writes source — the tool never does
+- `POST /__annotask/api/design-session/undo-batch` — Restore the newest apply batch's pre-apply bytes (hash-guarded; entries return to pending)
+- `POST /__annotask/api/design-session/detach-file` — Diverged-file resolution: keep the disk bytes, drop the file from the session
+- `GET /__annotask/api/design-session/snapshots` — Snapshot-engine state (touched files, divergence, apply batches) — persists to `.annotask/file-snapshots.json`; rehydrates across restarts (files revert only via explicit undo/discard)
+- `POST /__annotask/api/agent/spawn` — Spawn an allow-listed local CLI as SSE (same-port origin gate; `ANNOTASK_MAX_PERMISSION` ceiling)
+- `DELETE /__annotask/api/agent/spawn/:runId` — Abort a running spawn
+- `GET /__annotask/api/agent/detect` — Detect installed/logged-in local CLIs
+- `GET /__annotask/api/agent/models` — Per-provider model catalog (`?cli=ID`, `?refresh=1`)
+- `GET|POST /__annotask/api/tasks/:id/messages` — Per-task conversation thread (JSONL at `.annotask/conversations/<id>.jsonl`)
+- `GET /__annotask/api/tasks/:id/messages/stream` — Conversation SSE stream (honours `Last-Event-ID`)
+- `PATCH /__annotask/api/tasks/:id/messages/:msgId` — Update a message in place (partial-turn streaming)
+- `GET /__annotask/api/usage` — Aggregate token-usage summary from `.annotask/usage.jsonl`
+- `GET /__annotask/api/usage/recent` — Recent usage entries (`?limit=N`)
+- `GET /__annotask/api/init/state` — Init-runner state
+- `GET /__annotask/api/init/scan-targets` — Existence + mtime of durable scan artifacts
+- `POST /__annotask/api/init/start` — Start an init scan (skip flags, provider/model/effort)
+- `POST /__annotask/api/init/cancel` — Cancel a running scan
+- `POST /__annotask/api/init/skip` — Mark initialized without committing token data
+- `POST /__annotask/api/init/commit` — Commit reviewed spec (and optional style guide)
+- `GET /__annotask/api/system-prompt` — Composed embedded-agent system prompt (`?task_type=` adds the companion playbook)
+- `GET /__annotask/api/style-guide` — Contents of `.annotask/STYLE_GUIDE.md`
+- `GET /__annotask/api/read-file` — Read one project file by relative `?path=` (traversal-guarded)
+- `DELETE /__annotask/api/session-reset` — Clear the `.session-reset` sentinel after the shell wipes localStorage
 - `GET|POST /__annotask/api/performance` — Performance snapshots
 - `POST /__annotask/api/screenshots` — Upload a screenshot
 - `GET /__annotask/screenshots/:filename` — Serve a screenshot
 - `GET /__annotask/api/status` — Health check
-- `ws://localhost:5173/__annotask/ws` — Live WebSocket stream
+- `ws://localhost:5173/__annotask/ws` — Live WebSocket stream (events include `tasks:updated`, `components:updated`, `init:progress`, `runtime-endpoints:updated`, `wireframe:updated`)
 
 Use `/annotask-apply` to fetch and apply pending visual changes to source code.
 
@@ -152,7 +192,7 @@ Use `/annotask-apply` to fetch and apply pending visual changes to source code.
 `App.vue` is the shell orchestrator — it wires composables together and handles bridge events. **Do not add business logic directly to App.vue.** Extract new concerns into composables under `src/shell/composables/`.
 
 Key composables:
-- `useShellTheme` — Theme system: 63 CSS variables, 18 built-in themes, custom theme CRUD, system preference, localStorage persistence
+- `useShellTheme` — Theme system: 62 CSS variables, 18 built-in themes, custom theme CRUD, system preference, localStorage persistence
 - `useSelectionModel` — Element selection state, rect tracking, hover, live styles, style/class change handlers
 - `useTaskWorkflows` — Task creation flows (pin, arrow, highlight, section → task), pending task panel, accept/deny, annotation restoration, auto-opens task panel on create
 - `useAnnotationRects` — rAF loop keeping annotation overlays positioned during scroll/resize
@@ -166,20 +206,20 @@ When adding new shell features, create a new composable that accepts its depende
 
 ## Shell Theme System
 
-The shell has a VS Code-style theme system with 18 built-in themes and custom theme support. Themes control every color in the UI via 63 CSS custom properties.
+The shell has a VS Code-style theme system with 18 built-in themes and custom theme support. Themes control every color in the UI via 62 CSS custom properties.
 
 ### Architecture
 
-- `src/shell/themes/types.ts` — `ShellThemeColors` (63 vars), `ShellTheme` interface, `THEME_COLOR_KEYS` array
+- `src/shell/themes/types.ts` — `ShellThemeColors` (62 vars), `ShellTheme` interface, `THEME_COLOR_KEYS` array
 - `src/shell/themes/builtin.ts` — 18 built-in theme definitions with `deriveDefaults()` helper
 - `src/shell/composables/useShellTheme.ts` — Core composable: applies themes at runtime via `style.setProperty()`, handles localStorage persistence, system preference detection, custom theme CRUD, and a one-shot migration from the legacy `annotask:themeMode` key
 - `src/shell/components/ShellThemeEditor.vue` — Full-screen custom theme creator with grouped color pickers and live preview
 
 ### How themes are applied
 
-Themes are applied at runtime via `document.documentElement.style.setProperty()` for each of the 63 CSS variables. The `:root` block in App.vue provides dark fallback values, and `:root.light` provides light fallback values — these are safety nets for first paint before JS runs. Once `useShellTheme` initializes, it overrides all variables via inline styles.
+Themes are applied at runtime via `document.documentElement.style.setProperty()` for each of the 62 CSS variables. The `:root` block in App.vue provides dark fallback values, and `:root.light` provides light fallback values — these are safety nets for first paint before JS runs. Once `useShellTheme` initializes, it overrides all variables via inline styles.
 
-### CSS variable categories (63 total)
+### CSS variable categories (62 total)
 
 | Category | Variables | Purpose |
 |----------|-----------|---------|
@@ -192,7 +232,7 @@ Themes are applied at runtime via `document.documentElement.style.setProperty()`
 | Utility (2) | `--overlay`, `--shadow` | Overlays and shadows |
 | Status (7) | `--status-pending`, `--status-in-progress`, `--status-review`, `--status-denied`, `--status-accepted`, `--status-needs-info`, `--status-blocked` | Task lifecycle |
 | Severity (4) | `--severity-critical`, `--severity-serious`, `--severity-moderate`, `--severity-minor` | A11y/perf findings |
-| Modes (4) | `--mode-interact`, `--mode-arrow`, `--mode-draw`, `--mode-highlight` | Tool button active states |
+| Modes (3) | `--mode-interact`, `--mode-arrow`, `--mode-highlight` | Tool button active states |
 | Layout (2) | `--layout-flex`, `--layout-grid` | Layout visualization |
 | Roles (3) | `--role-container`, `--role-content`, `--role-component` | Element classification |
 | Syntax (7) | `--syntax-property`, `--syntax-string`, `--syntax-number`, `--syntax-boolean`, `--syntax-null`, `--syntax-operator`, `--syntax-punctuation` | Code highlighting |
@@ -248,6 +288,7 @@ Users create custom themes via Settings > Appearance > "+ Create Custom Theme".
 
 ## Key Shell Features
 
+- **Wireframe mode** — Freezes the current route into a manipulable image canvas: per-block html2canvas snapshots (each carrying its `data-annotask-file/-line` source anchor), drag with snap/align guides, 8-handle resize, marquee/shift-click multi-select with group move, arrow-key nudging, soft-delete/undelete, duplicate, notes, palette-drop component snapshots (configured in place), and drawn sections (a labeled box, optionally with a markdown spec). State persists per-route in `wireframe.json` (PNGs in `.annotask/wireframe-snapshots/`). "Implement this wireframe" diffs the sketch into anchored `wireframe_direction` entries, composes a labeled before/after screenshot, and runs the embedded agent through the apply loop — accept/undo/discard ride the file-snapshot engine. **NOTE:** explode-to-children and data-source binding are built but DEFERRED this release (gated in `src/shell/wireframeFeatures.ts`) — the code paths and persisted bindings remain read-only, but the UI entry points are hidden and new tasks won't carry bindings or exploded child blocks.
 - **Viewport preview** — Device presets + custom dimensions, viewport info included in tasks/reports
 - **Interaction history** — Pre-task user trace (route + ~20 recent actions). Always captured and persisted per task to `.annotask/interaction-history/<id>.json`; the "Embed interaction history" toggle only decides whether it rides in the task payload
 - **Element context / rendered HTML** — Post-render `outerHTML` of the selected element. Always captured and persisted per task to `.annotask/rendered-html/<id>.json` (200 KB cap); the "Embed rendered HTML" toggle only decides payload inclusion
@@ -255,7 +296,7 @@ Users create custom themes via Settings > Appearance > "+ Create Custom Theme".
 - **A11y checker** — axe-core WCAG scanning with one-click fix task creation (locally bundled, no CDN)
 - **Error monitoring** — Console error/warn capture with deduplication, bounded memory, one-click fix tasks
 - **Performance monitoring** — Web Vitals, DOM/resource/bundle analysis, interaction recording, perf score, one-click fix tasks
-- **Data view** — Discovered data sources, schema matching, page highlights, and `api_update` task creation
+- **Data view** — Discovered data sources, schema matching, page highlights
 - **Screenshots** — Snipping tool captures regions or full page, attached to tasks, served via API, auto-cleaned on accept (max 4MB)
 - **Task detail drawer** — Slide-out detail view with markdown rendering, inline editing, screenshot lightbox, element/file display, interaction log, JSON view, delete button
 - **Task lifecycle** — `pending → in_progress → review → accepted/denied` with `needs_info` (agent asks questions) and `blocked` (agent can't apply) statuses, resolution messages, live status updates
@@ -264,7 +305,6 @@ Users create custom themes via Settings > Appearance > "+ Create Custom Theme".
 - **Async I/O** — In-memory task cache with atomic file writes (no race conditions)
 - **Inspector highlights** — Selection/hover overlays that track scroll and resize via rAF loop
 - **Arrow tool** — Multi-color arrows with element outlines, edge-to-edge bezier paths, draggable endpoints, element-aware re-resolution on move, scroll/resize tracking via rAF
-- **Section tool** — Markdown editor (edit/preview toggle), dark theme, movable/resizable sections with drag handles, explicit "Add Task" / "Update Task" button
 - **Text highlights** — Multi-color highlights with visual overlay on selected text, sidebar task creation with preloaded text
 - **Scroll/resize tracking** — All annotations (arrows, highlights, sections) follow elements during scroll and window resize via rAF loop, same pattern as inspector selections
 - **Route persistence** — Iframe route saved to localStorage, restored on page reload
@@ -279,13 +319,13 @@ Canonical list — `TASK_TYPES` in `src/schema.ts` is the single source of truth
 | Type | Source | Description |
 |------|--------|-------------|
 | `annotation` | Pins, arrows, notes, text highlights | User intent described in `description`, optional `action` and `context` |
-| `section_request` | Drawn sections | New content area with `description` and `placement` |
+| `section_request` | Legacy — the Annotate tab no longer emits these (sections are wireframe sketch material riding `wireframe_apply` add directions); apply per SKILL.md when present in older task files | New content area with `description` and `placement` |
 | `style_update` | Inspector style/class edits | CSS changes in `context.changes` array with `property`, `before`, `after` |
 | `theme_update` | Theme page commit | One task per commit. `context.edits[]` — each entry carries `category`, `role`, `cssVar`, `theme_variant`, `theme_selector`, `before`, `after`, `sourceFile`, `sourceLine`, `isNew`. `context.specFile` is the relative path to `.annotask/design-spec.json`; the agent patches it after applying CSS edits so the Theme page hot-reloads |
 | `a11y_fix` | A11y panel violations | WCAG fix with `rule`, `impact`, `help`, `elements` in `context` |
 | `error_fix` | Errors tab "Fix" action | Console error/warning with `level`, `occurrences`, `errorId` in `context` |
 | `perf_fix` | Perf tab "Fix" action | Performance finding with `metric`, `value`, `unit`, `severity`, `category`, `findingId` in `context` |
-| `api_update` | Data view | Backend-contract edits for in-repo data sources; `context` carries `data_source_name`, `data_source_kind`, `schema_location`, `schema_kind`, `endpoint`, and desired change metadata |
+| `wireframe_apply` | Wireframe palette ("Build this route"), design session ("Apply now"), or snapshot sketch ("Implement this wireframe") | One task per route. `context.wireframe` = `{ route, instances[] }` — each instance carries an `anchor` (`file`, `line`, `position`, `component`, `targetTag`) and an `inserted` payload. `context.session` = `{ session_id, entries[] }` — design-session edits and/or **wireframe directions** (`change.type: 'wireframe_direction'`: per-block `op` move/resize/delete/add/note, tool-`measured` geometry + relational facts, user-said `note`, anchored `file`/`line`; `add` directions may carry `added.md` — the user's VERBATIM markdown spec for a drawn section — and `added.data`, a `WireframeDataBinding` naming a REAL catalog data source with drill-down `path`/`fields` and a `shape_source` honesty tag). An "Implement this wireframe" task also carries a labeled before/after composite as its screenshot. The server snapshots the touched files first so undo/discard stays byte-exact; on `review` it verifies literal entries against source and trusts direction entries (spatial outcomes verify visually). Applied via the `WIREFRAME_APPLY.md` companion playbook. **Note:** the `added.data` data-binding path is deferred this release (gated in `src/shell/wireframeFeatures.ts`) — new tasks won't carry bindings; only legacy task files do. |
 
 ## Task Lifecycle
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5cd3cb9..cd28a03 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,82 @@
 
 All notable changes to this project are documented here. Versions follow [Semantic Versioning](https://semver.org/). Dates are ISO 8601.
 
+## [0.4.0] - 2026-06-22
+
+### Fixed
+- **Apply/undo lifecycle no longer wedges.** A crash, aborted run, server restart, orphan reconcile, or an agent that pauses at `needs_info` / is `denied` used to strand the snapshot batch as `running` and the session entries as `applying` — permanently disabling Undo, Discard, AND re-apply at once, and leaving the wireframe canvas locked at `building` forever. Every terminal transition (HTTP and the server-side orphan/boot sweep) now routes through one shared closure that seals the batch, releases the entries, and unlocks the canvas. `applyInFlight` keys off the (always-sealed) batch status, so undo/discard re-enable as soon as the agent stops.
+- **Undo is byte-exact across the agent's whole footprint.** Previously only the *predicted anchor* files were snapshotted, so the freeform agent's edits to shared layouts / imported children / global CSS were silently un-reverted. In a git project the engine now captures a pre-apply baseline (`git stash create`) and, at seal, folds every tracked file the agent actually touched into the batch (pre-apply bytes from `git show`). An agent-**deleted** file is recreated from its held bytes on undo (it used to vanish despite a held copy). Non-git projects keep anchor-only coverage with a documented limitation.
+- **Retry re-verifies.** Denying and re-running an apply now re-stamps its entries so the next review re-checks them, instead of showing the first run's stale written/failed verdicts.
+- **Anchorless wireframe blocks no longer crash the apply.** A captured block with no `data-annotask-*` ancestor (file `''`) used to mint the task and then throw in `snapshotFiles`, stranding an orphan task with no batch. Empty anchors are filtered from the snapshot set; the directions still ride the task (screenshot-anchored).
+- **`needs_info` answers reach the agent.** On resume, the seed prompt now quotes the answered clarifications inline, so a no-MCP embedded agent doesn't loop asking the same question.
+- **Cross-tab safety.** When a second tab loses the spawn race (409 `task_already_running`), it no longer reverts the *winning* tab's live run to pending — the losing run is a benign no-op.
+- **Wireframe schema migration.** `wireframe.json` now runs through a migration shim before validation, so a future schema bump (or a legacy version-less doc) upgrades in place instead of silently wiping every saved wireframe.
+
+### Changed
+- **Wireframe surface reduced for this release.** Data binding (picker, shape drill-down, prop→field map, loop repeat) and explode-to-children are gated off (`src/shell/wireframeFeatures.ts`) while the binding shape-confidence honesty ladder is reworked; existing persisted bindings still render read-only. Capture/sketch/directions and the implement loop are unchanged.
+- **Embedded-agent cost guard.** Per-USD budget caps stay out (pricing isn't portable across the local-CLI / HTTP provider matrix); the idle + max-duration watchdogs are the runaway guard. The dead `BudgetCap` module was removed and the stale 0.3.0 CHANGELOG "budget cap" wording corrected.
+- **Security disclosure.** SECURITY.md now states the out-of-box posture explicitly (no permission ceiling by default; same-origin app code can drive agents), the README gained a Security section, and the dev server prints a loud warning when it binds beyond loopback (`vite --host`).
+- Wireframe capture/enter errors surface in an app-level banner instead of flashing and vanishing when the canvas fails to mount.
+
+### CI
+- Added a secret-gated, schedule/dispatch-only `live-cli` job that runs the apply→write→verify loop against a real CLI — the per-PR suites cover the server lifecycle/undo logic deterministically.
+
+## [0.3.0] - 2026-06-17
+
+### Added
+- **Embedded local-CLI agents.** All four local agent CLIs — claude, codex, opencode, and copilot — are first-class providers, plus HTTP API providers (Anthropic, OpenAI-compatible, OpenRouter). Runs are spawned as same-port-origin-gated SSE under an `ANNOTASK_MAX_PERMISSION` ceiling with redaction, and are bounded by idle + max-duration watchdogs (per-USD caps were dropped — pricing isn't portable across the local-CLI/HTTP provider matrix); a tabbed Settings overlay configures providers, models, effort, and per-persona project directions (`.annotask/agents.json`). Per-task conversation history persists to `.annotask/conversations/<taskId>.jsonl` and stays in sync across the shell Conversation tab, MCP readers, and the terminal for every provider.
+- **Wireframing — freeze, sketch, real.** A route can be frozen into a manipulable snapshot canvas (`wireframe:capture` rasterizes the page into per-block html2canvas captures, each carrying its `data-annotask-file/-line` source anchor). The canvas supports drag (snap/align guides), 8-handle resize, marquee/shift-click multi-select with group move, arrow-key nudge, soft-delete/undelete, duplicate, undo/redo + z-index, notes, double-click explode-to-children, place-first palette-component placement with an inline configure popover (props, data binding, loop repetition, live regenerated snapshot on the app-true surface), and drawn sections (a labeled box with an optional markdown spec and a REAL data-source binding with shape drill-down). State persists per-route in `.annotask/wireframe.json` (snapshot PNGs under `.annotask/wireframe-snapshots/`, orphans GC'd at boot) and survives F5. "Implement this wireframe" diffs the sketch into anchored `wireframe_direction` entries, composes a labeled before/after, and drives the embedded agent through the apply loop.
+- **Wireframe data binding.** Components and drawn sections bind to REAL catalog data sources (`GET /api/data-source-shape`) and drill into the resolved shape — into an OpenAPI/GraphQL/tRPC response (`shape_source: 'api-schema'`), a regex-inferred return type (`'source-details'`), or honest free-text (`'none'`). The binding (`name`, `path`, `fields`, `shape_source`) rides the add direction so the agent wires the real hook instead of guessing.
+- **Design-session apply loop + byte-exact reversibility.** Design-tool edits journal to `.annotask/design-session.json`; "Apply now" snapshots every touched file BEFORE the agent runs (`.annotask/file-snapshots.json`), mints ONE `wireframe_apply` task, and the embedded agent writes the source. Accept commits the bytes; "Undo last apply" restores that batch's pre-apply bytes; "Discard session" restores every touched file to its session base — all hash-guarded so a file edited outside Annotask is never clobbered, and agent-CREATED files are netted into undo in git projects.
+- **MCP grounding tools.** `annotask_conversation_read` / `annotask_conversation_post` / `annotask_conversation_subscribe` for the per-task thread, plus `annotask_get_source_excerpt`, `annotask_get_binding_classification`, `annotask_get_data_source_*`, `annotask_get_playbook`, and `annotask_get_agent_directions` (with matching CLI commands).
+- **`scripts/sync-skills.mjs`** + `pnpm sync:skills` — `skills/` is the canonical skill tree; the `.claude/skills/`, `.agents/skills/`, and vue-webpack playground mirrors are regenerated from it, and CI fails when the mirrors drift.
+- **`src/server/validation.ts`** — canonical home for screenshot filename regex, valid task statuses, allowed status transitions, POST/PATCH field whitelists, and `agent_feedback` schema. Replaces ad-hoc duplication across the HTTP API, MCP server, and state layer.
+- **`src/server/schemas.ts`** — zod schemas for every HTTP body and MCP tool argument set. The HTTP API and MCP server now parse at the boundary via `schema.safeParse()` instead of ad-hoc type checks.
+- **`AnnotaskServer.flush()`** — drain pending task/perf writes before shutdown. `startStandaloneServer`'s `close()` is now async and flushes before closing.
+- **`scripts/copy-vendor.mjs`** — replaces the inline `cp` chain in `pnpm build:vendor`. Fails the build loudly if an upstream package renames or drops a vendored file.
+- **`src/shell/utils/routes.ts`** + **`src/shell/composables/useLocalStorageRef.ts`** — shared helpers that replace per-site `normalizeRoute` copies and `ref + watch + localStorage` triplets previously inlined in `App.vue`.
+- **`docs/REVIEWING.md`** — PR review checklist with the invariants the codebase needs to keep.
+- **`CHANGELOG.md`** (this file) and a **Release Process** section in `CONTRIBUTING.md`.
+- Optional `code` field on API error responses (keeps legacy `error: string` intact).
+- Zod (`^4.3.6`) as a runtime dependency.
+
+### Changed
+- **Tool-strip pivot.** Wireframe mode is now the single "move things" surface in Design: the Reposition tool was removed everywhere, and the Annotate tab's Draw-Section tool moved into the wireframe canvas. The legacy `component_move`, `component_prop_update`, `text_update`, and `section_request` task/change types stay documented and applicable but are no longer emitted.
+- Docs/contract drift sweep: removed the long-dead `api_update` task type from every doc that still taught it as live, documented `wireframe_apply` in every task-type list, documented the embedded-agent / wireframe / init / usage / conversation endpoint surface and new WebSocket events, and rewrote the `PERF_FIX.md` playbook to match the real perf-finding enums.
+- **BREAKING (internal):** `ProjectState.addTask/updateTask/deleteTask` are now `async`. Callers inside annotask already `await` them; any external consumer of `createProjectState` must await.
+- Task mutations serialize through a single in-process mutex (`withTaskLock`). Concurrent PATCH requests to disjoint fields of the same task no longer lose writes.
+- Screenshot unlinks (on `accepted` or delete) are chained after the successful write. A failed write no longer leaves an orphan screenshot.
+- Screenshot upload filenames use `crypto.randomBytes(8)` (16 hex chars) — no more 5-char collision window.
+- `fs.watch` on `.annotask/` no longer invalidates the task cache on our own atomic writes (tracked via `selfWriteUntil` window).
+- WebSocket server enforces a 1 MiB per-frame size cap (`maxPayload`).
+- `Cache-Control` on screenshot responses is now `private` instead of `public`.
+- `server.json` is written with mode `0o600` — other users on shared machines can no longer read the live PID + port.
+- Component scanner caches now carry a 5-minute TTL and coalesce concurrent scans through a single in-flight promise.
+- MCP batch dispatch isolates per-item exceptions so one bad request no longer truncates the response array.
+- MCP `annotask_update_task` runs new `agent_feedback` entries through the shared zod schema instead of a tool-local duplicate.
+- MCP server version is baked from `package.json` at build time (`__ANNOTASK_VERSION__`) instead of a hardcoded value.
+- `iframeBridge` no longer posts to `targetOrigin='*'`. The shell derives the iframe's origin and refuses to send until it knows a concrete origin. Request IDs are now monotonic.
+- `useAnnotationRects` and `useSelectionModel` rAF loops skip work while `document.hidden` is true.
+- `useErrorMonitor` caps its buffer at 256 entries; `usePerfMonitor.perfFindings` caps at 128 (worst severities kept).
+- `package.json`: added `"sideEffects": false` (tree-shaking); excluded sourcemaps from the published tarball; pinned `axe-core` and `html2canvas-pro` to exact versions since both are vendored into `dist/vendor/`.
+
+### Fixed
+- **Wireframe apply lifecycle — data-loss races.** "Undo last apply" and "Discard session" are now inert while an apply run is in flight (the snapshot engine also refuses a still-running, unsealed batch), so a one-click revert can no longer clobber the agent's in-progress bytes. The batch now (re-)seals by task on every `review`, so re-apply-after-deny and pure-placement applies establish a correct undo baseline instead of falsely reporting "edited outside Annotask". A crashed/aborted seed run now seals its batch `failed` and returns its session entries to `pending` instead of stranding them in `applying`.
+- **XSS hardening.** The Conversation surface and agent-directions preview render model/user markdown through the shared `safeMd()` (DOMPurify) helper instead of raw `marked.parse()` + `v-html`.
+- Cumulative token counter no longer double-counts across turns (each persisted message holds exactly its own turn).
+- Wireframe live preview no longer silently degrades to a placeholder when a binding maps a nested object/array field — overlay props are plain-cloned before crossing `postMessage` (`DataCloneError`).
+- Dev server tolerates a wrong-shape `tasks.json` instead of crashing on boot.
+
+### Removed
+- `src/shell/composables/useThemeMode.ts` — the deprecated wrapper around `useShellTheme` was unused at any call site.
+
+### Security
+- All `/__annotask/*` requests are Host-gated against non-local hostnames. Agent spawn routes additionally enforce same-port origin matching (`origin_port_mismatch`) and the server-side `ANNOTASK_MAX_PERMISSION` permission ceiling so a page on another localhost port cannot spawn credential-bearing CLIs, and no client can request more permission than the admin allows.
+- `annotask_get_screenshot` MCP tool now routes `task.screenshot` through `isSafeScreenshot` before path construction, closing a path-traversal hole.
+
+### Breaking
+- **API error shape.** Responses now use `{ error: { code, message } }` instead of a bare `error: string`. `PATCH`/`DELETE` on a missing task now returns HTTP 404 (previously 200 with a magic `{error: 'Task not found'}` string).
+
 ## [0.2.6] - 2026-04-23
 
 ### Fixed
@@ -58,55 +134,3 @@ All notable changes to this project are documented here. Versions follow [Semant
 ## [0.1.0] - 2026-04-17
 
 Initial public release.
-
-## [Unreleased]
-
-### Added
-- **`src/server/validation.ts`** — canonical home for screenshot filename regex, valid task statuses, allowed status transitions, POST/PATCH field whitelists, and `agent_feedback` schema. Replaces ad-hoc duplication across the HTTP API, MCP server, and state layer.
-- **`src/server/schemas.ts`** — zod schemas for every HTTP body and MCP tool argument set. The HTTP API and MCP server now parse at the boundary via `schema.safeParse()` instead of ad-hoc type checks.
-- **`AnnotaskServer.flush()`** — drain pending task/perf writes before shutdown. `startStandaloneServer`'s `close()` is now async and flushes before closing.
-- **`scripts/copy-vendor.mjs`** — replaces the inline `cp` chain in `pnpm build:vendor`. Fails the build loudly if an upstream package renames or drops a vendored file.
-- **`src/shell/utils/routes.ts`** + **`src/shell/composables/useLocalStorageRef.ts`** — shared helpers that replace per-site `normalizeRoute` copies and `ref + watch + localStorage` triplets previously inlined in `App.vue`.
-- **`docs/REVIEWING.md`** — PR review checklist with the invariants the codebase needs to keep.
-- **`CHANGELOG.md`** (this file) and a **Release Process** section in `CONTRIBUTING.md`.
-- Unit tests for `createProjectState` (concurrent PATCH, concurrent delete+update, screenshot cleanup, path-traversal refusal, disk round-trip), every `validation.ts` export, and `normalizeRoute`. Test count: 128 → 160.
-- Optional `code` field on API error responses (keeps legacy `error: string` intact).
-- Zod (`^4.3.6`) as a runtime dependency.
-
-### Changed
-- **BREAKING (internal):** `ProjectState.addTask/updateTask/deleteTask` are now `async`. Callers inside annotask already `await` them; any external consumer of `createProjectState` must await.
-- Task mutations serialize through a single in-process mutex (`withTaskLock`). Concurrent PATCH requests to disjoint fields of the same task no longer lose writes.
-- Screenshot unlinks (on `accepted` or delete) are chained after the successful write. A failed write no longer leaves an orphan screenshot.
-- Screenshot upload filenames use `crypto.randomBytes(8)` (16 hex chars) instead of `Math.random().toString(36).slice(2,7)` — no more 5-char collision window.
-- `fs.watch` on `.annotask/` no longer invalidates the task cache on our own atomic writes (tracked via `selfWriteUntil` window).
-- WebSocket server enforces a 1 MiB per-frame size cap (`maxPayload`).
-- `Cache-Control` on screenshot responses is now `private` instead of `public`.
-- `server.json` is written with mode `0o600` — other users on shared machines can no longer read the live PID + port.
-- Component scanner caches now carry a 5-minute TTL and coalesce concurrent scans through a single in-flight promise.
-- MCP batch dispatch isolates per-item exceptions so one bad request no longer truncates the response array.
-- MCP `annotask_update_task` runs new `agent_feedback` entries through the shared zod schema instead of a tool-local duplicate.
-- MCP server version is baked from `package.json` at build time (`__ANNOTASK_VERSION__`) instead of a hardcoded `'0.0.29'`.
-- `iframeBridge` no longer posts to `targetOrigin='*'`. The shell derives the iframe's origin from `iframe.src`/`contentWindow.location.origin` and refuses to send until it knows a concrete origin. Request IDs are now monotonic.
-- `useAnnotationRects` and `useSelectionModel` rAF loops skip work while `document.hidden` is true.
-- `useErrorMonitor` caps its buffer at 256 entries (oldest discarded, dedup keys tracked).
-- `usePerfMonitor.perfFindings` caps at 128 entries (worst severities kept).
-- `package.json`: added `"sideEffects": false` (tree-shaking); excluded sourcemaps from the published tarball; pinned `axe-core` and `html2canvas-pro` to exact versions since both are vendored into `dist/vendor/`.
-- `.gitignore`: ignores `.claude/worktrees/`.
-
-### Removed
-- `src/shell/composables/useThemeMode.ts` — the deprecated wrapper around `useShellTheme` was unused at any call site.
-
-### Security
-- `annotask_get_screenshot` MCP tool now routes `task.screenshot` through `isSafeScreenshot` before path construction, closing a path-traversal hole for maliciously constructed task records.
-- Added `originMatchesPort` helper for endpoints that want a stricter same-port origin check (available for future hardening; not wired by default since the shell can be served from a different port than the user's app).
-
-### Breaking
-
-- **API error shape.** Responses now use `{ error: { code, message } }` instead of a bare `error: string`. The `code` is one of `invalid_json`, `body_too_large`, `body_not_object`, `validation_failed`, `invalid_transition`, `forbidden_origin`, `not_found`. `PATCH`/`DELETE` on a missing task now returns HTTP 404 (previously 200 with a magic `{error: 'Task not found'}` string). The CLI and API tests have been updated accordingly.
-
-### Extracted
-
-- `src/shell/composables/useChangeHistory.ts` — `doUndo`, `doClearChanges`, `commitChangesAsTask`, and `selectionChanges` moved out of `App.vue`. App.vue is now 2012 lines (from 2142 at the start of the cleanup).
-- `src/shell/components/PerfFindingDetail.vue` + `PerfResourceTables.vue` — pulled out of `PerfTab.vue`, which is now 199 lines (from 463).
-- `src/shell/components/TaskAgentFeedback.vue`, `TaskInteractionHistory.vue`, `TaskJsonView.vue` — pulled out of `TaskDetailModal.vue`, which is now 791 lines (from 966).
-- `src/shell/components/ThemeLibrariesTab.vue`, `ThemeAddTokenForm.vue` — pulled out of `ThemePage.vue`, which is now 819 lines (from 865). The add-token form, previously duplicated 5× with minor placeholder variations, is now one component reused across colors / families / scale / spacing / radius.
diff --git a/CLAUDE.md b/CLAUDE.md
index bd8fee6..48e4b08 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -29,6 +29,13 @@ Annotask includes an MCP server that starts automatically with the dev server at
 | `annotask_get_api_schemas` | List discovered OpenAPI, GraphQL, tRPC, and JSON Schema sources |
 | `annotask_get_api_operation` | Fetch one API operation by path |
 | `annotask_resolve_endpoint` | Match a concrete URL to a known API operation |
+| `annotask_get_source_excerpt` | Direct source excerpt by file/line (no task required) |
+| `annotask_get_binding_classification` | Round-trip-honesty classification of one element by file/line[/tag]: per-prop literal/bound/unknown, text kind, enclosing loop |
+| `annotask_get_playbook` | Fetch a task-type companion playbook (A11Y_RULES, THEME_UPDATE, ERROR_FIX, PERF_FIX, WIREFRAME_APPLY) |
+| `annotask_get_agent_directions` | Fetch per-persona project directions from `.annotask/agents.json` |
+| `annotask_conversation_read` | Read a task's conversation thread (optional `after_id` for cheap polling) |
+| `annotask_conversation_post` | Append a message to a task's conversation thread (role: user/assistant/system/tool) |
+| `annotask_conversation_subscribe` | Long-poll for new conversation messages after `after_id` |
 
 ### Applying tasks via MCP
 
@@ -70,6 +77,10 @@ annotask screenshot <id>     # Download a task's screenshot
 annotask components [search] # List components (add --mcp for JSON)
 annotask component <Name>    # Show component props
 annotask code-context <id>   # Ground task to current source excerpt
+annotask source-excerpt <file> <line>  # Direct source excerpt by file/line
+annotask binding-classify --file=F --line=N [--tag=T]  # literal/bound/loop honesty classification
+annotask playbook <task-type>  # Print a task-type companion playbook
+annotask agent-directions [persona]  # Per-persona project directions
 annotask component-examples Button # Real in-repo component usage examples
 annotask data-context <id>   # Resolve task data context
 annotask interaction-history <id>  # Pre-task user trace (always captured, embed toggle decides payload inclusion)
@@ -107,27 +118,60 @@ Options: `--port=N`, `--host=H`, `--server=URL` (override server.json),
 - `DELETE /__annotask/api/tasks/:id` — Delete a task and its screenshot
 - `GET /__annotask/api/design-spec` — Design spec (tokens, framework, breakpoints)
 - `GET /__annotask/api/components` — Component library catalog
+- `GET /__annotask/api/project-components` — The project's own `src/` components as a "Project" library (pinned first in the palette)
 - `GET /__annotask/api/component-usage` — Project component usage index
 - `GET /__annotask/api/component-examples/:name` — In-repo component usage examples
 - `GET /__annotask/api/code-context/:taskId` — Ground task to current source context
 - `GET /__annotask/api/source-excerpt` — Direct source excerpt by file/line
+- `GET /__annotask/api/binding-classify` — Round-trip honesty classification for one element (`?file&line&tag?`): per-prop literal/bound/unknown, text literal/bound/mixed, enclosing loop — agent grounding before rewriting props/text
 - `GET /__annotask/api/data-context/:taskId` — Stored or resolved task data context
 - `GET /__annotask/api/data-context/probe|resolve|element` — Shell data-context helpers
 - `GET /__annotask/api/data-sources` — Project data-source catalog (add `?include_runtime=true` to append the runtime-observed endpoint catalog)
 - `GET|POST|DELETE /__annotask/api/runtime-endpoints` — Runtime-observed endpoint catalog. Iframe fetch/XHR/beacon calls land here automatically. `GET ?merge_static=true` enriches rows with matching static sources + OpenAPI operations; `GET ?route=PATH` filters to one iframe route
 - `GET /__annotask/api/data-source-examples/:name` — In-repo data-source usage examples
 - `GET /__annotask/api/data-source-details/:name` — Definition-level data-source detail
+- `GET /__annotask/api/data-source-shape` — Shape resolution for the wireframe binding picker (`?name&kind&file`): walks the source's endpoint into a real API-schema tree (`shape_source: 'api-schema'`), falls back to regex return-type hints (`'source-details'`), or honestly nothing (`'none'`). Shell-only — agents re-ground via data-source-details / api-operation
 - `GET /__annotask/api/data-source-bindings/:name` — Binding graph for highlights
 - `GET /__annotask/api/api-schemas` — API schema catalog
 - `GET /__annotask/api/api-operation` — One API operation by path
 - `GET /__annotask/api/resolve-endpoint` — Resolve a concrete URL to a known operation
 - `GET|POST /__annotask/api/tasks/:id/interaction-history` — Per-task user-trace sidecar (always written on task create; embed toggle only gates inclusion in the task payload)
 - `GET|POST /__annotask/api/tasks/:id/rendered-html` — Per-task `outerHTML` sidecar (always written when a selection exists; 200 KB cap)
+- `GET /__annotask/api/agent-configs` — Per-persona project directions (`{ version, agents: { [personaId]: { projectDirections } } }`)
+- `PATCH /__annotask/api/agent-configs/:id` — Update one persona's `projectDirections`, `providerId`, `model`, or `effort`
+- `GET|PUT /__annotask/api/wireframe` — Multi-route wireframe document (`?route=PATH` slices one route; persists to `.annotask/wireframe.json`). Each route carries `instances[]` (palette placements) and an optional `canvas` (the snapshot-wireframe sketch: per-block captures with source anchors, transforms, notes, soft-deletes)
+- `POST /__annotask/api/wireframe-snapshots` — Upload a canvas block PNG (`{id, data}`; id-addressed, 4MB cap; persists to `.annotask/wireframe-snapshots/`)
+- `GET /__annotask/wireframe-snapshots/:filename` — Serve a canvas snapshot PNG (containment-guarded)
+- `DELETE /__annotask/api/wireframe-snapshots/:filename` — Drop a canvas snapshot PNG
+- `GET|PUT|DELETE /__annotask/api/design-session` — Design-session journal (ordered record of design-tool edits; CAS on `rev`, 409 on stale writes; persists to `.annotask/design-session.json`). DELETE = server-owned discard: clears the journal, removes session-created wireframe placements, and drops every route's canvas sketch (+ its snapshot PNGs)
+- `POST /__annotask/api/design-session/apply` — "Apply now" / "Implement this wireframe": snapshots the touched files, mints ONE `wireframe_apply` task (placements + design-session edits/directions in `context.session`; optional `screenshot` = the before/after composite), stamps statuses; the shell then runs the embedded agent on it. The agent writes source — the tool never does
+- `POST /__annotask/api/design-session/undo-batch` — Restore the newest apply batch's pre-apply bytes (hash-guarded; entries return to pending)
+- `POST /__annotask/api/design-session/detach-file` — Diverged-file resolution: keep the disk bytes, drop the file from the session
+- `GET /__annotask/api/design-session/snapshots` — Snapshot-engine state (touched files, divergence, apply batches) — persists to `.annotask/file-snapshots.json`; rehydrates across restarts (files revert only via explicit undo/discard)
+- `POST /__annotask/api/agent/spawn` — Spawn an allow-listed local CLI as SSE (same-port origin gate; `ANNOTASK_MAX_PERMISSION` ceiling)
+- `DELETE /__annotask/api/agent/spawn/:runId` — Abort a running spawn
+- `GET /__annotask/api/agent/detect` — Detect installed/logged-in local CLIs
+- `GET /__annotask/api/agent/models` — Per-provider model catalog (`?cli=ID`, `?refresh=1`)
+- `GET|POST /__annotask/api/tasks/:id/messages` — Per-task conversation thread (JSONL at `.annotask/conversations/<id>.jsonl`)
+- `GET /__annotask/api/tasks/:id/messages/stream` — Conversation SSE stream (honours `Last-Event-ID`)
+- `PATCH /__annotask/api/tasks/:id/messages/:msgId` — Update a message in place (partial-turn streaming)
+- `GET /__annotask/api/usage` — Aggregate token-usage summary from `.annotask/usage.jsonl`
+- `GET /__annotask/api/usage/recent` — Recent usage entries (`?limit=N`)
+- `GET /__annotask/api/init/state` — Init-runner state
+- `GET /__annotask/api/init/scan-targets` — Existence + mtime of durable scan artifacts
+- `POST /__annotask/api/init/start` — Start an init scan (skip flags, provider/model/effort)
+- `POST /__annotask/api/init/cancel` — Cancel a running scan
+- `POST /__annotask/api/init/skip` — Mark initialized without committing token data
+- `POST /__annotask/api/init/commit` — Commit reviewed spec (and optional style guide)
+- `GET /__annotask/api/system-prompt` — Composed embedded-agent system prompt (`?task_type=` adds the companion playbook)
+- `GET /__annotask/api/style-guide` — Contents of `.annotask/STYLE_GUIDE.md`
+- `GET /__annotask/api/read-file` — Read one project file by relative `?path=` (traversal-guarded)
+- `DELETE /__annotask/api/session-reset` — Clear the `.session-reset` sentinel after the shell wipes localStorage
 - `GET|POST /__annotask/api/performance` — Performance snapshots
 - `POST /__annotask/api/screenshots` — Upload a screenshot
 - `GET /__annotask/screenshots/:filename` — Serve a screenshot
 - `GET /__annotask/api/status` — Health check
-- `ws://localhost:5173/__annotask/ws` — Live WebSocket stream
+- `ws://localhost:5173/__annotask/ws` — Live WebSocket stream (events include `tasks:updated`, `components:updated`, `init:progress`, `runtime-endpoints:updated`, `wireframe:updated`, `session:updated`)
 
 Use `/annotask-apply` to fetch and apply pending visual changes to source code.
 
@@ -155,14 +199,14 @@ The shell has **3 top-level tabs** (see `useShellNavigation.ts`):
 |-----|-------------|--------------|
 | **Annotate** | `editor` | — (pins, arrows, sections, highlights) |
 | **Design** | `design` | `tokens` / `inspector` / `components` |
-| **Audit** | `develop` | `a11y` / `data` / `libraries` / `perf` / `errors` |
+| **Audit** | `develop` | `a11y` / `data` / `perf` / `errors` |
 
 The "Audit" tab uses internal id `develop` (the label was renamed but the id was kept to avoid a breaking localStorage migration). Tab state lives in `useShellNavigation` (`shellView`, `designSection`, `developSection`, `activePanel`), persisted to localStorage and migrated from legacy ids (`theme`, `components`, `data`, `perf`, `a11y`) on first run.
 
 `App.vue` is the shell orchestrator — it wires composables together and handles bridge events. **Do not add business logic directly to App.vue.** Extract new concerns into composables under `src/shell/composables/`.
 
 Key composables:
-- `useShellTheme` — Theme system: 63 CSS variables, 18 built-in themes, custom theme CRUD, system preference, localStorage persistence
+- `useShellTheme` — Theme system: 62 CSS variables, 18 built-in themes, custom theme CRUD, system preference, localStorage persistence
 - `useSelectionModel` — Element selection state, rect tracking, hover, live styles, style/class change handlers
 - `useTaskWorkflows` — Task creation flows (pin, arrow, highlight, section → task), pending task panel, accept/deny, annotation restoration, auto-opens task panel on create
 - `useAnnotationRects` — rAF loop keeping annotation overlays positioned during scroll/resize
@@ -176,20 +220,20 @@ When adding new shell features, create a new composable that accepts its depende
 
 ## Shell Theme System
 
-The shell has a VS Code-style theme system with 18 built-in themes and custom theme support. Themes control every color in the UI via 63 CSS custom properties.
+The shell has a VS Code-style theme system with 18 built-in themes and custom theme support. Themes control every color in the UI via 62 CSS custom properties.
 
 ### Architecture
 
-- `src/shell/themes/types.ts` — `ShellThemeColors` (63 vars), `ShellTheme` interface, `THEME_COLOR_KEYS` array
+- `src/shell/themes/types.ts` — `ShellThemeColors` (62 vars), `ShellTheme` interface, `THEME_COLOR_KEYS` array
 - `src/shell/themes/builtin.ts` — 18 built-in theme definitions with `deriveDefaults()` helper
 - `src/shell/composables/useShellTheme.ts` — Core composable: applies themes at runtime via `style.setProperty()`, handles localStorage persistence, system preference detection, custom theme CRUD, and a one-shot migration from the legacy `annotask:themeMode` key
 - `src/shell/components/ShellThemeEditor.vue` — Full-screen custom theme creator with grouped color pickers and live preview
 
 ### How themes are applied
 
-Themes are applied at runtime via `document.documentElement.style.setProperty()` for each of the 63 CSS variables. The `:root` block in App.vue provides dark fallback values, and `:root.light` provides light fallback values — these are safety nets for first paint before JS runs. Once `useShellTheme` initializes, it overrides all variables via inline styles.
+Themes are applied at runtime via `document.documentElement.style.setProperty()` for each of the 62 CSS variables. The `:root` block in App.vue provides dark fallback values, and `:root.light` provides light fallback values — these are safety nets for first paint before JS runs. Once `useShellTheme` initializes, it overrides all variables via inline styles.
 
-### CSS variable categories (63 total)
+### CSS variable categories (62 total)
 
 | Category | Variables | Purpose |
 |----------|-----------|---------|
@@ -202,7 +246,7 @@ Themes are applied at runtime via `document.documentElement.style.setProperty()`
 | Utility (2) | `--overlay`, `--shadow` | Overlays and shadows |
 | Status (7) | `--status-pending`, `--status-in-progress`, `--status-review`, `--status-denied`, `--status-accepted`, `--status-needs-info`, `--status-blocked` | Task lifecycle |
 | Severity (4) | `--severity-critical`, `--severity-serious`, `--severity-moderate`, `--severity-minor` | A11y/perf findings |
-| Modes (4) | `--mode-interact`, `--mode-arrow`, `--mode-draw`, `--mode-highlight` | Tool button active states |
+| Modes (3) | `--mode-interact`, `--mode-arrow`, `--mode-highlight` | Tool button active states |
 | Layout (2) | `--layout-flex`, `--layout-grid` | Layout visualization |
 | Roles (3) | `--role-container`, `--role-content`, `--role-component` | Element classification |
 | Syntax (7) | `--syntax-property`, `--syntax-string`, `--syntax-number`, `--syntax-boolean`, `--syntax-null`, `--syntax-operator`, `--syntax-punctuation` | Code highlighting |
@@ -258,13 +302,14 @@ Users create custom themes via Settings > Appearance > "+ Create Custom Theme".
 
 ## Key Shell Features
 
+- **Wireframe mode** — Freezes the current route into a manipulable image canvas: `wireframe:capture` rasterizes the page into per-block html2canvas snapshots (each carrying its `data-annotask-file/-line` source anchor), the canvas supports drag (snap/align guides; Alt disables), 8-handle resize, marquee/shift-click multi-select with group move, arrow-key nudging (Shift = 10px), soft-delete/undelete, duplicate, notes, double-click explode-to-children (re-captures one block a level deeper with per-child anchors), palette-drop component snapshots through a generate panel (pick → settings → optional data binding → honest preview snapshot on the app-true surface → place; gear button reconfigures in place), and drawn sections (a labeled box, optionally with a markdown spec and a data-source binding picked from the REAL catalog with shape drill-down). State persists per-route in `wireframe.json` (PNGs in `.annotask/wireframe-snapshots/`, orphans GC'd at boot) and survives F5; capturing under a viewport preset wireframes that device width. "Implement this wireframe" diffs the sketch against the original capture into anchored `wireframe_direction` entries (relations like "now above the filters" are the contract; pixels are hints), composes a labeled before/after screenshot, and runs the embedded agent through the apply loop — accept/undo/discard ride the file-snapshot engine, and in git projects agent-CREATED files are netted into the undo batch (hash-guarded deletion). The live iframe stays mounted under the canvas, so exit is lossless. **NOTE (current release): data-source binding and double-click explode-to-children are gated OFF via `src/shell/wireframeFeatures.ts` — the code paths and persisted bindings remain (render read-only), but the UI entry points are hidden and new tasks won't carry bindings/exploded containers.**
 - **Viewport preview** — Device presets + custom dimensions, viewport info included in tasks/reports
 - **Interaction history** — Tracks user navigation and clicks. Always captured and persisted per task to `.annotask/interaction-history/<id>.json`; the "Embed interaction history" toggle only decides whether it rides in the task payload. Agents retrieve via `annotask_get_interaction_history` when unembedded
 - **Element context / rendered HTML** — Post-render `outerHTML` of the selected element. Always captured and persisted per task to `.annotask/rendered-html/<id>.json` (200 KB cap); the "Embed rendered HTML" toggle only decides payload inclusion. Agents retrieve via `annotask_get_rendered_html`
 - **A11y checker** — axe-core WCAG scanning with one-click fix task creation (locally bundled, no CDN)
 - **Error monitoring** — Console error/warn capture with deduplication, bounded memory, one-click fix tasks
 - **Performance monitoring** — Web Vitals, DOM/resource/bundle analysis, interaction recording, perf score, one-click fix tasks
-- **Data view** — Discovered data sources, schema matching, page highlights, and `api_update` task creation
+- **Data view** — Discovered data sources, schema matching, page highlights
 - **Screenshots** — Snipping tool captures regions or full page, attached to tasks, served via API, auto-cleaned on accept (max 4MB)
 - **Task detail drawer** — Slide-out detail view with markdown rendering, inline editing, screenshot lightbox, element/file display, interaction log, JSON view, delete button
 - **Task lifecycle** — `pending → in_progress → review → accepted/denied` with `needs_info` (agent asks questions) and `blocked` (agent can't apply) statuses, resolution messages, live status updates
@@ -273,7 +318,6 @@ Users create custom themes via Settings > Appearance > "+ Create Custom Theme".
 - **Async I/O** — In-memory task cache with atomic file writes (no race conditions)
 - **Inspector highlights** — Selection/hover overlays that track scroll and resize via rAF loop
 - **Arrow tool** — Multi-color arrows with element outlines, edge-to-edge bezier paths, draggable endpoints, element-aware re-resolution on move, scroll/resize tracking via rAF
-- **Section tool** — Markdown editor (edit/preview toggle), dark theme, movable/resizable sections with drag handles, explicit "Add Task" / "Update Task" button
 - **Text highlights** — Multi-color highlights with visual overlay on selected text, sidebar task creation with preloaded text
 - **Scroll/resize tracking** — All annotations (arrows, highlights, sections) follow elements during scroll and window resize via rAF loop, same pattern as inspector selections
 - **Route persistence** — Iframe route saved to localStorage, restored on page reload
@@ -288,13 +332,13 @@ Canonical list — `TASK_TYPES` in `src/schema.ts` is the single source of truth
 | Type | Source | Description |
 |------|--------|-------------|
 | `annotation` | Pins, arrows, notes, text highlights | User intent described in `description`, optional `action` and `context` |
-| `section_request` | Drawn sections | New content area with `description` and `placement` |
-| `style_update` | Inspector style/class edits | CSS changes in `context.changes` array with `property`, `before`, `after` |
+| `section_request` | Legacy — the Annotate tab no longer emits these (sections are wireframe sketch material riding `wireframe_apply` add directions); apply per SKILL.md when present in older task files | New content area with `description` and `placement` |
+| `style_update` | Inspector style/class edits | `context.changes` array: CSS changes (`property`, `before`, `after`) and class changes. Legacy `component_prop_update`/`text_update` entries may appear in tasks minted before the snapshot-wireframe pivot — apply them per the SKILL.md rules when present |
 | `theme_update` | Theme page commit | One task per commit. `context.edits[]` — each entry carries `category`, `role`, `cssVar`, `theme_variant`, `theme_selector` (how that variant is activated in the DOM — attribute/class/media/default), `before`, `after`, `sourceFile`, `sourceLine`, `isNew`. `context.specFile` is the relative path to `.annotask/design-spec.json`; the agent patches it after applying CSS edits so the Theme page hot-reloads. |
 | `a11y_fix` | A11y panel violations | WCAG fix with `rule`, `impact`, `help`, `elements` in `context` |
 | `error_fix` | Errors tab "Fix" action | Console error/warning with `level`, `occurrences`, `errorId` in `context` |
 | `perf_fix` | Perf tab "Fix" action | Performance finding with `metric`, `value`, `unit`, `severity`, `category`, `findingId` in `context` |
-| `api_update` | Data view | Backend-contract edits for in-repo data sources; `context` carries `data_source_name`, `data_source_kind`, `schema_location`, `schema_kind`, `endpoint`, and desired change metadata |
+| `wireframe_apply` | Wireframe palette ("Build this route"), design session ("Apply now"), or snapshot sketch ("Implement this wireframe") | One task per route. `context.wireframe` = `{ route, instances[] }` — each instance carries an `anchor` (`file`, `line`, `position`, `component`, `targetTag`) and an `inserted` payload. `context.session` = `{ session_id, entries[] }` — design-session edits and/or **wireframe directions** (`change.type: 'wireframe_direction'`: per-block `op` move/resize/delete/add/note, tool-`measured` geometry + relational facts, user-said `note`, anchored `file`/`line`; `add` directions may carry `added.md` — the user's VERBATIM markdown spec for a drawn section — and `added.data`, a `WireframeDataBinding` naming a REAL catalog data source with drill-down `path`/`fields` and a `shape_source` honesty tag). An "Implement this wireframe" task also carries a labeled before/after composite as its screenshot. The server snapshots the touched files first so undo/discard stays byte-exact; on `review` it verifies literal entries against source and trusts direction entries (spatial outcomes verify visually). Applied via the `WIREFRAME_APPLY.md` companion playbook. |
 
 ## Task Lifecycle
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8d580c5..cc05062 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -90,7 +90,9 @@ Current change types in live reports:
 Schema-only experimental change types still present in the contract:
 
 - `scoped_style_update`
-- `prop_update`
+- `component_prop_update`
+- `text_update`
+- `wireframe_direction`
 - `component_delete`
 
 Current task types:
@@ -102,7 +104,7 @@ Current task types:
 - `a11y_fix`
 - `error_fix`
 - `perf_fix`
-- `api_update`
+- `wireframe_apply`
 
 Current statuses:
 
diff --git a/README.md b/README.md
index e4b566a..65fe35e 100644
--- a/README.md
+++ b/README.md
@@ -45,11 +45,38 @@ Review in the task drawer        <--> Answers questions / retries denied work
 Accept or deny changes
 ```
 
+The coding agent can be **external** (your editor's agent, reading tasks over MCP/CLI/HTTP) or **embedded** — see below.
+
+## Embedded agents
+
+Annotask can run a coding agent in-shell. Point it at a local CLI (claude, codex,
+opencode, copilot) or an HTTP provider (Anthropic, OpenAI-compatible, OpenRouter)
+in Settings, and the agent applies tasks without leaving the browser. Runs stream
+into a per-task conversation thread (persisted to `.annotask/conversations/`),
+are gated to the same origin/port, respect an optional `ANNOTASK_MAX_PERMISSION`
+ceiling, and are bounded by idle/duration watchdogs. The agent — never the tool —
+writes application source.
+
+## Wireframing
+
+Freeze the current route into a manipulable snapshot canvas, then sketch: drag,
+resize, multi-select and nudge, soft-delete, duplicate, drop palette components
+(configured in place with props), and draw sections with a markdown spec. Hit **Implement
+this wireframe** and Annotask diffs the sketch into anchored directions, snapshots
+every file it touches, and drives the embedded agent through the apply loop —
+spatial relations are the contract, pixels are hints. **Undo last apply**
+restores that batch's pre-apply bytes and **Discard session** restores every
+touched file to its session base, both hash-guarded so a file you edited
+outside Annotask is never clobbered. In git projects the reversal is byte-exact
+across the whole apply footprint — the engine baselines off `git stash-create`,
+auto-extends via `git show`, and recreates agent-deleted files — while non-git
+projects fall back to reverting the predicted anchor files only.
+
 ## What it does
 
 Annotask has three user-facing surfaces.
 
-- **Annotate**: pins, arrows, drawn sections, text highlights, screenshots, route-aware tasks, viewport capture.
+- **Annotate**: pins, arrows, text highlights, screenshots, route-aware tasks, viewport capture. (Sections are wireframe sketch material — draw them on the wireframe canvas.)
 - **Design**: tokens, live inspector, layout overlay, detected component catalogs, in-repo component examples.
 - **Audit**: accessibility, data sources, API schemas, detected data/state libraries, performance findings, console errors.
 
@@ -110,8 +137,8 @@ npx annotask init-skills
 
 ## Agent surfaces
 
-- **MCP**: `POST /__annotask/mcp` with 21 tools for tasks, design spec, components, screenshots, code context, data context, data sources, API schemas, runtime endpoints, interaction history, and rendered HTML.
-- **CLI**: `annotask status`, `tasks`, `task`, `design-spec`, `components`, `component-examples`, `data-context`, `data-sources`, `runtime-endpoints`, `interaction-history`, `rendered-html`, `api-schemas`, `resolve-endpoint`, `init-mcp`, `init-skills`, `mcp`, and more.
+- **MCP**: `POST /__annotask/mcp` with 28 tools for tasks, design spec, components, screenshots, code context, data context, data sources, API schemas, runtime endpoints, interaction history, rendered HTML, playbooks, and per-task conversations.
+- **CLI**: `annotask status`, `tasks`, `task`, `design-spec`, `components`, `component-examples`, `data-context`, `data-sources`, `runtime-endpoints`, `interaction-history`, `rendered-html`, `api-schemas`, `resolve-endpoint`, `source-excerpt`, `playbook`, `agent-directions`, `init-mcp`, `init-skills`, `mcp`, and more.
 - **HTTP + WebSocket**: local API under `/__annotask/api/*` and live updates on `/__annotask/ws`.
 
 ## Task model
@@ -125,7 +152,7 @@ Canonical task types live in `src/schema.ts`:
 - `a11y_fix`
 - `error_fix`
 - `perf_fix`
-- `api_update`
+- `wireframe_apply` — wireframe palette placements ("Build this route"); `context.wireframe` carries `{ route, instances[] }` with a per-instance `anchor` (`file`, `line`, `position`, `component`, `targetTag`) and `inserted` payload (`tag`, `componentName`, `library`, `module`, `props`, `classes`, `text_content`)
 
 Statuses:
 
@@ -150,6 +177,8 @@ pending -> in_progress -> review -> accepted | denied
 
 ## Current highlights
 
+- Embedded agent mode — apply tasks in-shell via a local CLI or HTTP provider, with a per-task conversation thread
+- Snapshot wireframing with byte-exact, hash-guarded undo/discard of every agent apply
 - Route-aware task filtering and editable route bar
 - Screenshot uploads and automatic cleanup on acceptance
 - Variant-aware design spec with `themes[]`, `defaultTheme`, and per-theme token values
@@ -163,7 +192,7 @@ pending -> in_progress -> review -> accepted | denied
 - Performance snapshots, findings, and session recording
 - Console error and warning capture with one-click fix tasks
 - Always-captured interaction history and rendered-HTML sidecars per task
-- 18 built-in shell themes plus custom theme editing across 63 CSS variables
+- 18 built-in shell themes plus custom theme editing across 62 CSS variables
 
 ## Framework support
 
@@ -179,6 +208,16 @@ pending -> in_progress -> review -> accepted | denied
 
 Annotask is dev-only. It does not run in production builds.
 
+## Security
+
+Annotask runs an **unauthenticated** dev API on your local server, and the embedded agent can write source files and run shell commands at your project root. By default there is no permission ceiling. Treat it like any other local dev tool:
+
+- Run it only on code (and dependencies) you trust — same-origin app code can reach the API.
+- Don't expose the dev server beyond `localhost`. `vite --host` opens it to your LAN; prefer an SSH tunnel, and Annotask prints a loud warning when it binds non-loopback.
+- In shared / CI / locked-down setups, set `ANNOTASK_MAX_PERMISSION=plan` (read-only) or `default` to cap what a spawned agent can do.
+
+See [SECURITY.md](./SECURITY.md) for the full model.
+
 ## Monorepos and MFEs
 
 Annotask is workspace-aware. When the project lives inside a pnpm, npm, Yarn, Bun, or Lerna workspace, server-side scanners can walk sibling packages for:
diff --git a/SECURITY.md b/SECURITY.md
index 560a659..31cbf88 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -21,6 +21,17 @@ Annotask assumes a **trusted local environment**: the developer's machine, runni
 - **Screenshot file names:** uploads use `crypto.randomBytes(8)` filenames (16 hex chars). The `annotask_get_screenshot` MCP tool also routes `task.screenshot` through `isSafeScreenshot` before touching the filesystem, closing a path-traversal hole for maliciously constructed task records.
 - **`server.json` permissions:** written with mode `0o600` so other users on shared machines cannot read the live PID and port.
 
+### Localhost threat model and embedded agents
+
+Any code running on the same machine — including the app being developed, its dependencies, and any other page served from `localhost` — shares the trust boundary with Annotask. In particular, same-origin app code can reach the Annotask API, including the agent spawn endpoint, since it runs on the same dev server. The mitigations are layered, not absolute:
+
+- **Spawn routes are same-port-origin-gated.** `POST /api/agent/spawn` and `DELETE /api/agent/spawn/:runId` require the request `Origin` to match the server's own port (`origin_port_mismatch` otherwise), so a page on a *different* localhost port cannot spawn CLIs that have credential access. A page on the *same* origin still can — that is inherent to running an unauthenticated dev tool inside the app's own server.
+- **`ANNOTASK_MAX_PERMISSION` is the server-side floor.** Spawned CLIs run with a permission mode (`plan` / `default` / `bypass`); the server refuses any spawn whose argv requests more than the configured ceiling, regardless of what the client asked for. **The default is no ceiling (`bypass`)** — and the local CLIs apply tasks headless, with claude/opencode defaulting to `--dangerously-skip-permissions`. So out of the box, any code that can reach the spawn endpoint (i.e. same-origin app code) can drive an agent that writes files and runs shell commands at the project root. In any shared, CI, or otherwise-not-fully-trusted environment, set `ANNOTASK_MAX_PERMISSION=plan` (read-only) or `default` so a compromised page cannot request `bypass`.
+- **All `/__annotask/*` requests are Host-gated:** the middleware validates the `Host` header against local hostnames (and `ANNOTASK_ALLOWED_HOSTS`) before any other handling, narrowing DNS-rebinding-style access.
+- **Spawned binaries are allow-listed** (`claude`, `codex`, `opencode`, `copilot`); free-form binary names and absolute paths are rejected, processes start with `shell: false`, cwd is pinned to the project root, and `PATH`/`HOME` overrides are dropped.
+
+None of this makes the dev server safe to expose beyond the developer's machine. If untrusted code runs in the app you are annotating, assume it can read Annotask state and drive agents up to the configured permission ceiling.
+
 ## Recommendations
 
 - Do not expose the dev server to untrusted networks.
diff --git a/docs/api.md b/docs/api.md
index 8179830..57b95ad 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -30,8 +30,11 @@ Current error codes:
 - `validation_failed`
 - `invalid_transition`
 - `forbidden_origin`
+- `origin_port_mismatch` (agent spawn routes only — origin must match the server's own port)
 - `not_found`
 - `missing_field`
+- `invalid_id`
+- `invalid_body`
 
 ## Task Model
 
@@ -44,7 +47,9 @@ Canonical task types:
 - `a11y_fix`
 - `error_fix`
 - `perf_fix`
-- `api_update`
+- `wireframe_apply` — created by the wireframe palette's "Build this route" or by the design-session apply path ("Apply now" / "Implement this wireframe"). `context.wireframe` carries `{ route, instances[] }`; each instance has an `anchor` (`file`, `line`, `position`, `component`, `targetTag`) and an `inserted` payload (`tag`, `componentName`, `library`, `module`, `props`, `classes`, `text_content`). `context.session` (when present) carries `{ session_id, entries[] }` — the design-session edits and/or wireframe directions. Applied via the `WIREFRAME_APPLY.md` companion playbook.
+
+There is no dedicated task type for backend-contract work; it surfaces as `annotation` tasks grounded with `data_context` and runtime-endpoint evidence.
 
 Statuses:
 
@@ -79,11 +84,16 @@ pending -> in_progress -> review -> accepted | denied
 | `GET` | `/__annotask/api/design-spec` | current design spec |
 | `GET` | `/__annotask/api/performance` | latest stored performance snapshot |
 | `POST` | `/__annotask/api/performance` | store a performance snapshot |
+| `GET` | `/__annotask/api/system-prompt` | composed embedded-agent system prompt (`?task_type=` adds the matching companion playbook) |
+| `GET` | `/__annotask/api/style-guide` | contents of `.annotask/STYLE_GUIDE.md` (init wizard review step) |
+| `GET` | `/__annotask/api/read-file` | read one project file by relative `?path=` (traversal-guarded to the project root) |
+| `DELETE` | `/__annotask/api/session-reset` | clear the `.annotask/.session-reset` sentinel after the shell wipes localStorage |
 
 Notes:
 
 - `report` supports `?mfe=NAME`
 - `report` can include `performance` when a snapshot exists
+- `status` reports `sessionReset: true` while the `.session-reset` sentinel exists on disk
 
 ### Tasks
 
@@ -246,6 +256,70 @@ Useful query params:
 - `schema_location`
 - `url`
 
+### Wireframe
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/__annotask/api/wireframe` | full multi-route wireframe document, or one route's slice with `?route=PATH` |
+| `PUT` | `/__annotask/api/wireframe` | replace the whole document (the shell owns the in-memory merge) |
+| `POST` | `/__annotask/api/wireframe-snapshots` | upload a canvas block PNG (`{id, data}`; id-addressed, 4MB cap) |
+| `GET` | `/__annotask/wireframe-snapshots/:filename` | serve a canvas snapshot PNG (containment-guarded) |
+| `DELETE` | `/__annotask/api/wireframe-snapshots/:filename` | drop a canvas snapshot PNG |
+| `GET` `PUT` `DELETE` | `/__annotask/api/design-session` | design-session journal (CAS on `rev`, 409 on stale writes); DELETE discards the journal, session-created placements, and every route's canvas sketch |
+| `POST` | `/__annotask/api/design-session/apply` | snapshot the touched files and mint one `wireframe_apply` task (placements + design-session edits/directions); the embedded agent then writes source |
+| `POST` | `/__annotask/api/design-session/undo-batch` | restore the newest apply batch's pre-apply bytes (hash-guarded) |
+| `POST` | `/__annotask/api/design-session/detach-file` | diverged-file resolution: keep the disk bytes, drop the file from the session |
+| `GET` | `/__annotask/api/design-session/snapshots` | snapshot-engine state (touched files, divergence, apply batches) |
+
+The document persists to `.annotask/wireframe.json` and is shape-validated (`{ version: "1.0", updatedAt, routes[] }`) on PUT. Snapshot PNGs live in `.annotask/wireframe-snapshots/` (orphans GC'd at boot). The design-session journal persists to `.annotask/design-session.json`; "Apply now" / "Implement this wireframe" snapshots the touched files first so undo/discard stays byte-exact — the agent writes source, the tool only snapshots and restores.
+
+### Agent Configs
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/__annotask/api/agent-configs` | per-persona project directions and provider preferences from `.annotask/agents.json` |
+| `PATCH` | `/__annotask/api/agent-configs/:id` | update one persona's `projectDirections`, `providerId`, `model`, or `effort` |
+
+### Embedded Agent
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/__annotask/api/agent/spawn` | spawn an allow-listed local CLI (claude / codex / opencode / copilot) and stream stdout/stderr back as SSE |
+| `DELETE` | `/__annotask/api/agent/spawn/:runId` | abort a running spawn by run id |
+| `GET` | `/__annotask/api/agent/detect` | detect which local CLIs are installed and logged in |
+| `GET` | `/__annotask/api/agent/models` | per-provider model catalog for `?cli=ID` (`?refresh=1` bypasses the 5-min cache) |
+
+The spawn routes enforce a stricter same-port origin check on top of the general localhost gate — a page on a different localhost port cannot spawn CLIs that have credential access (`origin_port_mismatch`). When `ANNOTASK_MAX_PERMISSION` is set to `plan` or `default`, the server refuses any spawn that exceeds it. The default is no ceiling (`bypass`).
+
+### Task Conversations
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/__annotask/api/tasks/:id/messages` | full per-task conversation snapshot (optional `?after=<id>`) |
+| `POST` | `/__annotask/api/tasks/:id/messages` | append a message; broadcasts to subscribers |
+| `GET` | `/__annotask/api/tasks/:id/messages/stream` | SSE stream; honours `Last-Event-ID` for resume |
+| `PATCH` | `/__annotask/api/tasks/:id/messages/:msgId` | update a message in place (used to flush a partial assistant turn while it streams) |
+
+Threads persist as append-only JSONL at `.annotask/conversations/<taskId>.jsonl`.
+
+### Usage
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/__annotask/api/usage` | aggregate token-usage totals, per-scope and per-provider, from `.annotask/usage.jsonl` |
+| `GET` | `/__annotask/api/usage/recent` | most recent usage entries, newest first (`?limit=N`, default 50, max 500) |
+
+### Init Wizard
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/__annotask/api/init/state` | current init-runner state |
+| `GET` | `/__annotask/api/init/scan-targets` | existence + mtime of the durable scan artifacts (`design-spec.json`, `agents.json`) |
+| `POST` | `/__annotask/api/init/start` | start an init scan (body can skip individual scanners and pin provider/model/effort) |
+| `POST` | `/__annotask/api/init/cancel` | cancel a running scan |
+| `POST` | `/__annotask/api/init/skip` | mark the project initialized without committing token data |
+| `POST` | `/__annotask/api/init/commit` | commit the reviewed spec (and optionally a style guide) to `.annotask/` |
+
 ## WebSocket
 
 Connect to `ws://localhost:<port>/__annotask/ws`.
@@ -261,6 +335,11 @@ Server-to-client events:
 | `changes:cleared` | `null` |
 | `tasks:updated` | task list payload |
 | `designspec:updated` | `null` |
+| `components:updated` | `{ scannedAt }` — a background component scan landed a fresh catalog |
+| `init:progress` | init-runner step state for the wizard |
+| `runtime-endpoints:updated` | current runtime endpoint catalog |
+| `wireframe:updated` | saved wireframe document (`null` when invalidated from disk) |
+| `session:updated` | `null` — broadcast when `.annotask/design-session.json` changes |
 
 Client-to-server events:
 
@@ -297,6 +376,13 @@ Current tool surface:
 - `annotask_resolve_endpoint`
 - `annotask_get_data_source_examples`
 - `annotask_get_data_source_details`
+- `annotask_get_source_excerpt`
+- `annotask_get_binding_classification`
+- `annotask_get_playbook`
+- `annotask_get_agent_directions`
+- `annotask_conversation_read`
+- `annotask_conversation_post`
+- `annotask_conversation_subscribe`
 
 Behavior differences from raw HTTP:
 
@@ -312,11 +398,11 @@ The live report's `changes[]` union currently includes:
 - `style_update`
 - `class_update`
 - `scoped_style_update` experimental
-- `prop_update` experimental
+- `component_prop_update` experimental
 - `component_insert`
-- `component_move`
+- `component_move` legacy — no longer emitted (the Reposition tool was removed); agents still apply it from older reports
 - `component_delete` experimental
 - `annotation`
-- `section_request`
+- `section_request` legacy — no longer emitted (sections are wireframe sketch material riding `wireframe_apply` add directions)
 
 The canonical definitions live in `src/schema.ts`.
diff --git a/docs/architecture.md b/docs/architecture.md
index e807979..4823cba 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -89,11 +89,49 @@ Representative files:
 - `src/server/code-context.ts`
 - `src/server/validation.ts`
 - `src/server/schemas.ts`
+- `src/server/agent-spawn.ts` — localhost-only subprocess spawner for local-CLI providers (SSE streaming, run registry, `ANNOTASK_MAX_PERMISSION` ceiling)
+- `src/server/agent-configs.ts` — per-persona project directions in `.annotask/agents.json`
+- `src/server/agent-detect.ts` — probe which local CLIs are installed and logged in
+- `src/server/agent-models.ts` — per-provider model catalog (live probe where supported, curated fallback)
+- `src/server/task-thread.ts` — per-task conversation threads (append-only JSONL + SSE)
+- `src/server/usage-ledger.ts` — append-only token-usage ledger at `.annotask/usage.jsonl`
+- `src/server/wireframe-store.ts` — persisted multi-route wireframe document
+- `src/server/apply-session.ts` — agent-apply orchestration ("Apply now" / "Implement this wireframe" → snapshot + mint task + run the embedded agent)
+- `src/server/file-snapshots.ts` — byte-exact snapshot/restore engine backing undo/discard
+- `src/server/session-store.ts` — design-session journal (`.annotask/design-session.json`)
+- `src/server/json-cas-store.ts` — compare-and-set rev store for journal writes (409 on stale)
+- `src/server/init.ts` — init-wizard scan runner (design spec, agent configs, style guide)
+- `src/server/path-safety.ts` — shared path-traversal guard for user-supplied file paths
+- `src/server/origin.ts` — origin validation (`isLocalOrigin`, stricter `originMatchesPort`)
 
 The server pre-warms component caches in the background on startup so the first Components page open and the first component-related MCP call do not pay the full scan cost. The component scan runs on a dedicated worker thread (`component-scanner-worker.ts`) so large bursts of synchronous filesystem and regex work do not block the event loop while the API serves task and context requests.
 
 Runtime-observed endpoint data lives alongside the static catalog: the injected bridge client forwards iframe `fetch` / XHR / beacon calls to `POST /__annotask/api/runtime-endpoints`, and `runtime-endpoints.ts` aggregates them per `(origin, method, pattern)` and joins them against static sources and OpenAPI operations on read.
 
+### Embedded Agent Layer
+
+`src/embedded/` lets the shell run apply/init/chat turns through an AI provider without leaving the browser.
+
+Four locally installed agent CLIs are first-class providers — all of them get the same spawn, streaming, permission, and conversation treatment:
+
+- `src/embedded/claude-local-provider.ts` — Claude Code
+- `src/embedded/codex-local-provider.ts` — Codex
+- `src/embedded/opencode-local-provider.ts` — opencode
+- `src/embedded/copilot-local-provider.ts` — GitHub Copilot CLI
+
+They share `src/embedded/cli-local-provider.ts` (spawn-over-HTTP plumbing against `/api/agent/spawn`) and sit alongside direct API providers (`anthropic-provider.ts`, `openai-provider.ts`, `openrouter-provider.ts`, `openai-compatible-provider.ts`, `paperclip-provider.ts`).
+
+Supporting modules:
+
+- `provider.ts` / `provider-factory.ts` / `provider-config.ts` - provider contract, construction, and settings
+- `permission-mode.ts` / `permission-mode-flags.ts` - `default` / `plan` / `bypass` modes mapped onto each CLI's native flags
+- `persona.ts` - per-task-type agent personas
+- `event-log.ts` / `redaction.ts` - turn event capture with secret redaction
+
+Runaway runs are bounded by idle and max-duration wall-clock watchdogs rather than a USD/token spend cap (a money cap is not portable across the provider mix).
+
+Server-side counterparts live in `src/server/`: `agent-spawn.ts` (allow-listed subprocess spawner, SSE streaming, run registry), `agent-detect.ts`, `agent-models.ts`, `agent-configs.ts`, `task-thread.ts` (per-task conversation persistence), and `usage-ledger.ts` (token spend). Spawn requests pass the same-port origin gate in `origin.ts`, and the server enforces the `ANNOTASK_MAX_PERMISSION` ceiling regardless of what the client asks for.
+
 ### MCP Layer
 
 `src/mcp/server.ts` exposes the agent-facing tool surface at `POST /__annotask/mcp`.
@@ -121,7 +159,7 @@ Current sub-sections:
 
 - Annotate: tasks and annotation workflows
 - Design: Tokens, Inspector, Components
-- Audit: Accessibility, Data, Libraries, Performance, Errors
+- Audit: Accessibility, Data, Performance, Errors
 
 Important constraint:
 
@@ -136,7 +174,7 @@ Key composables:
 - `useShellTheme` - built-in themes and custom theme CRUD
 - `useDesignSpec` - design-spec loading and theme activation helpers
 - `useProjectComponents` - Components page data, filters, and usage lookups
-- `useDataSources` - Audit data and library views, API schema links, `api_update` creation
+- `useDataSources` - Audit data and library views, API schema links, runtime endpoint catalog
 - `usePerfMonitor` - performance scans, findings, recordings
 - `useErrorMonitor` - console error and warning capture
 - `useA11yScanner` - WCAG scanning and fix-task creation
@@ -223,7 +261,7 @@ agent fetches task summaries
 ```text
 shell scan or monitor detects issue
   -> shell packages contextual details
-  -> creates a11y_fix / error_fix / perf_fix / api_update task
+  -> creates a11y_fix / error_fix / perf_fix task
   -> normal task pipeline takes over
 ```
 
@@ -238,6 +276,12 @@ Common files:
 - `server.json`
 - `performance.json`
 - `screenshots/`
+- `agents.json` - per-persona project directions and provider preferences
+- `wireframe.json` - multi-route wireframe document
+- `usage.jsonl` - append-only token-usage ledger
+- `conversations/<taskId>.jsonl` - append-only per-task conversation threads
+- `interaction-history/<taskId>.json` - per-task user-trace sidecars
+- `rendered-html/<taskId>.json` - per-task `outerHTML` sidecars
 
 Writes are atomic. Task mutations serialize through a lock in `state.ts`, and screenshot cleanup happens only after a successful task write.
 
diff --git a/docs/cli.md b/docs/cli.md
index 1325fcf..83263c2 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -186,6 +186,42 @@ annotask code-context <task-id> --context-lines=25
 
 Returns excerpt, enclosing symbol, import block, and excerpt hash.
 
+### `source-excerpt`
+
+Fetch a direct source excerpt by file and line, without a task.
+
+```bash
+annotask source-excerpt src/components/Header.vue 12
+annotask source-excerpt src/components/Header.vue 12 --context-lines=25 --mcp
+```
+
+### `binding-classify`
+
+Round-trip-honesty classification of one element by file and line (optionally a tag): per-prop literal/bound/unknown, the element's text kind, and the enclosing loop. Use it to ground an element before rewriting its props or text.
+
+```bash
+annotask binding-classify --file=src/components/Card.vue --line=12
+annotask binding-classify --file=src/components/Card.vue --line=12 --tag=button --mcp
+```
+
+### `playbook`
+
+Print a task-type companion playbook (`a11y_fix`, `theme_update`, `error_fix`, `perf_fix`, `wireframe_apply`).
+
+```bash
+annotask playbook wireframe_apply
+annotask playbook a11y_fix --mcp
+```
+
+### `agent-directions`
+
+Fetch per-persona project directions from `.annotask/agents.json`.
+
+```bash
+annotask agent-directions
+annotask agent-directions --mcp
+```
+
 ### `data-context`
 
 Resolve or re-resolve a task's `data_context`.
@@ -363,7 +399,9 @@ annotask help
 | `--limit=N` | `components`, `component-examples`, `data-source-examples` |
 | `--offset=N` | `components` |
 | `--context-lines=N` | `code-context`, `data-source-details` |
-| `--file=PATH` | `data-source-details` |
+| `--file=PATH` | `data-source-details`, `binding-classify` |
+| `--line=N` | `binding-classify` |
+| `--tag=T` | `binding-classify` |
 | `--refresh` | `data-context` |
 | `--used-only` | `data-sources` |
 | `--kind=K` | `data-sources`, `data-source-examples`, `data-source-details`, `api-schemas` |
diff --git a/docs/data-source-discovery.md b/docs/data-source-discovery.md
index 1e56043..2fdfe47 100644
--- a/docs/data-source-discovery.md
+++ b/docs/data-source-discovery.md
@@ -206,7 +206,7 @@ annotask data-source-details useUserQuery --file=src/composables/useUserQuery.ts
 
 Reach for the data-source catalog when a task asks to:
 
-- modify a fetch contract, query, mutation, or store — this is the `api_update` task type's primary surface
+- modify a fetch contract, query, mutation, or store — there is no dedicated task type for this; these arrive as `annotation` tasks carrying `data_context` plus runtime-endpoint evidence, and the catalog is how you ground them
 - add a new UI that needs to bind to existing data — start from `used_only=true` to see what's already fetched on this page
 - rewire a component to a different hook or store that matches project conventions
 - understand what data an element on the current page depends on — use the per-task `data_context`, then call `annotask_get_data_source_details` on the primary source for its shape
diff --git a/docs/distribution.md b/docs/distribution.md
index 52b23f5..437d605 100644
--- a/docs/distribution.md
+++ b/docs/distribution.md
@@ -38,6 +38,9 @@ Published skill files:
 - `skills/annotask-apply/SKILL.md`
 - `skills/annotask-apply/A11Y_RULES.md`
 - `skills/annotask-apply/THEME_UPDATE.md`
+- `skills/annotask-apply/ERROR_FIX.md`
+- `skills/annotask-apply/PERF_FIX.md`
+- `skills/annotask-apply/WIREFRAME_APPLY.md`
 
 ## Build Pipeline
 
diff --git a/docs/index.html b/docs/index.html
index c764c28..64302e3 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -13,16 +13,27 @@
 <link rel="icon" href="../favicon.ico" />
 <style>
   :root {
-    --bg: #0a0c12;
-    --panel: #161a24;
-    --border: #2a3142;
-    --fg: #e8ecf4;
-    --muted: #98a0b4;
-    --accent: #62dcae;
-    --accent-ink: #0a0c12;
+    --bg: #0a0a0a;
+    --panel: #141414;
+    --border: #2a2a2a;
+    --fg: #e4e4e7;
+    --muted: #71717a;
+    --accent: #3b82f6;
+    --accent-ink: #fff;
     --mono: ui-monospace, "JetBrains Mono", "Fira Code", Menlo, Consolas, monospace;
     --sans: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Inter", "Helvetica Neue", Arial, sans-serif;
   }
+  @media (prefers-color-scheme: light) {
+    :root {
+      --bg: #f8f9fa;
+      --panel: #ffffff;
+      --border: #d4d6db;
+      --fg: #1a1a1a;
+      --muted: #6b7280;
+      --accent: #2563eb;
+      --accent-ink: #fff;
+    }
+  }
   * { box-sizing: border-box; }
   html, body { margin: 0; padding: 0; background: var(--bg); color: var(--fg); font-family: var(--sans); -webkit-font-smoothing: antialiased; }
   a { color: var(--accent); text-decoration: none; }
@@ -71,10 +82,17 @@
   .card p { margin: 0; color: var(--muted); font-size: 15px; line-height: 1.55; }
 
   .install { display: grid; grid-template-columns: 1fr 1fr; gap: 24px; }
-  pre { background: #0d1118; border: 1px solid var(--border); border-radius: 10px; padding: 16px 18px; overflow-x: auto; font-family: var(--mono); font-size: 14px; color: var(--fg); margin: 0; }
+  pre { background: var(--panel); border: 1px solid var(--border); border-radius: 10px; padding: 16px 18px; overflow-x: auto; font-family: var(--mono); font-size: 14px; color: var(--fg); margin: 0; }
   pre code .k { color: #c084fc; }
   pre code .s { color: var(--accent); }
   pre code .c { color: var(--muted); }
+  @media (prefers-color-scheme: light) {
+    pre code .k { color: #7e22ce; }
+  }
+
+  .feature-shots { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; margin-top: 24px; }
+  .feature-shots img { width: 100%; border-radius: 10px; border: 1px solid var(--border); }
+  @media (max-width: 800px) { .feature-shots { grid-template-columns: 1fr; } }
 
   .stack-row { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
   .pill { display: inline-block; padding: 6px 12px; border-radius: 999px; background: var(--panel); border: 1px solid var(--border); color: var(--muted); font-size: 13px; }
@@ -114,7 +132,7 @@ <h1>Annotate the UI. <span class="green">Agent ships the code.</span></h1>
       <a class="btn ghost" href="#demo">Watch the demo</a>
     </div>
     <div class="hero-shot">
-      <img src="media/hero.png" alt="Annotate a low-contrast button. Agent applies the a11y fix. Re-render passes." />
+      <img src="media/screenshots/shell-overview.png" alt="Annotask shell showing annotation toolbar, app iframe, and task sidebar" />
     </div>
   </div>
 
@@ -133,7 +151,7 @@ <h2>What you get</h2>
     <div class="grid-3">
       <div class="card">
         <h3>Annotate</h3>
-        <p>Pins, arrows, drawn sections, text highlights, screenshots, route-aware tasks, viewport capture. Every annotation becomes a structured task with grounded context.</p>
+        <p>Pins, arrows, text highlights, screenshots, route-aware tasks, viewport capture. Every annotation becomes a structured task with grounded context. Sections are drawn on the wireframe canvas.</p>
       </div>
       <div class="card">
         <h3>Design</h3>
@@ -144,6 +162,11 @@ <h3>Audit</h3>
         <p>Local axe-core a11y scanning, runtime endpoint monitoring, console error capture, performance findings — each becomes a one-click fix task with full context.</p>
       </div>
     </div>
+    <div class="feature-shots">
+      <img src="media/screenshots/annotate-pins.png" alt="Pin annotations" loading="lazy" />
+      <img src="media/screenshots/design-inspector.png" alt="Live style inspector" loading="lazy" />
+      <img src="media/screenshots/audit-a11y.png" alt="Accessibility scanner" loading="lazy" />
+    </div>
   </section>
 
   <section id="install">
diff --git a/docs/media/screenshots/annotate-arrows.png b/docs/media/screenshots/annotate-arrows.png
new file mode 100644
index 0000000..83face9
Binary files /dev/null and b/docs/media/screenshots/annotate-arrows.png differ
diff --git a/docs/media/screenshots/annotate-highlights.png b/docs/media/screenshots/annotate-highlights.png
new file mode 100644
index 0000000..3ba6ffc
Binary files /dev/null and b/docs/media/screenshots/annotate-highlights.png differ
diff --git a/docs/media/screenshots/annotate-pins.png b/docs/media/screenshots/annotate-pins.png
new file mode 100644
index 0000000..f14fb6d
Binary files /dev/null and b/docs/media/screenshots/annotate-pins.png differ
diff --git a/docs/media/screenshots/audit-a11y.png b/docs/media/screenshots/audit-a11y.png
new file mode 100644
index 0000000..2f03f12
Binary files /dev/null and b/docs/media/screenshots/audit-a11y.png differ
diff --git a/docs/media/screenshots/audit-errors.png b/docs/media/screenshots/audit-errors.png
new file mode 100644
index 0000000..f212e02
Binary files /dev/null and b/docs/media/screenshots/audit-errors.png differ
diff --git a/docs/media/screenshots/audit-perf.png b/docs/media/screenshots/audit-perf.png
new file mode 100644
index 0000000..2915320
Binary files /dev/null and b/docs/media/screenshots/audit-perf.png differ
diff --git a/docs/media/screenshots/design-components.png b/docs/media/screenshots/design-components.png
new file mode 100644
index 0000000..f98b963
Binary files /dev/null and b/docs/media/screenshots/design-components.png differ
diff --git a/docs/media/screenshots/design-inspector.png b/docs/media/screenshots/design-inspector.png
new file mode 100644
index 0000000..3273c8d
Binary files /dev/null and b/docs/media/screenshots/design-inspector.png differ
diff --git a/docs/media/screenshots/design-tokens.png b/docs/media/screenshots/design-tokens.png
new file mode 100644
index 0000000..89d60c1
Binary files /dev/null and b/docs/media/screenshots/design-tokens.png differ
diff --git a/docs/media/screenshots/shell-overview.png b/docs/media/screenshots/shell-overview.png
new file mode 100644
index 0000000..ec4e331
Binary files /dev/null and b/docs/media/screenshots/shell-overview.png differ
diff --git a/docs/setup.md b/docs/setup.md
index 840303f..819106e 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -297,7 +297,7 @@ The shell currently exposes three top-level surfaces:
 
 - **Annotate** - annotations, screenshots, viewport tools, route-aware tasks
 - **Design** - tokens, inspector, layout overlay, component browser
-- **Audit** - a11y, data, libraries, performance, errors
+- **Audit** - a11y, data, performance, errors
 
 Internally the Audit tab still uses the `develop` view id for localStorage compatibility.
 
diff --git a/docs/skills.md b/docs/skills.md
index ef046d2..aca914e 100644
--- a/docs/skills.md
+++ b/docs/skills.md
@@ -57,7 +57,7 @@ Important current behavior:
 
 ## `/annotask-apply`
 
-Purpose: process actionable Annotask tasks and apply them to source code. `api_update` tasks are the exception: the skill inspects them and reports the required backend changes instead of editing the API.
+Purpose: process actionable Annotask tasks and apply them to source code. Cross-boundary API edits are the exception: the skill never edits the backend — it applies a frontend-only fallback when one exists, or marks the task `blocked` with the required backend change.
 
 The skill prefers MCP when available and falls back to CLI commands with `--mcp` for parity.
 
@@ -65,9 +65,9 @@ Actionable work usually includes:
 
 - `pending`
 - `denied` tasks with reviewer feedback
-- `needs_info` tasks whose questions have been answered
+- `in_progress` tasks whose `agent_feedback` now contains answers to earlier questions
 
-The skill skips unresolved `needs_info` and `blocked` tasks.
+The skill skips `needs_info` (still waiting on the user — answered tasks return to `in_progress`) and `blocked` tasks.
 
 ### Current Apply Flow
 
@@ -75,14 +75,14 @@ The skill skips unresolved `needs_info` and `blocked` tasks.
 2. triage tasks by touched files and shared state
 3. lock a task with `status: "in_progress"`
 4. fetch deeper context only when needed
-5. apply the source change, or report required backend changes for `api_update`
+5. apply the source change, or mark cross-boundary backend work `blocked`
 6. mark the task `review` with a short `resolution`
 7. re-check the queue before finishing
 
 The current workflow is aware of:
 
 - batched `theme_update` tasks with `context.edits[]` (handled via `THEME_UPDATE.md`)
-- `api_update` tasks created from the Audit data view and reported back as required backend work
+- batched `wireframe_apply` tasks with `context.wireframe.instances[]` (handled via `WIREFRAME_APPLY.md`)
 - code-context re-anchoring for retried or drifted tasks
 - component examples and data-source examples as grounding aids
 
@@ -95,7 +95,7 @@ The current workflow is aware of:
 - `a11y_fix`
 - `error_fix`
 - `perf_fix`
-- `api_update`
+- `wireframe_apply`
 
 ## MCP And CLI Parity
 
@@ -155,5 +155,10 @@ Published skill files live in the package root under:
 - `skills/annotask-apply/SKILL.md`
 - `skills/annotask-apply/A11Y_RULES.md` (companion playbook read on demand for `a11y_fix` tasks)
 - `skills/annotask-apply/THEME_UPDATE.md` (companion playbook read on demand for `theme_update` tasks)
+- `skills/annotask-apply/ERROR_FIX.md` (companion playbook read on demand for `error_fix` tasks)
+- `skills/annotask-apply/PERF_FIX.md` (companion playbook read on demand for `perf_fix` tasks)
+- `skills/annotask-apply/WIREFRAME_APPLY.md` (companion playbook read on demand for `wireframe_apply` tasks)
 
 They are copied or symlinked into the consumer project's chosen skill directories by `annotask init-skills`.
+
+`skills/` is the canonical copy. The in-repo `.claude/skills/`, `.agents/skills/`, and `playgrounds/simple/vue-webpack/.claude/skills/` directories are generated mirrors — run `pnpm sync:skills` after editing the canonical files (CI fails if the mirrors drift).
diff --git a/e2e/demo-record.config.ts b/e2e/demo-record.config.ts
new file mode 100644
index 0000000..53420ef
--- /dev/null
+++ b/e2e/demo-record.config.ts
@@ -0,0 +1,22 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: '.',
+  testMatch: 'demo-record.test.ts',
+  timeout: 120_000,
+  expect: { timeout: 10_000 },
+  fullyParallel: false,
+  retries: 0,
+  use: {
+    ...devices['Desktop Chrome'],
+    baseURL: 'http://localhost:5181',
+    viewport: { width: 1920, height: 1080 },
+    trace: 'off',
+  },
+  projects: [
+    {
+      name: 'demo',
+      use: { ...devices['Desktop Chrome'], viewport: { width: 1920, height: 1080 } },
+    },
+  ],
+})
diff --git a/e2e/demo-record.test.ts b/e2e/demo-record.test.ts
new file mode 100644
index 0000000..a730f8e
--- /dev/null
+++ b/e2e/demo-record.test.ts
@@ -0,0 +1,222 @@
+/**
+ * Automated demo recording — captures each segment as a video clip.
+ *
+ * Run:
+ *   pnpm demo:reset && pnpm dev:marketing
+ *   npx playwright test --config e2e/demo-record.config.ts
+ *
+ * Produces: demo/segments/*.webm
+ *
+ * NOTE: Segments that require iframe tool interactions (pins, arrows,
+ * sections) are best recorded manually. This script captures the
+ * segments that Playwright can automate reliably: shell loading, tab
+ * views, a11y scan, token inspector, and the result scroll.
+ */
+import { test, expect, type Page, type FrameLocator } from '@playwright/test'
+import { mkdirSync, renameSync, existsSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const SEGMENTS_DIR = join(__dirname, '..', 'demo', 'segments')
+const RAW_DIR = join(SEGMENTS_DIR, '_raw')
+mkdirSync(RAW_DIR, { recursive: true })
+
+/* ── Helpers ─────────────────────────────────────────────────────── */
+
+async function waitForShell(page: Page): Promise<FrameLocator> {
+  await page.goto('/__annotask/')
+  await page.waitForLoadState('domcontentloaded')
+  await expect(page.locator('.toolbar')).toBeVisible({ timeout: 15_000 })
+
+  try {
+    await page.locator('.init-modal-close').click({ timeout: 3000 })
+    await page.waitForTimeout(500)
+  } catch { /* no wizard */ }
+
+  const frame = page.frameLocator('.app-iframe')
+  await frame.locator('body').waitFor({ state: 'visible', timeout: 15_000 })
+  await page.waitForTimeout(1500)
+  return frame
+}
+
+async function saveVideo(page: Page, name: string) {
+  const video = page.video()
+  if (video) {
+    await page.close()
+    const src = await video.path()
+    if (src && existsSync(src)) {
+      const dest = join(SEGMENTS_DIR, `${name}.webm`)
+      renameSync(src, dest)
+      console.log(`  → ${name}.webm`)
+    }
+  }
+}
+
+/* ── Segments ────────────────────────────────────────────────────── */
+
+test.describe('Demo recording', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  // Segment 1: Cold open — before page scroll
+  test('segment-01-before-scroll', async ({ browser }) => {
+    const ctx = await browser.newContext({
+      viewport: { width: 1920, height: 1080 },
+      recordVideo: { dir: RAW_DIR, size: { width: 1920, height: 1080 } },
+    })
+    const page = await ctx.newPage()
+
+    await page.goto('http://localhost:5181/')
+    await page.waitForLoadState('domcontentloaded')
+    await page.waitForTimeout(1500)
+
+    // Smooth scroll down the "before" page
+    await page.evaluate(async () => {
+      const total = document.body.scrollHeight - window.innerHeight
+      const dur = 6000
+      const t0 = performance.now()
+      return new Promise<void>(resolve => {
+        (function step(ts: number) {
+          const p = Math.min((ts - t0) / dur, 1)
+          const e = p < 0.5 ? 2 * p * p : 1 - (-2 * p + 2) ** 2 / 2
+          window.scrollTo(0, total * e)
+          p < 1 ? requestAnimationFrame(step) : resolve()
+        })(t0)
+      })
+    })
+    await page.waitForTimeout(2000)
+
+    await saveVideo(page, 'segment-01-before-scroll')
+    await ctx.close()
+  })
+
+  // Segment 2: Setup — load shell
+  test('segment-02-setup', async ({ browser }) => {
+    const ctx = await browser.newContext({
+      viewport: { width: 1920, height: 1080 },
+      recordVideo: { dir: RAW_DIR, size: { width: 1920, height: 1080 } },
+    })
+    const page = await ctx.newPage()
+
+    await page.goto('http://localhost:5181/')
+    await page.waitForTimeout(2000)
+
+    await page.goto('http://localhost:5181/__annotask/')
+    await page.waitForLoadState('domcontentloaded')
+    await expect(page.locator('.toolbar')).toBeVisible({ timeout: 15_000 })
+
+    try {
+      await page.locator('.init-modal-close').click({ timeout: 3000 })
+      await page.waitForTimeout(500)
+    } catch { /* no wizard */ }
+
+    await page.waitForTimeout(3000)
+
+    await saveVideo(page, 'segment-02-setup')
+    await ctx.close()
+  })
+
+  // Segment 6: Style editor — Design > Inspector view
+  test('segment-06-style-editor', async ({ browser }) => {
+    const ctx = await browser.newContext({
+      viewport: { width: 1920, height: 1080 },
+      recordVideo: { dir: RAW_DIR, size: { width: 1920, height: 1080 } },
+    })
+    const page = await ctx.newPage()
+    await waitForShell(page)
+
+    await page.locator('[data-testid="tab-design"]').click()
+    await page.waitForTimeout(500)
+    await page.locator('[data-testid="design-inspector"]').click()
+    await page.waitForTimeout(3000)
+
+    await saveVideo(page, 'segment-06-style-editor')
+    await ctx.close()
+  })
+
+  // Segment 7: A11y scan — run scan and show results
+  test('segment-07-a11y-scan', async ({ browser }) => {
+    const ctx = await browser.newContext({
+      viewport: { width: 1920, height: 1080 },
+      recordVideo: { dir: RAW_DIR, size: { width: 1920, height: 1080 } },
+    })
+    const page = await ctx.newPage()
+    await waitForShell(page)
+
+    await page.locator('[data-testid="tab-audit"]').click()
+    await page.waitForTimeout(300)
+    await page.locator('[data-testid="audit-a11y"]').click()
+    await page.waitForTimeout(1000)
+
+    // Run the scan
+    try {
+      const scanBtn = page.locator('button:has-text("Scan"), button:has-text("Run")').first()
+      await scanBtn.click({ timeout: 3000 })
+      await page.waitForTimeout(8000)
+    } catch {
+      await page.waitForTimeout(2000)
+    }
+
+    // Hold on results
+    await page.waitForTimeout(3000)
+
+    await saveVideo(page, 'segment-07-a11y-scan')
+    await ctx.close()
+  })
+
+  // Segment 9: Token editor — Design > Tokens view
+  test('segment-09-token-editor', async ({ browser }) => {
+    const ctx = await browser.newContext({
+      viewport: { width: 1920, height: 1080 },
+      recordVideo: { dir: RAW_DIR, size: { width: 1920, height: 1080 } },
+    })
+    const page = await ctx.newPage()
+    await waitForShell(page)
+
+    await page.locator('[data-testid="tab-design"]').click()
+    await page.waitForTimeout(500)
+    await page.locator('[data-testid="design-tokens"]').click()
+    await page.waitForTimeout(4000)
+
+    await saveVideo(page, 'segment-09-token-editor')
+    await ctx.close()
+  })
+
+  // Segment 12: Result — polished page scroll (restore first)
+  test('segment-12-result-scroll', async ({ browser }) => {
+    const ctx = await browser.newContext({
+      viewport: { width: 1920, height: 1080 },
+      recordVideo: { dir: RAW_DIR, size: { width: 1920, height: 1080 } },
+    })
+    const page = await ctx.newPage()
+
+    // NOTE: This test expects the polished "after" state.
+    // Run `pnpm demo:restore` before this segment if the page is still degraded.
+    await page.goto('http://localhost:5181/')
+    await page.waitForLoadState('domcontentloaded')
+    await page.waitForTimeout(2000)
+
+    // Smooth scroll top to bottom
+    await page.evaluate(async () => {
+      const total = document.body.scrollHeight - window.innerHeight
+      const dur = 8000
+      const t0 = performance.now()
+      return new Promise<void>(resolve => {
+        (function step(ts: number) {
+          const p = Math.min((ts - t0) / dur, 1)
+          const e = p < 0.5 ? 2 * p * p : 1 - (-2 * p + 2) ** 2 / 2
+          window.scrollTo(0, total * e)
+          p < 1 ? requestAnimationFrame(step) : resolve()
+        })(t0)
+      })
+    })
+    await page.waitForTimeout(2000)
+
+    // Scroll back to hero
+    await page.evaluate(() => window.scrollTo({ top: 0, behavior: 'smooth' }))
+    await page.waitForTimeout(3000)
+
+    await saveVideo(page, 'segment-12-result-scroll')
+    await ctx.close()
+  })
+})
diff --git a/e2e/helpers/design-tool.ts b/e2e/helpers/design-tool.ts
new file mode 100644
index 0000000..d4b2580
--- /dev/null
+++ b/e2e/helpers/design-tool.ts
@@ -0,0 +1,106 @@
+import type { Page, APIRequestContext } from '@playwright/test'
+
+/**
+ * Shared helpers for the design-tool e2e suites — the repo's first
+ * task-creating/editing e2e. Encodes the hard-won gotchas: boot the wanted
+ * view via localStorage BEFORE the shell loads, dismiss the InitWizard via
+ * the API (with an Origin header), never trust networkidle (the shell holds a
+ * WebSocket), and count framenavigated to prove edits are reload-free.
+ */
+
+export const PLANETS_FIXTURE = {
+  planets: [
+    { id: 1, name: 'Mercury', type: 'rocky', moons: 0, distance_from_sun_mkm: 58, radius_km: 2439, avg_temp_c: 167, color: '#b1adad' },
+    { id: 2, name: 'Venus', type: 'rocky', moons: 0, distance_from_sun_mkm: 108, radius_km: 6051, avg_temp_c: 464, color: '#e6c89c' },
+    { id: 3, name: 'Earth', type: 'rocky', moons: 1, distance_from_sun_mkm: 150, radius_km: 6371, avg_temp_c: 15, color: '#6b93d6' },
+  ],
+}
+
+/** The /planets pages proxy to a FastAPI dev server that the Playwright
+ *  webServer list doesn't boot — intercept so the suite is hermetic.
+ *  page.route applies to iframe requests too (same page). */
+export async function interceptPlanetsApi(page: Page): Promise<void> {
+  await page.route('**/api/solar/planets*', (route) => route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify(PLANETS_FIXTURE),
+  }))
+}
+
+/** Dismiss the InitWizard server-side. Mutations require a local Origin. */
+export async function skipInitWizard(request: APIRequestContext, origin: string): Promise<void> {
+  await request.post('/__annotask/api/init/skip', { headers: { Origin: origin } }).catch(() => { /* already initialized */ })
+}
+
+/** Boot the shell straight into a design-tool view. localStorage must be
+ *  seeded BEFORE the shell script runs — addInitScript, not page.evaluate. */
+export async function bootDesignShell(page: Page, opts?: {
+  route?: string
+  section?: 'inspector' | 'components'
+}): Promise<void> {
+  const route = opts?.route ?? '/planets'
+  const section = opts?.section ?? 'inspector'
+  await page.addInitScript(({ route, section }) => {
+    localStorage.setItem('annotask:shellView', 'design')
+    localStorage.setItem('annotask:designSection', section)
+    localStorage.setItem('annotask:lastRoute', route)
+    // The default activePanel is 'tasks', which wins the panel v-else-if chain
+    // and hides the inspector — pin it to the inspector panel.
+    localStorage.setItem('annotask:activePanel', 'inspector')
+    // Default interaction mode is 'interact' (clicks pass through to the app);
+    // selection needs 'select'. Shell and iframe share this same-origin key.
+    localStorage.setItem('annotask:mode', 'select')
+  }, { route, section })
+  // networkidle never fires (shell WebSocket) — domcontentloaded + settle.
+  await page.goto('/__annotask/', { waitUntil: 'domcontentloaded' })
+  await page.locator('.toolbar').waitFor({ state: 'visible', timeout: 15_000 })
+  await page.waitForTimeout(1_000)
+}
+
+/** Counts full navigations of the MAIN frame — live edits must keep this at 0. */
+export function trackReloads(page: Page): () => number {
+  let count = 0
+  page.on('framenavigated', (frame) => {
+    if (frame === page.mainFrame()) count++
+  })
+  return () => count
+}
+
+export async function getDesignSession(request: APIRequestContext): Promise<{ entries: Array<Record<string, unknown>> }> {
+  const res = await request.get('/__annotask/api/design-session')
+  return res.json()
+}
+
+export async function discardDesignSession(request: APIRequestContext, origin: string): Promise<void> {
+  await request.delete('/__annotask/api/design-session', { headers: { Origin: origin } }).catch(() => { /* best effort */ })
+}
+
+/** Hermetic slate: leftover playground tasks and wireframe placements from
+ *  manual sessions would hijack the panel (Tasks wins) and remount stale
+ *  placements into the iframe. */
+export async function resetWorkspaceState(request: APIRequestContext, origin: string): Promise<void> {
+  try {
+    const tasks = (await (await request.get('/__annotask/api/tasks')).json()).tasks as Array<{ id: string }>
+    for (const t of tasks) {
+      await request.delete(`/__annotask/api/tasks/${t.id}`, { headers: { Origin: origin } })
+    }
+  } catch { /* best effort */ }
+  try {
+    const wf = await (await request.get('/__annotask/api/wireframe')).json()
+    if (Array.isArray(wf.routes) && wf.routes.some((r: { instances: unknown[]; canvas?: unknown }) => r.instances.length > 0 || r.canvas)) {
+      await request.put('/__annotask/api/wireframe', {
+        headers: { Origin: origin, 'Content-Type': 'application/json' },
+        data: { version: '1.0', updatedAt: Date.now(), ...(wf.rev !== undefined ? { rev: wf.rev } : {}), routes: [] },
+      })
+    }
+  } catch { /* best effort */ }
+}
+
+/** Toggle Wireframe mode on and wait for the capture to finish rendering
+ *  image blocks. Capture is sequential html2canvas work — give it time. */
+export async function enterWireframeMode(page: Page): Promise<void> {
+  await page.locator('[data-testid="tool-wireframe"]').click()
+  await page.locator('[data-testid="wireframe-canvas"]').waitFor({ state: 'visible', timeout: 10_000 })
+  await page.locator('.wf-block').first().waitFor({ state: 'visible', timeout: 30_000 })
+  await page.waitForTimeout(500)
+}
diff --git a/e2e/react-vite.wireframe.test.ts b/e2e/react-vite.wireframe.test.ts
new file mode 100644
index 0000000..d82820d
--- /dev/null
+++ b/e2e/react-vite.wireframe.test.ts
@@ -0,0 +1,63 @@
+import { test, expect } from '@playwright/test'
+import {
+  bootDesignShell,
+  interceptPlanetsApi,
+  skipInitWizard,
+  resetWorkspaceState,
+  enterWireframeMode,
+} from './helpers/design-tool'
+
+const ORIGIN = 'http://localhost:5174'
+
+// React parity: capture anchors come from rendered host elements, which React
+// DOES stamp — the usage-site limitation that killed live prop editing does
+// not apply to snapshot wireframing.
+test.describe('React + Vite wireframe capture (W1/W2 parity)', () => {
+  test.beforeEach(async ({ page, request }) => {
+    await skipInitWizard(request, ORIGIN)
+    await resetWorkspaceState(request, ORIGIN)
+    await interceptPlanetsApi(page)
+  })
+
+  test.afterEach(async ({ request }) => {
+    await resetWorkspaceState(request, ORIGIN)
+  })
+
+  test('captures anchored blocks, persists a drag, and restores after F5', async ({ page, request }) => {
+    await bootDesignShell(page)
+    const frame = page.frameLocator('.app-iframe')
+    await expect(frame.locator('h1.title')).toHaveText('Planets', { timeout: 15_000 })
+    await enterWireframeMode(page)
+
+    // Blocks render and at least one carries a Planets.tsx anchor.
+    expect(await page.locator('.wf-block img').count()).toBeGreaterThanOrEqual(2)
+    const wf = await (await request.get('/__annotask/api/wireframe')).json()
+    const canvas = wf.routes.find((r: { route: string }) => r.route === '/planets')!.canvas
+    type Blk = { id: string; rect: { x: number; y: number }; anchor?: { file: string; line: number } }
+    const anchored = (canvas.blocks as Blk[]).filter((b) => b.anchor?.file.includes('Planets.tsx') && b.anchor.line > 0)
+    expect(anchored.length).toBeGreaterThanOrEqual(1)
+
+    // One drag persists.
+    const target = anchored[0]
+    const el = page.locator(`[data-block-id="${target.id}"]`)
+    const box = (await el.boundingBox())!
+    await page.mouse.move(box.x + box.width / 2, box.y + Math.min(40, box.height / 2))
+    await page.mouse.down()
+    await page.mouse.move(box.x + box.width / 2 + 120, box.y + Math.min(40, box.height / 2) + 90, { steps: 8 })
+    await page.mouse.up()
+    await expect.poll(async () => {
+      const after = await (await request.get('/__annotask/api/wireframe')).json()
+      const c = after.routes.find((r: { route: string }) => r.route === '/planets')!.canvas
+      const b = (c.blocks as Blk[]).find((x) => x.id === target.id)!
+      return b.rect.x > target.rect.x + 80 && b.rect.y > target.rect.y + 60
+    }, { timeout: 5_000 }).toBe(true)
+
+    // F5 restores the canvas as left.
+    await page.reload({ waitUntil: 'domcontentloaded' })
+    await page.locator('.toolbar').waitFor({ state: 'visible', timeout: 15_000 })
+    await page.locator('[data-testid="wireframe-canvas"]').waitFor({ state: 'visible', timeout: 15_000 })
+    await page.waitForTimeout(1_000)
+    expect(await page.locator(`[data-block-id="${target.id}"]`).count()).toBe(1)
+    expect(await page.locator(`[data-block-id="${target.id}"] img`).evaluate((el) => (el as HTMLImageElement).naturalWidth)).toBeGreaterThan(0)
+  })
+})
diff --git a/e2e/screenshots.test.ts b/e2e/screenshots.test.ts
new file mode 100644
index 0000000..41495e0
--- /dev/null
+++ b/e2e/screenshots.test.ts
@@ -0,0 +1,243 @@
+import { test, expect } from '@playwright/test'
+import { mkdirSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const OUT = join(__dirname, '..', 'docs', 'media', 'screenshots')
+const MARKETING_OUT = join(__dirname, '..', 'playgrounds', 'simple', 'marketing', 'public', 'screenshots')
+mkdirSync(OUT, { recursive: true })
+mkdirSync(MARKETING_OUT, { recursive: true })
+
+/** Wait for the Annotask shell to be fully loaded */
+async function waitForShell(page: import('@playwright/test').Page) {
+  await page.goto('/__annotask/')
+  await page.waitForLoadState('domcontentloaded')
+  await expect(page.locator('.toolbar')).toBeVisible({ timeout: 15_000 })
+
+  // Dismiss init wizard if it appears
+  const closeBtn = page.locator('.init-modal-close')
+  try {
+    await closeBtn.click({ timeout: 3000 })
+    await page.waitForTimeout(500)
+  } catch {
+    // No init wizard — continue
+  }
+
+  // Wait for iframe app to render (SPA needs extra time)
+  const frame = page.frameLocator('.app-iframe')
+  await page.waitForTimeout(4000)
+  return frame
+}
+
+function shot(name: string) {
+  return { path: join(OUT, name), fullPage: false }
+}
+
+/** Save to both docs/media and marketing public */
+async function saveShot(page: import('@playwright/test').Page, name: string) {
+  await page.screenshot({ path: join(OUT, name), fullPage: false })
+  const { copyFileSync } = await import('fs')
+  copyFileSync(join(OUT, name), join(MARKETING_OUT, name))
+}
+
+test.describe('Marketing screenshots', () => {
+  test.describe.configure({ mode: 'serial' })
+
+  test('shell-overview', async ({ page }) => {
+    const frame = await waitForShell(page)
+    // Navigate to planets page for a richer overview shot
+    try {
+      await frame.locator('a:has-text("Planets")').first().click({ timeout: 3000 })
+      await page.waitForTimeout(3000)
+    } catch {
+      await page.waitForTimeout(1000)
+    }
+    await saveShot(page, 'shell-overview.png')
+  })
+
+  test('annotate-pins', async ({ page }) => {
+    const frame = await waitForShell(page)
+
+    // Ensure we're in Annotate view
+    await page.locator('[data-testid="tab-annotate"]').click()
+    // Switch to pin mode
+    await page.locator('[data-testid="tool-pin"]').click()
+
+    // Click several elements in the iframe to create pins
+    const targets = ['h1', 'nav a:first-child', 'nav a:nth-child(2)', '.planet-card:first-child, .card:first-child']
+    for (const selector of targets) {
+      try {
+        await frame.locator(selector).first().click({ timeout: 3000 })
+        await page.waitForTimeout(300)
+      } catch {
+        // Some elements may not exist on every route, skip
+      }
+    }
+    await page.waitForTimeout(500)
+    await saveShot(page, 'annotate-pins.png')
+  })
+
+  test('annotate-arrows', async ({ page }) => {
+    const frame = await waitForShell(page)
+
+    await page.locator('[data-testid="tab-annotate"]').click()
+    // Switch to arrow mode
+    await page.locator('[data-testid="tool-arrow"]').click()
+
+    // Draw arrows by clicking source then target elements
+    const pairs = [
+      ['h1', 'nav a:first-child'],
+      ['nav a:first-child', 'nav a:nth-child(2)'],
+    ]
+    for (const [src, tgt] of pairs) {
+      try {
+        await frame.locator(src).first().click({ timeout: 3000 })
+        await page.waitForTimeout(200)
+        await frame.locator(tgt).first().click({ timeout: 3000 })
+        await page.waitForTimeout(300)
+      } catch {
+        // Skip if elements not found
+      }
+    }
+    await page.waitForTimeout(500)
+    await saveShot(page, 'annotate-arrows.png')
+  })
+
+  test('annotate-highlights', async ({ page }) => {
+    const frame = await waitForShell(page)
+
+    await page.locator('[data-testid="tab-annotate"]').click()
+    // Switch to highlight mode
+    await page.locator('[data-testid="tool-highlight"]').click()
+
+    // Try to select text in the iframe
+    try {
+      const textEl = frame.locator('h1, h2, .header-title').first()
+      const textBox = await textEl.boundingBox()
+      if (textBox) {
+        await page.mouse.click(textBox.x + 5, textBox.y + textBox.height / 2)
+        await page.mouse.down()
+        await page.mouse.move(textBox.x + textBox.width - 5, textBox.y + textBox.height / 2, { steps: 10 })
+        await page.mouse.up()
+      }
+    } catch {
+      // Fallback — just show highlight mode active
+    }
+    await page.waitForTimeout(500)
+    await saveShot(page, 'annotate-highlights.png')
+  })
+
+  test('design-tokens', async ({ page }) => {
+    await waitForShell(page)
+    await page.locator('[data-testid="tab-design"]').click()
+    await page.locator('[data-testid="design-tokens"]').click()
+    await page.waitForTimeout(500)
+    await saveShot(page, 'design-tokens.png')
+  })
+
+  test('design-inspector', async ({ page }) => {
+    const frame = await waitForShell(page)
+    await page.locator('[data-testid="tab-design"]').click()
+    await page.locator('[data-testid="design-inspector"]').click()
+
+    // Try to select an element to show inspector
+    try {
+      const selectBtn = page.locator('[data-testid="tool-select"]')
+      if (await selectBtn.isVisible({ timeout: 2000 })) {
+        await selectBtn.click()
+      }
+      await frame.locator('h1, header, .header-title').first().click({ timeout: 3000 })
+      await page.waitForTimeout(500)
+    } catch {
+      // Element selection may not work — just show the inspector tab
+    }
+    await page.waitForTimeout(500)
+    await saveShot(page, 'design-inspector.png')
+  })
+
+  test('design-components', async ({ page }) => {
+    await waitForShell(page)
+    await page.locator('[data-testid="tab-design"]').click()
+    await page.locator('[data-testid="design-components"]').click()
+    await page.waitForTimeout(500)
+    await saveShot(page, 'design-components.png')
+  })
+
+  test('audit-a11y', async ({ page }) => {
+    await waitForShell(page)
+    await page.locator('[data-testid="tab-audit"]').click()
+    await page.locator('[data-testid="audit-a11y"]').click()
+
+    // Try to run a11y scan
+    try {
+      const scanBtn = page.locator('[data-testid="btn-scan-a11y"], button:has-text("Scan"), button:has-text("Run")')
+      await scanBtn.first().click({ timeout: 3000 })
+      await page.waitForTimeout(5000)
+    } catch {
+      // Button may not exist or scan may not complete
+      await page.waitForTimeout(1000)
+    }
+    await saveShot(page, 'audit-a11y.png')
+  })
+
+  test('audit-perf', async ({ page }) => {
+    await waitForShell(page)
+    await page.locator('[data-testid="tab-audit"]').click()
+    await page.locator('[data-testid="audit-perf"]').click()
+
+    // Try to run perf scan
+    try {
+      const scanBtn = page.locator('[data-testid="btn-scan-perf"], button:has-text("Scan"), button:has-text("Run")')
+      await scanBtn.first().click({ timeout: 3000 })
+      await page.waitForTimeout(5000)
+    } catch {
+      await page.waitForTimeout(1000)
+    }
+    await saveShot(page, 'audit-perf.png')
+  })
+
+  test('audit-errors', async ({ page }) => {
+    await waitForShell(page)
+    await page.locator('[data-testid="tab-audit"]').click()
+    await page.locator('[data-testid="audit-errors"]').click()
+    await page.waitForTimeout(1000)
+    await saveShot(page, 'audit-errors.png')
+  })
+
+  test('task-detail', async ({ page }) => {
+    const frame = await waitForShell(page)
+
+    // Create a pin to generate a task
+    await page.locator('[data-testid="tab-annotate"]').click()
+
+    try {
+      await page.locator('[data-testid="tool-pin"]').click({ timeout: 3000 })
+    } catch {
+      // Pin tool might already be active or use different selector
+    }
+
+    try {
+      await frame.locator('h1, header, .header-title').first().click({ timeout: 3000 })
+      await page.waitForTimeout(1000)
+
+      // Try to submit the pending task
+      const submitBtn = page.locator('button:has-text("Create"), button:has-text("Add Task"), button:has-text("Submit")')
+      if (await submitBtn.first().isVisible({ timeout: 2000 })) {
+        await submitBtn.first().click()
+        await page.waitForTimeout(500)
+      }
+
+      // Try to open task detail
+      const taskCard = page.locator('.task-card, [class*="task-card"], [class*="task-item"]').first()
+      if (await taskCard.isVisible({ timeout: 2000 })) {
+        await taskCard.click()
+        await page.waitForTimeout(500)
+      }
+    } catch {
+      // Show whatever state we ended up in
+    }
+    await page.waitForTimeout(500)
+    await saveShot(page, 'task-detail.png')
+  })
+})
diff --git a/e2e/vue-vite.design-apply.test.ts b/e2e/vue-vite.design-apply.test.ts
new file mode 100644
index 0000000..7b53443
--- /dev/null
+++ b/e2e/vue-vite.design-apply.test.ts
@@ -0,0 +1,106 @@
+import { test, expect } from '@playwright/test'
+import type { APIRequestContext } from '@playwright/test'
+import {
+  bootDesignShell,
+  interceptPlanetsApi,
+  skipInitWizard,
+  getDesignSession,
+  discardDesignSession,
+  resetWorkspaceState,
+} from './helpers/design-tool'
+
+const ORIGIN = 'http://localhost:5173'
+
+// Seed one pending style entry straight into the journal (the inspector UI
+// records these live; the apply loop only cares that the entry exists).
+async function seedStyleEntry(request: APIRequestContext): Promise<void> {
+  const current = await (await request.get('/__annotask/api/design-session')).json() as { sessionId?: string; rev?: number }
+  const doc = {
+    version: '1.0',
+    sessionId: current.sessionId ?? `ds-e2e-${Date.now()}`,
+    startedAt: Date.now(),
+    updatedAt: Date.now(),
+    ...(current.rev !== undefined ? { rev: current.rev } : {}),
+    entries: [
+      {
+        id: 'se-e2e-1',
+        ordinal: 1,
+        ts: Date.now(),
+        route: '/planets',
+        change: {
+          id: 'c-se-e2e-1', type: 'style_update', description: 'h1 color → blue',
+          file: 'src/pages/PlanetsPage.vue', section: 'style', line: 9,
+          element: 'h1', property: 'color', before: 'red', after: 'blue',
+        },
+        anchor: { file: 'src/pages/PlanetsPage.vue', line: 9, targetTag: 'h1' },
+        live: { status: 'pending' },
+      },
+    ],
+  }
+  const res = await request.put('/__annotask/api/design-session', {
+    headers: { Origin: ORIGIN },
+    data: doc,
+  })
+  expect(res.ok()).toBe(true)
+}
+
+// UI half of the agent-apply loop (no provider configured in e2e, so the
+// minted task waits for an agent — the full live loop is covered by
+// src/server/__tests__/apply-session-matrix.test.ts with real CLIs).
+test.describe('Vue + Vite design-session apply (UI)', () => {
+  test.beforeEach(async ({ page, request }) => {
+    await skipInitWizard(request, ORIGIN)
+    await discardDesignSession(request, ORIGIN)
+    await resetWorkspaceState(request, ORIGIN)
+    await interceptPlanetsApi(page)
+  })
+
+  test.afterEach(async ({ request }) => {
+    // Server-owned discard also unwinds anything a failing test left behind.
+    await resetWorkspaceState(request, ORIGIN)
+    await discardDesignSession(request, ORIGIN)
+  })
+
+  test('Apply now mints ONE task with context.session, snapshots the file, and statuses round-trip', async ({ page, request }) => {
+    await seedStyleEntry(request)
+    await bootDesignShell(page)
+    const frame = page.frameLocator('.app-iframe')
+    await expect(frame.locator('h1.title')).toHaveText('Planets', { timeout: 15_000 })
+
+    // The session panel lives in the Components section.
+    await page.locator('.toolbar button', { hasText: 'Components' }).click()
+    const panel = page.locator('[data-testid="design-session-panel"]')
+    await expect(panel).toBeVisible({ timeout: 10_000 })
+    await expect(panel.locator('.session-chip.pending')).toHaveCount(1)
+
+    await panel.locator('.session-apply').click()
+
+    // Entries flip to applying against a minted task + sealed snapshot batch.
+    await expect.poll(async () => {
+      const session = await getDesignSession(request)
+      return session.entries.map((e) => (e.live as { status: string }).status)
+    }, { timeout: 10_000 }).toEqual(['applying'])
+
+    const session = await getDesignSession(request)
+    const taskId = String(session.entries[0].taskId)
+    expect(taskId).toBeTruthy()
+
+    const tasks = (await (await request.get('/__annotask/api/tasks')).json()).tasks as Array<Record<string, unknown>>
+    const task = tasks.find((t) => t.id === taskId)!
+    expect(task.type).toBe('wireframe_apply')
+    const ctx = task.context as { session: { entries: Array<Record<string, unknown>> } }
+    expect(ctx.session.entries).toHaveLength(1)
+
+    const snapshots = await (await request.get('/__annotask/api/design-session/snapshots')).json() as { files: Record<string, unknown>; batches: Array<{ taskId: string }> }
+    expect(Object.keys(snapshots.files).some((f) => f.includes('PlanetsPage.vue'))).toBe(true)
+    expect(snapshots.batches[0]?.taskId).toBe(taskId)
+
+    // No agent ran (no provider in e2e): deleting the task releases the
+    // entries back to pending — the work is never silently lost.
+    await request.delete(`/__annotask/api/tasks/${taskId}`, { headers: { Origin: ORIGIN } })
+    await expect.poll(async () => {
+      const after = await getDesignSession(request)
+      return after.entries.map((e) => (e.live as { status: string }).status)
+    }, { timeout: 5_000 }).toEqual(['pending'])
+  })
+})
diff --git a/e2e/vue-vite.wireframe.test.ts b/e2e/vue-vite.wireframe.test.ts
new file mode 100644
index 0000000..2ddad61
--- /dev/null
+++ b/e2e/vue-vite.wireframe.test.ts
@@ -0,0 +1,591 @@
+import { test, expect } from '@playwright/test'
+import {
+  bootDesignShell,
+  interceptPlanetsApi,
+  skipInitWizard,
+  getDesignSession,
+  discardDesignSession,
+  resetWorkspaceState,
+  trackReloads,
+  enterWireframeMode,
+} from './helpers/design-tool'
+
+const ORIGIN = 'http://localhost:5173'
+
+// W1: Wireframe mode freezes the live route into anchored image blocks and
+// exits losslessly (the iframe never reloads — it was under the canvas the
+// whole time).
+test.describe('Vue + Vite wireframe capture (W1)', () => {
+  test.beforeEach(async ({ page, request }) => {
+    await skipInitWizard(request, ORIGIN)
+    await resetWorkspaceState(request, ORIGIN)
+    await interceptPlanetsApi(page)
+  })
+
+  test.afterEach(async ({ request }) => {
+    await resetWorkspaceState(request, ORIGIN)
+  })
+
+  test('toggle captures anchored blocks, persists the canvas, and toggling back is lossless', async ({ page, request }) => {
+    await bootDesignShell(page)
+    const frame = page.frameLocator('.app-iframe')
+    await expect(frame.locator('h1.title')).toHaveText('Planets', { timeout: 15_000 })
+
+    const reloads = trackReloads(page)
+    await enterWireframeMode(page)
+
+    // ≥3 image blocks (app header / page header / planets-content on /planets).
+    const imgs = page.locator('.wf-block img')
+    expect(await imgs.count()).toBeGreaterThanOrEqual(3)
+    // The PNGs actually decoded — not broken sources.
+    expect(await imgs.first().evaluate((el) => (el as HTMLImageElement).naturalWidth)).toBeGreaterThan(0)
+
+    // At least one block is anchored into the page component: click blocks
+    // until a chip shows PlanetsPage.vue:<line> (chips render on selection).
+    const blocks = page.locator('.wf-block')
+    const total = await blocks.count()
+    let anchored: string | null = null
+    for (let i = 0; i < total && !anchored; i++) {
+      await blocks.nth(i).click()
+      const chip = page.locator('[data-testid="wf-anchor-chip"]')
+      if (await chip.count()) {
+        const text = await chip.textContent()
+        if (text && /PlanetsPage\.vue:\d+/.test(text)) anchored = text
+      }
+    }
+    expect(anchored, 'no block carried a PlanetsPage.vue file:line anchor').toMatch(/PlanetsPage\.vue:\d+/)
+
+    // The canvas persisted server-side with anchors + snapshot filenames.
+    const wf = await (await request.get('/__annotask/api/wireframe')).json()
+    const planets = wf.routes.find((r: { route: string }) => r.route === '/planets')
+    expect(planets?.canvas?.blocks?.length).toBeGreaterThanOrEqual(3)
+    expect(planets.canvas.blocks.some((b: { image?: string }) => b.image)).toBe(true)
+    expect(planets.canvas.fullImage).toMatch(/\.png$/)
+
+    // Straggler coverage: the playground's bare <Button> sits AFTER <main> as
+    // a sibling (App.vue:48) — content outside the content root that isn't
+    // semantic chrome must still get a block, not just appear in the
+    // full-page "before" image. (anchor.file alone would false-pass: the
+    // header chrome block also anchors to App.vue via attribute fallthrough.)
+    expect(
+      planets.canvas.blocks.some((b: { kind: string; anchor?: { tag?: string } }) =>
+        b.kind === 'captured' && b.anchor?.tag === 'button'),
+      'the sibling-of-main <Button> must be captured as a block',
+    ).toBe(true)
+
+    // Lossless exit: overlay gone, live app visible, zero reloads end-to-end.
+    await page.locator('[data-testid="wf-exit"]').click()
+    await expect(page.locator('[data-testid="wireframe-canvas"]')).toHaveCount(0)
+    await expect(frame.locator('h1.title')).toHaveText('Planets')
+    expect(reloads()).toBe(0)
+  })
+
+  // W2: rearrange the sketch (resize/duplicate/note/move/palette drop/
+  // placeholder), then F5 — everything must come back as left. Blocks may
+  // legitimately overlap after a move (z-order decides), so all toolbar-block
+  // interactions happen BEFORE the big grid is dragged on top of it.
+  test('manipulation persists across a reload', async ({ page, request }) => {
+    test.setTimeout(120_000)
+    await page.setViewportSize({ width: 1600, height: 900 })
+    await bootDesignShell(page)
+    const frame = page.frameLocator('.app-iframe')
+    await expect(frame.locator('h1.title')).toHaveText('Planets', { timeout: 30_000 })
+    await enterWireframeMode(page)
+
+    type Blk = { id: string; kind: string; rect: { x: number; y: number; width: number; height: number }; originalRect?: { y: number }; anchor?: { file: string }; note?: string; duplicateOf?: string; label?: string; component?: { componentName?: string }; image?: string }
+    async function getCanvas(): Promise<{ blocks: Blk[] }> {
+      const wf = await (await request.get('/__annotask/api/wireframe')).json()
+      return wf.routes.find((r: { route: string }) => r.route === '/planets')!.canvas
+    }
+
+    // Content blocks anchored in PlanetsPage.vue, in original top-down order:
+    // page header, then the planets-content wrapper (layout + controls rail).
+    const initial = await getCanvas()
+    const content = initial.blocks
+      .filter((b) => b.anchor?.file.includes('PlanetsPage.vue'))
+      .sort((a, b) => (a.originalRect?.y ?? 0) - (b.originalRect?.y ?? 0))
+    expect(content.length).toBeGreaterThanOrEqual(2)
+    const toolbarBlk = content[content.length - 2]
+    const gridBlk = content[content.length - 1]
+
+    const blockEl = (id: string) => page.locator(`[data-block-id="${id}"]`)
+    // Top-left corner click: dodges the +16/+16 duplicate that appears later.
+    const selectBlock = (id: string) => blockEl(id).click({ position: { x: 8, y: 8 } })
+
+    // RESIZE: select the toolbar block, drag its SE handle.
+    await selectBlock(toolbarBlk.id)
+    const handle = (await page.locator('[data-testid="wf-resize-se"]').boundingBox())!
+    await page.mouse.move(handle.x + 5, handle.y + 5)
+    await page.mouse.down()
+    await page.mouse.move(handle.x + 85, handle.y + 45, { steps: 6 })
+    await page.mouse.up()
+    await expect.poll(async () => (await getCanvas()).blocks.find((b) => b.id === toolbarBlk.id)!.rect.width,
+      { timeout: 5_000 }).toBeGreaterThan(toolbarBlk.rect.width + 50)
+
+    // DUPLICATE first, then NOTE — a duplicate deep-copies the block, so the
+    // note must land after the copy exists or both blocks would carry it.
+    await selectBlock(toolbarBlk.id)
+    await page.locator('[data-testid="wf-duplicate-btn"]').click()
+    await selectBlock(toolbarBlk.id)
+    await page.locator('[data-testid="wf-note-btn"]').click()
+    await page.locator('[data-testid="wf-note-input"]').fill('make this a carousel')
+    await page.locator('[data-testid="wf-note-input"]').press('Enter')
+    await expect.poll(async () => {
+      const c = await getCanvas()
+      return {
+        dup: c.blocks.some((b) => b.duplicateOf === toolbarBlk.id),
+        note: c.blocks.find((b) => b.id === toolbarBlk.id)?.note,
+        copyNote: c.blocks.find((b) => b.duplicateOf === toolbarBlk.id)?.note,
+      }
+    }, { timeout: 5_000 }).toEqual({ dup: true, note: 'make this a carousel', copyNote: undefined })
+
+    // MOVE: drag the grid block above the filters toolbar (it will cover it —
+    // that's a sketch, overlaps are fine). Grab the grid by its BOTTOM strip:
+    // the z-topped duplicate from the previous step overlaps its upper half.
+    const gridBox = (await blockEl(gridBlk.id).boundingBox())!
+    const grabY = gridBox.y + gridBox.height - 12
+    const upBy = gridBlk.rect.y - toolbarBlk.rect.y + 24
+    await page.mouse.move(gridBox.x + gridBox.width / 2, grabY)
+    await page.mouse.down()
+    await page.mouse.move(gridBox.x + gridBox.width / 2, grabY - upBy, { steps: 10 })
+    await page.mouse.up()
+    await expect.poll(async () => {
+      const c = await getCanvas()
+      const grid = c.blocks.find((b) => b.id === gridBlk.id)!
+      const toolbar = c.blocks.find((b) => b.id === toolbarBlk.id)!
+      return grid.rect.y < toolbar.rect.y
+    }, { timeout: 5_000 }).toBe(true)
+
+    // PLACEHOLDER: draw a labeled box in the strip the grid vacated when it
+    // moved up (the stage is exactly as wide as the iframe — there is no free
+    // margin to the right). Synthetic pointer events: dispatched events skip
+    // hit-testing, so overlapping panels/scroll position can't flake this.
+    const stage = (await page.locator('.wf-stage').boundingBox())!
+    const gridOrigBottom = gridBlk.rect.y + gridBlk.rect.height
+    await page.locator('[data-testid="wf-draw-placeholder"]').click()
+    await page.evaluate(({ sx, sy, x1, y1, x2, y2 }) => {
+      const stageEl = document.querySelector('.wf-stage') as HTMLElement
+      const ev = (type: string, x: number, y: number) =>
+        new PointerEvent(type, { bubbles: true, clientX: sx + x, clientY: sy + y })
+      stageEl.dispatchEvent(ev('pointerdown', x1, y1))
+      window.dispatchEvent(ev('pointermove', x2, y2))
+      window.dispatchEvent(ev('pointerup', x2, y2))
+    }, { sx: stage.x, sy: stage.y, x1: 80, y1: gridOrigBottom - 70, x2: 420, y2: gridOrigBottom - 10 })
+    await page.locator('[data-testid="wf-placeholder-label"]').fill('pagination here')
+    await page.locator('[data-testid="wf-placeholder-label"]').press('Enter')
+    await expect.poll(async () => (await getCanvas()).blocks.find((b) => b.kind === 'placeholder')?.label,
+      { timeout: 5_000 }).toBe('pagination here')
+
+    // PALETTE DROP (place-first): synthetic HTML5 drag of the Header project
+    // component — string props mount standalone, so the live regen yields a REAL
+    // snapshot (a data-bound component like PlanetCard would honestly degrade to
+    // a placeholder render here). The drop MINTS the block instantly at the drop
+    // point and auto-selects it; the inline config popover opens and the snapshot
+    // fills in live (debounced) — no separate generate/place click.
+    await page.locator('.toolbar button', { hasText: 'Components' }).click()
+    const paletteItem = page.locator('.components-list-item[data-component-name="Header"]').first()
+    await paletteItem.waitFor({ state: 'visible', timeout: 15_000 })
+    await page.evaluate(({ dropX, dropY }) => {
+      const item = document.querySelector('.components-list-item[data-component-name="Header"]') as HTMLElement
+      const scroll = document.querySelector('.wf-scroll') as HTMLElement
+      const dt = new DataTransfer()
+      item.dispatchEvent(new DragEvent('dragstart', { bubbles: true, dataTransfer: dt }))
+      scroll.dispatchEvent(new DragEvent('dragover', { bubbles: true, cancelable: true, dataTransfer: dt, clientX: dropX, clientY: dropY }))
+      scroll.dispatchEvent(new DragEvent('drop', { bubbles: true, cancelable: true, dataTransfer: dt, clientX: dropX, clientY: dropY }))
+    }, { dropX: stage.x + 500, dropY: stage.y + gridOrigBottom - 50 })
+    // The block mints synchronously and auto-selects → the inline popover opens.
+    await page.locator('[data-testid="wf-block-popover"]').waitFor({ state: 'visible', timeout: 15_000 })
+    await expect.poll(async () => {
+      const b = (await getCanvas()).blocks.find((x) => x.kind === 'palette')
+      return b?.component?.componentName
+    }, { timeout: 15_000 }).toBe('Header')
+    // The live regen produced a REAL snapshot PNG (sidecar-persisted under the
+    // block id) — this is the same evidence the old gen-preview-img check made.
+    await expect.poll(async () => (await getCanvas()).blocks.find((x) => x.kind === 'palette')?.image,
+      { timeout: 20_000 }).toMatch(/\.png$/)
+    // Close the popover (deselect) so the reload measures a clean canvas.
+    await page.locator('[data-testid="wf-pop-close"]').click()
+
+    // F5 — the sketch must come back exactly as left.
+    const before = await getCanvas()
+    await page.reload({ waitUntil: 'domcontentloaded' })
+    await page.locator('.toolbar').waitFor({ state: 'visible', timeout: 15_000 })
+    await page.locator('[data-testid="wireframe-canvas"]').waitFor({ state: 'visible', timeout: 15_000 })
+    await page.waitForTimeout(1_000)
+
+    const visible = before.blocks.filter((b) => !(b as { deleted?: boolean }).deleted)
+    expect(await page.locator('.wf-block').count()).toBe(visible.length)
+    // Moved grid is rendered at its persisted (moved) position.
+    const gridAfter = (await getCanvas()).blocks.find((b) => b.id === gridBlk.id)!
+    const domTop = await blockEl(gridBlk.id).evaluate((el) => parseInt((el as HTMLElement).style.top, 10))
+    expect(domTop).toBe(Math.round(gridAfter.rect.y))
+    // The palette snapshot reloads from its sidecar PNG.
+    const paletteBlk = before.blocks.find((b) => b.kind === 'palette')!
+    expect(paletteBlk.image, 'Header must produce a real snapshot file').toMatch(/\.png$/)
+    expect(await blockEl(paletteBlk.id).locator('img').evaluate((el) => (el as HTMLImageElement).naturalWidth)).toBeGreaterThan(0)
+    // Placeholder + note chip survived.
+    await expect(page.locator('.wf-placeholder-label')).toHaveText('pagination here')
+    await expect(page.locator('.wf-note-chip')).toHaveCount(1)
+  })
+
+  // D4: the place-first config popover binds a REAL data source through the
+  // picker's shape tree (the playground ships a discoverable OpenAPI file, so
+  // usePlanets resolves 'api-schema' without the FastAPI running), live-
+  // regenerates the snapshot, survives a reload, and regenerates in place when
+  // the popover is reopened on the existing block.
+  // Data binding is gated off this release (see wireframeFeatures.ts →
+  // WIREFRAME_DATA_BINDING_ENABLED); re-enable this spec when the flag flips on.
+  test.skip('place-first config binds a data source and survives reload', async ({ page, request }) => {
+    test.setTimeout(120_000)
+    await page.setViewportSize({ width: 1600, height: 900 })
+    await bootDesignShell(page)
+    const frame = page.frameLocator('.app-iframe')
+    await expect(frame.locator('h1.title')).toHaveText('Planets', { timeout: 30_000 })
+    await enterWireframeMode(page)
+
+    type Blk = { id: string; kind: string; component?: { componentName?: string }; data?: Record<string, unknown>; image?: string }
+    async function getCanvas(): Promise<{ blocks: Blk[] }> {
+      const wf = await (await request.get('/__annotask/api/wireframe')).json()
+      return wf.routes.find((r: { route: string }) => r.route === '/planets')!.canvas
+    }
+    const paletteBlock = async () => (await getCanvas()).blocks.find((b) => b.kind === 'palette')
+
+    // Drop Header → the block mints instantly at the drop point, auto-selects,
+    // and the inline config popover opens in place.
+    await page.locator('.toolbar button', { hasText: 'Components' }).click()
+    await page.locator('.components-list-item[data-component-name="Header"]').first().waitFor({ state: 'visible', timeout: 15_000 })
+    const stage = (await page.locator('.wf-stage').boundingBox())!
+    await page.evaluate(({ dropX, dropY }) => {
+      const item = document.querySelector('.components-list-item[data-component-name="Header"]') as HTMLElement
+      const scroll = document.querySelector('.wf-scroll') as HTMLElement
+      const dt = new DataTransfer()
+      item.dispatchEvent(new DragEvent('dragstart', { bubbles: true, dataTransfer: dt }))
+      scroll.dispatchEvent(new DragEvent('dragover', { bubbles: true, cancelable: true, dataTransfer: dt, clientX: dropX, clientY: dropY }))
+      scroll.dispatchEvent(new DragEvent('drop', { bubbles: true, cancelable: true, dataTransfer: dt, clientX: dropX, clientY: dropY }))
+    }, { dropX: stage.x + 300, dropY: stage.y + 300 })
+    await page.locator('[data-testid="wf-block-popover"]').waitFor({ state: 'visible', timeout: 15_000 })
+    await expect.poll(async () => (await paletteBlock())?.component?.componentName, { timeout: 15_000 }).toBe('Header')
+    const placedId = (await paletteBlock())!.id
+
+    // Bind from the popover: open the picker, pick usePlanets, drill the REAL
+    // shape tree to planets[], narrow the fields to name + type.
+    await page.locator('[data-testid="wf-pop-bind"]').click()
+    await page.locator('[data-testid="binding-picker"]').waitFor({ state: 'visible', timeout: 10_000 })
+    await page.locator('[data-testid="binding-row-usePlanets"]').click()
+    await page.locator('[data-testid="binding-shape-tree"]').waitFor({ state: 'visible', timeout: 15_000 })
+    await expect(page.locator('.bp-shape-tag')).toHaveClass(/api-schema/)
+    await page.locator('.bp-tree-row .bp-twisty').first().click() // expand (response)
+    await page.locator('.bp-tree-row', { hasText: 'planets' }).click() // path = planets[]
+    await page.locator('[data-testid="binding-field-name"]').check()
+    await page.locator('[data-testid="binding-field-type"]').check()
+    await page.locator('[data-testid="binding-confirm"]').click()
+    // The popover's bound-source chip reflects the new binding.
+    await expect(page.locator('[data-testid="wf-pop-binding"]')).toContainText('usePlanets')
+
+    // The binding landed on the persisted block with the REAL drilled shape.
+    let placed: Blk | undefined
+    await expect.poll(async () => {
+      placed = await paletteBlock()
+      return placed?.data?.name
+    }, { timeout: 15_000 }).toBe('usePlanets')
+    expect(placed!.id).toBe(placedId)
+    expect(placed!.component?.componentName).toBe('Header')
+    expect(placed!.data).toMatchObject({
+      name: 'usePlanets',
+      path: 'planets[]',
+      fields: ['name', 'type'],
+      shape_source: 'api-schema',
+    })
+    // Binding live-regenerated the snapshot on the app-true surface → real PNG.
+    await expect.poll(async () => (await paletteBlock())?.image, { timeout: 20_000 }).toMatch(/\.png$/)
+    // Close the popover so the reload measures a clean canvas.
+    await page.locator('[data-testid="wf-pop-close"]').click()
+
+    // F5 — block, data chip, and snapshot all restore.
+    await page.reload({ waitUntil: 'domcontentloaded' })
+    await page.locator('.toolbar').waitFor({ state: 'visible', timeout: 15_000 })
+    await page.locator('[data-testid="wireframe-canvas"]').waitFor({ state: 'visible', timeout: 15_000 })
+    await page.waitForTimeout(1_000)
+    const blockEl = page.locator(`[data-block-id="${placedId}"]`)
+    await expect(page.locator(`[data-testid="wf-data-chip-${placedId}"]`)).toContainText('usePlanets')
+    expect(await blockEl.locator('img').evaluate((el) => (el as HTMLImageElement).naturalWidth)).toBeGreaterThan(0)
+
+    // RECONFIGURE IN PLACE: re-select the block (top-left corner — the gear is
+    // gone) to reopen the popover; the binding is intact, and nudging the loop
+    // repeat regenerates the snapshot without losing the binding.
+    const imgBefore = await blockEl.locator('img').getAttribute('src')
+    await blockEl.click({ position: { x: 8, y: 8 } })
+    await page.locator('[data-testid="wf-block-popover"]').waitFor({ state: 'visible', timeout: 10_000 })
+    await expect(page.locator('[data-testid="wf-pop-binding"]')).toContainText('usePlanets')
+    // planets[] is a list binding with bound fields → the repeat control shows
+    // once the catalog (re)loads the block's typed prop rows.
+    await page.locator('[data-testid="wf-pop-repeat"]').waitFor({ state: 'visible', timeout: 10_000 })
+    await page.locator('[data-testid="wf-pop-repeat"]').fill('4')
+    await page.locator('[data-testid="wf-pop-repeat"]').press('Enter')
+    // The repeat persisted and a fresh snapshot was re-uploaded (new filename),
+    // with the binding still intact.
+    await expect.poll(async () => (await paletteBlock())?.data?.repeat, { timeout: 10_000 }).toBe(4)
+    await expect.poll(async () => {
+      const b = await paletteBlock()
+      return b?.data?.name && b?.image
+    }, { timeout: 20_000 }).toMatch(/\.png$/)
+    await expect.poll(async () => blockEl.locator('img').getAttribute('src'), { timeout: 20_000 }).not.toBe(imgBefore)
+    await expect(page.locator(`[data-testid="wf-data-chip-${placedId}"]`)).toContainText('usePlanets')
+    expect(await blockEl.locator('img').evaluate((el) => (el as HTMLImageElement).naturalWidth)).toBeGreaterThan(0)
+    expect((await paletteBlock())!.data).toMatchObject({ name: 'usePlanets', path: 'planets[]', shape_source: 'api-schema' })
+  })
+
+  // W4: marquee multi-select, group nudge, explode-to-children, viewport label.
+  test('multi-select and group-nudge refine the sketch', async ({ page, request }) => {
+    test.setTimeout(120_000)
+    await bootDesignShell(page)
+    const frame = page.frameLocator('.app-iframe')
+    await expect(frame.locator('h1.title')).toHaveText('Planets', { timeout: 30_000 })
+    await enterWireframeMode(page)
+
+    await expect(page.locator('[data-testid="wf-viewport"]')).toHaveText(/^\d+×\d+ @[\d.]+x$/)
+
+    type Blk = { id: string; rect: { x: number; y: number; width: number; height: number }; originalRect?: { y: number }; anchor?: { file: string; line: number; cssClass?: string } }
+    async function getBlocks(): Promise<Blk[]> {
+      const wf = await (await request.get('/__annotask/api/wireframe')).json()
+      return wf.routes.find((r: { route: string }) => r.route === '/planets')!.canvas.blocks
+    }
+    const initial = await getBlocks()
+    const content = initial
+      .filter((b) => b.anchor?.file.includes('PlanetsPage.vue'))
+      .sort((a, b) => (a.originalRect?.y ?? 0) - (b.originalRect?.y ?? 0))
+    const headerBlk = content[0]
+    const gridBlk = content[content.length - 1]
+
+    // MARQUEE over the page header + content wrapper (synthetic events skip
+    // hit-testing).
+    await page.evaluate(({ x1, y1, x2, y2 }) => {
+      const stageEl = document.querySelector('.wf-stage') as HTMLElement
+      const r = stageEl.getBoundingClientRect()
+      const ev = (type: string, x: number, y: number) =>
+        new PointerEvent(type, { bubbles: true, clientX: r.left + x, clientY: r.top + y })
+      stageEl.dispatchEvent(ev('pointerdown', x1, y1))
+      window.dispatchEvent(ev('pointermove', x2, y2))
+      window.dispatchEvent(ev('pointerup', x2, y2))
+    }, { x1: 2, y1: headerBlk.rect.y + 2, x2: headerBlk.rect.x + headerBlk.rect.width - 2, y2: gridBlk.rect.y + gridBlk.rect.height - 2 })
+    const selected = await page.locator('.wf-block.selected').count()
+    expect(selected).toBeGreaterThanOrEqual(2)
+
+    // GROUP NUDGE: Shift+ArrowDown moves every selected block 10px.
+    await page.locator('[data-testid="wireframe-canvas"]').press('Shift+ArrowDown')
+    await expect.poll(async () => {
+      const blocks = await getBlocks()
+      return {
+        header: blocks.find((b) => b.id === headerBlk.id)!.rect.y,
+        grid: blocks.find((b) => b.id === gridBlk.id)!.rect.y,
+      }
+    }, { timeout: 5_000 }).toEqual({ header: headerBlk.rect.y + 10, grid: gridBlk.rect.y + 10 })
+
+    // NOTE: explode-to-children is gated off this release (see
+    // src/shell/wireframeFeatures.ts → WIREFRAME_EXPLODE_ENABLED). The
+    // double-click/explode assertions move back here when the flag flips on.
+  })
+})
+
+// Lives in this FILE deliberately: Playwright distributes separate spec files
+// across parallel workers, and these suites share one dev server's wireframe
+// document — same-file tests are the serialization boundary.
+// W3 UI half of "Implement this wireframe" (no provider configured in e2e, so
+// the minted task waits for an agent — the full live loop is covered by
+// src/server/__tests__/apply-session-matrix.test.ts with real CLIs).
+test.describe('Vue + Vite wireframe implement (W3 UI)', () => {
+  test.beforeEach(async ({ page, request }) => {
+    await skipInitWizard(request, ORIGIN)
+    await discardDesignSession(request, ORIGIN)
+    await resetWorkspaceState(request, ORIGIN)
+    await interceptPlanetsApi(page)
+  })
+
+  test.afterEach(async ({ request }) => {
+    await resetWorkspaceState(request, ORIGIN)
+    await discardDesignSession(request, ORIGIN)
+  })
+
+  test('Implement mints ONE direction task with a composite screenshot; deleting it unlocks the sketch', async ({ page, request }) => {
+    test.setTimeout(120_000)
+    await bootDesignShell(page)
+    const frame = page.frameLocator('.app-iframe')
+    await expect(frame.locator('h1.title')).toHaveText('Planets', { timeout: 30_000 })
+    await enterWireframeMode(page)
+
+    type Blk = { id: string; kind: string; rect: { x: number; y: number; width: number; height: number }; originalRect?: { y: number }; anchor?: { file: string } }
+    async function getCanvas(): Promise<{ status?: string; taskId?: string; blocks: Blk[] }> {
+      const wf = await (await request.get('/__annotask/api/wireframe')).json()
+      return wf.routes.find((r: { route: string }) => r.route === '/planets')!.canvas
+    }
+
+    const initial = await getCanvas()
+    const content = initial.blocks
+      .filter((b) => b.anchor?.file.includes('PlanetsPage.vue'))
+      .sort((a, b) => (a.originalRect?.y ?? 0) - (b.originalRect?.y ?? 0))
+    expect(content.length).toBeGreaterThanOrEqual(2)
+    const toolbarBlk = content[content.length - 2]
+    const gridBlk = content[content.length - 1]
+
+    // MOVE the grid above the filters toolbar (real mouse drag, bottom grab).
+    const gridBox = (await page.locator(`[data-block-id="${gridBlk.id}"]`).boundingBox())!
+    const grabY = gridBox.y + gridBox.height - 12
+    const upBy = gridBlk.rect.y - toolbarBlk.rect.y + 24
+    await page.mouse.move(gridBox.x + gridBox.width / 2, grabY)
+    await page.mouse.down()
+    await page.mouse.move(gridBox.x + gridBox.width / 2, grabY - upBy, { steps: 10 })
+    await page.mouse.up()
+
+    // PLACEHOLDER in the vacated strip (synthetic events skip hit-testing).
+    const stage = (await page.locator('.wf-stage').boundingBox())!
+    const gridOrigBottom = gridBlk.rect.y + gridBlk.rect.height
+    await page.locator('[data-testid="wf-draw-placeholder"]').click()
+    await page.evaluate(({ sx, sy, x1, y1, x2, y2 }) => {
+      const stageEl = document.querySelector('.wf-stage') as HTMLElement
+      const ev = (type: string, x: number, y: number) =>
+        new PointerEvent(type, { bubbles: true, clientX: sx + x, clientY: sy + y })
+      stageEl.dispatchEvent(ev('pointerdown', x1, y1))
+      window.dispatchEvent(ev('pointermove', x2, y2))
+      window.dispatchEvent(ev('pointerup', x2, y2))
+    }, { sx: stage.x, sy: stage.y, x1: 80, y1: gridOrigBottom - 70, x2: 420, y2: gridOrigBottom - 10 })
+    await page.locator('[data-testid="wf-placeholder-label"]').fill('pagination here')
+    await page.locator('[data-testid="wf-placeholder-label"]').press('Enter')
+
+    // IMPLEMENT: directions + composite + ONE wireframe_apply task.
+    await page.locator('[data-testid="wf-implement"]').click()
+    await expect(page.locator('[data-testid="wf-building"]')).toBeVisible({ timeout: 30_000 })
+
+    const session = await getDesignSession(request)
+    const directions = session.entries.filter((e) => (e.change as { type: string }).type === 'wireframe_direction')
+    expect(directions.length).toBeGreaterThanOrEqual(2) // move + add (other blocks may have jittered)
+    expect(directions.every((e) => (e.live as { status: string }).status === 'applying')).toBe(true)
+    const taskId = String(directions[0].taskId)
+
+    const tasks = (await (await request.get('/__annotask/api/tasks')).json()).tasks as Array<Record<string, unknown>>
+    const wireframeTasks = tasks.filter((t) => t.type === 'wireframe_apply')
+    expect(wireframeTasks).toHaveLength(1)
+    const task = wireframeTasks[0]
+    expect(task.id).toBe(taskId)
+    expect(String(task.description)).toContain('Implement the wireframe sketch on /planets')
+    // The composite screenshot rode along and is fetchable.
+    expect(String(task.screenshot)).toMatch(/\.png$/)
+    const shot = await request.get(`/__annotask/screenshots/${task.screenshot}`)
+    expect(shot.status()).toBe(200)
+
+    // The canvas locked to the task; snapshot batch exists.
+    const locked = await getCanvas()
+    expect(locked.status).toBe('building')
+    expect(locked.taskId).toBe(taskId)
+    const snapshots = await (await request.get('/__annotask/api/design-session/snapshots')).json() as { batches: Array<{ taskId: string }> }
+    expect(snapshots.batches[0]?.taskId).toBe(taskId)
+
+    // No agent ran: deleting the task releases the directions and unlocks the
+    // sketch for tweak-and-re-implement.
+    await request.delete(`/__annotask/api/tasks/${taskId}`, { headers: { Origin: ORIGIN } })
+    await expect.poll(async () => {
+      const after = await getDesignSession(request)
+      const dirs = after.entries.filter((e) => (e.change as { type: string }).type === 'wireframe_direction')
+      return dirs.map((e) => (e.live as { status: string }).status)
+    }, { timeout: 5_000 }).toEqual(directions.map(() => 'pending'))
+    await expect.poll(async () => (await getCanvas()).status ?? 'sketch', { timeout: 5_000 }).toBe('sketch')
+    await expect(page.locator('[data-testid="wf-implement"]')).toBeVisible({ timeout: 10_000 })
+  })
+
+  // D6: a drawn SECTION (md spec + data binding) survives F5 and rides the
+  // implement task's add direction with VERBATIM added.md/.data.
+  // Data binding is gated off this release (see wireframeFeatures.ts →
+  // WIREFRAME_DATA_BINDING_ENABLED). The drawn-section + md half stays shippable;
+  // re-enable this combined spec when binding flips back on.
+  test.skip('a section with md + binding implements into ONE task carrying both verbatim', async ({ page, request }) => {
+    test.setTimeout(120_000)
+    await bootDesignShell(page)
+    const frame = page.frameLocator('.app-iframe')
+    await expect(frame.locator('h1.title')).toHaveText('Planets', { timeout: 30_000 })
+    await enterWireframeMode(page)
+
+    type Blk = { id: string; kind: string; label?: string; md?: string; data?: Record<string, unknown> }
+    async function getCanvas(): Promise<{ blocks: Blk[] }> {
+      const wf = await (await request.get('/__annotask/api/wireframe')).json()
+      return wf.routes.find((r: { route: string }) => r.route === '/planets')!.canvas
+    }
+
+    // Draw the section in free space below the content.
+    const stage = (await page.locator('.wf-stage').boundingBox())!
+    await page.locator('[data-testid="wf-draw-placeholder"]').click()
+    await page.evaluate(({ sx, sy }) => {
+      const stageEl = document.querySelector('.wf-stage') as HTMLElement
+      const ev = (type: string, x: number, y: number) =>
+        new PointerEvent(type, { bubbles: true, clientX: sx + x, clientY: sy + y })
+      stageEl.dispatchEvent(ev('pointerdown', 60, 460))
+      window.dispatchEvent(ev('pointermove', 420, 580))
+      window.dispatchEvent(ev('pointerup', 420, 580))
+    }, { sx: stage.x, sy: stage.y })
+    await page.locator('[data-testid="wf-placeholder-label"]').fill('related planets')
+    await page.locator('[data-testid="wf-placeholder-label"]').press('Enter')
+    let secId = ''
+    await expect.poll(async () => {
+      const ph = (await getCanvas()).blocks.find((b) => b.kind === 'placeholder')
+      secId = ph?.id ?? ''
+      return ph?.label
+    }, { timeout: 5_000 }).toBe('related planets')
+
+    // Markdown spec.
+    const md = '## Related planets\n- name and type for each'
+    await page.locator(`[data-block-id="${secId}"]`).click({ position: { x: 8, y: 8 } })
+    await page.locator('[data-testid="wf-md-btn"]').click()
+    await page.locator('[data-testid="wf-md-input"]').fill(md)
+    await page.locator('[data-testid="wf-md-save"]').click()
+
+    // Binding through the picker's REAL shape tree (the playground's OpenAPI
+    // file resolves usePlanets to 'api-schema' without the FastAPI running).
+    await page.locator(`[data-block-id="${secId}"]`).click({ position: { x: 8, y: 8 } })
+    await page.locator('[data-testid="wf-data-btn"]').click()
+    await page.locator('[data-testid="binding-row-usePlanets"]').click()
+    await page.locator('[data-testid="binding-shape-tree"]').waitFor({ state: 'visible', timeout: 15_000 })
+    await page.locator('.bp-tree-row .bp-twisty').first().click()
+    await page.locator('.bp-tree-row', { hasText: 'planets' }).click()
+    await page.locator('[data-testid="binding-field-name"]').check()
+    await page.locator('[data-testid="binding-field-type"]').check()
+    await page.locator('[data-testid="binding-confirm"]').click()
+    await expect.poll(async () => (await getCanvas()).blocks.find((b) => b.id === secId)?.data?.name,
+      { timeout: 5_000 }).toBe('usePlanets')
+
+    // F5 — md + binding restore before implementing.
+    await page.reload({ waitUntil: 'domcontentloaded' })
+    await page.locator('[data-testid="wireframe-canvas"]').waitFor({ state: 'visible', timeout: 15_000 })
+    await page.waitForTimeout(1_000)
+    const restored = (await getCanvas()).blocks.find((b) => b.id === secId)!
+    expect(restored.md).toBe(md)
+    expect(restored.data).toMatchObject({ name: 'usePlanets', path: 'planets[]', shape_source: 'api-schema' })
+
+    // IMPLEMENT — ONE task; the add direction carries md + data VERBATIM.
+    await page.locator('[data-testid="wf-implement"]').click()
+    await expect(page.locator('[data-testid="wf-building"]')).toBeVisible({ timeout: 30_000 })
+
+    const session = await getDesignSession(request)
+    type AddChange = { type: string; op?: string; description?: string; added?: { md?: string; data?: Record<string, unknown> } }
+    const add = session.entries.find((e) => {
+      const c = e.change as AddChange
+      return c.type === 'wireframe_direction' && c.op === 'add'
+    })!
+    const change = add.change as AddChange
+    expect(change.added!.md).toBe(md)
+    expect(change.added!.data).toMatchObject({
+      kind: 'composable',
+      name: 'usePlanets',
+      path: 'planets[]',
+      fields: ['name', 'type'],
+      shape_source: 'api-schema',
+    })
+    expect(String(change.description)).toContain('first line: "Related planets"')
+    expect(String(change.description)).toContain('bind to the composable usePlanets')
+
+    const tasks = (await (await request.get('/__annotask/api/tasks')).json()).tasks as Array<Record<string, unknown>>
+    const wireframeTasks = tasks.filter((t) => t.type === 'wireframe_apply')
+    expect(wireframeTasks).toHaveLength(1)
+
+    // No agent in e2e: delete to unlock (the live loop is the matrix test's job).
+    await request.delete(`/__annotask/api/tasks/${wireframeTasks[0].id}`, { headers: { Origin: ORIGIN } })
+    await expect(page.locator('[data-testid="wf-implement"]')).toBeVisible({ timeout: 10_000 })
+  })
+})
diff --git a/justfile b/justfile
index 54ebfc2..0c9033f 100644
--- a/justfile
+++ b/justfile
@@ -74,6 +74,10 @@ svelte: ensure-api
 mfe: ensure-api
     pnpm dev:mfe-vite
 
+# Start the Annotask marketing page (live stats need the API)
+marketing: ensure-api
+    pnpm dev:marketing
+
 # Start shell UI in standalone dev mode
 shell:
     pnpm dev:shell
@@ -98,6 +102,7 @@ list:
     @echo "  just react        — React + Vite         (port 5174)"
     @echo "  just svelte       — Svelte + Vite        (port 5175)"
     @echo "  just mfe          — MFE + Vite           (port 5180, MFE mode)"
+  @echo "  just marketing    — Annotask marketing   (port 5181)"
     @echo "  just stop-api     — Stop background API"
     @echo ""
     @echo "The API auto-starts in the background when you run a playground."
diff --git a/package.json b/package.json
index 839095f..2690fd8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "annotask",
-  "version": "0.2.6",
+  "version": "0.4.0",
   "description": "Visual UI design tool for web apps. Make changes in the browser and generate structured reports that AI agents can apply to source code. Works with Vue, React, Svelte, SolidJS, and plain HTML via Vite or Webpack.",
   "license": "MIT",
   "type": "module",
@@ -34,6 +34,7 @@
     "build:shell": "vite build --config vite.config.shell.ts",
     "build:plugin": "tsup",
     "build:vendor": "node scripts/copy-vendor.mjs",
+    "sync:skills": "node scripts/sync-skills.mjs",
     "dev:shell": "vite --config vite.config.shell.ts",
     "dev:vue-vite": "pnpm --filter @annotask/playground-vue-vite dev",
     "dev:vue-primevue": "pnpm --filter @annotask/playground-vue-primevue dev",
@@ -46,6 +47,7 @@
     "dev:solid-vite": "pnpm --filter @annotask/playground-solid-vite dev",
     "dev:htmx-vite": "pnpm --filter @annotask/playground-htmx-vite dev",
     "dev:mfe-vite": "pnpm --filter @annotask/playground-mfe-vite dev",
+    "dev:marketing": "pnpm --filter @annotask/playground-marketing dev",
     "dev:stress-host": "pnpm --filter @annotask/stress-host dev",
     "dev:stress-vue-data-lab": "pnpm --filter @annotask/stress-mfe-vue-data-lab dev",
     "dev:stress-react-workflows": "pnpm --filter @annotask/stress-mfe-react-workflows dev",
@@ -64,14 +66,38 @@
     "typecheck": "tsc --noEmit && vue-tsc --noEmit -p src/shell/tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:e2e": "playwright test"
+    "test:e2e": "playwright test",
+    "screenshots": "npx playwright test --project=screenshots",
+    "demo:reset": "bash scripts/demo-reset.sh",
+    "demo:reset:hero": "bash scripts/demo-reset-hero.sh",
+    "demo:restore": "bash scripts/demo-restore.sh",
+    "test:live-providers": "ANNOTASK_LIVE_CLI=1 vitest run src/embedded/__tests__/cli-providers-live.test.ts",
+    "test:cli-matrix:stress": "vitest run src/server/__tests__/init-cli-matrix-stress.test.ts",
+    "test:apply-matrix": "vitest run src/server/__tests__/apply-cli-matrix.test.ts"
   },
   "pnpm": {
     "overrides": {
       "follow-redirects": ">=1.16.0",
       "defu": ">=6.1.5",
       "lodash": ">=4.18.0",
-      "dompurify": ">=3.4.0"
+      "dompurify": ">=3.4.9",
+      "shell-quote": ">=1.8.4",
+      "fast-uri": ">=3.1.2",
+      "devalue": ">=5.8.1",
+      "undici": ">=7.28.0 <8",
+      "react-router": ">=7.15.1 <8",
+      "react-router-dom": ">=7.15.1 <8",
+      "ws": ">=8.21.0",
+      "vite": ">=6.4.3 <7",
+      "postcss": ">=8.5.10",
+      "svelte": ">=5.55.7 <6",
+      "js-yaml": ">=4.2.0 <5",
+      "qs": ">=6.15.2 <7",
+      "uuid": ">=11.1.1 <12",
+      "launch-editor": ">=2.14.1",
+      "webpack-dev-server": ">=5.2.5 <6",
+      "http-proxy-middleware": ">=2.0.10 <3",
+      "@babel/core": ">=7.29.6"
     }
   },
   "engines": {
@@ -110,7 +136,15 @@
     }
   },
   "dependencies": {
-    "ws": "^8.20.0",
+    "@codemirror/commands": "^6.10.3",
+    "@codemirror/lang-markdown": "^6.5.0",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/search": "^6.7.0",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.43.0",
+    "@lezer/highlight": "^1.2.3",
+    "codemirror": "^6.0.2",
+    "ws": "^8.21.0",
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2"
   },
@@ -119,6 +153,7 @@
     "@babel/parser": "^7.0.0",
     "@playwright/test": "^1.58.2",
     "@types/js-yaml": "^4.0.9",
+    "@types/jsdom": "^28.0.3",
     "@types/node": "^25.5.0",
     "@types/prismjs": "^1.26.6",
     "@types/ws": "^8.18.1",
@@ -134,6 +169,7 @@
     "marked": "^17.0.5",
     "prismjs": "^1.30.0",
     "svelte": "^5.0.0",
+    "testreel": "^0.2.0",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vite": "^6.4.2",
diff --git a/playgrounds/simple/astro/package.json b/playgrounds/simple/astro/package.json
index 180165e..6b4fa1b 100644
--- a/playgrounds/simple/astro/package.json
+++ b/playgrounds/simple/astro/package.json
@@ -7,7 +7,7 @@
     "dev": "astro dev"
   },
   "dependencies": {
-    "astro": "^5.0.0"
+    "astro": "^6.0.0"
   },
   "devDependencies": {
     "annotask": "workspace:*"
diff --git a/playgrounds/simple/justfile b/playgrounds/simple/justfile
index dbe321b..8b9a14f 100644
--- a/playgrounds/simple/justfile
+++ b/playgrounds/simple/justfile
@@ -63,6 +63,33 @@ mfe:
 start name:
     cd {{name}} && pnpm dev
 
+# Clear Annotask init artifacts for a playground (e.g. just clear-init vue-vite)
+clear-init name:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    dir="{{name}}"
+    if [ ! -d "$dir" ]; then
+        echo "[Annotask] Playground not found: $dir" >&2
+        exit 1
+    fi
+    if [ ! -d "$dir/.annotask" ]; then
+        echo "[Annotask] No init state to clear for $dir"
+        exit 0
+    fi
+    rm -f "$dir/.annotask/design-spec.json"
+    rm -f "$dir/.annotask/STYLE_GUIDE.md"
+    rm -f "$dir/.annotask/agents.json"
+    rm -f "$dir/.annotask/usage.jsonl"
+    rm -f "$dir/.annotask/runtime-endpoints.json"
+    rm -rf "$dir/.annotask/cache"
+    # Drop a sentinel that tells the shell to wipe browser-side state
+    # (localStorage: workflow choice, provider settings, theme, route cache)
+    # on its next load. The dev server returns `sessionReset: true` from
+    # /__annotask/api/status until App.vue acknowledges via DELETE.
+    touch "$dir/.annotask/.session-reset"
+    echo "[Annotask] Cleared init state for $dir"
+    echo "[Annotask] Browser localStorage will reset on next shell load (refresh http://localhost:5173/__annotask/)."
+
 # Install dependencies for all playgrounds
 install:
     cd .. && pnpm install
@@ -92,6 +119,7 @@ list:
     @echo "  just htmx         — htmx + Vite          (port 5178)"
     @echo "  just mfe          — MFE + Vite           (port 5180, MFE mode)"
     @echo "  just start <dir>  — Any playground by directory name"
+    @echo "  just clear-init <dir> — Clear Annotask init state for a playground"
     @echo "  just stop-api     — Stop background API"
     @echo ""
     @echo "The API auto-starts in the background when you run a playground."
diff --git a/playgrounds/simple/marketing/index.html b/playgrounds/simple/marketing/index.html
new file mode 100644
index 0000000..3e97dd5
--- /dev/null
+++ b/playgrounds/simple/marketing/index.html
@@ -0,0 +1,305 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Annotask — annotate the UI, agent applies the change</title>
+  <meta name="description" content="Open-source dev-only browser overlay for your running web app. Annotate the UI, and an AI coding agent applies changes back to source. Vite + Webpack." />
+  <meta property="og:title" content="Annotask — annotate the UI, agent applies the change" />
+  <meta property="og:description" content="Dev-only browser overlay turns UI annotations into AI-applied code changes. Vite + Webpack. MCP, CLI, HTTP." />
+  <meta property="og:url" content="https://kurtstohrer.github.io/annotask/" />
+  <meta name="twitter:card" content="summary_large_image" />
+  <link rel="icon" href="/favicon.ico" />
+</head>
+<body>
+<div class="wrap">
+
+  <!-- ── Header ──────────────────────────────────────────────── -->
+  <header>
+    <div class="brand">
+      <img src="/annotask-logo.png" alt="" width="28" height="28" />
+      <span>Annotask</span>
+    </div>
+    <nav>
+      <a href="https://github.com/kurtstohrer/annotask">GitHub</a>
+      <a href="#features">Features</a>
+      <a href="#demo">Demo</a>
+      <a href="#install">Install</a>
+      <a href="https://github.com/kurtstohrer/annotask/blob/main/docs/api.md">Docs</a>
+    </nav>
+  </header>
+
+  <main>
+
+  <!-- ── Hero ────────────────────────────────────────────────── -->
+  <div class="hero">
+    <h1>Annotate the UI.<br /><span class="accent">Agent applies the change.</span></h1>
+    <p class="lede">Annotask is a dev-only browser overlay for your running web app. Mark up the UI with pins, arrows, sections, and highlights. A coding agent reads the structured tasks and applies changes back to source over MCP, CLI, or HTTP. Accept or deny in the browser.</p>
+    <div class="cta">
+      <a class="btn primary" href="https://github.com/kurtstohrer/annotask">View on GitHub</a>
+      <a class="btn ghost" href="#install">Install</a>
+      <a class="btn ghost" href="#demo">Watch the demo</a>
+    </div>
+    <div class="stats-strip">
+      <div class="stat"><span class="stat-value" data-stat="installs">—</span><span class="stat-label">installs</span></div>
+      <div class="stat"><span class="stat-value" data-stat="github_stars">—</span><span class="stat-label">GitHub stars</span></div>
+      <div class="stat"><span class="stat-value" data-stat="contributors">—</span><span class="stat-label">contributors</span></div>
+      <div class="stat"><span class="stat-value" data-stat="frameworks_supported">—</span><span class="stat-label">frameworks</span></div>
+    </div>
+    <div class="hero-shot">
+      <img src="/screenshots/shell-overview.png" alt="Annotask shell showing the annotation toolbar, app iframe, and task sidebar" />
+    </div>
+  </div>
+
+  <!-- ── How it works ────────────────────────────────────────── -->
+  <section id="how-it-works">
+    <h2>How it works</h2>
+    <p class="section-lede">One annotation becomes one structured task. One agent applies the diff. One click to accept.</p>
+    <div class="steps">
+      <div class="step">
+        <h3>Annotate</h3>
+        <p>Pin a note, draw an arrow between elements, highlight text, or sketch a section. Each annotation captures the element, its source file, screenshot, and route context.</p>
+      </div>
+      <div class="step">
+        <h3>Agent applies</h3>
+        <p>Your AI coding agent reads the structured task via MCP, CLI, or HTTP. It gets grounded context — source excerpt, design tokens, component props, interaction history — and applies the change to your source file.</p>
+      </div>
+      <div class="step">
+        <h3>Accept or deny</h3>
+        <p>The task moves to review. You see the result in the browser instantly (HMR). Accept to close, or deny with feedback and the agent re-applies.</p>
+      </div>
+    </div>
+  </section>
+
+  <!-- ── Demo ────────────────────────────────────────────────── -->
+  <section id="demo">
+    <h2>The loop, in 90 seconds</h2>
+    <p class="section-lede">Annotate a low-contrast link, agent applies the a11y fix, task flips to review.</p>
+    <div class="video-frame">
+      <img src="/screenshots/shell-overview.png" alt="Annotask demo — annotate, agent applies, accept or deny" />
+    </div>
+    <p class="caption">Full 90-second walkthrough on a React + Vite playground.</p>
+  </section>
+
+  <!-- ── Annotate features ───────────────────────────────────── -->
+  <section id="features">
+    <h2>Annotate</h2>
+    <p class="section-lede">Three annotation tools, each creating a structured task with grounded context. Every annotation captures the selected element, its source file and line, a screenshot, viewport, and route.</p>
+    <div class="grid-2">
+      <div class="card">
+        <img class="card-img" src="/screenshots/annotate-pins.png" alt="Pin annotations on UI elements" loading="lazy" />
+        <div class="card-body">
+          <h3>Pins &amp; notes</h3>
+          <p>Click any element to drop a numbered pin. Add a description, and the task includes the element's source file, computed styles, and component context.</p>
+        </div>
+      </div>
+      <div class="card">
+        <img class="card-img" src="/screenshots/annotate-arrows.png" alt="Arrow annotations connecting elements" loading="lazy" />
+        <div class="card-body">
+          <h3>Arrows</h3>
+          <p>Draw bezier arrows between elements in six colors. Arrows track scroll and resize, and carry both source and target element context in the task.</p>
+        </div>
+      </div>
+      <div class="card">
+        <img class="card-img" src="/screenshots/annotate-highlights.png" alt="Text highlight annotations" loading="lazy" />
+        <div class="card-body">
+          <h3>Text highlights</h3>
+          <p>Select text to highlight it in six colors. The task includes the highlighted text, the element context, and a prompt field for describing the change.</p>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <!-- ── Design features ─────────────────────────────────────── -->
+  <section>
+    <h2>Design</h2>
+    <p class="section-lede">Inspect live tokens, edit styles in-browser, and browse detected component libraries — all grounded in your actual source code.</p>
+    <div class="grid-3">
+      <div class="card">
+        <img class="card-img" src="/screenshots/design-tokens.png" alt="Design token inspector" loading="lazy" />
+        <div class="card-body">
+          <h3>Token inspector</h3>
+          <p>View extracted design tokens — colors, typography, spacing, breakpoints — from your CSS custom properties, Tailwind config, or theme files.</p>
+        </div>
+      </div>
+      <div class="card">
+        <img class="card-img" src="/screenshots/design-inspector.png" alt="Live style inspector" loading="lazy" />
+        <div class="card-body">
+          <h3>Live style editor</h3>
+          <p>Select any element, edit its styles and classes in real time. Changes are tracked as diffs and committed as structured tasks for the agent.</p>
+        </div>
+      </div>
+      <div class="card">
+        <img class="card-img" src="/screenshots/design-components.png" alt="Component catalog" loading="lazy" />
+        <div class="card-body">
+          <h3>Component catalog</h3>
+          <p>Detected components from your project and libraries with props, usage counts, and real in-repo examples. Search by name, library, or category.</p>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <!-- ── Audit features ──────────────────────────────────────── -->
+  <section>
+    <h2>Audit</h2>
+    <p class="section-lede">Accessibility scanning, performance monitoring, and error capture — each finding becomes a one-click fix task with full context.</p>
+    <div class="grid-3">
+      <div class="card">
+        <img class="card-img" src="/screenshots/audit-a11y.png" alt="Accessibility scanner" loading="lazy" />
+        <div class="card-body">
+          <h3>Accessibility</h3>
+          <p>Local axe-core WCAG scanning with impact severity, affected elements, and one-click task creation. Tab order visualization overlay.</p>
+        </div>
+      </div>
+      <div class="card">
+        <img class="card-img" src="/screenshots/audit-perf.png" alt="Performance monitor" loading="lazy" />
+        <div class="card-body">
+          <h3>Performance</h3>
+          <p>Web Vitals, DOM/resource/bundle analysis, interaction recording, and performance scoring. Record sessions and scan for findings.</p>
+        </div>
+      </div>
+      <div class="card">
+        <img class="card-img" src="/screenshots/audit-errors.png" alt="Error monitor" loading="lazy" />
+        <div class="card-body">
+          <h3>Error monitor</h3>
+          <p>Console error and warning capture with deduplication, stack traces, source mapping, and one-click fix tasks. Bounded memory, no performance cost.</p>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <!-- ── Agent integration ───────────────────────────────────── -->
+  <section id="agent">
+    <h2>Agent integration</h2>
+    <p class="section-lede">Three ways to connect an AI coding agent. Tasks flow through a structured lifecycle with grounded context at every step.</p>
+    <div class="agent-grid">
+      <div class="agent-block">
+        <h3>MCP (Model Context Protocol)</h3>
+<pre><code><span class="c"># One command to configure your editor</span>
+npx annotask init-mcp --editor=claude
+
+<span class="c"># Works with Claude, Cursor, Zed, VS Code, Windsurf</span></code></pre>
+      </div>
+      <div class="agent-block">
+        <h3>CLI</h3>
+<pre><code><span class="c"># List pending tasks</span>
+annotask tasks --status=pending
+
+<span class="c"># Get full task detail</span>
+annotask task &lt;id&gt;
+
+<span class="c"># Update status after applying</span>
+annotask update-task &lt;id&gt; --status=review</code></pre>
+      </div>
+      <div class="agent-block">
+        <h3>HTTP API</h3>
+<pre><code><span class="c"># RESTful API at your dev server</span>
+<span class="k">GET</span>  /__annotask/api/tasks
+<span class="k">GET</span>  /__annotask/api/tasks/:id
+<span class="k">PATCH</span> /__annotask/api/tasks/:id
+<span class="k">POST</span> /__annotask/api/screenshots</code></pre>
+      </div>
+      <div class="agent-block">
+        <h3>MCP tools</h3>
+<pre><code>annotask_get_tasks
+annotask_get_task
+annotask_update_task
+annotask_get_code_context
+annotask_get_design_spec
+annotask_get_screenshot
+<span class="c">… 18 tools total</span></code></pre>
+      </div>
+    </div>
+
+    <h3 style="margin-top: 32px;">Task lifecycle</h3>
+    <div class="lifecycle">
+      <span class="status pending">pending</span>
+      <span class="arrow">&rarr;</span>
+      <span class="status in-progress">in_progress</span>
+      <span class="arrow">&rarr;</span>
+      <span class="status review">review</span>
+      <span class="arrow">&rarr;</span>
+      <span class="status accepted">accepted</span>
+      <span class="arrow">/</span>
+      <span class="status denied">denied</span>
+    </div>
+  </section>
+
+  <!-- ── Framework support ───────────────────────────────────── -->
+  <section>
+    <h2>Works with your stack</h2>
+    <p class="section-lede">Drop in a Vite or Webpack plugin. Annotask auto-detects your framework and injects source-location attributes at build time.</p>
+    <div class="pill-row">
+      <span class="pill">Vue 3</span>
+      <span class="pill">React</span>
+      <span class="pill">Svelte</span>
+      <span class="pill">SolidJS</span>
+      <span class="pill">Astro</span>
+      <span class="pill">Plain HTML</span>
+      <span class="pill">htmx</span>
+    </div>
+    <div class="pill-row" style="margin-top: 8px;">
+      <span class="pill accent">Vite</span>
+      <span class="pill accent">Webpack</span>
+    </div>
+  </section>
+
+  <!-- ── Install ─────────────────────────────────────────────── -->
+  <section id="install">
+    <h2>Install</h2>
+    <p class="section-lede">Add the plugin, start your dev server, open <code>/__annotask/</code>. The agent connects over MCP, CLI, or HTTP.</p>
+    <div class="install-grid">
+      <div>
+        <h3>Vite</h3>
+<pre><code><span class="k">import</span> { defineConfig } <span class="k">from</span> <span class="s">'vite'</span>
+<span class="k">import</span> vue <span class="k">from</span> <span class="s">'@vitejs/plugin-vue'</span>
+<span class="k">import</span> { annotask } <span class="k">from</span> <span class="s">'annotask'</span>
+
+<span class="k">export default</span> defineConfig({
+  plugins: [vue(), annotask()],
+})</code></pre>
+      </div>
+      <div>
+        <h3>Webpack</h3>
+<pre><code><span class="k">import</span> { AnnotaskWebpackPlugin } <span class="k">from</span> <span class="s">'annotask/webpack'</span>
+
+<span class="k">export default</span> {
+  plugins: [<span class="k">new</span> AnnotaskWebpackPlugin()],
+}</code></pre>
+      </div>
+    </div>
+    <p style="margin-top: 24px; color: var(--muted);">Then wire an agent:</p>
+<pre><code><span class="c"># MCP (Claude, Cursor, Zed, VS Code, Windsurf)</span>
+npx annotask init-mcp --editor=claude
+
+<span class="c"># or install the bundled skills</span>
+npx annotask init-skills</code></pre>
+  </section>
+
+  <!-- ── Dogfood banner ──────────────────────────────────────── -->
+  <div class="dogfood">
+    <p>This page is running with Annotask enabled. Open <code>/__annotask/</code> to try it live.</p>
+  </div>
+
+  <!-- ── Status ──────────────────────────────────────────────── -->
+  <section>
+    <h2>Open source</h2>
+    <p class="section-lede">Annotask is free, MIT-licensed, and dev-only — it never ships to production. Contributions welcome.</p>
+    <div class="cta" style="justify-content: flex-start;">
+      <a class="btn primary" href="https://github.com/kurtstohrer/annotask">View on GitHub</a>
+      <a class="btn ghost" href="https://github.com/kurtstohrer/annotask/issues">Open an issue</a>
+    </div>
+  </section>
+
+  </main>
+
+  <!-- ── Footer ──────────────────────────────────────────────── -->
+  <footer>
+    <p>Annotask &middot; MIT &middot; <a href="https://github.com/kurtstohrer/annotask">kurtstohrer/annotask</a></p>
+  </footer>
+
+</div>
+
+<script type="module" src="/src/main.js"></script>
+</body>
+</html>
diff --git a/playgrounds/simple/marketing/package.json b/playgrounds/simple/marketing/package.json
new file mode 100644
index 0000000..942e8f0
--- /dev/null
+++ b/playgrounds/simple/marketing/package.json
@@ -0,0 +1,16 @@
+{
+  "name": "@annotask/playground-marketing",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite"
+  },
+  "devDependencies": {
+    "annotask": "workspace:*",
+    "vite": "^6.4.2"
+  },
+  "dependencies": {
+    "@shoelace-style/shoelace": "^2.20.1"
+  }
+}
diff --git a/playgrounds/simple/marketing/public/annotask-logo.png b/playgrounds/simple/marketing/public/annotask-logo.png
new file mode 100644
index 0000000..936e359
Binary files /dev/null and b/playgrounds/simple/marketing/public/annotask-logo.png differ
diff --git a/playgrounds/simple/marketing/public/favicon.ico b/playgrounds/simple/marketing/public/favicon.ico
new file mode 100644
index 0000000..6890590
Binary files /dev/null and b/playgrounds/simple/marketing/public/favicon.ico differ
diff --git a/playgrounds/simple/marketing/public/screenshots/annotate-arrows.png b/playgrounds/simple/marketing/public/screenshots/annotate-arrows.png
new file mode 100644
index 0000000..83face9
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/annotate-arrows.png differ
diff --git a/playgrounds/simple/marketing/public/screenshots/annotate-highlights.png b/playgrounds/simple/marketing/public/screenshots/annotate-highlights.png
new file mode 100644
index 0000000..3ba6ffc
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/annotate-highlights.png differ
diff --git a/playgrounds/simple/marketing/public/screenshots/annotate-pins.png b/playgrounds/simple/marketing/public/screenshots/annotate-pins.png
new file mode 100644
index 0000000..f14fb6d
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/annotate-pins.png differ
diff --git a/playgrounds/simple/marketing/public/screenshots/audit-a11y.png b/playgrounds/simple/marketing/public/screenshots/audit-a11y.png
new file mode 100644
index 0000000..2f03f12
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/audit-a11y.png differ
diff --git a/playgrounds/simple/marketing/public/screenshots/audit-errors.png b/playgrounds/simple/marketing/public/screenshots/audit-errors.png
new file mode 100644
index 0000000..f212e02
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/audit-errors.png differ
diff --git a/playgrounds/simple/marketing/public/screenshots/audit-perf.png b/playgrounds/simple/marketing/public/screenshots/audit-perf.png
new file mode 100644
index 0000000..2915320
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/audit-perf.png differ
diff --git a/playgrounds/simple/marketing/public/screenshots/design-components.png b/playgrounds/simple/marketing/public/screenshots/design-components.png
new file mode 100644
index 0000000..f98b963
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/design-components.png differ
diff --git a/playgrounds/simple/marketing/public/screenshots/design-inspector.png b/playgrounds/simple/marketing/public/screenshots/design-inspector.png
new file mode 100644
index 0000000..3273c8d
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/design-inspector.png differ
diff --git a/playgrounds/simple/marketing/public/screenshots/design-tokens.png b/playgrounds/simple/marketing/public/screenshots/design-tokens.png
new file mode 100644
index 0000000..89d60c1
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/design-tokens.png differ
diff --git a/playgrounds/simple/marketing/public/screenshots/shell-overview.png b/playgrounds/simple/marketing/public/screenshots/shell-overview.png
new file mode 100644
index 0000000..ec4e331
Binary files /dev/null and b/playgrounds/simple/marketing/public/screenshots/shell-overview.png differ
diff --git a/playgrounds/simple/marketing/src/api.js b/playgrounds/simple/marketing/src/api.js
new file mode 100644
index 0000000..f6820de
--- /dev/null
+++ b/playgrounds/simple/marketing/src/api.js
@@ -0,0 +1,16 @@
+// Marketing API client — backed by the shared playground FastAPI service
+// (playgrounds/simple/api, proxied via /api in vite.config.js).
+
+/** Project stats: { installs, github_stars, contributors, frameworks_supported } */
+export async function fetchStats() {
+  const res = await fetch('/api/marketing/stats')
+  if (!res.ok) throw new Error(`stats: ${res.status}`)
+  return res.json()
+}
+
+/** Release feed: [{ version, date, headline, highlights }] — no UI consumes this yet. */
+export async function fetchChangelog(limit = 5) {
+  const res = await fetch(`/api/marketing/changelog?limit=${limit}`)
+  if (!res.ok) throw new Error(`changelog: ${res.status}`)
+  return res.json()
+}
diff --git a/playgrounds/simple/marketing/src/main.js b/playgrounds/simple/marketing/src/main.js
new file mode 100644
index 0000000..c004c55
--- /dev/null
+++ b/playgrounds/simple/marketing/src/main.js
@@ -0,0 +1,28 @@
+import './style.css'
+import { fetchStats } from './api.js'
+
+// Shoelace web components — register base path for assets
+import { setBasePath } from '@shoelace-style/shoelace/dist/utilities/base-path.js'
+setBasePath('/node_modules/@shoelace-style/shoelace/dist')
+
+// Live project stats in the hero strip — keep the "—" placeholders if the API is down
+const compact = (n) => (n >= 1000 ? `${(n / 1000).toFixed(1).replace(/\.0$/, '')}k` : String(n))
+fetchStats()
+  .then((stats) => {
+    for (const el of document.querySelectorAll('[data-stat]')) {
+      const value = stats[el.dataset.stat]
+      if (typeof value === 'number') el.textContent = compact(value)
+    }
+  })
+  .catch(() => {})
+
+// Smooth scroll for anchor links
+document.addEventListener('click', (e) => {
+  const link = e.target.closest('a[href^="#"]')
+  if (!link) return
+  const target = document.querySelector(link.getAttribute('href'))
+  if (target) {
+    e.preventDefault()
+    target.scrollIntoView({ behavior: 'smooth', block: 'start' })
+  }
+})
diff --git a/playgrounds/simple/marketing/src/style.css b/playgrounds/simple/marketing/src/style.css
new file mode 100644
index 0000000..8732b1e
--- /dev/null
+++ b/playgrounds/simple/marketing/src/style.css
@@ -0,0 +1,184 @@
+/* ── Annotask Marketing Page ─────────────────────────────────────── */
+
+/* ── Design tokens (dark default, Annotask Dark theme) ─────────── */
+:root {
+  --bg: #0a0a0a;
+  --surface: #141414;
+  --surface-2: #1e1e1e;
+  --surface-3: #262626;
+  --border: #2a2a2a;
+  --border-strong: #404040;
+  --fg: #e4e4e7;
+  --muted: #71717a;
+  --accent: #3b82f6;
+  --accent-hover: #2563eb;
+  --accent-muted: rgba(59, 130, 246, 0.15);
+  --danger: #ef4444;
+  --success: #22c55e;
+  --warning: #f59e0b;
+  --text-on-accent: #fff;
+  --text-link: #60a5fa;
+  --overlay: rgba(0, 0, 0, 0.5);
+  --shadow: rgba(0, 0, 0, 0.4);
+  --code-bg: #141414;
+  --code-property: #7dd3fc;
+  --code-string: #86efac;
+  --code-keyword: #c084fc;
+  --code-comment: #71717a;
+  --sans: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Inter", "Helvetica Neue", Arial, sans-serif;
+  --mono: ui-monospace, "JetBrains Mono", "Fira Code", Menlo, Consolas, monospace;
+}
+
+/* ── Light mode (Annotask Light theme) ─────────────────────────── */
+@media (prefers-color-scheme: light) {
+  :root {
+    --bg: #f8f9fa;
+    --surface: #ffffff;
+    --surface-2: #f0f1f3;
+    --surface-3: #e5e7eb;
+    --border: #d4d6db;
+    --border-strong: #9ca3af;
+    --fg: #1a1a1a;
+    --muted: #6b7280;
+    --accent: #2563eb;
+    --accent-hover: #1d4ed8;
+    --accent-muted: rgba(37, 99, 235, 0.12);
+    --danger: #dc2626;
+    --success: #16a34a;
+    --warning: #d97706;
+    --text-on-accent: #fff;
+    --text-link: #2563eb;
+    --overlay: rgba(0, 0, 0, 0.3);
+    --shadow: rgba(0, 0, 0, 0.12);
+    --code-bg: #f0f1f3;
+    --code-property: #0369a1;
+    --code-string: #15803d;
+    --code-keyword: #7e22ce;
+    --code-comment: #6b7280;
+  }
+}
+
+/* ── Reset & base ──────────────────────────────────────────────── */
+*, *::before, *::after { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; background: var(--bg); color: var(--fg); font-family: var(--sans); -webkit-font-smoothing: antialiased; line-height: 1.6; }
+a { color: var(--text-link); text-decoration: none; }
+a:hover { text-decoration: underline; }
+img { max-width: 100%; height: auto; }
+
+/* ── Layout ────────────────────────────────────────────────────── */
+.wrap { max-width: 1120px; margin: 0 auto; padding: 0 24px; }
+
+/* ── Header ────────────────────────────────────────────────────── */
+header { padding: 24px 0; display: flex; align-items: center; justify-content: space-between; }
+header .brand { display: flex; align-items: center; gap: 10px; font-weight: 700; font-size: 18px; letter-spacing: 0.02em; color: var(--fg); }
+header .brand img { width: 28px; height: 28px; }
+header nav { display: flex; gap: 20px; }
+header nav a { color: var(--muted); font-size: 14px; font-weight: 500; }
+header nav a:hover { color: var(--fg); text-decoration: none; }
+
+/* ── Hero ──────────────────────────────────────────────────────── */
+.hero { padding: 72px 0 40px; text-align: center; }
+.hero h1 { font-size: clamp(36px, 5.5vw, 60px); line-height: 1.08; margin: 0 0 20px; letter-spacing: -0.025em; font-weight: 800; }
+.hero h1 .accent { color: var(--accent); }
+.hero .lede { font-size: clamp(17px, 2vw, 20px); color: var(--muted); max-width: 680px; margin: 0 auto 32px; line-height: 1.55; }
+.cta { display: inline-flex; gap: 12px; flex-wrap: wrap; justify-content: center; }
+
+/* ── Buttons ───────────────────────────────────────────────────── */
+.btn { display: inline-flex; align-items: center; gap: 6px; padding: 14px 20px; border-radius: 12px; font-weight: 600; font-size: 15px; border: 1px solid var(--border); cursor: pointer; transition: all 0.15s; }
+.btn.primary { background: var(--accent); color: var(--text-on-accent); border-color: var(--accent); }
+.btn.primary:hover { background: var(--accent-hover); border-color: var(--accent-hover); text-decoration: none; }
+.btn.ghost { background: transparent; color: var(--fg); }
+.btn.ghost:hover { border-color: var(--accent); color: var(--accent); text-decoration: none; }
+
+/* ── Live stats strip ──────────────────────────────────────────── */
+.stats-strip { display: inline-flex; gap: 0; margin-top: 36px; border: 1px solid var(--border); border-radius: 12px; background: var(--surface); overflow: hidden; }
+.stat { display: flex; flex-direction: column; gap: 2px; padding: 14px 28px; }
+.stat + .stat { border-left: 1px solid var(--border); }
+.stat-value { font-size: 22px; font-weight: 700; color: var(--accent); font-variant-numeric: tabular-nums; }
+.stat-label { font-size: 12px; color: var(--muted); }
+
+/* ── Hero screenshot ───────────────────────────────────────────── */
+.hero-shot { margin: 48px auto 0; max-width: 1040px; }
+.hero-shot img { width: 100%; border-radius: 14px; border: 1px solid var(--border); box-shadow: 0 30px 80px -20px var(--shadow); }
+
+/* ── Sections ──────────────────────────────────────────────────── */
+section { padding: 72px 0; border-top: 1px solid var(--border); }
+section h2 { font-size: clamp(26px, 3vw, 36px); margin: 0 0 10px; letter-spacing: -0.015em; font-weight: 700; }
+section .section-lede { color: var(--muted); margin: 0 0 36px; max-width: 680px; font-size: 16px; line-height: 1.6; }
+
+/* ── How it works (3-step) ─────────────────────────────────────── */
+.steps { display: grid; grid-template-columns: repeat(3, 1fr); gap: 24px; counter-reset: step; }
+.step { position: relative; padding: 24px; border-radius: 12px; background: var(--surface); border: 1px solid var(--border); }
+.step::before { counter-increment: step; content: counter(step); display: flex; align-items: center; justify-content: center; width: 32px; height: 32px; border-radius: 8px; background: var(--accent-muted); color: var(--accent); font-weight: 700; font-size: 14px; margin-bottom: 14px; }
+.step h3 { margin: 0 0 6px; font-size: 17px; }
+.step p { margin: 0; color: var(--muted); font-size: 14px; line-height: 1.55; }
+
+/* ── Feature grids ─────────────────────────────────────────────── */
+.grid-2 { display: grid; grid-template-columns: repeat(2, 1fr); gap: 20px; }
+.grid-3 { display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px; }
+
+/* ── Feature cards ─────────────────────────────────────────────── */
+.card { background: var(--surface); border: 1px solid var(--border); border-radius: 12px; overflow: hidden; }
+.card .card-img { width: 100%; aspect-ratio: 16 / 10; object-fit: cover; display: block; border-bottom: 1px solid var(--border); }
+.card .card-body { padding: 18px 20px; }
+.card h3 { margin: 0 0 6px; font-size: 16px; font-weight: 600; }
+.card p { margin: 0; color: var(--muted); font-size: 14px; line-height: 1.5; }
+
+/* ── Agent integration ─────────────────────────────────────────── */
+.agent-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 24px; }
+.agent-block h3 { margin: 0 0 10px; font-size: 16px; font-weight: 600; }
+
+/* ── Code blocks ───────────────────────────────────────────────── */
+pre { background: var(--code-bg); border: 1px solid var(--border); border-radius: 10px; padding: 16px 18px; overflow-x: auto; font-family: var(--mono); font-size: 13px; color: var(--fg); margin: 0; line-height: 1.6; }
+pre .k { color: var(--code-keyword); }
+pre .s { color: var(--code-string); }
+pre .c { color: var(--code-comment); }
+pre .p { color: var(--code-property); }
+pre .f { color: var(--accent); }
+
+/* ── Lifecycle diagram ─────────────────────────────────────────── */
+.lifecycle { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; margin-top: 20px; padding: 18px; border-radius: 10px; background: var(--surface); border: 1px solid var(--border); font-size: 13px; font-family: var(--mono); }
+.lifecycle .status { padding: 4px 10px; border-radius: 6px; font-weight: 600; }
+.lifecycle .status.pending { background: color-mix(in srgb, var(--muted) 20%, transparent); color: var(--muted); }
+.lifecycle .status.in-progress { background: color-mix(in srgb, var(--accent) 20%, transparent); color: var(--accent); }
+.lifecycle .status.review { background: color-mix(in srgb, var(--warning) 20%, transparent); color: var(--warning); }
+.lifecycle .status.accepted { background: color-mix(in srgb, var(--success) 20%, transparent); color: var(--success); }
+.lifecycle .status.denied { background: color-mix(in srgb, var(--danger) 20%, transparent); color: var(--danger); }
+.lifecycle .arrow { color: var(--muted); }
+
+/* ── Framework pills ───────────────────────────────────────────── */
+.pill-row { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 12px; }
+.pill { display: inline-block; padding: 7px 14px; border-radius: 999px; background: var(--surface); border: 1px solid var(--border); color: var(--muted); font-size: 13px; font-weight: 500; }
+.pill.accent { border-color: var(--accent); color: var(--accent); }
+
+/* ── Install section ───────────────────────────────────────────── */
+.install-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 24px; }
+.install-grid h3 { margin: 0 0 10px; font-size: 16px; font-weight: 600; }
+
+/* ── Dogfood banner ────────────────────────────────────────────── */
+.dogfood { text-align: center; padding: 32px; margin-top: 8px; border-radius: 12px; background: var(--accent-muted); border: 1px solid color-mix(in srgb, var(--accent) 30%, transparent); }
+.dogfood p { margin: 0; font-size: 15px; }
+.dogfood code { font-family: var(--mono); background: color-mix(in srgb, var(--accent) 15%, transparent); padding: 2px 6px; border-radius: 4px; font-size: 13px; }
+
+/* ── Demo section ──────────────────────────────────────────────── */
+.video-frame { background: var(--surface); border: 1px solid var(--border); border-radius: 14px; aspect-ratio: 16 / 9; display: flex; align-items: center; justify-content: center; overflow: hidden; }
+.video-frame img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.caption { color: var(--muted); margin-top: 14px; font-size: 14px; }
+
+/* ── Footer ────────────────────────────────────────────────────── */
+footer { padding: 40px 0; color: var(--muted); font-size: 14px; text-align: center; border-top: 1px solid var(--border); }
+footer a { color: var(--muted); }
+footer a:hover { color: var(--fg); }
+
+/* ── Responsive ────────────────────────────────────────────────── */
+@media (max-width: 900px) {
+  .steps { grid-template-columns: 1fr; }
+  .grid-2 { grid-template-columns: 1fr; }
+  .grid-3 { grid-template-columns: 1fr; }
+  .agent-grid { grid-template-columns: 1fr; }
+  .install-grid { grid-template-columns: 1fr; }
+}
+@media (max-width: 600px) {
+  header nav { display: none; }
+  .hero { padding: 48px 0 24px; }
+}
diff --git a/playgrounds/simple/marketing/vite.config.js b/playgrounds/simple/marketing/vite.config.js
new file mode 100644
index 0000000..787f57b
--- /dev/null
+++ b/playgrounds/simple/marketing/vite.config.js
@@ -0,0 +1,15 @@
+import { defineConfig } from 'vite'
+import { annotask } from 'annotask'
+
+export default defineConfig({
+  plugins: [annotask()],
+  server: {
+    port: 5181,
+    proxy: {
+      '/api': 'http://localhost:8888',
+      // The shared FastAPI's OpenAPI document — lets Annotask's schema scanner
+      // resolve data-source shapes (shape_source: 'api-schema').
+      '/openapi.json': 'http://localhost:8888',
+    },
+  },
+})
diff --git a/playgrounds/simple/react-vite/src/App.tsx b/playgrounds/simple/react-vite/src/App.tsx
index 0853815..aad8905 100644
--- a/playgrounds/simple/react-vite/src/App.tsx
+++ b/playgrounds/simple/react-vite/src/App.tsx
@@ -5,6 +5,7 @@ import Footer from './components/Footer'
 import Landing from './pages/Landing'
 import Changelog from './pages/Changelog'
 import Integrations from './pages/Integrations'
+import Planets from './pages/Planets'
 
 type Theme = 'dark' | 'light'
 
@@ -29,6 +30,7 @@ function App() {
           <Route path="/" element={<Landing />} />
           <Route path="/changelog" element={<Changelog />} />
           <Route path="/integrations" element={<Integrations />} />
+          <Route path="/planets" element={<Planets />} />
         </Routes>
       </main>
       <Footer />
diff --git a/playgrounds/simple/react-vite/src/components/PlanetCard.tsx b/playgrounds/simple/react-vite/src/components/PlanetCard.tsx
new file mode 100644
index 0000000..8139017
--- /dev/null
+++ b/playgrounds/simple/react-vite/src/components/PlanetCard.tsx
@@ -0,0 +1,35 @@
+export interface Planet {
+  id: string
+  name: string
+  type: string
+  moons: number
+  distance_from_sun_mkm: number
+  color?: string
+}
+
+interface PlanetCardProps {
+  planet: Planet
+  active?: boolean
+}
+
+// Mirrors vue-vite's PlanetCard: a real project component with a bound prop
+// (`planet`), a literal-friendly prop (`active`), and loop rendering on the
+// /planets page — the M2 design-tool acceptance surface for React.
+export default function PlanetCard({ planet, active }: PlanetCardProps) {
+  return (
+    <button
+      className={`planet-card${active ? ' active' : ''}`}
+      style={{ ['--planet-color' as string]: planet.color ?? '#8888ff' }}
+    >
+      <span className="orb" style={{ background: planet.color ?? '#8888ff' }} />
+      <span className="body">
+        <span className="name">{planet.name}</span>
+        <span className="type">{planet.type}</span>
+      </span>
+      <span className="meta">
+        <span className="moons">{planet.moons} moons</span>
+        <span className="distance">{planet.distance_from_sun_mkm} mkm</span>
+      </span>
+    </button>
+  )
+}
diff --git a/playgrounds/simple/react-vite/src/pages/Planets.tsx b/playgrounds/simple/react-vite/src/pages/Planets.tsx
new file mode 100644
index 0000000..d61c1e0
--- /dev/null
+++ b/playgrounds/simple/react-vite/src/pages/Planets.tsx
@@ -0,0 +1,40 @@
+import { useEffect, useState } from 'react'
+import PlanetCard, { type Planet } from '../components/PlanetCard'
+
+// Minimal mirror of vue-vite's /planets page: fetches the same API and renders
+// a .map() loop of PlanetCard — literal text (h1), a bound prop (planet), and
+// loop rendering for the design-tool acceptance checks. No search/filter
+// parity needed.
+export default function Planets() {
+  const [planets, setPlanets] = useState<Planet[]>([])
+  const [error, setError] = useState('')
+
+  useEffect(() => {
+    let cancelled = false
+    fetch('/api/solar/planets?sort_by=distance_from_sun_mkm')
+      .then((res) => {
+        if (!res.ok) throw new Error('api')
+        return res.json()
+      })
+      .then((data) => {
+        if (!cancelled) setPlanets(Array.isArray(data?.planets) ? data.planets : Array.isArray(data) ? data : [])
+      })
+      .catch(() => {
+        if (!cancelled) setError('Could not load planets — is the API running?')
+      })
+    return () => { cancelled = true }
+  }, [])
+
+  return (
+    <section className="planets-page" style={{ padding: '32px 24px', maxWidth: 960, margin: '0 auto' }}>
+      <h1 className="title">Planets</h1>
+      <p className="subtitle">{planets.length} worlds in the catalog</p>
+      {error && <p className="error">{error}</p>}
+      <div className="grid" style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(220px, 1fr))', gap: 12 }}>
+        {planets.map((planet) => (
+          <PlanetCard key={planet.id} planet={planet} active={false} />
+        ))}
+      </div>
+    </section>
+  )
+}
diff --git a/playgrounds/simple/vue-vite/.gitignore b/playgrounds/simple/vue-vite/.gitignore
index e5cefce..61f4648 100644
--- a/playgrounds/simple/vue-vite/.gitignore
+++ b/playgrounds/simple/vue-vite/.gitignore
@@ -1,2 +1,2 @@
-# Annotask config (generated)
+# Annotask (generated)
 .annotask/
diff --git a/playgrounds/simple/vue-vite/package.json b/playgrounds/simple/vue-vite/package.json
index 7f3cdf9..780b531 100644
--- a/playgrounds/simple/vue-vite/package.json
+++ b/playgrounds/simple/vue-vite/package.json
@@ -7,7 +7,9 @@
     "dev": "vite"
   },
   "dependencies": {
+    "@primevue/themes": "^4.5.4",
     "primeicons": "^7.0.0",
+    "primevue": "^4.5.4",
     "vue": "^3.5.0",
     "vue-router": "^5.0.4"
   },
diff --git a/playgrounds/simple/vue-vite/src/App.vue b/playgrounds/simple/vue-vite/src/App.vue
index 5a25b5f..7e621a1 100644
--- a/playgrounds/simple/vue-vite/src/App.vue
+++ b/playgrounds/simple/vue-vite/src/App.vue
@@ -34,6 +34,10 @@ watch(theme, applyTheme)
 function toggleTheme() {
   theme.value = theme.value === 'dark' ? 'light' : 'dark'
 }
+
+function scrollTop() {
+  window.scrollTo({ top: 0, behavior: 'smooth' })
+}
 </script>
 
 <template>
@@ -43,6 +47,11 @@ function toggleTheme() {
     <main class="content">
       <router-view />
     </main>
+
+    <!-- Deliberately a SIBLING of <main> that is not semantic chrome — the
+         canonical fixture for the wireframe capture's straggler pass
+         (e2e W1 asserts a captured block with anchor.tag === 'button'). -->
+    <button class="back-to-top" @click="scrollTop">↑ Back to top</button>
   </div>
 </template>
 
@@ -80,6 +89,19 @@ body {
 
 .app { min-height: 100vh; }
 
+.back-to-top {
+  display: block;
+  margin: 0 auto 20px;
+  padding: 8px 14px;
+  background: var(--surface-alt);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  color: var(--text-muted);
+  cursor: pointer;
+  font-size: 13px;
+}
+.back-to-top:hover { color: var(--text); }
+
 .content {
   max-width: 1200px;
   margin: 0 auto;
diff --git a/playgrounds/simple/vue-vite/src/main.ts b/playgrounds/simple/vue-vite/src/main.ts
index 9f26bcc..f8fa76c 100644
--- a/playgrounds/simple/vue-vite/src/main.ts
+++ b/playgrounds/simple/vue-vite/src/main.ts
@@ -1,9 +1,12 @@
 import { createApp } from 'vue'
 import App from './App.vue'
 import router from './router'
+import PrimeVue from 'primevue/config'
+import Aura from '@primevue/themes/aura'
 
 import 'primeicons/primeicons.css'
 
 const app = createApp(App)
 app.use(router)
+app.use(PrimeVue, { theme: { preset: Aura, options: { darkModeSelector: '.dark' } } })
 app.mount('#app')
diff --git a/playgrounds/simple/vue-vite/src/pages/OverviewPage.vue b/playgrounds/simple/vue-vite/src/pages/OverviewPage.vue
index a4f6a3a..0be0984 100644
--- a/playgrounds/simple/vue-vite/src/pages/OverviewPage.vue
+++ b/playgrounds/simple/vue-vite/src/pages/OverviewPage.vue
@@ -55,7 +55,8 @@ function isSunHit(x: number, y: number): boolean {
   if (!sunHit) return false
   const dx = x - sunHit.x
   const dy = y - sunHit.y
-  return dx * dx + dy * dy <= sunHit.r * sunHit.r
+  const hitR = sunHit.r + 4
+  return dx * dx + dy * dy <= hitR * hitR
 }
 
 function onCanvasPointerMove(event: PointerEvent) {
@@ -192,6 +193,15 @@ function startOrbitAnimation(canvas: HTMLCanvasElement, list: Planet[]) {
       ctx!.stroke()
       ctx!.restore()
     }
+    if (hoveredSun.value && sunHit) {
+      ctx!.save()
+      ctx!.strokeStyle = 'rgba(255,255,255,0.9)'
+      ctx!.lineWidth = 1.5
+      ctx!.beginPath()
+      ctx!.arc(sunHit.x, sunHit.y, sunHit.r + 4, 0, Math.PI * 2)
+      ctx!.stroke()
+      ctx!.restore()
+    }
 
     rafId = requestAnimationFrame(frame)
   }
@@ -241,7 +251,7 @@ onBeforeUnmount(() => {
 
 .page-header { display: flex; flex-direction: column; gap: 6px; }
 .title { font-size: 28px; font-weight: 700; letter-spacing: -0.02em; }
-.lede { color: var(--text-muted); font-size: 14px; max-width: 640px; }
+.lede { color: var(--text-muted); font-size: 18px; max-width: 640px; }
 
 .orbit-stage {
   position: relative;
diff --git a/playgrounds/simple/vue-vite/src/pages/PlanetsPage.vue b/playgrounds/simple/vue-vite/src/pages/PlanetsPage.vue
index fbea5c4..a595c2f 100644
--- a/playgrounds/simple/vue-vite/src/pages/PlanetsPage.vue
+++ b/playgrounds/simple/vue-vite/src/pages/PlanetsPage.vue
@@ -3,6 +3,8 @@ import { ref, computed, onMounted, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import PlanetCard from '../components/PlanetCard.vue'
 import PlanetDetail from '../components/PlanetDetail.vue'
+import Button from 'primevue/button'
+import Tag from 'primevue/tag'
 import { usePlanets } from '../composables/usePlanets'
 import type { Planet, PlanetType } from '../types'
 
@@ -52,6 +54,12 @@ const filtered = computed(() => {
   return out
 })
 
+function resetFilters() {
+  search.value = ''
+  typeFilter.value = ''
+  sortBy.value = 'distance_from_sun_mkm'
+}
+
 function select(planet: Planet) {
   selected.value = planet
   router.replace({ query: { ...route.query, id: String(planet.id) } })
@@ -79,55 +87,63 @@ watch(
         <h1 class="title">Planets</h1>
         <p class="lede">Click a planet card to view more info.</p>
       </div>
+
     </header>
 
     <p v-if="error" class="error-banner">{{ error }}</p>
 
-    <div class="toolbar">
-      <div class="field">
-        <i class="pi pi-search"></i>
-        <input
-          v-model="search"
-          type="search"
-          placeholder="Search planets…"
-          aria-label="Search planets"
-        />
-      </div>
-      <label class="select">
-        Type
-        <select v-model="typeFilter" aria-label="Filter by type">
-          <option value="">All</option>
-          <option value="Terrestrial">Terrestrial</option>
-          <option value="Gas Giant">Gas Giant</option>
-          <option value="Ice Giant">Ice Giant</option>
-        </select>
-      </label>
-      <label class="select">
-        Sort
-        <select v-model="sortBy" aria-label="Sort planets by">
-          <option value="distance_from_sun_mkm">Distance from Sun</option>
-          <option value="name">Name</option>
-          <option value="radius_km">Radius</option>
-          <option value="moons">Moons</option>
-          <option value="avg_temp_c">Temperature</option>
-        </select>
-      </label>
-    </div>
+    <div class="planets-content">
+      <aside class="controls">
+        <div class="toolbar">
+          <label class="select">
+            Type
+            <select v-model="typeFilter" aria-label="Filter by type">
+              <option value="">All</option>
+              <option value="Terrestrial">Terrestrial</option>
+              <option value="Gas Giant">Gas Giant</option>
+              <option value="Ice Giant">Ice Giant</option>
+            </select>
+          </label>
+          <label class="select">
+            Sort
+            <select v-model="sortBy" aria-label="Sort planets by">
+              <option value="distance_from_sun_mkm">Distance from Sun</option>
+              <option value="name">Name</option>
+              <option value="radius_km">Radius</option>
+              <option value="moons">Moons</option>
+              <option value="avg_temp_c">Temperature</option>
+            </select>
+          </label>
+          <!-- PrimeVue components — exercise component-library discovery + highlights -->
+          <Tag :value="`${filtered.length} planets`" severity="info" rounded />
+          <Button label="Reset" icon="pi pi-times" severity="secondary" size="small" outlined @click="resetFilters" />
+          <div class="field">
+            <i class="pi pi-search"></i>
+            <input
+              v-model="search"
+              type="search"
+              placeholder="Search planets…"
+              aria-label="Search planets"
+            />
+          </div>
+        </div>
+      </aside>
 
-    <div class="layout">
-      <div class="planet-list">
-        <p v-if="loading" class="loading">Loading planets…</p>
-        <p v-else-if="!filtered.length" class="empty">No planets match your filters.</p>
-        <PlanetCard
-          v-for="planet in filtered"
-          v-else
-          :key="planet.id"
-          :planet="planet"
-          :active="selected?.id === planet.id"
-          @select="select"
-        />
+      <div class="layout">
+        <div class="planet-list">
+          <p v-if="loading" class="loading">Loading planets…</p>
+          <p v-else-if="!filtered.length" class="empty">No planets match your filters.</p>
+          <PlanetCard
+            v-for="planet in filtered"
+            v-else
+            :key="planet.id"
+            :planet="planet"
+            :active="selected?.id === planet.id"
+            @select="select"
+          />
+        </div>
+        <PlanetDetail v-if="selected" :planet="selected" @close="close" />
       </div>
-      <PlanetDetail v-if="selected" :planet="selected" @close="close" />
     </div>
   </section>
 </template>
@@ -139,6 +155,19 @@ watch(
 .title { font-size: 26px; font-weight: 700; letter-spacing: -0.02em; }
 .lede { color: var(--text-muted); font-size: 14px; margin-top: 4px; }
 
+.planets-content {
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  align-items: stretch;
+}
+
+.controls {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
 .toolbar {
   display: flex;
   gap: 10px;
@@ -148,8 +177,9 @@ watch(
 
 .field {
   position: relative;
-  flex: 1;
+  flex: 1 1 240px;
   min-width: 220px;
+  max-width: 440px;
 }
 
 .field i {
@@ -204,6 +234,8 @@ watch(
 }
 
 .layout {
+  flex: 1.2;
+  min-width: 0;
   display: flex;
   gap: 20px;
   align-items: flex-start;
diff --git a/playgrounds/simple/vue-vite/tsconfig.json b/playgrounds/simple/vue-vite/tsconfig.json
index 63ee02f..97f7227 100644
--- a/playgrounds/simple/vue-vite/tsconfig.json
+++ b/playgrounds/simple/vue-vite/tsconfig.json
@@ -1,7 +1,14 @@
 {
-  "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
     "jsx": "preserve",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
     "types": ["vite/client"]
   },
   "include": ["src", "env.d.ts"]
diff --git a/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/A11Y_RULES.md b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/A11Y_RULES.md
new file mode 100644
index 0000000..8062295
--- /dev/null
+++ b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/A11Y_RULES.md
@@ -0,0 +1,77 @@
+# A11Y Rules
+
+Read this file for `a11y_fix` tasks. If you are applying a batch of a11y tasks, read it once for the batch, not once per task.
+
+## Task context
+
+The `a11y_fix` task `context` contains:
+
+- `rule`: axe rule ID, or Annotask's synthetic `tab-order` rule
+- `impact`, `help`, `helpUrl`
+- `elements[]`: offending elements with `html`, `selector`, `fix`, source `file` / `line` / `component`
+- `elements[i].a11y`: computed accessibility metadata for the specific element
+
+```text
+elements[i].a11y = {
+  accessible_name, name_source,
+  role, role_source,
+  tabindex, focusable,
+  focus_indicator,
+  contrast,
+  aria_attrs,
+}
+```
+
+If `screenshot_meta` is present, retrieve it via `annotask_get_screenshot` before proposing visual changes such as contrast or focus-ring fixes.
+
+## Rule playbook
+
+Match on `context.rule`.
+
+| Rule(s) | Fix layer | What to do |
+|---|---|---|
+| `color-contrast`, `color-contrast-enhanced` | Design tokens first | See **Color contrast playbook** below. |
+| `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` that points at visible text. If `name_source === 'placeholder'`, the input still has no real label. |
+| `button-name`, `link-name`, `input-button-name` | Markup | Add visible text or `aria-label`. For icon-only buttons, add a visually hidden label (`sr-only` or the project equivalent). Do not rely on `title`. |
+| `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | Use `alt=""` for decorative imagery and descriptive `alt` for informational imagery. For SVG icons paired with visible text, use `aria-hidden="true"`. |
+| `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These usually live in layout/root files, not leaf components. |
+| `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert or promote `<h1>`, then renumber subsequent heading levels so the outline is contiguous. Usually a layout or section change. |
+| `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what is set. Use `helpUrl` to confirm the role's allowed and required attributes, then remove or add attributes accordingly. |
+| `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Remove `aria-hidden`, move the focusable elements out, or make them unfocusable with `tabindex="-1"` if appropriate. |
+| `tabindex`, `tab-order` | Markup | Remove positive `tabindex`; use `0` for normal DOM-order focus or `-1` for programmatic focus only. For synthetic `tab-order`, inspect `context.tab_order.flag` (`positive`, `unreachable`, `reorder`) and make DOM order match visual order. |
+| `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Fix the framework's document-level source of truth: `index.html`, `app/layout.tsx`, `src/routes/+layout.svelte`, or the equivalent root document. |
+| `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>` or `<span>`. Do not nest interactive elements. |
+| `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element in the layout. Use the project's visually-hidden pattern that becomes visible on `:focus`. |
+| `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="..."` values and rename one. If the id is generated, make the generation key unique per instance. |
+| `frame-title`, `iframe-title` | Markup | Add `title="..."` describing the iframe's purpose. |
+
+## Color contrast playbook
+
+Use this when `context.rule` is `color-contrast` or `color-contrast-enhanced`. The goal is to land **one token-level edit** that fixes the violation on the first try, without spraying inline overrides or hardcoded hex into component CSS.
+
+1. **Read the structured contrast block first.** `elements[i].a11y.contrast` gives you `foreground`, `background`, and `ratio` as actual computed hex. Treat these as facts; do not re-derive from screenshots.
+2. **Open the source at `elements[i].file:line` and locate the failing CSS rule.** Identify how `color` and `background`/`background-color` are set:
+   - `var(--token-name)` → token-level fix (preferred).
+   - hardcoded hex / `rgb()` / `hsl()` → component-level fix.
+   - inline `style={…}` / `style="…"` → component-level fix on that one instance.
+   - Tailwind / utility class (e.g. `bg-blue-500 text-white`) → swap utility classes or extend the project's theme config; do not add ad-hoc inline overrides.
+3. **For the token path** — the common case in design-system playgrounds:
+   - Find the variable's definition (typically a `:root` / `:root[data-theme="*"]` block in `tokens.css`, `globals.css`, `theme.css`, or equivalent). Use `grep` for `--token-name:` if you have to.
+   - Edit the variable **at its definition**, inside the theme block that matches the current `color_scheme` on the task (`dark` vs `light`). Do not redefine the variable on the component selector — that bypasses the design system and breaks every other consumer.
+   - If both themes look like they fail, fix the variable in each theme block separately, computing per-theme.
+4. **Pick which token to move.** When both `color` and `background` are tokens, default to:
+   - **Brand background + white/near-white text (`--accent` + `--text-on-accent`):** keep the white text token, darken the brand token. Brand tokens earn their lightness; light text on brand is almost always the intended pattern, and darkening the brand by ~10–20% luminance is usually the smallest visible change.
+   - **Muted text on neutral surface (`--text-muted`, `--text-subtle` on `--surface*`):** lighten the text token, do not darken the surface. Surface tokens drive layout perception and many components consume them.
+   - **Disabled/placeholder text:** if the project intentionally uses a low-contrast token, keep the rule failure scoped to that pattern and fix only the offending public-facing instance, not the token.
+5. **Choose the new value by luminance, not by eye.** For text vs. opaque background, target ≥4.5:1 (normal text) or ≥3:1 (large/bold ≥18pt or 14pt+700). Move the token in **one direction only** (darken bg *or* lighten fg) — do not split the fix across both ends. After editing, the diff should be one line in the tokens file.
+6. **Sanity-check sibling tokens.** If you darken `--accent`, glance at `--accent-strong` (the hover/pressed variant) and `--accent-soft` (low-opacity surfaces). If `--accent-strong` is already darker than your new `--accent` value, leave it. If it's now lighter, slide it darker by the same delta so the brand ramp stays monotonic.
+7. **Do not touch the component CSS.** A clean token fix has no edits in the component file. If you find yourself opening the component to override the variable, stop — you are about to re-introduce the instance-level pattern the playbook is trying to prevent.
+
+The agent should also confirm the re-render passes after applying: the user's a11y panel re-scans automatically once the file saves, and the violation should drop off. If it doesn't, the wrong token was moved or the change landed in the wrong theme block.
+
+## General rules
+
+- Prefer pattern fixes over instance fixes. If many entries point at the same file or component, fix the source component once.
+- For synthetic `tab-order`, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no axe `helpUrl`; use the WCAG page in `context.helpUrl`.
+- When `a11y.accessible_name` is empty and `a11y.focusable` is true, naming is usually the highest-priority fix.
+- Layout and document-head rules usually belong in root or layout files, not the selected leaf component.
diff --git a/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/ERROR_FIX.md b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/ERROR_FIX.md
new file mode 100644
index 0000000..d6b598c
--- /dev/null
+++ b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/ERROR_FIX.md
@@ -0,0 +1,40 @@
+# Error fix tasks
+
+`error_fix` tasks come from the Errors tab in the Annotask shell. Each task
+captures one or more console errors with their stack traces, the route where
+they happened, and the number of occurrences.
+
+## Read order
+
+1. **`task.context.level`** — `'error'` or `'warn'`. Errors block; warnings
+   often don't. Don't suppress warnings into errors and don't downgrade
+   errors into warnings just to make the panel quieter.
+2. **`task.context.errorId`** — stable hash. Use it to confirm you're
+   fixing what the user saw, not a sibling error from the same file.
+3. **`task.context.occurrences`** — when this is high (>50), the error is
+   firing on every render or interaction. Prioritize root-cause fixes over
+   try/catch wrappers.
+4. **Stack trace** — read the top frame to locate the throw, but read the
+   second and third frames to understand who called it. The fix usually
+   lives at the caller, not the throw site.
+
+## Fix patterns
+
+- **Undefined property access** (`Cannot read properties of undefined`) —
+  fix the producer, not the consumer. Adding `?.` everywhere hides the
+  real defect.
+- **Hydration mismatch** (React/Vue/Svelte SSR) — the server and client
+  rendered different output. Find the divergent branch (often
+  `typeof window !== 'undefined'`) and align them.
+- **Network errors** — surface to the user; don't swallow with a generic
+  toast unless the user explicitly asked for one.
+
+## Don't
+
+- Don't add `try/catch` around the call site just to silence the error.
+- Don't add `console.error` suppressions or noise filters.
+- Don't change the error to a warning to clear the panel.
+
+When you finish, set `status: 'review'` with a one-line resolution that
+states (a) the root cause and (b) the file you touched. The user will
+verify in the Errors tab that the count stays at zero.
diff --git a/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/PERF_FIX.md b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/PERF_FIX.md
new file mode 100644
index 0000000..fd2259f
--- /dev/null
+++ b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/PERF_FIX.md
@@ -0,0 +1,57 @@
+# Performance fix tasks
+
+`perf_fix` tasks come from the Perf tab. Each task points at one finding:
+a Web Vital that regressed, a heavy resource group, a heavy bundle
+package, or long main-thread tasks captured during a recording.
+
+## Read order
+
+1. **`task.context.category`** — what kind of finding this is:
+   `'vital' | 'resource' | 'long-task' | 'bundle'`. The fix surface
+   varies dramatically by category; don't apply a vitals recipe to a
+   bundle task.
+2. **`task.context.metric`** — present **only on `vital` findings**: the
+   uppercase Web Vital name (`'LCP'`, `'CLS'`, `'INP'`, `'TTFB'`,
+   `'FCP'`). Non-vital findings have no `metric`; key off `category`
+   and `findingId` instead.
+3. **`task.context.findingId`** — stable id that also encodes the
+   offender: `vital:LCP`, `resource:heavy-script`,
+   `bundle:lodash`, `blocking:long-tasks`.
+4. **`task.context.value`** + **`unit`** — the observed value (`'ms'`
+   for vitals and long tasks, `'bytes'` for resource/bundle findings,
+   empty unit for CLS which is unitless). Use this to verify your fix
+   in the Perf tab post-edit.
+5. **`task.context.severity`** — the Web Vitals rating scale:
+   `'good' | 'needs-improvement' | 'poor'`. `poor` CLS (>0.25) usually
+   means a single layout shift you can squash; `needs-improvement` may
+   be unfixable without redesign.
+6. **`task.context.detail`** / **`resources`** — human-readable summary,
+   and (on `resource` findings) the offending URLs with sizes and
+   durations. `context.metrics` carries the full snapshot when one was
+   captured.
+
+## Fix patterns
+
+- **LCP** — defer or preload the largest contentful element. Drop hero
+  images to the right format/size; preconnect to the right origins.
+- **CLS** — explicit dimensions on images, reserved space for async
+  content (banners, ads, late-loaded fonts).
+- **INP** — break long tasks, debounce input handlers, move work off the
+  main thread. `blocking:long-tasks` findings give you Total Blocking
+  Time and pair naturally with INP work.
+- **Resource / bundle size** — confirm the offender lives in user code,
+  not a vendor chunk. Tree-shake or lazy-load instead of swapping
+  libraries; the `bundle:<package>` finding's detail may already
+  suggest a lighter alternative.
+
+## Don't
+
+- Don't suppress the metric by changing what gets counted (e.g. excluding
+  a route from RUM).
+- Don't ship a "fix" that improves the metric in dev but regresses in
+  prod (e.g. removing `import.meta.hot` blocks).
+- Don't refactor unrelated code in a perf task.
+
+Set `status: 'review'` with a resolution that names the finding and the
+post-fix expected value (`'CLS dropped from 0.31 to ~0.05 — reserved space
+for hero image'`). The user re-runs the Perf scan to confirm.
diff --git a/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/SKILL.md b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/SKILL.md
index 49921a2..49bca89 100644
--- a/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/SKILL.md
+++ b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/SKILL.md
@@ -1,7 +1,14 @@
+---
+name: annotask-apply
+description: Apply pending Annotask design tasks to the source code. Use when the user asks to apply Annotask changes, apply design changes, sync Annotask, or runs /annotask-apply.
+---
+
 # annotask-apply
 
 Apply pending Annotask design tasks to the source code.
 
+> **For editor agents (Claude Code, Cursor, Windsurf).** Annotask's built-in agent runs apply directly through the shell — the user runs a task from the Conversation tab and the local-CLI provider edits files in place. This skill exists when the user prefers to drive apply from their own editor agent instead.
+
 ## When to use
 
 Use this skill when the user says:
@@ -12,7 +19,7 @@ Use this skill when the user says:
 
 ## How it works
 
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
+Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, and text highlights (sections are wireframe sketch material — they arrive as `wireframe_apply` add directions, not Annotate tasks). These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
 
 ## MCP preference
 
@@ -96,144 +103,93 @@ npx annotask update-task TASK_ID --status=in_progress --mcp
 
 #### b. Reference the design spec for consistency
 
-Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
+Use the design spec when the task changes visual design, layout tokens, typography, spacing, or introduces new UI that should match the existing system.
 
-**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
+**MCP:** `annotask_get_design_spec()`
 
 ```bash
 npx annotask design-spec --mcp
 ```
 
-Response example:
-```json
-{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
-```
-
-For detailed tokens in a specific category:
+For one category only:
 
 ```bash
 npx annotask design-spec --category=colors --mcp
 ```
 
-**When to use:**
-- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
-- **Typography changes** — Reference the font scale and families from the spec
-- **Responsive design** — Use detected breakpoints when adding media queries
-- **New components** — Match the design system when creating new UI
+Apply it narrowly:
+- Prefer existing tokens over hardcoded values
+- Use the project's spacing and breakpoint scale
+- Reuse the detected styling conventions instead of introducing a new pattern
 
-**How to apply:**
-- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
-- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
-- For responsive design, use the detected breakpoints
-- Document the token reference in your resolution note (e.g., "Applied primary color token")
+#### c. Gather only the extra context this task needs
 
-#### c. Find relevant components (required when adding any UI element)
+Start with the task summary. Pull more context only when it changes the implementation.
 
-If the task asks you to add, insert, or create a UI element of any kind — a table, button, card, modal, input, dropdown, form, list, nav, etc. — you **must** search the component library first before writing HTML from scratch. This applies to all task types: `section_request`, `annotation` with actions like `add_column`/`add_row`/`wrap_container`, and free-text `annotation` notes whose `description` implies new UI.
+**Re-anchor stale tasks**
 
-**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
+For **denied** tasks, old `in_progress` tasks, or any task whose `file`/`line` may have drifted, call `annotask_get_code_context(task_id)` before editing.
 
 ```bash
-npx annotask components "button" --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
-```
-
-For a specific component, get its full prop signature:
-
-```bash
-npx annotask component Button --mcp
+npx annotask code-context TASK_ID --mcp
 ```
 
-For **in-repo usage examples** (real prop combinations + import path this project actually uses), call `annotask_get_component_examples(name: "Button")` — or `npx annotask component-examples Button --mcp`. Prefer the example's import path and prop shape over reinventing: the examples show how *this* codebase uses the component, not just what the library exposes.
+Use `symbol` + `excerpt` to locate the edit target. Treat `excerpt_hash` as a cheap drift check across retries.
 
-#### c-ter. Find the data source (required for any task that adds or modifies data-driven UI)
+**If the task adds UI, find components first**
 
-Before writing UI that renders data, check what's already wired. If the task's summary contains `data_context_summary` (e.g. `"hook:useUserQuery"` or `"store:useCounterStore"`), that's the primary data source powering the selected element. For the full picture:
+If the task asks you to add, insert, or create UI of any kind — table, button, card, modal, input, dropdown, form, list, nav, layout wrapper — search the component library before writing custom HTML. This applies to `section_request`, structural `annotation` actions like `add_row` or `wrap_container`, and free-text notes that clearly imply new UI.
 
-**MCP:** `annotask_get_data_context(task_id: "TASK_ID")` — returns the complete `DataContext`: every data reference in the enclosing file (`sources`, sorted with the primary source at index 0 — closest to `task.line`, tie-broken by kind precedence), `rendered_identifiers` from the template/JSX (CSV), and `route_bindings` (CSV).
+**MCP:** `annotask_get_components(search: "button")`
 
 ```bash
-npx annotask data-context TASK_ID --mcp
+npx annotask components "button" --mcp
 ```
 
-To browse the project's catalog of hooks, stores, and fetch wrappers (sorted by `used_count` — most load-bearing first):
-
-**MCP:** `annotask_get_data_sources(used_only: true)` — filter to entries actually used elsewhere in the codebase.
+If a candidate looks right, inspect the exact API and project usage:
 
 ```bash
-npx annotask data-sources --used-only --mcp
+npx annotask component Button --mcp
+npx annotask component-examples Button --mcp
 ```
 
-To see **real in-repo usages** of a specific data source (destructuring patterns, parameter shape, common wrappers — parallel to `annotask_get_component_examples`):
+Prefer the import path and prop shape from `annotask_get_component_examples` over inventing a fresh usage.
 
-**MCP:** `annotask_get_data_source_examples(name: "useUserQuery", kind: "composable")`
+**If the task binds or changes data, inspect the existing data path**
 
-```bash
-npx annotask data-source-examples useUserQuery --kind=composable --mcp
-```
+Do this only for data-driven work: showing real data, rewiring an existing hook/store, changing filters or queries, or fixing a denied task that used fake or wrong data.
 
-To see **what shape comes back** from an API — cross-reference declared schemas (OpenAPI, GraphQL, tRPC) so you don't guess field names:
-
-**MCP:** `annotask_resolve_endpoint(url: "/api/cats")` → returns the best-match operation with a confidence score.
+Start with what the task already tells you:
+- If the summary has `data_context_summary`, use that as the first candidate source
+- If that is not enough, call `annotask_get_data_context(task_id)` to inspect nearby sources in the current file
 
 ```bash
-npx annotask resolve-endpoint /api/cats --mcp
+npx annotask data-context TASK_ID --mcp
 ```
 
-**MCP:** `annotask_get_api_operation(path: "/api/cats", method: "GET")` — full request / response schema for a known path pattern.
+Only expand further when needed:
+- `annotask_get_data_sources(used_only: true)` / `npx annotask data-sources --used-only --mcp` when you need to find a reused project-level source
+- `annotask_get_data_source_examples(name)` / `npx annotask data-source-examples NAME --kind=composable --mcp` when you need the real import path or call-site shape
+- `annotask_resolve_endpoint(url)` or `annotask_get_api_operation(path, method)` when you need response field names or schema details
+- `annotask_get_api_schemas(detail: true)` only as a last resort when you still do not know which schema owns the endpoint
 
-```bash
-npx annotask api-operation /api/cats --method=GET --mcp
-```
+Prefer reusing an existing hook/store/fetch wrapper over writing new data plumbing.
+
+**If the task references a flow or rendered structure, pull it on demand**
 
-**MCP:** `annotask_get_api_schemas(detail: true)` — browse every discovered schema source up front.
+Use interaction history when the task depends on the user's path through the app:
 
 ```bash
-npx annotask api-schemas --detail --mcp
+npx annotask interaction-history TASK_ID --mcp
 ```
 
-If a task summary shows `response_schema_ref: "Cat[]"`, the agent already knows a declared shape exists — `annotask_get_api_operation` or `annotask_resolve_endpoint` will surface the full JSON schema.
-
-**When to use:**
-- Any task where the user's description mentions adding, replacing, or rewiring data — "show the current user", "list orders", "filter by status", "fetch from the API".
-- Denied tasks where feedback mentions wrong or fake data.
-- Section requests that need to render real information.
-
-**How to apply:**
-- Prefer reusing a hook/store from `data_context.sources` or `data-sources` catalog over writing new fetch code.
-- Copy the import path and call-site shape from `data-source-examples`, not from library docs.
-- If `sources[0]` doesn't match the user's description (e.g. task says "user name" but `sources[0]` is `useOrdersQuery`), check the rest of the `sources` list — the right hook is usually there.
-
-**When to use:**
-- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
-- **UI additions** — Check if a table, button, card, modal, input, form, list, or nav component already exists before writing custom HTML
-- **Styling consistency** — Using library components ensures your changes match the design system
-
-**How to apply:**
-- Search for components matching the intent (e.g., "table" if adding tabular data, "dropdown" if adding a select menu)
-- Read the props to understand customization options (variant, size, disabled, etc.)
-- Call `annotask_get_component_examples` to see how the component is already used in this codebase; copy the import path and prop patterns from there
-- Use the component in your JSX/Vue/Svelte code with appropriate props
-- Document the component reference in your resolution note
-
-#### c-bis. Re-anchor older or retried tasks
-
-For **denied** tasks, tasks that have been sitting in the queue while you edited other files, or any task whose `file`/`line` you suspect has drifted: call `annotask_get_code_context(task_id)` before editing.
+Use rendered HTML when the task refers to post-render structure that is easier to inspect from the DOM than from source:
 
 ```bash
-npx annotask code-context TASK_ID --mcp
-```
-
-Response:
-```json
-{"file":"src/components/Header.vue","line":42,"symbol":"Header","excerpt_start_line":27,"excerpt_end_line":57,"excerpt":"...","imports":["import ..."],"excerpt_hash":"ab12cd34ef56..."}
+npx annotask rendered-html TASK_ID --mcp
 ```
 
-Use `symbol` + `excerpt` to locate the edit target; the `excerpt_hash` is a cheap drift check on subsequent retries (if the hash changes between attempts, the surrounding code moved). Skip this step for fresh pending tasks where `file`/`line` are known good.
+Both tools prefer embedded task payloads when present and otherwise fall back to the per-task sidecar under `.annotask/`.
 
 #### d. Apply the change
 
@@ -241,121 +197,26 @@ Read the task type and apply accordingly:
 
 - **`annotation` with `action: "text_edit"`**: The `description` field says what text to change. Find the text in the source file and apply the edit.
 
-- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run step c first.
+- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run the component lookup in step c first.
 
-- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run step c (component library search) before writing HTML.**
+- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run the component lookup in step c before writing HTML.**
 
 - **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
 
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
-
-- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID, or the synthetic `tab-order` rule from Annotask's tab-order overlay), `impact`, `help`, `helpUrl`, and `elements` array with `html`, `selector`, `fix`, source `file`/`line`/`component`, and a per-element `a11y` block with computed accessibility metadata:
-
-  ```
-  elements[i].a11y = {
-    accessible_name, name_source,   // "Sign in", source: aria-label | labelledby | label | alt | text | placeholder | none
-    role, role_source,              // "button", source: explicit | implicit | none
-    tabindex, focusable,            // null | number, true/false
-    focus_indicator,                // "visible" | "none" | "unknown"
-    contrast,                       // { foreground, background, ratio, aa_normal, aa_large, ... } only when element has text
-    aria_attrs,                     // [{ name: "aria-expanded", value: "false" }, ...]
-  }
-  ```
-
-  If `screenshot_meta` is present (the user manually attached one with the snip tool), retrieve it via `annotask_get_screenshot` before proposing visual changes (color-contrast, focus rings).
-
-  **Per-rule playbook.** Most rules fall into one of these patterns — match by `context.rule`:
-
-  | Rule(s) | Fix layer | What to do |
-  |---|---|---|
-  | `color-contrast`, `color-contrast-enhanced` | Design tokens first | Read `elements[i].a11y.contrast` for the actual fg/bg hex + ratio. If the colors come from theme tokens (check `cssVar` lookups in the source), adjust the token. If the contrast comes from a one-off inline style or hardcoded class, fix the component, not the token (you'd regress every other consumer). |
-  | `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` referencing visible text. `a11y.accessible_name` shows what (if anything) the input currently exposes — when `name_source === 'placeholder'`, the input has no real label. |
-  | `button-name`, `link-name`, `input-button-name` | Markup | Add visible text content or `aria-label`. For icon-only buttons add a visually hidden `<span class="sr-only">` (or your project's equivalent). Don't add `title` — it's not reliable for SR users. |
-  | `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | `alt=""` for decorative imagery, descriptive `alt` for informational. For `<img>` that conveys text, use the text. For SVG icons that pair with visible text, use `aria-hidden="true"`. |
-  | `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These almost always live in a layout component (e.g. `App.vue`, `_layout.tsx`, `RootLayout`), not in leaf components. |
-  | `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert/promote `<h1>`; renumber subsequent levels so the outline is contiguous. Usually a layout/section component change, not a leaf change. |
-  | `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what's set. Reference the WAI-ARIA roles spec (`helpUrl`) for the role's allowed attributes. Remove disallowed attrs; add required ones. |
-  | `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Either remove `aria-hidden`, or move the focusable elements outside (or set `tabindex="-1"` and ensure they're never the focus target). |
-  | `tabindex`, **synthetic** `tab-order` | Markup | Remove positive `tabindex`; use 0 (focusable in DOM order) or -1 (programmatically focusable, not in tab order). For the synthetic `tab-order` rule, `context.tab_order.flag` is one of `positive` / `unreachable` / `reorder` — fix the source markup so DOM order matches visual order. |
-  | `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Single source of truth — usually `index.html` (Vite/CRA), `app/layout.tsx` (Next), `src/routes/+layout.svelte` (SvelteKit), or the framework's root document. |
-  | `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>`/`<span>`. Don't nest interactive elements (e.g. `<button>` inside `<a>`). |
-  | `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element of the layout. Style it with the visually-hidden pattern that becomes visible on `:focus`. |
-  | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="…"` and rename one. If the id is dynamic, ensure the generation key is unique per instance. |
-  | `frame-title`, `iframe-title` | Markup | Add `title="…"` describing the iframe's purpose. |
-
-  **General rules:**
-  - Prefer **pattern fixes** over instance fixes. When `elements` contains many entries that share the same `file`/`component`, change the source component once — don't paste the same fix N times.
-  - For the synthetic `tab-order` rule, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no `helpUrl` from axe — use the linked WCAG focus-order page in `context.helpUrl`.
-  - When `a11y.accessible_name` is empty and `a11y.focusable` is true, the element is unreachable for screen readers — naming is the highest-priority fix.
-
-- **`theme_update`**: One or more design token value changes committed together from the Theme page. A single task now covers every edit the user made in one Commit click — do not expect one task per token. The `context` object contains:
-  - `edits`: array of token edits. Each entry has:
-    - `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
-    - `role`: semantic role name (e.g. `primary`, `background`, `heading`)
-    - `cssVar`: CSS variable name if backed by one (e.g. `--color-primary`), or `null`
-    - `theme_variant`: the theme id this edit targets (e.g. `light`, `dark`)
-    - `theme_selector`: how that variant is activated in the DOM — `{kind:'default'}`, `{kind:'attribute',host,name,value}`, `{kind:'class',host,name}`, or `{kind:'media',media}` — tells you which CSS block owns this variable (`:root`, `:root[data-theme="dark"]`, `.dark`, `@media (prefers-color-scheme: dark)`)
-    - `before`: old value (`null` for new tokens)
-    - `after`: new value
-    - `sourceFile` / `sourceLine`: where the current declaration lives (both `null` for new tokens — you pick the location)
-    - `isNew`: `true` if this token didn't exist before
-  - `styling`: array of project styling methods (e.g. `["tailwind", "scoped-css"]`)
-  - `specFile`: relative path to the design spec (typically `.annotask/design-spec.json`)
-
-  **How to apply:**
-  1. **Group `context.edits` by `sourceFile`.** For each file (skipping `null`/`isNew` for now), open it once, apply every edit against its file in a single Edit-batch, save. Use `theme_selector` + `cssVar` to locate the right declaration block — e.g. an edit with `theme_selector: {kind:'attribute',host:'html',name:'data-theme',value:'dark'}` belongs inside `:root[data-theme="dark"] { … }`, a `{kind:'default'}` edit belongs in the base `:root { … }` block.
-  2. **Tailwind config edits:** if `cssVar` is `null` and `sourceFile` references `tailwind.config.*`, update the corresponding key. If edits span both Tailwind and raw CSS, handle each file independently.
-  3. **New tokens (`isNew: true`):** add the CSS variable to the declaration block matching `theme_selector`. If no block exists for that variant yet, create one (e.g. add `:root[data-theme="dark"] { --new-var: …; }` at the end of the main tokens file). After writing, remember the final file path and line for step 4.
-  4. **Patch `.annotask/design-spec.json` once at the end.** Resolve `context.specFile` against the MFE root (the directory containing `.annotask/`). For each edit:
-     - Existing token: find `spec.<category>` — note dotted categories like `typography.families` map to nested paths — locate the entry by `role`, then set `values[theme_variant] = after`.
-     - New token: append a token object with `role`, `values: { [theme_variant]: after }`, `cssVar`, and fresh `sourceFile` / `sourceLine` pointing at where you added the declaration in step 3.
-     - When writing, keep the existing JSON formatting (same indentation, trailing newline) so the file watcher's next broadcast is clean.
-  5. The server watches `design-spec.json`; saving it fires a `designspec:updated` push and the Theme page refetches automatically.
-
-  **Worked example:** `context.edits = [{ category:'colors', role:'background', cssVar:'--stress-bg', theme_variant:'light', theme_selector:{kind:'default'}, before:'#f4f7fb', after:'#ff00ff', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:12, isNew:false }, { category:'colors', role:'text', cssVar:'--stress-text', theme_variant:'dark', theme_selector:{kind:'attribute',host:'html',name:'data-theme',value:'dark'}, before:'#e7eefb', after:'#ffeb3b', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:65, isNew:false }]` → open `tokens.css` once, update `--stress-bg` in the `:root` block and `--stress-text` in the `:root[data-theme="dark"]` block, save. Then open `.annotask/design-spec.json`, set `colors[?role=='background'].values.light = '#ff00ff'` and `colors[?role=='text'].values.dark = '#ffeb3b'`, save. Mark the task `review` with resolution `"Updated 2 color tokens in tokens.css and design-spec.json"`.
-
-- **`api_update`**: In-repo backend-contract edit. Created from the shell's Data view when the user selects an internal data source (`schema_in_repo === true`) and fills in a desired change. Only valid for in-repo schemas — external APIs cannot be edited from Annotask and should be marked `blocked` with an explanation if a request implies one.
-
-  The `context` object carries:
-  - `data_source_name`: hook/store/query identifier (e.g. `useCatsQuery`)
-  - `data_source_kind`: one of `composable | signal | store | fetch | graphql | loader | rpc`
-  - `schema_location`: path to the schema file (e.g. `openapi.yaml`, `src/trpc/router.ts`)
-  - `schema_kind`: `openapi | graphql | trpc | jsonschema`
-  - `endpoint`: literal endpoint / query key when the source used one
-  - `operation`: `{ method, path }` from the matched schema operation, when a match exists
-  - `desired_change`: user's description of the needed contract change
-  - `rationale`: optional "why"
-
-  **How to apply:**
-  - Open the schema file at `context.schema_location`. Read the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`) and make the change described in `desired_change`.
-  - Update the handler / backend implementation that serves that operation (typical pairs: OpenAPI routes ↔ the framework-specific handler file, tRPC router ↔ its procedure body).
-  - Update the frontend data source at `file:line` if the shape change affects the consumer (e.g. return type, destructured fields).
-  - If the change is additive (new optional field), you usually don't need to change existing callers. If it's breaking (required field, renamed field), search for all usages with `annotask_get_data_source_examples` and update them.
-  - Record what you changed in the resolution note — mention which schema location, which operation, and any frontend call sites touched.
-
-- **`annotation` with cross-boundary API edits**: An annotation task may turn out to require an in-repo API change (e.g. "show expiration date on the tier badge" when the `Cat` schema does not currently return `expires_at`).
-
-  **Rule**: do **not** silently edit the backend. Ask the user first via a `needs_info` question:
-  > This change requires updating the internal API route `GET /api/cats` to add an `expires_at` field on the `Cat` response. Proceed with both frontend and backend edits? (yes / no)
-
-  If the user approves, continue the same task (do **not** spawn a separate `api_update` task). Record each API edit structurally in `task.context.api_edits[]`:
-  ```json
-  {
-    "api_edits": [
-      {
-        "schema_location": "openapi.yaml",
-        "schema_kind": "openapi",
-        "operation": { "method": "GET", "path": "/api/cats" },
-        "change_summary": "Added nullable expires_at: string (ISO date) to the Cat response schema and handler."
-      }
-    ]
-  }
-  ```
-  Annotask's summary lifting will surface `api_edits_count` on the triage view so the user sees this task crossed the frontend/backend line.
-
-  If the user denies, do the frontend-only thing you can, or mark the task `blocked` with an explanation pointing at the missing backend support.
-
-  If the data source is external (`schema_in_repo === false`) and the task requires a contract change, mark the task `blocked` immediately — Annotask cannot edit APIs outside the repo.
+  The same `context.changes` array may also carry these three **legacy** types — the current UI no longer emits them, but apply them per these rules when they appear in older tasks:
+  - `{"type": "component_prop_update", "element", "prop", "before", "after", "binding", "prop_type"?, "file", "line"}` — one prop value change at a component **usage site** (`file:line` is where `<Element …>` is written). Respect `binding`: `"literal"` means rewrite the plain attribute value (`label="Reset"` → `label="Clear"`); `"expression-literal"` means the literal is written through binding syntax — **keep the syntax** (`:count="3"` → `:count="4"`, `count={3}` → `count={4}`); `"new"` means the prop isn't present at the usage site — add it using the framework's idiomatic form for `prop_type`. Bound expressions never appear here (the UI refuses them) — if `before` doesn't match what you find in source, re-anchor via `annotask_get_code_context` instead of guessing, and never rewrite an expression that references variables.
+  - `{"type": "text_update", "element", "before", "after", "file", "line"}` — a literal text-content change. The element at `file:line` has a single literal text run equal to `before`; replace it with `after`. If the text there is an interpolation/expression or doesn't match `before`, the source drifted — re-anchor or ask, never overwrite a binding.
+  - `{"type": "component_move", "element": {"tag", "component"?, "from_file", "from_line"}, "move_to": {"target_file", "target_line", "position"}}` — relocate the element's source block from `from_file:from_line` to the given position (`before`/`after`/`append`/`prepend`) relative to `target_file:target_line`. Move the markup intact (including its bindings and children); adjust imports only if the move crosses files.
+
+- **`section_request`** (**legacy** — the current UI no longer emits these; sections now arrive as `wireframe_apply` `add` directions with an `md` body. Apply this rule when older task files carry one): Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and the relevant step-c lookups before writing custom HTML.
+
+- **`a11y_fix`**: Fix an accessibility violation. Read `A11Y_RULES.md` in this skill directory before applying the change. If you are working through multiple a11y tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: prefer pattern fixes over instance fixes, expect layout/head rules to live in root or layout files, and fetch the screenshot first when the issue is visual (contrast, focus ring, hidden text, similar).
+
+- **`theme_update`**: Apply batched design-token edits from the Theme page. Read `THEME_UPDATE.md` in this skill directory before applying the change. If you are working through multiple theme tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: one task may include many edits, update source files before `.annotask/design-spec.json`, and land `theme_update` before dependent `style_update` tasks.
+
+- **`wireframe_apply`**: Implement the user's wireframe — snapshot-sketch directions (`context.session` entries with `change.type: 'wireframe_direction'`) and/or palette placements (`context.wireframe.instances[]`) — in real source. Read `WIREFRAME_APPLY.md` in this skill directory before applying the change. If you are working through multiple wireframe tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: pixel geometry is a hint and the direction's `relations` are the contract (implement intent with idiomatic layout, never absolute positioning); placements/directions carry durable `anchor`s (`file`/`line`) — resolve component imports via `annotask_get_component_examples` rather than guessing; and never fabricate handlers/children/data — placeholders stay visibly placeholders.
+
+- **`annotation` with cross-boundary API edits**: Some frontend requests turn out to depend on backend work (for example, a field is not returned by the current response schema). Do **not** edit the backend and do **not** ask for permission to do so. If there is a meaningful frontend-only fallback, apply it and explain the missing backend support in the resolution note. Otherwise, mark the task `blocked` and tell the user which API/schema change would be required.
 
 #### e. Ask for clarification (only when stuck)
 
diff --git a/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/THEME_UPDATE.md b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/THEME_UPDATE.md
new file mode 100644
index 0000000..b56494b
--- /dev/null
+++ b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/THEME_UPDATE.md
@@ -0,0 +1,46 @@
+# Theme Update
+
+Read this file for `theme_update` tasks. If you are applying a batch of theme tasks, read it once for the batch, not once per task.
+
+## Task context
+
+`theme_update` batches every token edit from one Theme-page commit into a single task.
+
+The `context` object contains:
+
+- `edits[]`: token edits
+- `styling[]`: project styling methods such as `tailwind` or `scoped-css`
+- `specFile`: relative path to `.annotask/design-spec.json`
+
+Each edit contains:
+
+- `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
+- `role`: semantic token role such as `primary` or `background`
+- `cssVar`: CSS variable name when present, otherwise `null`
+- `theme_variant`: variant id such as `light` or `dark`
+- `theme_selector`: selector metadata describing which declaration block owns the value
+- `before`, `after`
+- `sourceFile`, `sourceLine`
+- `isNew`
+
+## Apply flow
+
+1. Group `context.edits` by `sourceFile`.
+2. For each existing source file, open it once and apply every edit in one pass.
+3. Use `theme_selector` + `cssVar` to locate the correct block:
+   - `{kind:'default'}` -> base `:root`
+   - `{kind:'attribute', ...}` -> matching attribute-scoped block such as `:root[data-theme="dark"]`
+   - `{kind:'class', ...}` -> matching class-scoped block such as `.dark`
+   - `{kind:'media', ...}` -> matching media-query block
+4. If `cssVar` is `null` and the file is `tailwind.config.*`, update the matching config key instead of searching CSS.
+5. For `isNew: true`, add the token to the correct variant block. Create the block if it does not exist yet.
+6. Patch `.annotask/design-spec.json` once at the end:
+   - existing token -> update `values[theme_variant]`
+   - new token -> append a token entry with `role`, `values`, `cssVar`, `sourceFile`, and `sourceLine`
+7. Keep the existing JSON formatting so the file watcher emits a clean update.
+
+## Defaults
+
+- One `theme_update` task may touch multiple files.
+- Edit source files before patching `.annotask/design-spec.json`.
+- `theme_update` should land before any dependent `style_update` in the same apply run.
diff --git a/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/WIREFRAME_APPLY.md b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/WIREFRAME_APPLY.md
new file mode 100644
index 0000000..dfbc207
--- /dev/null
+++ b/playgrounds/simple/vue-webpack/.claude/skills/annotask-apply/WIREFRAME_APPLY.md
@@ -0,0 +1,121 @@
+# Wireframe Apply
+
+Read this file for `wireframe_apply` tasks. If you are applying a batch, read it once for the batch, not once per instance.
+
+A `wireframe_apply` task arrives two ways:
+
+1. **"Implement this wireframe"** — the user froze a route into a snapshot sketch (per-block images of the real render), rearranged it freely, and asked you to implement the intent. The task carries **wireframe directions** in `context.session.entries[]` (`change.type === 'wireframe_direction'`) plus a labeled before/after composite screenshot.
+2. **"Build this route" / "Apply now"** — palette placements in `context.wireframe.instances[]` and/or design-session edits in `context.session.entries[]` (style/class/move/insert change types).
+
+A task may carry both halves. Handle directions with the rules below; handle placements and other session entries with the later sections.
+
+## Wireframe directions (`change.type: 'wireframe_direction'`)
+
+The user rearranged a SKETCH — images of the rendered page, not the live app. The server diffed the sketch against the original capture into one direction per changed block:
+
+- `op`: `move` | `resize` | `delete` | `add` | `note`.
+- `block`: `{ label, component?, tag? }` — the block's identity as captured. Tool-derived, never invented.
+- `file`/`line` (top level): the block's captured source anchor — or, for `add`, the nearest anchored NEIGHBOR block (see `added.position`).
+- `measured`: TOOL-MEASURED geometry. `before`/`after` rects, `dx`/`dy`, `wPct`/`hPct` (percent of original), and `relations[]` — order-flip / full-width / alignment facts computed from box geometry (e.g. `"now above the filters (was below)"`).
+- `added` (op `add` only): `kind` `component` (a real palette component — `componentName`/`library`/`module`/`props` are REAL scanner output) | `placeholder` (a user-drawn labeled box) | `duplicate` (another copy of a captured block's markup). `position` (`before`/`after`/`append`) is relative to the anchored neighbor. May carry `md` (the user's VERBATIM markdown spec for a drawn section) and/or `data` (a binding to a REAL catalog data source — see *Data bindings on adds* below).
+- `note`: the user's VERBATIM words for that block. `measured` is what the tool measured; `note` is what the user said — never conflate them, and never present a measured relation as a user request.
+
+### Intent over pixels
+
+**Pixel geometry is a hint; the relations are the contract.** `"now above the filters (was below)"` IS the instruction; `y 480→180` is evidence. Implement with idiomatic layout — reorder siblings, change flex/grid order, adjust column spans, use design tokens (`annotask_get_design_spec`) for sizes — never absolute positioning to hit coordinates. A resize of `+50% w` on a card grid usually means "fewer, larger columns", not `width: 1200px`.
+
+### Use the visuals
+
+The task screenshot (`annotask_get_screenshot`) is a labeled composite: **left = the captured render (truth at capture time); right = the user's sketch — rearranged images, not real UI.** Numbered badges on the right pane map 1:1 to the numbered directions in the task description. Look at it before writing code: spatial intent (what ended up next to what) is often clearer in the image than in prose.
+
+### Per-op rules
+
+- **move** — relocate the block's anchored markup to satisfy the relations. Apply per-file edits bottom-up (descending line); re-ground drifted anchors with `annotask_get_source_excerpt`. A loop-rendered block moves as the loop, not one iteration. An exploded container appears as both a container block and separate child blocks (each with finer anchors): directions on children mean restructuring INSIDE the container; a direction on the container means moving the whole thing, children included. (Explode-to-children is deferred this release — `WIREFRAME_EXPLODE_ENABLED=false` — so new tasks won't carry exploded child blocks; this guidance applies to legacy task files that already do.)
+- **resize** — prefer tokens/utility classes/grid-template changes over raw px. Say in the resolution what you chose and why.
+- **delete** — remove the anchored markup. Remove now-dead local bindings only when provably unused; never delete shared code.
+- **add / component** — resolve the real import via `annotask_get_component_examples` (proven specifier + export kind). No in-repo examples → fall back to `library`/`module` and say so. Apply `added.props` primitives only; never fabricate handlers, bindings, or children. When `added.data` is present, wire the REAL source per *Data bindings on adds* below — never sample data.
+- **add / placeholder** (bare — no `md`) — emit a *visibly labeled* placeholder element (e.g. `<div class="placeholder">pagination here</div>` styled per project conventions) or the minimal honest scaffold the label names. **Never fabricate data or content.**
+- **add / placeholder with `added.md` (a drawn SECTION)** — the markdown is the user's verbatim spec for the region: build what it describes per project conventions (component-library-first — run the SKILL.md step-c lookups before writing custom HTML; design tokens for styling). Use `added.data` for any data the section shows. Data-driven content with NO binding → visible placeholder slots or `needs_info` — **never fabricate data or fields.**
+- **add / duplicate** — duplicate the anchored block's markup. If it's loop-rendered, the user probably wants another ITEM or a second instance of the section — read the note/screenshot, ask via `needs_info` when ambiguous.
+- **note** — implement the user's verbatim ask. Ambiguous → `needs_info`, never guess silently.
+
+Before rewriting any expression or bound markup you encounter mid-edit, re-classify it against CURRENT source: `annotask_get_binding_classification` (CLI: `annotask binding-classify`). Never rewrite an expression that references variables.
+
+### Data bindings on adds (`added.data`)
+
+> **Gated off this release.** Wireframe data binding is DEFERRED (`WIREFRAME_DATA_BINDING_ENABLED=false` in `src/shell/wireframeFeatures.ts`), so new `wireframe_apply` tasks won't carry `added.data`. This section applies to legacy/older task files that already contain a binding — when one is present, wire it per the rules below.
+
+`added.data` means "wire THIS source" — it is REAL scanner-catalog identity, never invented:
+
+- `kind`/`name`/`module`/`endpoint`: the source as the project defines it (`module` is its defining file). `path` drills into the response shape (`planets[]` = the list; `data.user` = an object); `fields` are the keys the element should display.
+- `shape_source` is the honesty tag for where the drill-down shape came from:
+  - `api-schema` — a real API contract matched the source's endpoint; the path/fields were picked off the actual response schema. Trust the shape; `annotask_get_api_operation` returns the full operation when you need more.
+  - `source-details` — regex-inferred return-type hints only (no confidence score is carried — the tag is the only signal). Re-verify against the real definition before relying on field names.
+  - `none` — the user typed the path/fields blind. Ground them yourself before wiring.
+- **Re-grounding protocol (always):** call `annotask_get_data_source_details` for the definition and `annotask_get_data_source_examples` for the proven import + call pattern — wire the source the way the project already wires it (same import specifier, same destructuring, loops/`v-for` over the `path` collection, render the `fields`).
+- The binding contradicts current source (source renamed, field gone, shape changed)? → `needs_info` with what you found. **Never invent fields**; runtime endpoints carry no response shapes — don't pretend otherwise.
+
+### Verification & status
+
+Directions are spatial — the server does NOT verify them against source. When you set `review`, direction entries flip `written` on trust (bindings included — their wiring rides the trusted resolution); **your resolution is the only record of what actually landed**, so make it specific and honest per direction: which file(s), what structural change, for bindings the imported source + call site + rendered fields, any file you created (name new files explicitly — in git projects the server nets newly-created files into the undo batch, but your resolution is still the human-readable record). `blocked_reason` when a direction is impossible; `needs_info` for ambiguity; denied → read `feedback` and re-apply the same task.
+
+## Placements (`context.wireframe`)
+
+`context.wireframe` contains:
+
+- `route`: the iframe route the placements were made on (e.g. `/planets`).
+- `instances[]`: one entry per placement.
+
+Each instance contains:
+
+- `id`: stable placement id.
+- `kind`: `component` | `html` | `layout-preset`.
+- `anchor`: where it goes — `{ file, line, position, component, targetTag }`.
+  - `file`, `line`: the drop target's source location (`data-annotask-file` / `-line`). `line` is the target's **opening-tag** line.
+  - `position`: `before` | `after` | `append` | `prepend` — placement relative to the target element.
+  - `component`: the target's owning component (context).
+- `inserted`: what to add — `{ tag, componentName?, library?, props?, classes?, text_content? }`. `inserted.props` are the REAL props.
+- `previewProps` (optional): the display-only sample props the user actually saw rendered on the canvas (e.g. `{ label: "Button" }`). Use them as **hints** for sensible prop values and label text when `inserted.props` is empty or sparse — they show what the user previewed and approved. They are still samples: never lift fabricated event handlers, data bindings, or children from them.
+- `fidelity`: how faithfully it previewed — `live` (rendered in real context), `isolated-preview` (rendered detached, no provider tree), `placeholder` (could not render). Lower fidelity is a hint that the component needs context/props you may have to wire by hand; it is not a blocker.
+- `mounted`: whether the live preview produced output.
+- `status` / `taskId`: lifecycle bookkeeping (`building` + the owning task id while you work). Read-only for you — see the lifecycle section below.
+
+### Apply flow for placements
+
+1. Group `context.wireframe.instances` by `anchor.file`. Open each file once and apply all its placements in one pass, **bottom-up** (descending `anchor.line`): every insertion shifts the lines below it, so applying the highest line number first keeps the remaining anchors' line numbers valid without re-counting.
+2. Locate the anchor element at `anchor.line` in that file. Insert the new markup relative to it per `anchor.position` (`before`/`after` = sibling; `append`/`prepend` = first/last child of the target). Match the file's framework (read `annotask_get_design_spec` for `framework` once) and the surrounding indentation.
+3. Emit markup per `kind`:
+   - **html** → the raw element: `<tag class="…">text_content</tag>` using `inserted.classes` / `inserted.text_content`. Omit empty attributes.
+   - **layout-preset** → a styled wrapper (`<div class="…">` / `<section class="…">`) with `inserted.classes`. It has **no children** — leave it empty for the user to fill. Never fabricate children.
+   - **component** → resolve the real import first, then emit `<ComponentName …props />` (or framework equivalent) at the anchor and add the import if the file does not already import it.
+4. For a `component`, call `annotask_get_component_examples` with `inserted.componentName` (and `inserted.library`) to get the **proven** import specifier + export kind (named vs default) from real in-repo usage. Use that exact import path. If there are no in-repo examples, fall back to `inserted.library` / the scanner `module`, and say so in your resolution — do **not** invent an import path.
+5. Apply props from `inserted.props`, but only primitives that differ from the component's documented defaults. **Never fabricate** event handlers, data bindings, children, or named slots — if a component clearly needs them, note it in the resolution (or use `needs_info`).
+6. After all placements land, set status to `review` with a per-instance resolution (what you inserted, where, and any import you had to guess).
+
+## Other design-session edits (`context.session`)
+
+`context.session` may also carry non-direction entries — the user's design-session edits:
+
+- `session_id`: bookkeeping. The server owns `.annotask/design-session.json`, `.annotask/wireframe.json` (which also carries the canvas sketch), and `.annotask/file-snapshots.json` — **never edit, rewrite, or clean up those files yourself**. Apply through source code only; the server verifies your work and updates the session when you set `review`.
+- `entries[]`: each is `{ id, change, anchor, evidence?, instance_id? }`.
+  - `change` is one of the structured change types (`style_update`, `class_update`, `component_insert`, legacy `component_prop_update`/`text_update`/`component_move`, …) — apply each per the change-type rules in SKILL.md step d.
+  - `anchor` (`{ file, line, targetTag? }`) is where the edit was recorded. Your own earlier edits in the same run shift lines — apply **bottom-up per file** like placements, and re-ground via `annotask_get_source_excerpt` when an anchor doesn't match.
+  - `evidence.classification` (legacy `component_prop_update`/`text_update` entries only) is the round-trip-honesty proof from when the user made the edit: `literal` edits rewrite a plain literal in place; `expression-literal` edits keep the binding syntax (`:count="3"` → `:count="4"`); `bound` edits never appear (the UI refused them). If what you find at the anchor contradicts the evidence, the source drifted — re-anchor or ask via `needs_info`, never rewrite an expression.
+- Prefer idiomatic placement over literal transcription: if a `style_update` matches a design token (`token_role` present, or an obvious token in `annotask_get_design_spec`), apply the token/class rather than a raw value, and say so in the resolution.
+- After you set `review`, the server re-reads the source per entry and marks each `written` or `failed` (directions are trusted — see above) — a `failed` badge in the user's panel means your edit wasn't found where expected, so make resolutions specific about what landed where.
+
+## Lifecycle (do NOT edit .annotask files)
+
+- When the user **accepts** your task, the server removes its instances and the implemented canvas sketch from `wireframe.json` automatically.
+- When the user **deletes** the task, the server reverts instances to `placed` and unlocks the sketch (`building` → `sketch`) so the user can tweak and re-implement.
+- When the user **denies** the task, everything stays locked to your task — re-apply against the same task after reading `feedback`.
+
+## Edge cases
+
+- If an `anchor.file`/`line` no longer matches the described element (source drifted since the capture/placement), call `annotask_get_code_context` for the task to re-anchor; if you still can't place it, mark that instance/direction and use `needs_info`.
+- If a placement or direction requires data/state that doesn't exist yet (e.g. a list component with no data source on the route), use `blocked_reason` to explain what's missing rather than fabricating data.
+
+## Defaults
+
+- One `wireframe_apply` task may touch multiple files and multiple frameworks (MFEs) — handle each file independently.
+- The sketch is a wireframe, not a final design: prioritize correct structure, real imports, and the stated relations over pixel-perfect geometry.
diff --git a/playgrounds/simple/vue-webpack/.claude/skills/annotask-init/SKILL.md b/playgrounds/simple/vue-webpack/.claude/skills/annotask-init/SKILL.md
index 63df6c7..ac5d4e0 100644
--- a/playgrounds/simple/vue-webpack/.claude/skills/annotask-init/SKILL.md
+++ b/playgrounds/simple/vue-webpack/.claude/skills/annotask-init/SKILL.md
@@ -1,7 +1,14 @@
+---
+name: annotask-init
+description: Initialize Annotask for this project by scanning the codebase and generating .annotask/design-spec.json. Use when the user asks to initialize, set up, configure, or scan their project for Annotask, or runs /annotask-init.
+---
+
 # annotask-init
 
 Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
 
+> **For editor agents only.** Annotask's built-in agent runs init through the shell UI — open `http://localhost:5173/__annotask/` and the wizard walks the user through provider setup, project scan, and style guide. This skill exists for users who prefer their own editor agent (Claude Code, Cursor, Windsurf) to do the deeper token extraction the in-shell baseline doesn't cover.
+
 ## When to use
 
 Use this skill when the user says any of:
diff --git a/playgrounds/simple/vue-webpack/.claude/skills/annotask-watch/SKILL.md b/playgrounds/simple/vue-webpack/.claude/skills/annotask-watch/SKILL.md
index d983e8a..8ae3731 100644
--- a/playgrounds/simple/vue-webpack/.claude/skills/annotask-watch/SKILL.md
+++ b/playgrounds/simple/vue-webpack/.claude/skills/annotask-watch/SKILL.md
@@ -1,3 +1,8 @@
+---
+name: annotask-watch
+description: Watch for Annotask design changes in real-time and describe what the user is doing. Use when the user asks to watch or monitor Annotask design changes live.
+---
+
 # annotask-watch
 
 Watch for Annotask design changes in real-time and describe what the user is doing.
diff --git a/playgrounds/stress-test/apps/host-single-spa/.claude/skills/annotask-apply/SKILL.md b/playgrounds/stress-test/apps/host-single-spa/.claude/skills/annotask-apply/SKILL.md
deleted file mode 100644
index 49921a2..0000000
--- a/playgrounds/stress-test/apps/host-single-spa/.claude/skills/annotask-apply/SKILL.md
+++ /dev/null
@@ -1,460 +0,0 @@
-# annotask-apply
-
-Apply pending Annotask design tasks to the source code.
-
-## When to use
-
-Use this skill when the user says:
-- "apply the Annotask changes"
-- "apply my design changes"
-- "sync Annotask"
-- `/annotask-apply`
-
-## How it works
-
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
-
-## MCP preference
-
-If you have `annotask_*` MCP tools available, prefer them over CLI commands — they return structured data directly, are faster, and avoid shell/npx issues. If MCP tools are not available, use the CLI commands shown below.
-
-**Always pass `--mcp` to CLI commands.** The flag emits compact JSON that matches the MCP tool response shapes exactly (no ANSI colors, no human prefixes, `visual` stripped, `agent_feedback` trimmed). That way the same parsing logic works whether you're calling the MCP tool or the CLI fallback.
-
-## Steps
-
-### 0. Check server status
-
-**MCP:** If you have MCP tools, the server is already running — skip this step.
-
-```bash
-npx annotask status --mcp
-```
-
-If this fails, the Annotask dev server isn't running. Ask the user to start it.
-
-### 1. Fetch pending tasks
-
-**MCP:** `annotask_get_tasks(status: "pending")` — returns compact summaries. Use `detail: true` for full objects.
-
-```bash
-npx annotask tasks --mcp --status=pending
-```
-
-Response (compact task summaries):
-```json
-{"version":"1.0","count":1,"tasks":[{"id":"task-123","type":"annotation","status":"pending","description":"Change the header background to match the new brand colors","file":"src/components/Header.vue","line":5,"action":"text_edit","screenshot":"screenshot-1711800000-ab3kf.png"}]}
-```
-
-Each task summary has: `id`, `type`, `status`, `description`, `file`, `line`, and optionally `component`, `action`, `screenshot`, `feedback` (on denied tasks), `blocked_reason`, `resolution`.
-
-For full task details (context, viewport, interaction_history, agent_feedback), use `annotask_get_task` MCP tool or `npx annotask task <id> --mcp` for a single task (`npx annotask tasks --mcp --detail` for the full list). Only fetch full details when the summary doesn't provide enough context to apply the change.
-
-### Screenshot reference
-
-Some tasks include a `screenshot` field. The screenshot shows exactly what the user sees in the browser. To view it:
-
-**MCP:** `annotask_get_screenshot(task_id: "TASK_ID")` — returns base64-encoded PNG directly.
-
-```bash
-npx annotask screenshot TASK_ID
-```
-
-This downloads the PNG to `.annotask/screenshots/`. Use it as visual context alongside the task description and source code. (The screenshot command writes the file on disk — `--mcp` doesn't apply.)
-
-### 2. Triage, group, then apply
-
-Filter actionable tasks: `status: "pending"`, `status: "denied"` (with `feedback`), and `status: "in_progress"` tasks whose `agent_feedback` now contains answers to earlier questions. Skip `needs_info` (waiting for user) and `blocked` (marked not actionable).
-
-Before locking anything, **triage** — read all actionable task summaries and group them by touched resources:
-
-- **By file**: tasks whose `file` is the same go in one group (Edits batched on one Read).
-- **By shared state**: any task that writes `.annotask/design-spec.json`, `:root` CSS variables, `tailwind.config.*`, or a global stylesheet goes in the *shared-state* group regardless of which source file triggered it.
-- **By dependency**: if a `theme_update` adds or changes a token that a `style_update` in the same batch consumes, the `theme_update` goes in an earlier phase. If a `section_request` introduces the UI that an `a11y_fix` targets, the `section_request` goes first.
-
-Within each group: process serially, reading the file once and batching Edits. Across groups that are fully disjoint (no shared file, no shared state, no dependency edge), you may launch parallel subagents — one per group — to apply them concurrently. If in doubt, run serially.
-
-#### Parallelism rules
-
-- **Same file → same group, serial.** Never have two tasks editing the same file concurrently.
-- **Shared global state → one group, serial.** `.annotask/design-spec.json`, `:root` blocks in shared CSS, `tailwind.config.*`, shared layout files, i18n catalogs, route tables, barrel exports.
-- **Dependency order**: `theme_update` before any `style_update` that references the new/changed token; structural task (`section_request`, `annotation` with `wrap_container`/`add_row`/`add_column`) before an `a11y_fix` or `style_update` on the same new UI.
-- **Stale locators**: after edits land, the `file`/`line` on remaining tasks may drift. When in doubt, call `annotask_get_code_context(task_id)` before editing — it returns the current symbol, a ±15 line excerpt, and an `excerpt_hash` you can compare across retries. Otherwise, search by surrounding text/element context over trusting `line` from the original triage.
-- **Non-idempotent inserts**: `add_row`, `add_column`, `section_request`, and free-text "add this" notes can duplicate on retry. Before inserting, confirm the target isn't already present.
-- **If using parallel subagents**: each subagent receives only its group's task IDs plus project context. After all subagents finish, run a quick typecheck/build sanity pass before returning control to the user. If any subagent failed, surface it clearly — do not silently accept partial success.
-
-For each task in a group, follow this cycle:
-
-#### a. Lock the task
-
-Mark it `in_progress` so the user sees you're working on it:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "in_progress")`
-
-```bash
-npx annotask update-task TASK_ID --status=in_progress --mcp
-```
-
-#### b. Reference the design spec for consistency
-
-Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
-
-**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
-
-```bash
-npx annotask design-spec --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
-```
-
-For detailed tokens in a specific category:
-
-```bash
-npx annotask design-spec --category=colors --mcp
-```
-
-**When to use:**
-- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
-- **Typography changes** — Reference the font scale and families from the spec
-- **Responsive design** — Use detected breakpoints when adding media queries
-- **New components** — Match the design system when creating new UI
-
-**How to apply:**
-- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
-- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
-- For responsive design, use the detected breakpoints
-- Document the token reference in your resolution note (e.g., "Applied primary color token")
-
-#### c. Find relevant components (required when adding any UI element)
-
-If the task asks you to add, insert, or create a UI element of any kind — a table, button, card, modal, input, dropdown, form, list, nav, etc. — you **must** search the component library first before writing HTML from scratch. This applies to all task types: `section_request`, `annotation` with actions like `add_column`/`add_row`/`wrap_container`, and free-text `annotation` notes whose `description` implies new UI.
-
-**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
-
-```bash
-npx annotask components "button" --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
-```
-
-For a specific component, get its full prop signature:
-
-```bash
-npx annotask component Button --mcp
-```
-
-For **in-repo usage examples** (real prop combinations + import path this project actually uses), call `annotask_get_component_examples(name: "Button")` — or `npx annotask component-examples Button --mcp`. Prefer the example's import path and prop shape over reinventing: the examples show how *this* codebase uses the component, not just what the library exposes.
-
-#### c-ter. Find the data source (required for any task that adds or modifies data-driven UI)
-
-Before writing UI that renders data, check what's already wired. If the task's summary contains `data_context_summary` (e.g. `"hook:useUserQuery"` or `"store:useCounterStore"`), that's the primary data source powering the selected element. For the full picture:
-
-**MCP:** `annotask_get_data_context(task_id: "TASK_ID")` — returns the complete `DataContext`: every data reference in the enclosing file (`sources`, sorted with the primary source at index 0 — closest to `task.line`, tie-broken by kind precedence), `rendered_identifiers` from the template/JSX (CSV), and `route_bindings` (CSV).
-
-```bash
-npx annotask data-context TASK_ID --mcp
-```
-
-To browse the project's catalog of hooks, stores, and fetch wrappers (sorted by `used_count` — most load-bearing first):
-
-**MCP:** `annotask_get_data_sources(used_only: true)` — filter to entries actually used elsewhere in the codebase.
-
-```bash
-npx annotask data-sources --used-only --mcp
-```
-
-To see **real in-repo usages** of a specific data source (destructuring patterns, parameter shape, common wrappers — parallel to `annotask_get_component_examples`):
-
-**MCP:** `annotask_get_data_source_examples(name: "useUserQuery", kind: "composable")`
-
-```bash
-npx annotask data-source-examples useUserQuery --kind=composable --mcp
-```
-
-To see **what shape comes back** from an API — cross-reference declared schemas (OpenAPI, GraphQL, tRPC) so you don't guess field names:
-
-**MCP:** `annotask_resolve_endpoint(url: "/api/cats")` → returns the best-match operation with a confidence score.
-
-```bash
-npx annotask resolve-endpoint /api/cats --mcp
-```
-
-**MCP:** `annotask_get_api_operation(path: "/api/cats", method: "GET")` — full request / response schema for a known path pattern.
-
-```bash
-npx annotask api-operation /api/cats --method=GET --mcp
-```
-
-**MCP:** `annotask_get_api_schemas(detail: true)` — browse every discovered schema source up front.
-
-```bash
-npx annotask api-schemas --detail --mcp
-```
-
-If a task summary shows `response_schema_ref: "Cat[]"`, the agent already knows a declared shape exists — `annotask_get_api_operation` or `annotask_resolve_endpoint` will surface the full JSON schema.
-
-**When to use:**
-- Any task where the user's description mentions adding, replacing, or rewiring data — "show the current user", "list orders", "filter by status", "fetch from the API".
-- Denied tasks where feedback mentions wrong or fake data.
-- Section requests that need to render real information.
-
-**How to apply:**
-- Prefer reusing a hook/store from `data_context.sources` or `data-sources` catalog over writing new fetch code.
-- Copy the import path and call-site shape from `data-source-examples`, not from library docs.
-- If `sources[0]` doesn't match the user's description (e.g. task says "user name" but `sources[0]` is `useOrdersQuery`), check the rest of the `sources` list — the right hook is usually there.
-
-**When to use:**
-- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
-- **UI additions** — Check if a table, button, card, modal, input, form, list, or nav component already exists before writing custom HTML
-- **Styling consistency** — Using library components ensures your changes match the design system
-
-**How to apply:**
-- Search for components matching the intent (e.g., "table" if adding tabular data, "dropdown" if adding a select menu)
-- Read the props to understand customization options (variant, size, disabled, etc.)
-- Call `annotask_get_component_examples` to see how the component is already used in this codebase; copy the import path and prop patterns from there
-- Use the component in your JSX/Vue/Svelte code with appropriate props
-- Document the component reference in your resolution note
-
-#### c-bis. Re-anchor older or retried tasks
-
-For **denied** tasks, tasks that have been sitting in the queue while you edited other files, or any task whose `file`/`line` you suspect has drifted: call `annotask_get_code_context(task_id)` before editing.
-
-```bash
-npx annotask code-context TASK_ID --mcp
-```
-
-Response:
-```json
-{"file":"src/components/Header.vue","line":42,"symbol":"Header","excerpt_start_line":27,"excerpt_end_line":57,"excerpt":"...","imports":["import ..."],"excerpt_hash":"ab12cd34ef56..."}
-```
-
-Use `symbol` + `excerpt` to locate the edit target; the `excerpt_hash` is a cheap drift check on subsequent retries (if the hash changes between attempts, the surrounding code moved). Skip this step for fresh pending tasks where `file`/`line` are known good.
-
-#### d. Apply the change
-
-Read the task type and apply accordingly:
-
-- **`annotation` with `action: "text_edit"`**: The `description` field says what text to change. Find the text in the source file and apply the edit.
-
-- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run step c first.
-
-- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run step c (component library search) before writing HTML.**
-
-- **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
-
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
-
-- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID, or the synthetic `tab-order` rule from Annotask's tab-order overlay), `impact`, `help`, `helpUrl`, and `elements` array with `html`, `selector`, `fix`, source `file`/`line`/`component`, and a per-element `a11y` block with computed accessibility metadata:
-
-  ```
-  elements[i].a11y = {
-    accessible_name, name_source,   // "Sign in", source: aria-label | labelledby | label | alt | text | placeholder | none
-    role, role_source,              // "button", source: explicit | implicit | none
-    tabindex, focusable,            // null | number, true/false
-    focus_indicator,                // "visible" | "none" | "unknown"
-    contrast,                       // { foreground, background, ratio, aa_normal, aa_large, ... } only when element has text
-    aria_attrs,                     // [{ name: "aria-expanded", value: "false" }, ...]
-  }
-  ```
-
-  If `screenshot_meta` is present (the user manually attached one with the snip tool), retrieve it via `annotask_get_screenshot` before proposing visual changes (color-contrast, focus rings).
-
-  **Per-rule playbook.** Most rules fall into one of these patterns — match by `context.rule`:
-
-  | Rule(s) | Fix layer | What to do |
-  |---|---|---|
-  | `color-contrast`, `color-contrast-enhanced` | Design tokens first | Read `elements[i].a11y.contrast` for the actual fg/bg hex + ratio. If the colors come from theme tokens (check `cssVar` lookups in the source), adjust the token. If the contrast comes from a one-off inline style or hardcoded class, fix the component, not the token (you'd regress every other consumer). |
-  | `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` referencing visible text. `a11y.accessible_name` shows what (if anything) the input currently exposes — when `name_source === 'placeholder'`, the input has no real label. |
-  | `button-name`, `link-name`, `input-button-name` | Markup | Add visible text content or `aria-label`. For icon-only buttons add a visually hidden `<span class="sr-only">` (or your project's equivalent). Don't add `title` — it's not reliable for SR users. |
-  | `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | `alt=""` for decorative imagery, descriptive `alt` for informational. For `<img>` that conveys text, use the text. For SVG icons that pair with visible text, use `aria-hidden="true"`. |
-  | `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These almost always live in a layout component (e.g. `App.vue`, `_layout.tsx`, `RootLayout`), not in leaf components. |
-  | `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert/promote `<h1>`; renumber subsequent levels so the outline is contiguous. Usually a layout/section component change, not a leaf change. |
-  | `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what's set. Reference the WAI-ARIA roles spec (`helpUrl`) for the role's allowed attributes. Remove disallowed attrs; add required ones. |
-  | `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Either remove `aria-hidden`, or move the focusable elements outside (or set `tabindex="-1"` and ensure they're never the focus target). |
-  | `tabindex`, **synthetic** `tab-order` | Markup | Remove positive `tabindex`; use 0 (focusable in DOM order) or -1 (programmatically focusable, not in tab order). For the synthetic `tab-order` rule, `context.tab_order.flag` is one of `positive` / `unreachable` / `reorder` — fix the source markup so DOM order matches visual order. |
-  | `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Single source of truth — usually `index.html` (Vite/CRA), `app/layout.tsx` (Next), `src/routes/+layout.svelte` (SvelteKit), or the framework's root document. |
-  | `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>`/`<span>`. Don't nest interactive elements (e.g. `<button>` inside `<a>`). |
-  | `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element of the layout. Style it with the visually-hidden pattern that becomes visible on `:focus`. |
-  | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="…"` and rename one. If the id is dynamic, ensure the generation key is unique per instance. |
-  | `frame-title`, `iframe-title` | Markup | Add `title="…"` describing the iframe's purpose. |
-
-  **General rules:**
-  - Prefer **pattern fixes** over instance fixes. When `elements` contains many entries that share the same `file`/`component`, change the source component once — don't paste the same fix N times.
-  - For the synthetic `tab-order` rule, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no `helpUrl` from axe — use the linked WCAG focus-order page in `context.helpUrl`.
-  - When `a11y.accessible_name` is empty and `a11y.focusable` is true, the element is unreachable for screen readers — naming is the highest-priority fix.
-
-- **`theme_update`**: One or more design token value changes committed together from the Theme page. A single task now covers every edit the user made in one Commit click — do not expect one task per token. The `context` object contains:
-  - `edits`: array of token edits. Each entry has:
-    - `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
-    - `role`: semantic role name (e.g. `primary`, `background`, `heading`)
-    - `cssVar`: CSS variable name if backed by one (e.g. `--color-primary`), or `null`
-    - `theme_variant`: the theme id this edit targets (e.g. `light`, `dark`)
-    - `theme_selector`: how that variant is activated in the DOM — `{kind:'default'}`, `{kind:'attribute',host,name,value}`, `{kind:'class',host,name}`, or `{kind:'media',media}` — tells you which CSS block owns this variable (`:root`, `:root[data-theme="dark"]`, `.dark`, `@media (prefers-color-scheme: dark)`)
-    - `before`: old value (`null` for new tokens)
-    - `after`: new value
-    - `sourceFile` / `sourceLine`: where the current declaration lives (both `null` for new tokens — you pick the location)
-    - `isNew`: `true` if this token didn't exist before
-  - `styling`: array of project styling methods (e.g. `["tailwind", "scoped-css"]`)
-  - `specFile`: relative path to the design spec (typically `.annotask/design-spec.json`)
-
-  **How to apply:**
-  1. **Group `context.edits` by `sourceFile`.** For each file (skipping `null`/`isNew` for now), open it once, apply every edit against its file in a single Edit-batch, save. Use `theme_selector` + `cssVar` to locate the right declaration block — e.g. an edit with `theme_selector: {kind:'attribute',host:'html',name:'data-theme',value:'dark'}` belongs inside `:root[data-theme="dark"] { … }`, a `{kind:'default'}` edit belongs in the base `:root { … }` block.
-  2. **Tailwind config edits:** if `cssVar` is `null` and `sourceFile` references `tailwind.config.*`, update the corresponding key. If edits span both Tailwind and raw CSS, handle each file independently.
-  3. **New tokens (`isNew: true`):** add the CSS variable to the declaration block matching `theme_selector`. If no block exists for that variant yet, create one (e.g. add `:root[data-theme="dark"] { --new-var: …; }` at the end of the main tokens file). After writing, remember the final file path and line for step 4.
-  4. **Patch `.annotask/design-spec.json` once at the end.** Resolve `context.specFile` against the MFE root (the directory containing `.annotask/`). For each edit:
-     - Existing token: find `spec.<category>` — note dotted categories like `typography.families` map to nested paths — locate the entry by `role`, then set `values[theme_variant] = after`.
-     - New token: append a token object with `role`, `values: { [theme_variant]: after }`, `cssVar`, and fresh `sourceFile` / `sourceLine` pointing at where you added the declaration in step 3.
-     - When writing, keep the existing JSON formatting (same indentation, trailing newline) so the file watcher's next broadcast is clean.
-  5. The server watches `design-spec.json`; saving it fires a `designspec:updated` push and the Theme page refetches automatically.
-
-  **Worked example:** `context.edits = [{ category:'colors', role:'background', cssVar:'--stress-bg', theme_variant:'light', theme_selector:{kind:'default'}, before:'#f4f7fb', after:'#ff00ff', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:12, isNew:false }, { category:'colors', role:'text', cssVar:'--stress-text', theme_variant:'dark', theme_selector:{kind:'attribute',host:'html',name:'data-theme',value:'dark'}, before:'#e7eefb', after:'#ffeb3b', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:65, isNew:false }]` → open `tokens.css` once, update `--stress-bg` in the `:root` block and `--stress-text` in the `:root[data-theme="dark"]` block, save. Then open `.annotask/design-spec.json`, set `colors[?role=='background'].values.light = '#ff00ff'` and `colors[?role=='text'].values.dark = '#ffeb3b'`, save. Mark the task `review` with resolution `"Updated 2 color tokens in tokens.css and design-spec.json"`.
-
-- **`api_update`**: In-repo backend-contract edit. Created from the shell's Data view when the user selects an internal data source (`schema_in_repo === true`) and fills in a desired change. Only valid for in-repo schemas — external APIs cannot be edited from Annotask and should be marked `blocked` with an explanation if a request implies one.
-
-  The `context` object carries:
-  - `data_source_name`: hook/store/query identifier (e.g. `useCatsQuery`)
-  - `data_source_kind`: one of `composable | signal | store | fetch | graphql | loader | rpc`
-  - `schema_location`: path to the schema file (e.g. `openapi.yaml`, `src/trpc/router.ts`)
-  - `schema_kind`: `openapi | graphql | trpc | jsonschema`
-  - `endpoint`: literal endpoint / query key when the source used one
-  - `operation`: `{ method, path }` from the matched schema operation, when a match exists
-  - `desired_change`: user's description of the needed contract change
-  - `rationale`: optional "why"
-
-  **How to apply:**
-  - Open the schema file at `context.schema_location`. Read the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`) and make the change described in `desired_change`.
-  - Update the handler / backend implementation that serves that operation (typical pairs: OpenAPI routes ↔ the framework-specific handler file, tRPC router ↔ its procedure body).
-  - Update the frontend data source at `file:line` if the shape change affects the consumer (e.g. return type, destructured fields).
-  - If the change is additive (new optional field), you usually don't need to change existing callers. If it's breaking (required field, renamed field), search for all usages with `annotask_get_data_source_examples` and update them.
-  - Record what you changed in the resolution note — mention which schema location, which operation, and any frontend call sites touched.
-
-- **`annotation` with cross-boundary API edits**: An annotation task may turn out to require an in-repo API change (e.g. "show expiration date on the tier badge" when the `Cat` schema does not currently return `expires_at`).
-
-  **Rule**: do **not** silently edit the backend. Ask the user first via a `needs_info` question:
-  > This change requires updating the internal API route `GET /api/cats` to add an `expires_at` field on the `Cat` response. Proceed with both frontend and backend edits? (yes / no)
-
-  If the user approves, continue the same task (do **not** spawn a separate `api_update` task). Record each API edit structurally in `task.context.api_edits[]`:
-  ```json
-  {
-    "api_edits": [
-      {
-        "schema_location": "openapi.yaml",
-        "schema_kind": "openapi",
-        "operation": { "method": "GET", "path": "/api/cats" },
-        "change_summary": "Added nullable expires_at: string (ISO date) to the Cat response schema and handler."
-      }
-    ]
-  }
-  ```
-  Annotask's summary lifting will surface `api_edits_count` on the triage view so the user sees this task crossed the frontend/backend line.
-
-  If the user denies, do the frontend-only thing you can, or mark the task `blocked` with an explanation pointing at the missing backend support.
-
-  If the data source is external (`schema_in_repo === false`) and the task requires a contract change, mark the task `blocked` immediately — Annotask cannot edit APIs outside the repo.
-
-#### e. Ask for clarification (only when stuck)
-
-If you are **genuinely stuck** — missing API context, unclear library usage, ambiguous intent that could lead to a wrong implementation — ask the user for clarification instead of guessing:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", questions: [{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}])`
-
-```bash
-npx annotask update-task TASK_ID --mcp --ask='{"message":"Optional markdown context","questions":[{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}]}'
-```
-
-This sets the task to `needs_info` status. The user sees your questions in the Annotask UI and responds there. When answered, the task returns to `in_progress` with answers in `agent_feedback`.
-
-**Question types:**
-- `text` — free-text answer from user
-- `choice` — user picks from your provided `options` array
-
-**Guidelines:**
-- Only ask when you truly cannot proceed — do not ask for confirmation on straightforward tasks
-- Be specific: "Which CSS framework should I use for the grid?" is better than "How should I do this?"
-- Combine related questions into a single ask rather than multiple rounds
-- After asking, move on to the next task. Come back to check answers later via `annotask_get_tasks` MCP tool or `npx annotask tasks --mcp`
-
-#### f. Mark as blocked (when the task can't be done)
-
-If the task is **fundamentally outside your control** — a performance issue in a third-party library, an accessibility bug in a dependency, a config change that requires infrastructure access, etc. — mark it as blocked with an explanation:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", blocked_reason: "This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone.")`
-
-```bash
-npx annotask update-task TASK_ID --mcp --blocked-reason="This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone."
-```
-
-This sets the task to `blocked` status automatically. The user sees your explanation and can either **dismiss** the task or **push back** (deny it with feedback asking you to try a different approach).
-
-**When to use blocked vs needs_info:**
-- `needs_info` = "I can do this, but I need more information from you"
-- `blocked` = "This can't be done through source code changes — here's why"
-
-#### g. Mark for review immediately
-
-As soon as you finish applying **this** task, mark it for review with a brief resolution note:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "review", resolution: "Swapped grid to flexbox, added gap-4 for spacing")`
-
-```bash
-npx annotask update-task TASK_ID --status=review --resolution="Swapped grid to flexbox, added gap-4 for spacing" --mcp
-```
-
-Keep resolutions short — one sentence describing what you changed, not why. The user sees it in the Annotask shell alongside the diff.
-
-#### h. Move to the next task in the group
-
-Repeat steps a–g for each remaining task in the current group, then move to the next group (or confirm parallel subagents have finished). Per-task review flipping is what powers incremental feedback — each task moves to `review` as soon as *its own* edit lands, even inside a batched group, so the user can accept or deny early while later tasks are still in flight.
-
-### 3. Second sweep — catch denies and new tasks that arrived mid-run
-
-Because tasks flip to `review` as soon as their edit lands, the user may have been reviewing (and denying) early tasks while you were still applying later ones. They may also have created brand-new tasks. Before reporting, re-fetch once:
-
-**MCP:** `annotask_get_tasks(status: "denied")` and `annotask_get_tasks(status: "pending")`
-
-```bash
-npx annotask tasks --mcp --status=denied
-npx annotask tasks --mcp --status=pending
-```
-
-If either query returns tasks you did not handle in step 2, loop back to step 2 and process them — re-triage, re-group, apply. Repeat step 3 after each sweep until both queries come back empty.
-
-**If a task keeps returning denied across multiple sweeps**, stop guessing and ask. Use step 2e (`annotask_update_task` with `questions`) to flip it to `needs_info` and let the user clarify what they actually want, rather than burning more sweeps on a misread requirement.
-
-### 4. Report to the user
-
-Tell the user:
-- Which tasks were applied
-- Which files were modified
-- Any tasks that couldn't be applied (and why)
-
-The user will review changes in Annotask and either **accept** (task removed) or **deny with feedback** (task stays denied for next apply).
-
-### Denied tasks
-
-Tasks with `status: "denied"` and a `feedback` field were rejected by the user. They are processed alongside pending tasks in step 2. Read the `feedback` carefully to understand what went wrong and re-apply with corrections.
-
-## Task lifecycle
-
-```
-pending → in_progress (agent working) → review (user checks) → accepted (removed)
-                  ↓                          ↓                → denied (with feedback → agent re-applies)
-             needs_info (waiting)        blocked (can't do)   → dismissed (user deletes)
-                  ↓                          ↓                → pushed back (denied → agent retries)
-             in_progress (resume)        user decides
-```
-
-## Important notes
-
-- Tasks are the source of truth — fetch tasks, not the report
-- The `feedback` field on denied tasks is critical — it tells you what the user didn't like
-- Tasks with `status: "review"` are waiting for user review — don't re-apply them
-- Tasks with `status: "needs_info"` are waiting for the user to answer your questions — skip them and check back later
-- Tasks with `status: "blocked"` have been flagged as not actionable — skip them unless the user pushes back with feedback
-- When a `needs_info` task returns to `in_progress`, check `agent_feedback` for the user's answers before resuming work
-- After applying, the user's page will hot-reload via Vite HMR showing the changes immediately
diff --git a/playgrounds/stress-test/apps/host-single-spa/.claude/skills/annotask-init/SKILL.md b/playgrounds/stress-test/apps/host-single-spa/.claude/skills/annotask-init/SKILL.md
deleted file mode 100644
index 63df6c7..0000000
--- a/playgrounds/stress-test/apps/host-single-spa/.claude/skills/annotask-init/SKILL.md
+++ /dev/null
@@ -1,321 +0,0 @@
-# annotask-init
-
-Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
-
-## When to use
-
-Use this skill when the user says any of:
-- "initialize Annotask" / "init Annotask"
-- "set up Annotask" / "configure Annotask"
-- "scan my project for Annotask"
-- `/annotask-init`
-
-## What it does
-
-Scans the project to detect the framework, design tokens (colors, typography, spacing, borders), icon library, and component library. Writes `.annotask/design-spec.json` which Annotask reads to populate the Theme page with editable design tokens.
-
-## Output schema
-
-Every token carries resolved values for every detected theme variant via a
-`values` map keyed by theme id. Tokens that don't change across variants repeat
-the same value under each id — this keeps every token one uniform shape.
-
-```json
-{
-  "role": "primary",
-  "values": { "light": "#3b82f6", "dark": "#60a5fa" },
-  "cssVar": "--color-primary",
-  "source": "var(--color-primary)",
-  "sourceFile": "src/assets/main.css",
-  "sourceLine": 12
-}
-```
-
-- `role` — semantic name (see vocabularies below)
-- `values` — resolved value per theme variant, keyed by theme id (`light`, `dark`, or a named theme). Single-theme apps use `{ "default": "…" }`.
-- `cssVar` — the CSS custom property name, if backed by one. Omit if not a CSS variable.
-- `source` — human-readable provenance: `var(--x)`, `tailwind.config:colors.primary`, `@theme:--color-primary`
-- `sourceFile` — relative path to the file where the value is defined
-- `sourceLine` — line number in that file (the `:root` variant's definition is fine when multiple exist)
-
-Theme variants themselves are listed at the top of the spec under `themes`,
-with a `selector` describing how each variant is activated in the DOM so the
-Annotask shell can match it against the iframe's current state:
-
-```json
-"themes": [
-  { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-  { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-],
-"defaultTheme": "light"
-```
-
-`selector.kind` is one of `attribute` (with `name`, `value`, optional `host`), `class` (with `name`, optional `host`), `media` (with `media: '(prefers-color-scheme: dark)'`), or `default` (no selector — the base `:root` values). Apps with only one theme should emit a single `{ "id": "default", "name": "Default", "selector": { "kind": "default" } }` variant.
-
-## Steps
-
-### 1. Detect framework
-
-Check `package.json` dependencies:
-- `vue` → name "vue", read version
-- `react` / `react-dom` → name "react"
-- `svelte` → name "svelte"
-- `solid-js` → name "solid"
-
-Check for styling:
-- `tailwindcss` in devDependencies or dependencies → add "tailwind" to styling array
-- Look for `<style scoped>` in `.vue` files → add "scoped-css"
-- Look for CSS module imports (`.module.css`) → add "css-modules"
-
-### 2. Detect theme variants
-
-Before extracting any token values, determine which theme variants the project
-supports so you know which scopes to resolve values under. Check these signals
-in order and stop at the first match:
-
-1. **Tailwind `.dark` class** — If CSS files contain `.dark { … }` / `:root.dark { … }` / `html.dark { … }` blocks, or Tailwind v3 config has `darkMode: 'class'`, or Tailwind v4 CSS contains `@custom-variant dark (&:where(.dark, .dark *))`. Emit two variants:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }`
-
-2. **Data-attribute theming** — If CSS contains `[data-theme="…"]`, `[data-bs-theme="…"]`, `[data-mui-color-scheme="…"]`, `[data-mantine-color-scheme="…"]`, or `[data-color-scheme="…"]` selectors. Emit one variant per distinct attribute value:
-   - `{ "id": "<value>", "name": "<Value>", "scheme": "light|dark (if obvious)", "selector": { "kind": "attribute", "host": "html", "name": "<attr-name>", "value": "<value>" } }`
-
-3. **`@media (prefers-color-scheme: dark)` blocks** — If the project only switches via media queries. Emit:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "media", "media": "(prefers-color-scheme: dark)" } }`
-
-4. **Single theme** — If none of the above are present:
-   - `[ { "id": "default", "name": "Default", "selector": { "kind": "default" } } ]`
-
-Set `defaultTheme` to the variant id used when no selector matches — typically `"light"` or `"default"`.
-
-### 3. Scan colors
-
-**Find color sources:**
-
-1. **CSS variables**: Search for `:root`, `:root.dark`, `html.dark`, `[data-theme="…"]`, and `@media (prefers-color-scheme: dark) :root` declarations across CSS files and Vue `<style>` blocks. Extract `--variable-name: value` pairs, remembering which variant scope each came from.
-
-2. **Tailwind v4** (version >= 4): Search for `@theme` blocks in CSS files. Extract custom properties defined within them. `@theme` blocks without a variant selector apply to every variant.
-
-3. **Tailwind v3** (version < 4): Read `tailwind.config.js`, `tailwind.config.ts`, or `tailwind.config.mjs`. Extract `theme.extend.colors`. Convert to flat key-value pairs.
-
-**Resolve each color under every detected variant.** Produce a `values` map
-keyed by theme id. When a variant doesn't override the token, copy the base
-(`:root`/light/default) value so every token has a value for every variant.
-When a variant-specific block defines a new CSS variable that doesn't appear
-in the base scope, leave the missing variants blank (the server normalizer
-will fill them when the spec is read).
-
-**Classify into semantic roles using this fixed vocabulary:**
-
-| Role | Match heuristics (in variable/key name) |
-|------|----------------------------------------|
-| `primary` | primary, brand |
-| `secondary` | secondary |
-| `accent` | accent |
-| `background` | bg, background |
-| `surface` | surface, card |
-| `text` | text, foreground, fg (but not text-muted) |
-| `text-muted` | text-muted, muted, subtle |
-| `border` | border, divider, separator |
-| `danger` | danger, error, destructive, red |
-| `warning` | warning, amber, yellow (semantic) |
-| `success` | success, green (semantic) |
-| `info` | info, blue (semantic) |
-
-If a variable doesn't match any heuristic, use a descriptive role name derived from the variable name (e.g., `--sidebar-bg` → role `sidebar-bg`).
-
-**Limits**: Maximum 30 color tokens. Prioritize semantic roles first, then most-used custom colors.
-
-### 4. Scan typography
-
-Apply the same per-variant `values` map strategy used for colors: resolve each
-token under every detected variant, copying the base value for variants that
-don't override it.
-
-**Font families**: Search for:
-- CSS variables containing `font`, `family` in `:root` or `@theme`
-- `fontFamily` in Tailwind config
-- Direct `font-family` declarations on `body`, `html`, `h1`-`h6` elements
-
-Classify as:
-- `heading` — used on h1-h6 or named heading/display
-- `body` — used on body/html or named sans/body/base
-- `mono` — monospace, code, named mono
-
-**Font scale**: Search for:
-- CSS variables containing `font-size`, `text-` size names
-- `fontSize` in Tailwind config
-- `@theme` size definitions
-
-Use roles: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or by ascending size order).
-
-**Weights**: Scan component files for `font-weight` values and Tailwind weight classes (`font-bold`, `font-semibold`, etc.). List unique weights as strings: `["400", "500", "600", "700"]`.
-
-### 5. Scan spacing
-
-Search for:
-- CSS variables containing `space`, `gap`, `margin`, `padding`, `size`
-- `spacing` in Tailwind config
-- `@theme` spacing definitions
-
-Use roles: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or ascending size).
-
-**Limits**: Maximum 12 spacing tokens.
-
-### 6. Scan border radius
-
-Search for:
-- CSS variables containing `radius`, `rounded`
-- `borderRadius` in Tailwind config
-- `@theme` radius definitions
-
-Use roles: `sm`, `md`, `lg`, `xl`, `full` (match by name or ascending size).
-
-### 7. Scan breakpoints
-
-Detect responsive breakpoints from whatever styling system the project uses. Output as a flat object mapping name → min-width value.
-
-**Sources (check in order):**
-
-1. **Tailwind v4** (>= 4): Look in CSS files for `@theme` blocks defining `--breakpoint-*` custom properties, or `@custom-media` rules.
-
-2. **Tailwind v3** (< 4): Read `tailwind.config.{js,ts,mjs}`. Extract `theme.screens` or `theme.extend.screens`. Default Tailwind screens: `{ "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" }` — use these as fallback if Tailwind is detected but no custom screens are defined.
-
-3. **Bootstrap**: Check for `bootstrap` in package.json. Default Bootstrap breakpoints: `{ "sm": "576px", "md": "768px", "lg": "992px", "xl": "1200px", "xxl": "1400px" }`.
-
-4. **CSS custom properties**: Search `:root` for variables containing `breakpoint`, `screen`, `bp` in the name (e.g., `--bp-mobile: 480px`).
-
-5. **CSS `@media` patterns**: Scan `.css`, `.scss`, `.vue` files for `@media` queries with `min-width` or `max-width`. Extract the 3–6 most common breakpoint values and assign roles by ascending size: `sm`, `md`, `lg`, `xl`, `2xl`.
-
-**Output example:**
-```json
-"breakpoints": {
-  "sm": "640px",
-  "md": "768px",
-  "lg": "1024px",
-  "xl": "1280px",
-  "2xl": "1536px"
-}
-```
-
-If no breakpoints are detected, omit the `breakpoints` field (don't include an empty object).
-
-### 8. Detect icon library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `lucide-vue-next` or `lucide-react` | lucide |
-| `@heroicons/vue` or `@heroicons/react` | heroicons |
-| `@fortawesome/vue-fontawesome` or `@fortawesome/react-fontawesome` | fontawesome |
-| `@phosphor-icons/vue` or `@phosphor-icons/react` | phosphor |
-| `@tabler/icons-vue` or `@tabler/icons-react` | tabler |
-
-Read the version from package.json.
-
-### 9. Detect component library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `primevue` | PrimeVue |
-| `vuetify` | Vuetify |
-| `element-plus` | Element Plus |
-| `@headlessui/vue` | Headless UI |
-| `radix-vue` | Radix Vue |
-| `naive-ui` | Naive UI |
-| `@shadcn/ui` or `shadcn-vue` | shadcn/ui |
-
-If found, scan `src/` for import statements to find used components:
-```bash
-grep -rh "from '${package}" --include='*.vue' --include='*.ts' --include='*.js' src/ | sort -u
-```
-
-Extract component names from the imports. Read the version from package.json.
-
-### 10. Write design spec
-
-Create `.annotask/design-spec.json`:
-
-```json
-{
-  "version": "1.0",
-  "framework": {
-    "name": "vue",
-    "version": "3.5.0",
-    "styling": ["tailwind", "scoped-css"]
-  },
-  "themes": [
-    { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-    { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-  ],
-  "defaultTheme": "light",
-  "colors": [
-    { "role": "primary",    "values": { "light": "#3b82f6", "dark": "#60a5fa" }, "cssVar": "--color-primary", "source": "var(--color-primary)", "sourceFile": "src/assets/main.css", "sourceLine": 5 },
-    { "role": "background", "values": { "light": "#ffffff", "dark": "#0b1120" }, "cssVar": "--bg",            "source": "var(--bg)",            "sourceFile": "src/assets/main.css", "sourceLine": 3 }
-  ],
-  "typography": {
-    "families": [
-      { "role": "body", "values": { "light": "Inter, sans-serif", "dark": "Inter, sans-serif" }, "cssVar": "--font-sans", "source": "var(--font-sans)", "sourceFile": "src/assets/main.css", "sourceLine": 10 }
-    ],
-    "scale": [
-      { "role": "base", "values": { "light": "1rem", "dark": "1rem" }, "cssVar": "--text-base", "source": "var(--text-base)", "sourceFile": "src/assets/main.css", "sourceLine": 15 }
-    ],
-    "weights": ["400", "500", "600", "700"]
-  },
-  "spacing": [
-    { "role": "sm", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--space-sm", "source": "var(--space-sm)", "sourceFile": "src/assets/main.css", "sourceLine": 20 }
-  ],
-  "borders": {
-    "radius": [
-      { "role": "md", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--radius-md", "source": "var(--radius-md)", "sourceFile": "src/assets/main.css", "sourceLine": 25 }
-    ]
-  },
-  "breakpoints": {
-    "sm": "640px",
-    "md": "768px",
-    "lg": "1024px",
-    "xl": "1280px",
-    "2xl": "1536px"
-  },
-  "icons": {
-    "library": "lucide",
-    "version": "0.300.0"
-  },
-  "components": {
-    "library": "PrimeVue",
-    "version": "4.5.4",
-    "used": ["DataTable", "Column", "InputText", "Tag", "Button"]
-  }
-}
-```
-
-### 11. Clean up old config
-
-If `.annotask/config.json` exists, delete it — it's been replaced by `design-spec.json`.
-
-### 12. Update .gitignore
-
-Check if `.gitignore` contains `.annotask/`. If not, append:
-```
-# Annotask (generated)
-.annotask/
-```
-
-### 13. Report to user
-
-Tell the user:
-- What was detected (framework, number of color/typography/spacing tokens, libraries)
-- That they can open the **Theme** page in Annotask to view and edit tokens
-- That they can re-run `/annotask-init` to rescan
-
-## Notes
-
-- This skill is idempotent — re-running overwrites the design spec with fresh data
-- The design spec is gitignored because it's generated and may vary per developer
-- If detection fails for any section, use empty defaults (empty array, null) rather than omitting the field
-- All top-level fields are required — use empty values for missing data
-- When a token has a CSS variable backing, always populate the `cssVar` field — this enables live preview in the Theme page
diff --git a/playgrounds/stress-test/apps/host-single-spa/.mcp.json b/playgrounds/stress-test/apps/host-single-spa/.mcp.json
deleted file mode 100644
index 5527f21..0000000
--- a/playgrounds/stress-test/apps/host-single-spa/.mcp.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "annotask": {
-      "command": "npx",
-      "args": [
-        "annotask",
-        "mcp"
-      ]
-    }
-  }
-}
diff --git a/playgrounds/stress-test/apps/mfe-htmx-partials/.claude/skills/annotask-apply/SKILL.md b/playgrounds/stress-test/apps/mfe-htmx-partials/.claude/skills/annotask-apply/SKILL.md
deleted file mode 100644
index 49921a2..0000000
--- a/playgrounds/stress-test/apps/mfe-htmx-partials/.claude/skills/annotask-apply/SKILL.md
+++ /dev/null
@@ -1,460 +0,0 @@
-# annotask-apply
-
-Apply pending Annotask design tasks to the source code.
-
-## When to use
-
-Use this skill when the user says:
-- "apply the Annotask changes"
-- "apply my design changes"
-- "sync Annotask"
-- `/annotask-apply`
-
-## How it works
-
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
-
-## MCP preference
-
-If you have `annotask_*` MCP tools available, prefer them over CLI commands — they return structured data directly, are faster, and avoid shell/npx issues. If MCP tools are not available, use the CLI commands shown below.
-
-**Always pass `--mcp` to CLI commands.** The flag emits compact JSON that matches the MCP tool response shapes exactly (no ANSI colors, no human prefixes, `visual` stripped, `agent_feedback` trimmed). That way the same parsing logic works whether you're calling the MCP tool or the CLI fallback.
-
-## Steps
-
-### 0. Check server status
-
-**MCP:** If you have MCP tools, the server is already running — skip this step.
-
-```bash
-npx annotask status --mcp
-```
-
-If this fails, the Annotask dev server isn't running. Ask the user to start it.
-
-### 1. Fetch pending tasks
-
-**MCP:** `annotask_get_tasks(status: "pending")` — returns compact summaries. Use `detail: true` for full objects.
-
-```bash
-npx annotask tasks --mcp --status=pending
-```
-
-Response (compact task summaries):
-```json
-{"version":"1.0","count":1,"tasks":[{"id":"task-123","type":"annotation","status":"pending","description":"Change the header background to match the new brand colors","file":"src/components/Header.vue","line":5,"action":"text_edit","screenshot":"screenshot-1711800000-ab3kf.png"}]}
-```
-
-Each task summary has: `id`, `type`, `status`, `description`, `file`, `line`, and optionally `component`, `action`, `screenshot`, `feedback` (on denied tasks), `blocked_reason`, `resolution`.
-
-For full task details (context, viewport, interaction_history, agent_feedback), use `annotask_get_task` MCP tool or `npx annotask task <id> --mcp` for a single task (`npx annotask tasks --mcp --detail` for the full list). Only fetch full details when the summary doesn't provide enough context to apply the change.
-
-### Screenshot reference
-
-Some tasks include a `screenshot` field. The screenshot shows exactly what the user sees in the browser. To view it:
-
-**MCP:** `annotask_get_screenshot(task_id: "TASK_ID")` — returns base64-encoded PNG directly.
-
-```bash
-npx annotask screenshot TASK_ID
-```
-
-This downloads the PNG to `.annotask/screenshots/`. Use it as visual context alongside the task description and source code. (The screenshot command writes the file on disk — `--mcp` doesn't apply.)
-
-### 2. Triage, group, then apply
-
-Filter actionable tasks: `status: "pending"`, `status: "denied"` (with `feedback`), and `status: "in_progress"` tasks whose `agent_feedback` now contains answers to earlier questions. Skip `needs_info` (waiting for user) and `blocked` (marked not actionable).
-
-Before locking anything, **triage** — read all actionable task summaries and group them by touched resources:
-
-- **By file**: tasks whose `file` is the same go in one group (Edits batched on one Read).
-- **By shared state**: any task that writes `.annotask/design-spec.json`, `:root` CSS variables, `tailwind.config.*`, or a global stylesheet goes in the *shared-state* group regardless of which source file triggered it.
-- **By dependency**: if a `theme_update` adds or changes a token that a `style_update` in the same batch consumes, the `theme_update` goes in an earlier phase. If a `section_request` introduces the UI that an `a11y_fix` targets, the `section_request` goes first.
-
-Within each group: process serially, reading the file once and batching Edits. Across groups that are fully disjoint (no shared file, no shared state, no dependency edge), you may launch parallel subagents — one per group — to apply them concurrently. If in doubt, run serially.
-
-#### Parallelism rules
-
-- **Same file → same group, serial.** Never have two tasks editing the same file concurrently.
-- **Shared global state → one group, serial.** `.annotask/design-spec.json`, `:root` blocks in shared CSS, `tailwind.config.*`, shared layout files, i18n catalogs, route tables, barrel exports.
-- **Dependency order**: `theme_update` before any `style_update` that references the new/changed token; structural task (`section_request`, `annotation` with `wrap_container`/`add_row`/`add_column`) before an `a11y_fix` or `style_update` on the same new UI.
-- **Stale locators**: after edits land, the `file`/`line` on remaining tasks may drift. When in doubt, call `annotask_get_code_context(task_id)` before editing — it returns the current symbol, a ±15 line excerpt, and an `excerpt_hash` you can compare across retries. Otherwise, search by surrounding text/element context over trusting `line` from the original triage.
-- **Non-idempotent inserts**: `add_row`, `add_column`, `section_request`, and free-text "add this" notes can duplicate on retry. Before inserting, confirm the target isn't already present.
-- **If using parallel subagents**: each subagent receives only its group's task IDs plus project context. After all subagents finish, run a quick typecheck/build sanity pass before returning control to the user. If any subagent failed, surface it clearly — do not silently accept partial success.
-
-For each task in a group, follow this cycle:
-
-#### a. Lock the task
-
-Mark it `in_progress` so the user sees you're working on it:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "in_progress")`
-
-```bash
-npx annotask update-task TASK_ID --status=in_progress --mcp
-```
-
-#### b. Reference the design spec for consistency
-
-Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
-
-**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
-
-```bash
-npx annotask design-spec --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
-```
-
-For detailed tokens in a specific category:
-
-```bash
-npx annotask design-spec --category=colors --mcp
-```
-
-**When to use:**
-- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
-- **Typography changes** — Reference the font scale and families from the spec
-- **Responsive design** — Use detected breakpoints when adding media queries
-- **New components** — Match the design system when creating new UI
-
-**How to apply:**
-- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
-- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
-- For responsive design, use the detected breakpoints
-- Document the token reference in your resolution note (e.g., "Applied primary color token")
-
-#### c. Find relevant components (required when adding any UI element)
-
-If the task asks you to add, insert, or create a UI element of any kind — a table, button, card, modal, input, dropdown, form, list, nav, etc. — you **must** search the component library first before writing HTML from scratch. This applies to all task types: `section_request`, `annotation` with actions like `add_column`/`add_row`/`wrap_container`, and free-text `annotation` notes whose `description` implies new UI.
-
-**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
-
-```bash
-npx annotask components "button" --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
-```
-
-For a specific component, get its full prop signature:
-
-```bash
-npx annotask component Button --mcp
-```
-
-For **in-repo usage examples** (real prop combinations + import path this project actually uses), call `annotask_get_component_examples(name: "Button")` — or `npx annotask component-examples Button --mcp`. Prefer the example's import path and prop shape over reinventing: the examples show how *this* codebase uses the component, not just what the library exposes.
-
-#### c-ter. Find the data source (required for any task that adds or modifies data-driven UI)
-
-Before writing UI that renders data, check what's already wired. If the task's summary contains `data_context_summary` (e.g. `"hook:useUserQuery"` or `"store:useCounterStore"`), that's the primary data source powering the selected element. For the full picture:
-
-**MCP:** `annotask_get_data_context(task_id: "TASK_ID")` — returns the complete `DataContext`: every data reference in the enclosing file (`sources`, sorted with the primary source at index 0 — closest to `task.line`, tie-broken by kind precedence), `rendered_identifiers` from the template/JSX (CSV), and `route_bindings` (CSV).
-
-```bash
-npx annotask data-context TASK_ID --mcp
-```
-
-To browse the project's catalog of hooks, stores, and fetch wrappers (sorted by `used_count` — most load-bearing first):
-
-**MCP:** `annotask_get_data_sources(used_only: true)` — filter to entries actually used elsewhere in the codebase.
-
-```bash
-npx annotask data-sources --used-only --mcp
-```
-
-To see **real in-repo usages** of a specific data source (destructuring patterns, parameter shape, common wrappers — parallel to `annotask_get_component_examples`):
-
-**MCP:** `annotask_get_data_source_examples(name: "useUserQuery", kind: "composable")`
-
-```bash
-npx annotask data-source-examples useUserQuery --kind=composable --mcp
-```
-
-To see **what shape comes back** from an API — cross-reference declared schemas (OpenAPI, GraphQL, tRPC) so you don't guess field names:
-
-**MCP:** `annotask_resolve_endpoint(url: "/api/cats")` → returns the best-match operation with a confidence score.
-
-```bash
-npx annotask resolve-endpoint /api/cats --mcp
-```
-
-**MCP:** `annotask_get_api_operation(path: "/api/cats", method: "GET")` — full request / response schema for a known path pattern.
-
-```bash
-npx annotask api-operation /api/cats --method=GET --mcp
-```
-
-**MCP:** `annotask_get_api_schemas(detail: true)` — browse every discovered schema source up front.
-
-```bash
-npx annotask api-schemas --detail --mcp
-```
-
-If a task summary shows `response_schema_ref: "Cat[]"`, the agent already knows a declared shape exists — `annotask_get_api_operation` or `annotask_resolve_endpoint` will surface the full JSON schema.
-
-**When to use:**
-- Any task where the user's description mentions adding, replacing, or rewiring data — "show the current user", "list orders", "filter by status", "fetch from the API".
-- Denied tasks where feedback mentions wrong or fake data.
-- Section requests that need to render real information.
-
-**How to apply:**
-- Prefer reusing a hook/store from `data_context.sources` or `data-sources` catalog over writing new fetch code.
-- Copy the import path and call-site shape from `data-source-examples`, not from library docs.
-- If `sources[0]` doesn't match the user's description (e.g. task says "user name" but `sources[0]` is `useOrdersQuery`), check the rest of the `sources` list — the right hook is usually there.
-
-**When to use:**
-- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
-- **UI additions** — Check if a table, button, card, modal, input, form, list, or nav component already exists before writing custom HTML
-- **Styling consistency** — Using library components ensures your changes match the design system
-
-**How to apply:**
-- Search for components matching the intent (e.g., "table" if adding tabular data, "dropdown" if adding a select menu)
-- Read the props to understand customization options (variant, size, disabled, etc.)
-- Call `annotask_get_component_examples` to see how the component is already used in this codebase; copy the import path and prop patterns from there
-- Use the component in your JSX/Vue/Svelte code with appropriate props
-- Document the component reference in your resolution note
-
-#### c-bis. Re-anchor older or retried tasks
-
-For **denied** tasks, tasks that have been sitting in the queue while you edited other files, or any task whose `file`/`line` you suspect has drifted: call `annotask_get_code_context(task_id)` before editing.
-
-```bash
-npx annotask code-context TASK_ID --mcp
-```
-
-Response:
-```json
-{"file":"src/components/Header.vue","line":42,"symbol":"Header","excerpt_start_line":27,"excerpt_end_line":57,"excerpt":"...","imports":["import ..."],"excerpt_hash":"ab12cd34ef56..."}
-```
-
-Use `symbol` + `excerpt` to locate the edit target; the `excerpt_hash` is a cheap drift check on subsequent retries (if the hash changes between attempts, the surrounding code moved). Skip this step for fresh pending tasks where `file`/`line` are known good.
-
-#### d. Apply the change
-
-Read the task type and apply accordingly:
-
-- **`annotation` with `action: "text_edit"`**: The `description` field says what text to change. Find the text in the source file and apply the edit.
-
-- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run step c first.
-
-- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run step c (component library search) before writing HTML.**
-
-- **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
-
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
-
-- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID, or the synthetic `tab-order` rule from Annotask's tab-order overlay), `impact`, `help`, `helpUrl`, and `elements` array with `html`, `selector`, `fix`, source `file`/`line`/`component`, and a per-element `a11y` block with computed accessibility metadata:
-
-  ```
-  elements[i].a11y = {
-    accessible_name, name_source,   // "Sign in", source: aria-label | labelledby | label | alt | text | placeholder | none
-    role, role_source,              // "button", source: explicit | implicit | none
-    tabindex, focusable,            // null | number, true/false
-    focus_indicator,                // "visible" | "none" | "unknown"
-    contrast,                       // { foreground, background, ratio, aa_normal, aa_large, ... } only when element has text
-    aria_attrs,                     // [{ name: "aria-expanded", value: "false" }, ...]
-  }
-  ```
-
-  If `screenshot_meta` is present (the user manually attached one with the snip tool), retrieve it via `annotask_get_screenshot` before proposing visual changes (color-contrast, focus rings).
-
-  **Per-rule playbook.** Most rules fall into one of these patterns — match by `context.rule`:
-
-  | Rule(s) | Fix layer | What to do |
-  |---|---|---|
-  | `color-contrast`, `color-contrast-enhanced` | Design tokens first | Read `elements[i].a11y.contrast` for the actual fg/bg hex + ratio. If the colors come from theme tokens (check `cssVar` lookups in the source), adjust the token. If the contrast comes from a one-off inline style or hardcoded class, fix the component, not the token (you'd regress every other consumer). |
-  | `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` referencing visible text. `a11y.accessible_name` shows what (if anything) the input currently exposes — when `name_source === 'placeholder'`, the input has no real label. |
-  | `button-name`, `link-name`, `input-button-name` | Markup | Add visible text content or `aria-label`. For icon-only buttons add a visually hidden `<span class="sr-only">` (or your project's equivalent). Don't add `title` — it's not reliable for SR users. |
-  | `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | `alt=""` for decorative imagery, descriptive `alt` for informational. For `<img>` that conveys text, use the text. For SVG icons that pair with visible text, use `aria-hidden="true"`. |
-  | `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These almost always live in a layout component (e.g. `App.vue`, `_layout.tsx`, `RootLayout`), not in leaf components. |
-  | `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert/promote `<h1>`; renumber subsequent levels so the outline is contiguous. Usually a layout/section component change, not a leaf change. |
-  | `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what's set. Reference the WAI-ARIA roles spec (`helpUrl`) for the role's allowed attributes. Remove disallowed attrs; add required ones. |
-  | `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Either remove `aria-hidden`, or move the focusable elements outside (or set `tabindex="-1"` and ensure they're never the focus target). |
-  | `tabindex`, **synthetic** `tab-order` | Markup | Remove positive `tabindex`; use 0 (focusable in DOM order) or -1 (programmatically focusable, not in tab order). For the synthetic `tab-order` rule, `context.tab_order.flag` is one of `positive` / `unreachable` / `reorder` — fix the source markup so DOM order matches visual order. |
-  | `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Single source of truth — usually `index.html` (Vite/CRA), `app/layout.tsx` (Next), `src/routes/+layout.svelte` (SvelteKit), or the framework's root document. |
-  | `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>`/`<span>`. Don't nest interactive elements (e.g. `<button>` inside `<a>`). |
-  | `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element of the layout. Style it with the visually-hidden pattern that becomes visible on `:focus`. |
-  | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="…"` and rename one. If the id is dynamic, ensure the generation key is unique per instance. |
-  | `frame-title`, `iframe-title` | Markup | Add `title="…"` describing the iframe's purpose. |
-
-  **General rules:**
-  - Prefer **pattern fixes** over instance fixes. When `elements` contains many entries that share the same `file`/`component`, change the source component once — don't paste the same fix N times.
-  - For the synthetic `tab-order` rule, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no `helpUrl` from axe — use the linked WCAG focus-order page in `context.helpUrl`.
-  - When `a11y.accessible_name` is empty and `a11y.focusable` is true, the element is unreachable for screen readers — naming is the highest-priority fix.
-
-- **`theme_update`**: One or more design token value changes committed together from the Theme page. A single task now covers every edit the user made in one Commit click — do not expect one task per token. The `context` object contains:
-  - `edits`: array of token edits. Each entry has:
-    - `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
-    - `role`: semantic role name (e.g. `primary`, `background`, `heading`)
-    - `cssVar`: CSS variable name if backed by one (e.g. `--color-primary`), or `null`
-    - `theme_variant`: the theme id this edit targets (e.g. `light`, `dark`)
-    - `theme_selector`: how that variant is activated in the DOM — `{kind:'default'}`, `{kind:'attribute',host,name,value}`, `{kind:'class',host,name}`, or `{kind:'media',media}` — tells you which CSS block owns this variable (`:root`, `:root[data-theme="dark"]`, `.dark`, `@media (prefers-color-scheme: dark)`)
-    - `before`: old value (`null` for new tokens)
-    - `after`: new value
-    - `sourceFile` / `sourceLine`: where the current declaration lives (both `null` for new tokens — you pick the location)
-    - `isNew`: `true` if this token didn't exist before
-  - `styling`: array of project styling methods (e.g. `["tailwind", "scoped-css"]`)
-  - `specFile`: relative path to the design spec (typically `.annotask/design-spec.json`)
-
-  **How to apply:**
-  1. **Group `context.edits` by `sourceFile`.** For each file (skipping `null`/`isNew` for now), open it once, apply every edit against its file in a single Edit-batch, save. Use `theme_selector` + `cssVar` to locate the right declaration block — e.g. an edit with `theme_selector: {kind:'attribute',host:'html',name:'data-theme',value:'dark'}` belongs inside `:root[data-theme="dark"] { … }`, a `{kind:'default'}` edit belongs in the base `:root { … }` block.
-  2. **Tailwind config edits:** if `cssVar` is `null` and `sourceFile` references `tailwind.config.*`, update the corresponding key. If edits span both Tailwind and raw CSS, handle each file independently.
-  3. **New tokens (`isNew: true`):** add the CSS variable to the declaration block matching `theme_selector`. If no block exists for that variant yet, create one (e.g. add `:root[data-theme="dark"] { --new-var: …; }` at the end of the main tokens file). After writing, remember the final file path and line for step 4.
-  4. **Patch `.annotask/design-spec.json` once at the end.** Resolve `context.specFile` against the MFE root (the directory containing `.annotask/`). For each edit:
-     - Existing token: find `spec.<category>` — note dotted categories like `typography.families` map to nested paths — locate the entry by `role`, then set `values[theme_variant] = after`.
-     - New token: append a token object with `role`, `values: { [theme_variant]: after }`, `cssVar`, and fresh `sourceFile` / `sourceLine` pointing at where you added the declaration in step 3.
-     - When writing, keep the existing JSON formatting (same indentation, trailing newline) so the file watcher's next broadcast is clean.
-  5. The server watches `design-spec.json`; saving it fires a `designspec:updated` push and the Theme page refetches automatically.
-
-  **Worked example:** `context.edits = [{ category:'colors', role:'background', cssVar:'--stress-bg', theme_variant:'light', theme_selector:{kind:'default'}, before:'#f4f7fb', after:'#ff00ff', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:12, isNew:false }, { category:'colors', role:'text', cssVar:'--stress-text', theme_variant:'dark', theme_selector:{kind:'attribute',host:'html',name:'data-theme',value:'dark'}, before:'#e7eefb', after:'#ffeb3b', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:65, isNew:false }]` → open `tokens.css` once, update `--stress-bg` in the `:root` block and `--stress-text` in the `:root[data-theme="dark"]` block, save. Then open `.annotask/design-spec.json`, set `colors[?role=='background'].values.light = '#ff00ff'` and `colors[?role=='text'].values.dark = '#ffeb3b'`, save. Mark the task `review` with resolution `"Updated 2 color tokens in tokens.css and design-spec.json"`.
-
-- **`api_update`**: In-repo backend-contract edit. Created from the shell's Data view when the user selects an internal data source (`schema_in_repo === true`) and fills in a desired change. Only valid for in-repo schemas — external APIs cannot be edited from Annotask and should be marked `blocked` with an explanation if a request implies one.
-
-  The `context` object carries:
-  - `data_source_name`: hook/store/query identifier (e.g. `useCatsQuery`)
-  - `data_source_kind`: one of `composable | signal | store | fetch | graphql | loader | rpc`
-  - `schema_location`: path to the schema file (e.g. `openapi.yaml`, `src/trpc/router.ts`)
-  - `schema_kind`: `openapi | graphql | trpc | jsonschema`
-  - `endpoint`: literal endpoint / query key when the source used one
-  - `operation`: `{ method, path }` from the matched schema operation, when a match exists
-  - `desired_change`: user's description of the needed contract change
-  - `rationale`: optional "why"
-
-  **How to apply:**
-  - Open the schema file at `context.schema_location`. Read the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`) and make the change described in `desired_change`.
-  - Update the handler / backend implementation that serves that operation (typical pairs: OpenAPI routes ↔ the framework-specific handler file, tRPC router ↔ its procedure body).
-  - Update the frontend data source at `file:line` if the shape change affects the consumer (e.g. return type, destructured fields).
-  - If the change is additive (new optional field), you usually don't need to change existing callers. If it's breaking (required field, renamed field), search for all usages with `annotask_get_data_source_examples` and update them.
-  - Record what you changed in the resolution note — mention which schema location, which operation, and any frontend call sites touched.
-
-- **`annotation` with cross-boundary API edits**: An annotation task may turn out to require an in-repo API change (e.g. "show expiration date on the tier badge" when the `Cat` schema does not currently return `expires_at`).
-
-  **Rule**: do **not** silently edit the backend. Ask the user first via a `needs_info` question:
-  > This change requires updating the internal API route `GET /api/cats` to add an `expires_at` field on the `Cat` response. Proceed with both frontend and backend edits? (yes / no)
-
-  If the user approves, continue the same task (do **not** spawn a separate `api_update` task). Record each API edit structurally in `task.context.api_edits[]`:
-  ```json
-  {
-    "api_edits": [
-      {
-        "schema_location": "openapi.yaml",
-        "schema_kind": "openapi",
-        "operation": { "method": "GET", "path": "/api/cats" },
-        "change_summary": "Added nullable expires_at: string (ISO date) to the Cat response schema and handler."
-      }
-    ]
-  }
-  ```
-  Annotask's summary lifting will surface `api_edits_count` on the triage view so the user sees this task crossed the frontend/backend line.
-
-  If the user denies, do the frontend-only thing you can, or mark the task `blocked` with an explanation pointing at the missing backend support.
-
-  If the data source is external (`schema_in_repo === false`) and the task requires a contract change, mark the task `blocked` immediately — Annotask cannot edit APIs outside the repo.
-
-#### e. Ask for clarification (only when stuck)
-
-If you are **genuinely stuck** — missing API context, unclear library usage, ambiguous intent that could lead to a wrong implementation — ask the user for clarification instead of guessing:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", questions: [{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}])`
-
-```bash
-npx annotask update-task TASK_ID --mcp --ask='{"message":"Optional markdown context","questions":[{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}]}'
-```
-
-This sets the task to `needs_info` status. The user sees your questions in the Annotask UI and responds there. When answered, the task returns to `in_progress` with answers in `agent_feedback`.
-
-**Question types:**
-- `text` — free-text answer from user
-- `choice` — user picks from your provided `options` array
-
-**Guidelines:**
-- Only ask when you truly cannot proceed — do not ask for confirmation on straightforward tasks
-- Be specific: "Which CSS framework should I use for the grid?" is better than "How should I do this?"
-- Combine related questions into a single ask rather than multiple rounds
-- After asking, move on to the next task. Come back to check answers later via `annotask_get_tasks` MCP tool or `npx annotask tasks --mcp`
-
-#### f. Mark as blocked (when the task can't be done)
-
-If the task is **fundamentally outside your control** — a performance issue in a third-party library, an accessibility bug in a dependency, a config change that requires infrastructure access, etc. — mark it as blocked with an explanation:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", blocked_reason: "This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone.")`
-
-```bash
-npx annotask update-task TASK_ID --mcp --blocked-reason="This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone."
-```
-
-This sets the task to `blocked` status automatically. The user sees your explanation and can either **dismiss** the task or **push back** (deny it with feedback asking you to try a different approach).
-
-**When to use blocked vs needs_info:**
-- `needs_info` = "I can do this, but I need more information from you"
-- `blocked` = "This can't be done through source code changes — here's why"
-
-#### g. Mark for review immediately
-
-As soon as you finish applying **this** task, mark it for review with a brief resolution note:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "review", resolution: "Swapped grid to flexbox, added gap-4 for spacing")`
-
-```bash
-npx annotask update-task TASK_ID --status=review --resolution="Swapped grid to flexbox, added gap-4 for spacing" --mcp
-```
-
-Keep resolutions short — one sentence describing what you changed, not why. The user sees it in the Annotask shell alongside the diff.
-
-#### h. Move to the next task in the group
-
-Repeat steps a–g for each remaining task in the current group, then move to the next group (or confirm parallel subagents have finished). Per-task review flipping is what powers incremental feedback — each task moves to `review` as soon as *its own* edit lands, even inside a batched group, so the user can accept or deny early while later tasks are still in flight.
-
-### 3. Second sweep — catch denies and new tasks that arrived mid-run
-
-Because tasks flip to `review` as soon as their edit lands, the user may have been reviewing (and denying) early tasks while you were still applying later ones. They may also have created brand-new tasks. Before reporting, re-fetch once:
-
-**MCP:** `annotask_get_tasks(status: "denied")` and `annotask_get_tasks(status: "pending")`
-
-```bash
-npx annotask tasks --mcp --status=denied
-npx annotask tasks --mcp --status=pending
-```
-
-If either query returns tasks you did not handle in step 2, loop back to step 2 and process them — re-triage, re-group, apply. Repeat step 3 after each sweep until both queries come back empty.
-
-**If a task keeps returning denied across multiple sweeps**, stop guessing and ask. Use step 2e (`annotask_update_task` with `questions`) to flip it to `needs_info` and let the user clarify what they actually want, rather than burning more sweeps on a misread requirement.
-
-### 4. Report to the user
-
-Tell the user:
-- Which tasks were applied
-- Which files were modified
-- Any tasks that couldn't be applied (and why)
-
-The user will review changes in Annotask and either **accept** (task removed) or **deny with feedback** (task stays denied for next apply).
-
-### Denied tasks
-
-Tasks with `status: "denied"` and a `feedback` field were rejected by the user. They are processed alongside pending tasks in step 2. Read the `feedback` carefully to understand what went wrong and re-apply with corrections.
-
-## Task lifecycle
-
-```
-pending → in_progress (agent working) → review (user checks) → accepted (removed)
-                  ↓                          ↓                → denied (with feedback → agent re-applies)
-             needs_info (waiting)        blocked (can't do)   → dismissed (user deletes)
-                  ↓                          ↓                → pushed back (denied → agent retries)
-             in_progress (resume)        user decides
-```
-
-## Important notes
-
-- Tasks are the source of truth — fetch tasks, not the report
-- The `feedback` field on denied tasks is critical — it tells you what the user didn't like
-- Tasks with `status: "review"` are waiting for user review — don't re-apply them
-- Tasks with `status: "needs_info"` are waiting for the user to answer your questions — skip them and check back later
-- Tasks with `status: "blocked"` have been flagged as not actionable — skip them unless the user pushes back with feedback
-- When a `needs_info` task returns to `in_progress`, check `agent_feedback` for the user's answers before resuming work
-- After applying, the user's page will hot-reload via Vite HMR showing the changes immediately
diff --git a/playgrounds/stress-test/apps/mfe-htmx-partials/.claude/skills/annotask-init/SKILL.md b/playgrounds/stress-test/apps/mfe-htmx-partials/.claude/skills/annotask-init/SKILL.md
deleted file mode 100644
index 63df6c7..0000000
--- a/playgrounds/stress-test/apps/mfe-htmx-partials/.claude/skills/annotask-init/SKILL.md
+++ /dev/null
@@ -1,321 +0,0 @@
-# annotask-init
-
-Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
-
-## When to use
-
-Use this skill when the user says any of:
-- "initialize Annotask" / "init Annotask"
-- "set up Annotask" / "configure Annotask"
-- "scan my project for Annotask"
-- `/annotask-init`
-
-## What it does
-
-Scans the project to detect the framework, design tokens (colors, typography, spacing, borders), icon library, and component library. Writes `.annotask/design-spec.json` which Annotask reads to populate the Theme page with editable design tokens.
-
-## Output schema
-
-Every token carries resolved values for every detected theme variant via a
-`values` map keyed by theme id. Tokens that don't change across variants repeat
-the same value under each id — this keeps every token one uniform shape.
-
-```json
-{
-  "role": "primary",
-  "values": { "light": "#3b82f6", "dark": "#60a5fa" },
-  "cssVar": "--color-primary",
-  "source": "var(--color-primary)",
-  "sourceFile": "src/assets/main.css",
-  "sourceLine": 12
-}
-```
-
-- `role` — semantic name (see vocabularies below)
-- `values` — resolved value per theme variant, keyed by theme id (`light`, `dark`, or a named theme). Single-theme apps use `{ "default": "…" }`.
-- `cssVar` — the CSS custom property name, if backed by one. Omit if not a CSS variable.
-- `source` — human-readable provenance: `var(--x)`, `tailwind.config:colors.primary`, `@theme:--color-primary`
-- `sourceFile` — relative path to the file where the value is defined
-- `sourceLine` — line number in that file (the `:root` variant's definition is fine when multiple exist)
-
-Theme variants themselves are listed at the top of the spec under `themes`,
-with a `selector` describing how each variant is activated in the DOM so the
-Annotask shell can match it against the iframe's current state:
-
-```json
-"themes": [
-  { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-  { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-],
-"defaultTheme": "light"
-```
-
-`selector.kind` is one of `attribute` (with `name`, `value`, optional `host`), `class` (with `name`, optional `host`), `media` (with `media: '(prefers-color-scheme: dark)'`), or `default` (no selector — the base `:root` values). Apps with only one theme should emit a single `{ "id": "default", "name": "Default", "selector": { "kind": "default" } }` variant.
-
-## Steps
-
-### 1. Detect framework
-
-Check `package.json` dependencies:
-- `vue` → name "vue", read version
-- `react` / `react-dom` → name "react"
-- `svelte` → name "svelte"
-- `solid-js` → name "solid"
-
-Check for styling:
-- `tailwindcss` in devDependencies or dependencies → add "tailwind" to styling array
-- Look for `<style scoped>` in `.vue` files → add "scoped-css"
-- Look for CSS module imports (`.module.css`) → add "css-modules"
-
-### 2. Detect theme variants
-
-Before extracting any token values, determine which theme variants the project
-supports so you know which scopes to resolve values under. Check these signals
-in order and stop at the first match:
-
-1. **Tailwind `.dark` class** — If CSS files contain `.dark { … }` / `:root.dark { … }` / `html.dark { … }` blocks, or Tailwind v3 config has `darkMode: 'class'`, or Tailwind v4 CSS contains `@custom-variant dark (&:where(.dark, .dark *))`. Emit two variants:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }`
-
-2. **Data-attribute theming** — If CSS contains `[data-theme="…"]`, `[data-bs-theme="…"]`, `[data-mui-color-scheme="…"]`, `[data-mantine-color-scheme="…"]`, or `[data-color-scheme="…"]` selectors. Emit one variant per distinct attribute value:
-   - `{ "id": "<value>", "name": "<Value>", "scheme": "light|dark (if obvious)", "selector": { "kind": "attribute", "host": "html", "name": "<attr-name>", "value": "<value>" } }`
-
-3. **`@media (prefers-color-scheme: dark)` blocks** — If the project only switches via media queries. Emit:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "media", "media": "(prefers-color-scheme: dark)" } }`
-
-4. **Single theme** — If none of the above are present:
-   - `[ { "id": "default", "name": "Default", "selector": { "kind": "default" } } ]`
-
-Set `defaultTheme` to the variant id used when no selector matches — typically `"light"` or `"default"`.
-
-### 3. Scan colors
-
-**Find color sources:**
-
-1. **CSS variables**: Search for `:root`, `:root.dark`, `html.dark`, `[data-theme="…"]`, and `@media (prefers-color-scheme: dark) :root` declarations across CSS files and Vue `<style>` blocks. Extract `--variable-name: value` pairs, remembering which variant scope each came from.
-
-2. **Tailwind v4** (version >= 4): Search for `@theme` blocks in CSS files. Extract custom properties defined within them. `@theme` blocks without a variant selector apply to every variant.
-
-3. **Tailwind v3** (version < 4): Read `tailwind.config.js`, `tailwind.config.ts`, or `tailwind.config.mjs`. Extract `theme.extend.colors`. Convert to flat key-value pairs.
-
-**Resolve each color under every detected variant.** Produce a `values` map
-keyed by theme id. When a variant doesn't override the token, copy the base
-(`:root`/light/default) value so every token has a value for every variant.
-When a variant-specific block defines a new CSS variable that doesn't appear
-in the base scope, leave the missing variants blank (the server normalizer
-will fill them when the spec is read).
-
-**Classify into semantic roles using this fixed vocabulary:**
-
-| Role | Match heuristics (in variable/key name) |
-|------|----------------------------------------|
-| `primary` | primary, brand |
-| `secondary` | secondary |
-| `accent` | accent |
-| `background` | bg, background |
-| `surface` | surface, card |
-| `text` | text, foreground, fg (but not text-muted) |
-| `text-muted` | text-muted, muted, subtle |
-| `border` | border, divider, separator |
-| `danger` | danger, error, destructive, red |
-| `warning` | warning, amber, yellow (semantic) |
-| `success` | success, green (semantic) |
-| `info` | info, blue (semantic) |
-
-If a variable doesn't match any heuristic, use a descriptive role name derived from the variable name (e.g., `--sidebar-bg` → role `sidebar-bg`).
-
-**Limits**: Maximum 30 color tokens. Prioritize semantic roles first, then most-used custom colors.
-
-### 4. Scan typography
-
-Apply the same per-variant `values` map strategy used for colors: resolve each
-token under every detected variant, copying the base value for variants that
-don't override it.
-
-**Font families**: Search for:
-- CSS variables containing `font`, `family` in `:root` or `@theme`
-- `fontFamily` in Tailwind config
-- Direct `font-family` declarations on `body`, `html`, `h1`-`h6` elements
-
-Classify as:
-- `heading` — used on h1-h6 or named heading/display
-- `body` — used on body/html or named sans/body/base
-- `mono` — monospace, code, named mono
-
-**Font scale**: Search for:
-- CSS variables containing `font-size`, `text-` size names
-- `fontSize` in Tailwind config
-- `@theme` size definitions
-
-Use roles: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or by ascending size order).
-
-**Weights**: Scan component files for `font-weight` values and Tailwind weight classes (`font-bold`, `font-semibold`, etc.). List unique weights as strings: `["400", "500", "600", "700"]`.
-
-### 5. Scan spacing
-
-Search for:
-- CSS variables containing `space`, `gap`, `margin`, `padding`, `size`
-- `spacing` in Tailwind config
-- `@theme` spacing definitions
-
-Use roles: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or ascending size).
-
-**Limits**: Maximum 12 spacing tokens.
-
-### 6. Scan border radius
-
-Search for:
-- CSS variables containing `radius`, `rounded`
-- `borderRadius` in Tailwind config
-- `@theme` radius definitions
-
-Use roles: `sm`, `md`, `lg`, `xl`, `full` (match by name or ascending size).
-
-### 7. Scan breakpoints
-
-Detect responsive breakpoints from whatever styling system the project uses. Output as a flat object mapping name → min-width value.
-
-**Sources (check in order):**
-
-1. **Tailwind v4** (>= 4): Look in CSS files for `@theme` blocks defining `--breakpoint-*` custom properties, or `@custom-media` rules.
-
-2. **Tailwind v3** (< 4): Read `tailwind.config.{js,ts,mjs}`. Extract `theme.screens` or `theme.extend.screens`. Default Tailwind screens: `{ "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" }` — use these as fallback if Tailwind is detected but no custom screens are defined.
-
-3. **Bootstrap**: Check for `bootstrap` in package.json. Default Bootstrap breakpoints: `{ "sm": "576px", "md": "768px", "lg": "992px", "xl": "1200px", "xxl": "1400px" }`.
-
-4. **CSS custom properties**: Search `:root` for variables containing `breakpoint`, `screen`, `bp` in the name (e.g., `--bp-mobile: 480px`).
-
-5. **CSS `@media` patterns**: Scan `.css`, `.scss`, `.vue` files for `@media` queries with `min-width` or `max-width`. Extract the 3–6 most common breakpoint values and assign roles by ascending size: `sm`, `md`, `lg`, `xl`, `2xl`.
-
-**Output example:**
-```json
-"breakpoints": {
-  "sm": "640px",
-  "md": "768px",
-  "lg": "1024px",
-  "xl": "1280px",
-  "2xl": "1536px"
-}
-```
-
-If no breakpoints are detected, omit the `breakpoints` field (don't include an empty object).
-
-### 8. Detect icon library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `lucide-vue-next` or `lucide-react` | lucide |
-| `@heroicons/vue` or `@heroicons/react` | heroicons |
-| `@fortawesome/vue-fontawesome` or `@fortawesome/react-fontawesome` | fontawesome |
-| `@phosphor-icons/vue` or `@phosphor-icons/react` | phosphor |
-| `@tabler/icons-vue` or `@tabler/icons-react` | tabler |
-
-Read the version from package.json.
-
-### 9. Detect component library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `primevue` | PrimeVue |
-| `vuetify` | Vuetify |
-| `element-plus` | Element Plus |
-| `@headlessui/vue` | Headless UI |
-| `radix-vue` | Radix Vue |
-| `naive-ui` | Naive UI |
-| `@shadcn/ui` or `shadcn-vue` | shadcn/ui |
-
-If found, scan `src/` for import statements to find used components:
-```bash
-grep -rh "from '${package}" --include='*.vue' --include='*.ts' --include='*.js' src/ | sort -u
-```
-
-Extract component names from the imports. Read the version from package.json.
-
-### 10. Write design spec
-
-Create `.annotask/design-spec.json`:
-
-```json
-{
-  "version": "1.0",
-  "framework": {
-    "name": "vue",
-    "version": "3.5.0",
-    "styling": ["tailwind", "scoped-css"]
-  },
-  "themes": [
-    { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-    { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-  ],
-  "defaultTheme": "light",
-  "colors": [
-    { "role": "primary",    "values": { "light": "#3b82f6", "dark": "#60a5fa" }, "cssVar": "--color-primary", "source": "var(--color-primary)", "sourceFile": "src/assets/main.css", "sourceLine": 5 },
-    { "role": "background", "values": { "light": "#ffffff", "dark": "#0b1120" }, "cssVar": "--bg",            "source": "var(--bg)",            "sourceFile": "src/assets/main.css", "sourceLine": 3 }
-  ],
-  "typography": {
-    "families": [
-      { "role": "body", "values": { "light": "Inter, sans-serif", "dark": "Inter, sans-serif" }, "cssVar": "--font-sans", "source": "var(--font-sans)", "sourceFile": "src/assets/main.css", "sourceLine": 10 }
-    ],
-    "scale": [
-      { "role": "base", "values": { "light": "1rem", "dark": "1rem" }, "cssVar": "--text-base", "source": "var(--text-base)", "sourceFile": "src/assets/main.css", "sourceLine": 15 }
-    ],
-    "weights": ["400", "500", "600", "700"]
-  },
-  "spacing": [
-    { "role": "sm", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--space-sm", "source": "var(--space-sm)", "sourceFile": "src/assets/main.css", "sourceLine": 20 }
-  ],
-  "borders": {
-    "radius": [
-      { "role": "md", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--radius-md", "source": "var(--radius-md)", "sourceFile": "src/assets/main.css", "sourceLine": 25 }
-    ]
-  },
-  "breakpoints": {
-    "sm": "640px",
-    "md": "768px",
-    "lg": "1024px",
-    "xl": "1280px",
-    "2xl": "1536px"
-  },
-  "icons": {
-    "library": "lucide",
-    "version": "0.300.0"
-  },
-  "components": {
-    "library": "PrimeVue",
-    "version": "4.5.4",
-    "used": ["DataTable", "Column", "InputText", "Tag", "Button"]
-  }
-}
-```
-
-### 11. Clean up old config
-
-If `.annotask/config.json` exists, delete it — it's been replaced by `design-spec.json`.
-
-### 12. Update .gitignore
-
-Check if `.gitignore` contains `.annotask/`. If not, append:
-```
-# Annotask (generated)
-.annotask/
-```
-
-### 13. Report to user
-
-Tell the user:
-- What was detected (framework, number of color/typography/spacing tokens, libraries)
-- That they can open the **Theme** page in Annotask to view and edit tokens
-- That they can re-run `/annotask-init` to rescan
-
-## Notes
-
-- This skill is idempotent — re-running overwrites the design spec with fresh data
-- The design spec is gitignored because it's generated and may vary per developer
-- If detection fails for any section, use empty defaults (empty array, null) rather than omitting the field
-- All top-level fields are required — use empty values for missing data
-- When a token has a CSS variable backing, always populate the `cssVar` field — this enables live preview in the Theme page
diff --git a/playgrounds/stress-test/apps/mfe-htmx-partials/.mcp.json b/playgrounds/stress-test/apps/mfe-htmx-partials/.mcp.json
deleted file mode 100644
index 5527f21..0000000
--- a/playgrounds/stress-test/apps/mfe-htmx-partials/.mcp.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "annotask": {
-      "command": "npx",
-      "args": [
-        "annotask",
-        "mcp"
-      ]
-    }
-  }
-}
diff --git a/playgrounds/stress-test/apps/mfe-react-sidebar/.mcp.json b/playgrounds/stress-test/apps/mfe-react-sidebar/.mcp.json
deleted file mode 100644
index 5527f21..0000000
--- a/playgrounds/stress-test/apps/mfe-react-sidebar/.mcp.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "annotask": {
-      "command": "npx",
-      "args": [
-        "annotask",
-        "mcp"
-      ]
-    }
-  }
-}
diff --git a/playgrounds/stress-test/apps/mfe-react-workflows/.claude/skills/annotask-apply/SKILL.md b/playgrounds/stress-test/apps/mfe-react-workflows/.claude/skills/annotask-apply/SKILL.md
deleted file mode 100644
index 49921a2..0000000
--- a/playgrounds/stress-test/apps/mfe-react-workflows/.claude/skills/annotask-apply/SKILL.md
+++ /dev/null
@@ -1,460 +0,0 @@
-# annotask-apply
-
-Apply pending Annotask design tasks to the source code.
-
-## When to use
-
-Use this skill when the user says:
-- "apply the Annotask changes"
-- "apply my design changes"
-- "sync Annotask"
-- `/annotask-apply`
-
-## How it works
-
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
-
-## MCP preference
-
-If you have `annotask_*` MCP tools available, prefer them over CLI commands — they return structured data directly, are faster, and avoid shell/npx issues. If MCP tools are not available, use the CLI commands shown below.
-
-**Always pass `--mcp` to CLI commands.** The flag emits compact JSON that matches the MCP tool response shapes exactly (no ANSI colors, no human prefixes, `visual` stripped, `agent_feedback` trimmed). That way the same parsing logic works whether you're calling the MCP tool or the CLI fallback.
-
-## Steps
-
-### 0. Check server status
-
-**MCP:** If you have MCP tools, the server is already running — skip this step.
-
-```bash
-npx annotask status --mcp
-```
-
-If this fails, the Annotask dev server isn't running. Ask the user to start it.
-
-### 1. Fetch pending tasks
-
-**MCP:** `annotask_get_tasks(status: "pending")` — returns compact summaries. Use `detail: true` for full objects.
-
-```bash
-npx annotask tasks --mcp --status=pending
-```
-
-Response (compact task summaries):
-```json
-{"version":"1.0","count":1,"tasks":[{"id":"task-123","type":"annotation","status":"pending","description":"Change the header background to match the new brand colors","file":"src/components/Header.vue","line":5,"action":"text_edit","screenshot":"screenshot-1711800000-ab3kf.png"}]}
-```
-
-Each task summary has: `id`, `type`, `status`, `description`, `file`, `line`, and optionally `component`, `action`, `screenshot`, `feedback` (on denied tasks), `blocked_reason`, `resolution`.
-
-For full task details (context, viewport, interaction_history, agent_feedback), use `annotask_get_task` MCP tool or `npx annotask task <id> --mcp` for a single task (`npx annotask tasks --mcp --detail` for the full list). Only fetch full details when the summary doesn't provide enough context to apply the change.
-
-### Screenshot reference
-
-Some tasks include a `screenshot` field. The screenshot shows exactly what the user sees in the browser. To view it:
-
-**MCP:** `annotask_get_screenshot(task_id: "TASK_ID")` — returns base64-encoded PNG directly.
-
-```bash
-npx annotask screenshot TASK_ID
-```
-
-This downloads the PNG to `.annotask/screenshots/`. Use it as visual context alongside the task description and source code. (The screenshot command writes the file on disk — `--mcp` doesn't apply.)
-
-### 2. Triage, group, then apply
-
-Filter actionable tasks: `status: "pending"`, `status: "denied"` (with `feedback`), and `status: "in_progress"` tasks whose `agent_feedback` now contains answers to earlier questions. Skip `needs_info` (waiting for user) and `blocked` (marked not actionable).
-
-Before locking anything, **triage** — read all actionable task summaries and group them by touched resources:
-
-- **By file**: tasks whose `file` is the same go in one group (Edits batched on one Read).
-- **By shared state**: any task that writes `.annotask/design-spec.json`, `:root` CSS variables, `tailwind.config.*`, or a global stylesheet goes in the *shared-state* group regardless of which source file triggered it.
-- **By dependency**: if a `theme_update` adds or changes a token that a `style_update` in the same batch consumes, the `theme_update` goes in an earlier phase. If a `section_request` introduces the UI that an `a11y_fix` targets, the `section_request` goes first.
-
-Within each group: process serially, reading the file once and batching Edits. Across groups that are fully disjoint (no shared file, no shared state, no dependency edge), you may launch parallel subagents — one per group — to apply them concurrently. If in doubt, run serially.
-
-#### Parallelism rules
-
-- **Same file → same group, serial.** Never have two tasks editing the same file concurrently.
-- **Shared global state → one group, serial.** `.annotask/design-spec.json`, `:root` blocks in shared CSS, `tailwind.config.*`, shared layout files, i18n catalogs, route tables, barrel exports.
-- **Dependency order**: `theme_update` before any `style_update` that references the new/changed token; structural task (`section_request`, `annotation` with `wrap_container`/`add_row`/`add_column`) before an `a11y_fix` or `style_update` on the same new UI.
-- **Stale locators**: after edits land, the `file`/`line` on remaining tasks may drift. When in doubt, call `annotask_get_code_context(task_id)` before editing — it returns the current symbol, a ±15 line excerpt, and an `excerpt_hash` you can compare across retries. Otherwise, search by surrounding text/element context over trusting `line` from the original triage.
-- **Non-idempotent inserts**: `add_row`, `add_column`, `section_request`, and free-text "add this" notes can duplicate on retry. Before inserting, confirm the target isn't already present.
-- **If using parallel subagents**: each subagent receives only its group's task IDs plus project context. After all subagents finish, run a quick typecheck/build sanity pass before returning control to the user. If any subagent failed, surface it clearly — do not silently accept partial success.
-
-For each task in a group, follow this cycle:
-
-#### a. Lock the task
-
-Mark it `in_progress` so the user sees you're working on it:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "in_progress")`
-
-```bash
-npx annotask update-task TASK_ID --status=in_progress --mcp
-```
-
-#### b. Reference the design spec for consistency
-
-Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
-
-**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
-
-```bash
-npx annotask design-spec --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
-```
-
-For detailed tokens in a specific category:
-
-```bash
-npx annotask design-spec --category=colors --mcp
-```
-
-**When to use:**
-- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
-- **Typography changes** — Reference the font scale and families from the spec
-- **Responsive design** — Use detected breakpoints when adding media queries
-- **New components** — Match the design system when creating new UI
-
-**How to apply:**
-- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
-- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
-- For responsive design, use the detected breakpoints
-- Document the token reference in your resolution note (e.g., "Applied primary color token")
-
-#### c. Find relevant components (required when adding any UI element)
-
-If the task asks you to add, insert, or create a UI element of any kind — a table, button, card, modal, input, dropdown, form, list, nav, etc. — you **must** search the component library first before writing HTML from scratch. This applies to all task types: `section_request`, `annotation` with actions like `add_column`/`add_row`/`wrap_container`, and free-text `annotation` notes whose `description` implies new UI.
-
-**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
-
-```bash
-npx annotask components "button" --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
-```
-
-For a specific component, get its full prop signature:
-
-```bash
-npx annotask component Button --mcp
-```
-
-For **in-repo usage examples** (real prop combinations + import path this project actually uses), call `annotask_get_component_examples(name: "Button")` — or `npx annotask component-examples Button --mcp`. Prefer the example's import path and prop shape over reinventing: the examples show how *this* codebase uses the component, not just what the library exposes.
-
-#### c-ter. Find the data source (required for any task that adds or modifies data-driven UI)
-
-Before writing UI that renders data, check what's already wired. If the task's summary contains `data_context_summary` (e.g. `"hook:useUserQuery"` or `"store:useCounterStore"`), that's the primary data source powering the selected element. For the full picture:
-
-**MCP:** `annotask_get_data_context(task_id: "TASK_ID")` — returns the complete `DataContext`: every data reference in the enclosing file (`sources`, sorted with the primary source at index 0 — closest to `task.line`, tie-broken by kind precedence), `rendered_identifiers` from the template/JSX (CSV), and `route_bindings` (CSV).
-
-```bash
-npx annotask data-context TASK_ID --mcp
-```
-
-To browse the project's catalog of hooks, stores, and fetch wrappers (sorted by `used_count` — most load-bearing first):
-
-**MCP:** `annotask_get_data_sources(used_only: true)` — filter to entries actually used elsewhere in the codebase.
-
-```bash
-npx annotask data-sources --used-only --mcp
-```
-
-To see **real in-repo usages** of a specific data source (destructuring patterns, parameter shape, common wrappers — parallel to `annotask_get_component_examples`):
-
-**MCP:** `annotask_get_data_source_examples(name: "useUserQuery", kind: "composable")`
-
-```bash
-npx annotask data-source-examples useUserQuery --kind=composable --mcp
-```
-
-To see **what shape comes back** from an API — cross-reference declared schemas (OpenAPI, GraphQL, tRPC) so you don't guess field names:
-
-**MCP:** `annotask_resolve_endpoint(url: "/api/cats")` → returns the best-match operation with a confidence score.
-
-```bash
-npx annotask resolve-endpoint /api/cats --mcp
-```
-
-**MCP:** `annotask_get_api_operation(path: "/api/cats", method: "GET")` — full request / response schema for a known path pattern.
-
-```bash
-npx annotask api-operation /api/cats --method=GET --mcp
-```
-
-**MCP:** `annotask_get_api_schemas(detail: true)` — browse every discovered schema source up front.
-
-```bash
-npx annotask api-schemas --detail --mcp
-```
-
-If a task summary shows `response_schema_ref: "Cat[]"`, the agent already knows a declared shape exists — `annotask_get_api_operation` or `annotask_resolve_endpoint` will surface the full JSON schema.
-
-**When to use:**
-- Any task where the user's description mentions adding, replacing, or rewiring data — "show the current user", "list orders", "filter by status", "fetch from the API".
-- Denied tasks where feedback mentions wrong or fake data.
-- Section requests that need to render real information.
-
-**How to apply:**
-- Prefer reusing a hook/store from `data_context.sources` or `data-sources` catalog over writing new fetch code.
-- Copy the import path and call-site shape from `data-source-examples`, not from library docs.
-- If `sources[0]` doesn't match the user's description (e.g. task says "user name" but `sources[0]` is `useOrdersQuery`), check the rest of the `sources` list — the right hook is usually there.
-
-**When to use:**
-- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
-- **UI additions** — Check if a table, button, card, modal, input, form, list, or nav component already exists before writing custom HTML
-- **Styling consistency** — Using library components ensures your changes match the design system
-
-**How to apply:**
-- Search for components matching the intent (e.g., "table" if adding tabular data, "dropdown" if adding a select menu)
-- Read the props to understand customization options (variant, size, disabled, etc.)
-- Call `annotask_get_component_examples` to see how the component is already used in this codebase; copy the import path and prop patterns from there
-- Use the component in your JSX/Vue/Svelte code with appropriate props
-- Document the component reference in your resolution note
-
-#### c-bis. Re-anchor older or retried tasks
-
-For **denied** tasks, tasks that have been sitting in the queue while you edited other files, or any task whose `file`/`line` you suspect has drifted: call `annotask_get_code_context(task_id)` before editing.
-
-```bash
-npx annotask code-context TASK_ID --mcp
-```
-
-Response:
-```json
-{"file":"src/components/Header.vue","line":42,"symbol":"Header","excerpt_start_line":27,"excerpt_end_line":57,"excerpt":"...","imports":["import ..."],"excerpt_hash":"ab12cd34ef56..."}
-```
-
-Use `symbol` + `excerpt` to locate the edit target; the `excerpt_hash` is a cheap drift check on subsequent retries (if the hash changes between attempts, the surrounding code moved). Skip this step for fresh pending tasks where `file`/`line` are known good.
-
-#### d. Apply the change
-
-Read the task type and apply accordingly:
-
-- **`annotation` with `action: "text_edit"`**: The `description` field says what text to change. Find the text in the source file and apply the edit.
-
-- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run step c first.
-
-- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run step c (component library search) before writing HTML.**
-
-- **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
-
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
-
-- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID, or the synthetic `tab-order` rule from Annotask's tab-order overlay), `impact`, `help`, `helpUrl`, and `elements` array with `html`, `selector`, `fix`, source `file`/`line`/`component`, and a per-element `a11y` block with computed accessibility metadata:
-
-  ```
-  elements[i].a11y = {
-    accessible_name, name_source,   // "Sign in", source: aria-label | labelledby | label | alt | text | placeholder | none
-    role, role_source,              // "button", source: explicit | implicit | none
-    tabindex, focusable,            // null | number, true/false
-    focus_indicator,                // "visible" | "none" | "unknown"
-    contrast,                       // { foreground, background, ratio, aa_normal, aa_large, ... } only when element has text
-    aria_attrs,                     // [{ name: "aria-expanded", value: "false" }, ...]
-  }
-  ```
-
-  If `screenshot_meta` is present (the user manually attached one with the snip tool), retrieve it via `annotask_get_screenshot` before proposing visual changes (color-contrast, focus rings).
-
-  **Per-rule playbook.** Most rules fall into one of these patterns — match by `context.rule`:
-
-  | Rule(s) | Fix layer | What to do |
-  |---|---|---|
-  | `color-contrast`, `color-contrast-enhanced` | Design tokens first | Read `elements[i].a11y.contrast` for the actual fg/bg hex + ratio. If the colors come from theme tokens (check `cssVar` lookups in the source), adjust the token. If the contrast comes from a one-off inline style or hardcoded class, fix the component, not the token (you'd regress every other consumer). |
-  | `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` referencing visible text. `a11y.accessible_name` shows what (if anything) the input currently exposes — when `name_source === 'placeholder'`, the input has no real label. |
-  | `button-name`, `link-name`, `input-button-name` | Markup | Add visible text content or `aria-label`. For icon-only buttons add a visually hidden `<span class="sr-only">` (or your project's equivalent). Don't add `title` — it's not reliable for SR users. |
-  | `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | `alt=""` for decorative imagery, descriptive `alt` for informational. For `<img>` that conveys text, use the text. For SVG icons that pair with visible text, use `aria-hidden="true"`. |
-  | `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These almost always live in a layout component (e.g. `App.vue`, `_layout.tsx`, `RootLayout`), not in leaf components. |
-  | `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert/promote `<h1>`; renumber subsequent levels so the outline is contiguous. Usually a layout/section component change, not a leaf change. |
-  | `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what's set. Reference the WAI-ARIA roles spec (`helpUrl`) for the role's allowed attributes. Remove disallowed attrs; add required ones. |
-  | `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Either remove `aria-hidden`, or move the focusable elements outside (or set `tabindex="-1"` and ensure they're never the focus target). |
-  | `tabindex`, **synthetic** `tab-order` | Markup | Remove positive `tabindex`; use 0 (focusable in DOM order) or -1 (programmatically focusable, not in tab order). For the synthetic `tab-order` rule, `context.tab_order.flag` is one of `positive` / `unreachable` / `reorder` — fix the source markup so DOM order matches visual order. |
-  | `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Single source of truth — usually `index.html` (Vite/CRA), `app/layout.tsx` (Next), `src/routes/+layout.svelte` (SvelteKit), or the framework's root document. |
-  | `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>`/`<span>`. Don't nest interactive elements (e.g. `<button>` inside `<a>`). |
-  | `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element of the layout. Style it with the visually-hidden pattern that becomes visible on `:focus`. |
-  | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="…"` and rename one. If the id is dynamic, ensure the generation key is unique per instance. |
-  | `frame-title`, `iframe-title` | Markup | Add `title="…"` describing the iframe's purpose. |
-
-  **General rules:**
-  - Prefer **pattern fixes** over instance fixes. When `elements` contains many entries that share the same `file`/`component`, change the source component once — don't paste the same fix N times.
-  - For the synthetic `tab-order` rule, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no `helpUrl` from axe — use the linked WCAG focus-order page in `context.helpUrl`.
-  - When `a11y.accessible_name` is empty and `a11y.focusable` is true, the element is unreachable for screen readers — naming is the highest-priority fix.
-
-- **`theme_update`**: One or more design token value changes committed together from the Theme page. A single task now covers every edit the user made in one Commit click — do not expect one task per token. The `context` object contains:
-  - `edits`: array of token edits. Each entry has:
-    - `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
-    - `role`: semantic role name (e.g. `primary`, `background`, `heading`)
-    - `cssVar`: CSS variable name if backed by one (e.g. `--color-primary`), or `null`
-    - `theme_variant`: the theme id this edit targets (e.g. `light`, `dark`)
-    - `theme_selector`: how that variant is activated in the DOM — `{kind:'default'}`, `{kind:'attribute',host,name,value}`, `{kind:'class',host,name}`, or `{kind:'media',media}` — tells you which CSS block owns this variable (`:root`, `:root[data-theme="dark"]`, `.dark`, `@media (prefers-color-scheme: dark)`)
-    - `before`: old value (`null` for new tokens)
-    - `after`: new value
-    - `sourceFile` / `sourceLine`: where the current declaration lives (both `null` for new tokens — you pick the location)
-    - `isNew`: `true` if this token didn't exist before
-  - `styling`: array of project styling methods (e.g. `["tailwind", "scoped-css"]`)
-  - `specFile`: relative path to the design spec (typically `.annotask/design-spec.json`)
-
-  **How to apply:**
-  1. **Group `context.edits` by `sourceFile`.** For each file (skipping `null`/`isNew` for now), open it once, apply every edit against its file in a single Edit-batch, save. Use `theme_selector` + `cssVar` to locate the right declaration block — e.g. an edit with `theme_selector: {kind:'attribute',host:'html',name:'data-theme',value:'dark'}` belongs inside `:root[data-theme="dark"] { … }`, a `{kind:'default'}` edit belongs in the base `:root { … }` block.
-  2. **Tailwind config edits:** if `cssVar` is `null` and `sourceFile` references `tailwind.config.*`, update the corresponding key. If edits span both Tailwind and raw CSS, handle each file independently.
-  3. **New tokens (`isNew: true`):** add the CSS variable to the declaration block matching `theme_selector`. If no block exists for that variant yet, create one (e.g. add `:root[data-theme="dark"] { --new-var: …; }` at the end of the main tokens file). After writing, remember the final file path and line for step 4.
-  4. **Patch `.annotask/design-spec.json` once at the end.** Resolve `context.specFile` against the MFE root (the directory containing `.annotask/`). For each edit:
-     - Existing token: find `spec.<category>` — note dotted categories like `typography.families` map to nested paths — locate the entry by `role`, then set `values[theme_variant] = after`.
-     - New token: append a token object with `role`, `values: { [theme_variant]: after }`, `cssVar`, and fresh `sourceFile` / `sourceLine` pointing at where you added the declaration in step 3.
-     - When writing, keep the existing JSON formatting (same indentation, trailing newline) so the file watcher's next broadcast is clean.
-  5. The server watches `design-spec.json`; saving it fires a `designspec:updated` push and the Theme page refetches automatically.
-
-  **Worked example:** `context.edits = [{ category:'colors', role:'background', cssVar:'--stress-bg', theme_variant:'light', theme_selector:{kind:'default'}, before:'#f4f7fb', after:'#ff00ff', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:12, isNew:false }, { category:'colors', role:'text', cssVar:'--stress-text', theme_variant:'dark', theme_selector:{kind:'attribute',host:'html',name:'data-theme',value:'dark'}, before:'#e7eefb', after:'#ffeb3b', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:65, isNew:false }]` → open `tokens.css` once, update `--stress-bg` in the `:root` block and `--stress-text` in the `:root[data-theme="dark"]` block, save. Then open `.annotask/design-spec.json`, set `colors[?role=='background'].values.light = '#ff00ff'` and `colors[?role=='text'].values.dark = '#ffeb3b'`, save. Mark the task `review` with resolution `"Updated 2 color tokens in tokens.css and design-spec.json"`.
-
-- **`api_update`**: In-repo backend-contract edit. Created from the shell's Data view when the user selects an internal data source (`schema_in_repo === true`) and fills in a desired change. Only valid for in-repo schemas — external APIs cannot be edited from Annotask and should be marked `blocked` with an explanation if a request implies one.
-
-  The `context` object carries:
-  - `data_source_name`: hook/store/query identifier (e.g. `useCatsQuery`)
-  - `data_source_kind`: one of `composable | signal | store | fetch | graphql | loader | rpc`
-  - `schema_location`: path to the schema file (e.g. `openapi.yaml`, `src/trpc/router.ts`)
-  - `schema_kind`: `openapi | graphql | trpc | jsonschema`
-  - `endpoint`: literal endpoint / query key when the source used one
-  - `operation`: `{ method, path }` from the matched schema operation, when a match exists
-  - `desired_change`: user's description of the needed contract change
-  - `rationale`: optional "why"
-
-  **How to apply:**
-  - Open the schema file at `context.schema_location`. Read the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`) and make the change described in `desired_change`.
-  - Update the handler / backend implementation that serves that operation (typical pairs: OpenAPI routes ↔ the framework-specific handler file, tRPC router ↔ its procedure body).
-  - Update the frontend data source at `file:line` if the shape change affects the consumer (e.g. return type, destructured fields).
-  - If the change is additive (new optional field), you usually don't need to change existing callers. If it's breaking (required field, renamed field), search for all usages with `annotask_get_data_source_examples` and update them.
-  - Record what you changed in the resolution note — mention which schema location, which operation, and any frontend call sites touched.
-
-- **`annotation` with cross-boundary API edits**: An annotation task may turn out to require an in-repo API change (e.g. "show expiration date on the tier badge" when the `Cat` schema does not currently return `expires_at`).
-
-  **Rule**: do **not** silently edit the backend. Ask the user first via a `needs_info` question:
-  > This change requires updating the internal API route `GET /api/cats` to add an `expires_at` field on the `Cat` response. Proceed with both frontend and backend edits? (yes / no)
-
-  If the user approves, continue the same task (do **not** spawn a separate `api_update` task). Record each API edit structurally in `task.context.api_edits[]`:
-  ```json
-  {
-    "api_edits": [
-      {
-        "schema_location": "openapi.yaml",
-        "schema_kind": "openapi",
-        "operation": { "method": "GET", "path": "/api/cats" },
-        "change_summary": "Added nullable expires_at: string (ISO date) to the Cat response schema and handler."
-      }
-    ]
-  }
-  ```
-  Annotask's summary lifting will surface `api_edits_count` on the triage view so the user sees this task crossed the frontend/backend line.
-
-  If the user denies, do the frontend-only thing you can, or mark the task `blocked` with an explanation pointing at the missing backend support.
-
-  If the data source is external (`schema_in_repo === false`) and the task requires a contract change, mark the task `blocked` immediately — Annotask cannot edit APIs outside the repo.
-
-#### e. Ask for clarification (only when stuck)
-
-If you are **genuinely stuck** — missing API context, unclear library usage, ambiguous intent that could lead to a wrong implementation — ask the user for clarification instead of guessing:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", questions: [{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}])`
-
-```bash
-npx annotask update-task TASK_ID --mcp --ask='{"message":"Optional markdown context","questions":[{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}]}'
-```
-
-This sets the task to `needs_info` status. The user sees your questions in the Annotask UI and responds there. When answered, the task returns to `in_progress` with answers in `agent_feedback`.
-
-**Question types:**
-- `text` — free-text answer from user
-- `choice` — user picks from your provided `options` array
-
-**Guidelines:**
-- Only ask when you truly cannot proceed — do not ask for confirmation on straightforward tasks
-- Be specific: "Which CSS framework should I use for the grid?" is better than "How should I do this?"
-- Combine related questions into a single ask rather than multiple rounds
-- After asking, move on to the next task. Come back to check answers later via `annotask_get_tasks` MCP tool or `npx annotask tasks --mcp`
-
-#### f. Mark as blocked (when the task can't be done)
-
-If the task is **fundamentally outside your control** — a performance issue in a third-party library, an accessibility bug in a dependency, a config change that requires infrastructure access, etc. — mark it as blocked with an explanation:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", blocked_reason: "This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone.")`
-
-```bash
-npx annotask update-task TASK_ID --mcp --blocked-reason="This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone."
-```
-
-This sets the task to `blocked` status automatically. The user sees your explanation and can either **dismiss** the task or **push back** (deny it with feedback asking you to try a different approach).
-
-**When to use blocked vs needs_info:**
-- `needs_info` = "I can do this, but I need more information from you"
-- `blocked` = "This can't be done through source code changes — here's why"
-
-#### g. Mark for review immediately
-
-As soon as you finish applying **this** task, mark it for review with a brief resolution note:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "review", resolution: "Swapped grid to flexbox, added gap-4 for spacing")`
-
-```bash
-npx annotask update-task TASK_ID --status=review --resolution="Swapped grid to flexbox, added gap-4 for spacing" --mcp
-```
-
-Keep resolutions short — one sentence describing what you changed, not why. The user sees it in the Annotask shell alongside the diff.
-
-#### h. Move to the next task in the group
-
-Repeat steps a–g for each remaining task in the current group, then move to the next group (or confirm parallel subagents have finished). Per-task review flipping is what powers incremental feedback — each task moves to `review` as soon as *its own* edit lands, even inside a batched group, so the user can accept or deny early while later tasks are still in flight.
-
-### 3. Second sweep — catch denies and new tasks that arrived mid-run
-
-Because tasks flip to `review` as soon as their edit lands, the user may have been reviewing (and denying) early tasks while you were still applying later ones. They may also have created brand-new tasks. Before reporting, re-fetch once:
-
-**MCP:** `annotask_get_tasks(status: "denied")` and `annotask_get_tasks(status: "pending")`
-
-```bash
-npx annotask tasks --mcp --status=denied
-npx annotask tasks --mcp --status=pending
-```
-
-If either query returns tasks you did not handle in step 2, loop back to step 2 and process them — re-triage, re-group, apply. Repeat step 3 after each sweep until both queries come back empty.
-
-**If a task keeps returning denied across multiple sweeps**, stop guessing and ask. Use step 2e (`annotask_update_task` with `questions`) to flip it to `needs_info` and let the user clarify what they actually want, rather than burning more sweeps on a misread requirement.
-
-### 4. Report to the user
-
-Tell the user:
-- Which tasks were applied
-- Which files were modified
-- Any tasks that couldn't be applied (and why)
-
-The user will review changes in Annotask and either **accept** (task removed) or **deny with feedback** (task stays denied for next apply).
-
-### Denied tasks
-
-Tasks with `status: "denied"` and a `feedback` field were rejected by the user. They are processed alongside pending tasks in step 2. Read the `feedback` carefully to understand what went wrong and re-apply with corrections.
-
-## Task lifecycle
-
-```
-pending → in_progress (agent working) → review (user checks) → accepted (removed)
-                  ↓                          ↓                → denied (with feedback → agent re-applies)
-             needs_info (waiting)        blocked (can't do)   → dismissed (user deletes)
-                  ↓                          ↓                → pushed back (denied → agent retries)
-             in_progress (resume)        user decides
-```
-
-## Important notes
-
-- Tasks are the source of truth — fetch tasks, not the report
-- The `feedback` field on denied tasks is critical — it tells you what the user didn't like
-- Tasks with `status: "review"` are waiting for user review — don't re-apply them
-- Tasks with `status: "needs_info"` are waiting for the user to answer your questions — skip them and check back later
-- Tasks with `status: "blocked"` have been flagged as not actionable — skip them unless the user pushes back with feedback
-- When a `needs_info` task returns to `in_progress`, check `agent_feedback` for the user's answers before resuming work
-- After applying, the user's page will hot-reload via Vite HMR showing the changes immediately
diff --git a/playgrounds/stress-test/apps/mfe-react-workflows/.claude/skills/annotask-init/SKILL.md b/playgrounds/stress-test/apps/mfe-react-workflows/.claude/skills/annotask-init/SKILL.md
deleted file mode 100644
index 63df6c7..0000000
--- a/playgrounds/stress-test/apps/mfe-react-workflows/.claude/skills/annotask-init/SKILL.md
+++ /dev/null
@@ -1,321 +0,0 @@
-# annotask-init
-
-Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
-
-## When to use
-
-Use this skill when the user says any of:
-- "initialize Annotask" / "init Annotask"
-- "set up Annotask" / "configure Annotask"
-- "scan my project for Annotask"
-- `/annotask-init`
-
-## What it does
-
-Scans the project to detect the framework, design tokens (colors, typography, spacing, borders), icon library, and component library. Writes `.annotask/design-spec.json` which Annotask reads to populate the Theme page with editable design tokens.
-
-## Output schema
-
-Every token carries resolved values for every detected theme variant via a
-`values` map keyed by theme id. Tokens that don't change across variants repeat
-the same value under each id — this keeps every token one uniform shape.
-
-```json
-{
-  "role": "primary",
-  "values": { "light": "#3b82f6", "dark": "#60a5fa" },
-  "cssVar": "--color-primary",
-  "source": "var(--color-primary)",
-  "sourceFile": "src/assets/main.css",
-  "sourceLine": 12
-}
-```
-
-- `role` — semantic name (see vocabularies below)
-- `values` — resolved value per theme variant, keyed by theme id (`light`, `dark`, or a named theme). Single-theme apps use `{ "default": "…" }`.
-- `cssVar` — the CSS custom property name, if backed by one. Omit if not a CSS variable.
-- `source` — human-readable provenance: `var(--x)`, `tailwind.config:colors.primary`, `@theme:--color-primary`
-- `sourceFile` — relative path to the file where the value is defined
-- `sourceLine` — line number in that file (the `:root` variant's definition is fine when multiple exist)
-
-Theme variants themselves are listed at the top of the spec under `themes`,
-with a `selector` describing how each variant is activated in the DOM so the
-Annotask shell can match it against the iframe's current state:
-
-```json
-"themes": [
-  { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-  { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-],
-"defaultTheme": "light"
-```
-
-`selector.kind` is one of `attribute` (with `name`, `value`, optional `host`), `class` (with `name`, optional `host`), `media` (with `media: '(prefers-color-scheme: dark)'`), or `default` (no selector — the base `:root` values). Apps with only one theme should emit a single `{ "id": "default", "name": "Default", "selector": { "kind": "default" } }` variant.
-
-## Steps
-
-### 1. Detect framework
-
-Check `package.json` dependencies:
-- `vue` → name "vue", read version
-- `react` / `react-dom` → name "react"
-- `svelte` → name "svelte"
-- `solid-js` → name "solid"
-
-Check for styling:
-- `tailwindcss` in devDependencies or dependencies → add "tailwind" to styling array
-- Look for `<style scoped>` in `.vue` files → add "scoped-css"
-- Look for CSS module imports (`.module.css`) → add "css-modules"
-
-### 2. Detect theme variants
-
-Before extracting any token values, determine which theme variants the project
-supports so you know which scopes to resolve values under. Check these signals
-in order and stop at the first match:
-
-1. **Tailwind `.dark` class** — If CSS files contain `.dark { … }` / `:root.dark { … }` / `html.dark { … }` blocks, or Tailwind v3 config has `darkMode: 'class'`, or Tailwind v4 CSS contains `@custom-variant dark (&:where(.dark, .dark *))`. Emit two variants:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }`
-
-2. **Data-attribute theming** — If CSS contains `[data-theme="…"]`, `[data-bs-theme="…"]`, `[data-mui-color-scheme="…"]`, `[data-mantine-color-scheme="…"]`, or `[data-color-scheme="…"]` selectors. Emit one variant per distinct attribute value:
-   - `{ "id": "<value>", "name": "<Value>", "scheme": "light|dark (if obvious)", "selector": { "kind": "attribute", "host": "html", "name": "<attr-name>", "value": "<value>" } }`
-
-3. **`@media (prefers-color-scheme: dark)` blocks** — If the project only switches via media queries. Emit:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "media", "media": "(prefers-color-scheme: dark)" } }`
-
-4. **Single theme** — If none of the above are present:
-   - `[ { "id": "default", "name": "Default", "selector": { "kind": "default" } } ]`
-
-Set `defaultTheme` to the variant id used when no selector matches — typically `"light"` or `"default"`.
-
-### 3. Scan colors
-
-**Find color sources:**
-
-1. **CSS variables**: Search for `:root`, `:root.dark`, `html.dark`, `[data-theme="…"]`, and `@media (prefers-color-scheme: dark) :root` declarations across CSS files and Vue `<style>` blocks. Extract `--variable-name: value` pairs, remembering which variant scope each came from.
-
-2. **Tailwind v4** (version >= 4): Search for `@theme` blocks in CSS files. Extract custom properties defined within them. `@theme` blocks without a variant selector apply to every variant.
-
-3. **Tailwind v3** (version < 4): Read `tailwind.config.js`, `tailwind.config.ts`, or `tailwind.config.mjs`. Extract `theme.extend.colors`. Convert to flat key-value pairs.
-
-**Resolve each color under every detected variant.** Produce a `values` map
-keyed by theme id. When a variant doesn't override the token, copy the base
-(`:root`/light/default) value so every token has a value for every variant.
-When a variant-specific block defines a new CSS variable that doesn't appear
-in the base scope, leave the missing variants blank (the server normalizer
-will fill them when the spec is read).
-
-**Classify into semantic roles using this fixed vocabulary:**
-
-| Role | Match heuristics (in variable/key name) |
-|------|----------------------------------------|
-| `primary` | primary, brand |
-| `secondary` | secondary |
-| `accent` | accent |
-| `background` | bg, background |
-| `surface` | surface, card |
-| `text` | text, foreground, fg (but not text-muted) |
-| `text-muted` | text-muted, muted, subtle |
-| `border` | border, divider, separator |
-| `danger` | danger, error, destructive, red |
-| `warning` | warning, amber, yellow (semantic) |
-| `success` | success, green (semantic) |
-| `info` | info, blue (semantic) |
-
-If a variable doesn't match any heuristic, use a descriptive role name derived from the variable name (e.g., `--sidebar-bg` → role `sidebar-bg`).
-
-**Limits**: Maximum 30 color tokens. Prioritize semantic roles first, then most-used custom colors.
-
-### 4. Scan typography
-
-Apply the same per-variant `values` map strategy used for colors: resolve each
-token under every detected variant, copying the base value for variants that
-don't override it.
-
-**Font families**: Search for:
-- CSS variables containing `font`, `family` in `:root` or `@theme`
-- `fontFamily` in Tailwind config
-- Direct `font-family` declarations on `body`, `html`, `h1`-`h6` elements
-
-Classify as:
-- `heading` — used on h1-h6 or named heading/display
-- `body` — used on body/html or named sans/body/base
-- `mono` — monospace, code, named mono
-
-**Font scale**: Search for:
-- CSS variables containing `font-size`, `text-` size names
-- `fontSize` in Tailwind config
-- `@theme` size definitions
-
-Use roles: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or by ascending size order).
-
-**Weights**: Scan component files for `font-weight` values and Tailwind weight classes (`font-bold`, `font-semibold`, etc.). List unique weights as strings: `["400", "500", "600", "700"]`.
-
-### 5. Scan spacing
-
-Search for:
-- CSS variables containing `space`, `gap`, `margin`, `padding`, `size`
-- `spacing` in Tailwind config
-- `@theme` spacing definitions
-
-Use roles: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or ascending size).
-
-**Limits**: Maximum 12 spacing tokens.
-
-### 6. Scan border radius
-
-Search for:
-- CSS variables containing `radius`, `rounded`
-- `borderRadius` in Tailwind config
-- `@theme` radius definitions
-
-Use roles: `sm`, `md`, `lg`, `xl`, `full` (match by name or ascending size).
-
-### 7. Scan breakpoints
-
-Detect responsive breakpoints from whatever styling system the project uses. Output as a flat object mapping name → min-width value.
-
-**Sources (check in order):**
-
-1. **Tailwind v4** (>= 4): Look in CSS files for `@theme` blocks defining `--breakpoint-*` custom properties, or `@custom-media` rules.
-
-2. **Tailwind v3** (< 4): Read `tailwind.config.{js,ts,mjs}`. Extract `theme.screens` or `theme.extend.screens`. Default Tailwind screens: `{ "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" }` — use these as fallback if Tailwind is detected but no custom screens are defined.
-
-3. **Bootstrap**: Check for `bootstrap` in package.json. Default Bootstrap breakpoints: `{ "sm": "576px", "md": "768px", "lg": "992px", "xl": "1200px", "xxl": "1400px" }`.
-
-4. **CSS custom properties**: Search `:root` for variables containing `breakpoint`, `screen`, `bp` in the name (e.g., `--bp-mobile: 480px`).
-
-5. **CSS `@media` patterns**: Scan `.css`, `.scss`, `.vue` files for `@media` queries with `min-width` or `max-width`. Extract the 3–6 most common breakpoint values and assign roles by ascending size: `sm`, `md`, `lg`, `xl`, `2xl`.
-
-**Output example:**
-```json
-"breakpoints": {
-  "sm": "640px",
-  "md": "768px",
-  "lg": "1024px",
-  "xl": "1280px",
-  "2xl": "1536px"
-}
-```
-
-If no breakpoints are detected, omit the `breakpoints` field (don't include an empty object).
-
-### 8. Detect icon library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `lucide-vue-next` or `lucide-react` | lucide |
-| `@heroicons/vue` or `@heroicons/react` | heroicons |
-| `@fortawesome/vue-fontawesome` or `@fortawesome/react-fontawesome` | fontawesome |
-| `@phosphor-icons/vue` or `@phosphor-icons/react` | phosphor |
-| `@tabler/icons-vue` or `@tabler/icons-react` | tabler |
-
-Read the version from package.json.
-
-### 9. Detect component library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `primevue` | PrimeVue |
-| `vuetify` | Vuetify |
-| `element-plus` | Element Plus |
-| `@headlessui/vue` | Headless UI |
-| `radix-vue` | Radix Vue |
-| `naive-ui` | Naive UI |
-| `@shadcn/ui` or `shadcn-vue` | shadcn/ui |
-
-If found, scan `src/` for import statements to find used components:
-```bash
-grep -rh "from '${package}" --include='*.vue' --include='*.ts' --include='*.js' src/ | sort -u
-```
-
-Extract component names from the imports. Read the version from package.json.
-
-### 10. Write design spec
-
-Create `.annotask/design-spec.json`:
-
-```json
-{
-  "version": "1.0",
-  "framework": {
-    "name": "vue",
-    "version": "3.5.0",
-    "styling": ["tailwind", "scoped-css"]
-  },
-  "themes": [
-    { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-    { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-  ],
-  "defaultTheme": "light",
-  "colors": [
-    { "role": "primary",    "values": { "light": "#3b82f6", "dark": "#60a5fa" }, "cssVar": "--color-primary", "source": "var(--color-primary)", "sourceFile": "src/assets/main.css", "sourceLine": 5 },
-    { "role": "background", "values": { "light": "#ffffff", "dark": "#0b1120" }, "cssVar": "--bg",            "source": "var(--bg)",            "sourceFile": "src/assets/main.css", "sourceLine": 3 }
-  ],
-  "typography": {
-    "families": [
-      { "role": "body", "values": { "light": "Inter, sans-serif", "dark": "Inter, sans-serif" }, "cssVar": "--font-sans", "source": "var(--font-sans)", "sourceFile": "src/assets/main.css", "sourceLine": 10 }
-    ],
-    "scale": [
-      { "role": "base", "values": { "light": "1rem", "dark": "1rem" }, "cssVar": "--text-base", "source": "var(--text-base)", "sourceFile": "src/assets/main.css", "sourceLine": 15 }
-    ],
-    "weights": ["400", "500", "600", "700"]
-  },
-  "spacing": [
-    { "role": "sm", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--space-sm", "source": "var(--space-sm)", "sourceFile": "src/assets/main.css", "sourceLine": 20 }
-  ],
-  "borders": {
-    "radius": [
-      { "role": "md", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--radius-md", "source": "var(--radius-md)", "sourceFile": "src/assets/main.css", "sourceLine": 25 }
-    ]
-  },
-  "breakpoints": {
-    "sm": "640px",
-    "md": "768px",
-    "lg": "1024px",
-    "xl": "1280px",
-    "2xl": "1536px"
-  },
-  "icons": {
-    "library": "lucide",
-    "version": "0.300.0"
-  },
-  "components": {
-    "library": "PrimeVue",
-    "version": "4.5.4",
-    "used": ["DataTable", "Column", "InputText", "Tag", "Button"]
-  }
-}
-```
-
-### 11. Clean up old config
-
-If `.annotask/config.json` exists, delete it — it's been replaced by `design-spec.json`.
-
-### 12. Update .gitignore
-
-Check if `.gitignore` contains `.annotask/`. If not, append:
-```
-# Annotask (generated)
-.annotask/
-```
-
-### 13. Report to user
-
-Tell the user:
-- What was detected (framework, number of color/typography/spacing tokens, libraries)
-- That they can open the **Theme** page in Annotask to view and edit tokens
-- That they can re-run `/annotask-init` to rescan
-
-## Notes
-
-- This skill is idempotent — re-running overwrites the design spec with fresh data
-- The design spec is gitignored because it's generated and may vary per developer
-- If detection fails for any section, use empty defaults (empty array, null) rather than omitting the field
-- All top-level fields are required — use empty values for missing data
-- When a token has a CSS variable backing, always populate the `cssVar` field — this enables live preview in the Theme page
diff --git a/playgrounds/stress-test/apps/mfe-react-workflows/.mcp.json b/playgrounds/stress-test/apps/mfe-react-workflows/.mcp.json
deleted file mode 100644
index 5527f21..0000000
--- a/playgrounds/stress-test/apps/mfe-react-workflows/.mcp.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "annotask": {
-      "command": "npx",
-      "args": [
-        "annotask",
-        "mcp"
-      ]
-    }
-  }
-}
diff --git a/playgrounds/stress-test/apps/mfe-solid-component-lab/.claude/skills/annotask-apply/SKILL.md b/playgrounds/stress-test/apps/mfe-solid-component-lab/.claude/skills/annotask-apply/SKILL.md
deleted file mode 100644
index 49921a2..0000000
--- a/playgrounds/stress-test/apps/mfe-solid-component-lab/.claude/skills/annotask-apply/SKILL.md
+++ /dev/null
@@ -1,460 +0,0 @@
-# annotask-apply
-
-Apply pending Annotask design tasks to the source code.
-
-## When to use
-
-Use this skill when the user says:
-- "apply the Annotask changes"
-- "apply my design changes"
-- "sync Annotask"
-- `/annotask-apply`
-
-## How it works
-
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
-
-## MCP preference
-
-If you have `annotask_*` MCP tools available, prefer them over CLI commands — they return structured data directly, are faster, and avoid shell/npx issues. If MCP tools are not available, use the CLI commands shown below.
-
-**Always pass `--mcp` to CLI commands.** The flag emits compact JSON that matches the MCP tool response shapes exactly (no ANSI colors, no human prefixes, `visual` stripped, `agent_feedback` trimmed). That way the same parsing logic works whether you're calling the MCP tool or the CLI fallback.
-
-## Steps
-
-### 0. Check server status
-
-**MCP:** If you have MCP tools, the server is already running — skip this step.
-
-```bash
-npx annotask status --mcp
-```
-
-If this fails, the Annotask dev server isn't running. Ask the user to start it.
-
-### 1. Fetch pending tasks
-
-**MCP:** `annotask_get_tasks(status: "pending")` — returns compact summaries. Use `detail: true` for full objects.
-
-```bash
-npx annotask tasks --mcp --status=pending
-```
-
-Response (compact task summaries):
-```json
-{"version":"1.0","count":1,"tasks":[{"id":"task-123","type":"annotation","status":"pending","description":"Change the header background to match the new brand colors","file":"src/components/Header.vue","line":5,"action":"text_edit","screenshot":"screenshot-1711800000-ab3kf.png"}]}
-```
-
-Each task summary has: `id`, `type`, `status`, `description`, `file`, `line`, and optionally `component`, `action`, `screenshot`, `feedback` (on denied tasks), `blocked_reason`, `resolution`.
-
-For full task details (context, viewport, interaction_history, agent_feedback), use `annotask_get_task` MCP tool or `npx annotask task <id> --mcp` for a single task (`npx annotask tasks --mcp --detail` for the full list). Only fetch full details when the summary doesn't provide enough context to apply the change.
-
-### Screenshot reference
-
-Some tasks include a `screenshot` field. The screenshot shows exactly what the user sees in the browser. To view it:
-
-**MCP:** `annotask_get_screenshot(task_id: "TASK_ID")` — returns base64-encoded PNG directly.
-
-```bash
-npx annotask screenshot TASK_ID
-```
-
-This downloads the PNG to `.annotask/screenshots/`. Use it as visual context alongside the task description and source code. (The screenshot command writes the file on disk — `--mcp` doesn't apply.)
-
-### 2. Triage, group, then apply
-
-Filter actionable tasks: `status: "pending"`, `status: "denied"` (with `feedback`), and `status: "in_progress"` tasks whose `agent_feedback` now contains answers to earlier questions. Skip `needs_info` (waiting for user) and `blocked` (marked not actionable).
-
-Before locking anything, **triage** — read all actionable task summaries and group them by touched resources:
-
-- **By file**: tasks whose `file` is the same go in one group (Edits batched on one Read).
-- **By shared state**: any task that writes `.annotask/design-spec.json`, `:root` CSS variables, `tailwind.config.*`, or a global stylesheet goes in the *shared-state* group regardless of which source file triggered it.
-- **By dependency**: if a `theme_update` adds or changes a token that a `style_update` in the same batch consumes, the `theme_update` goes in an earlier phase. If a `section_request` introduces the UI that an `a11y_fix` targets, the `section_request` goes first.
-
-Within each group: process serially, reading the file once and batching Edits. Across groups that are fully disjoint (no shared file, no shared state, no dependency edge), you may launch parallel subagents — one per group — to apply them concurrently. If in doubt, run serially.
-
-#### Parallelism rules
-
-- **Same file → same group, serial.** Never have two tasks editing the same file concurrently.
-- **Shared global state → one group, serial.** `.annotask/design-spec.json`, `:root` blocks in shared CSS, `tailwind.config.*`, shared layout files, i18n catalogs, route tables, barrel exports.
-- **Dependency order**: `theme_update` before any `style_update` that references the new/changed token; structural task (`section_request`, `annotation` with `wrap_container`/`add_row`/`add_column`) before an `a11y_fix` or `style_update` on the same new UI.
-- **Stale locators**: after edits land, the `file`/`line` on remaining tasks may drift. When in doubt, call `annotask_get_code_context(task_id)` before editing — it returns the current symbol, a ±15 line excerpt, and an `excerpt_hash` you can compare across retries. Otherwise, search by surrounding text/element context over trusting `line` from the original triage.
-- **Non-idempotent inserts**: `add_row`, `add_column`, `section_request`, and free-text "add this" notes can duplicate on retry. Before inserting, confirm the target isn't already present.
-- **If using parallel subagents**: each subagent receives only its group's task IDs plus project context. After all subagents finish, run a quick typecheck/build sanity pass before returning control to the user. If any subagent failed, surface it clearly — do not silently accept partial success.
-
-For each task in a group, follow this cycle:
-
-#### a. Lock the task
-
-Mark it `in_progress` so the user sees you're working on it:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "in_progress")`
-
-```bash
-npx annotask update-task TASK_ID --status=in_progress --mcp
-```
-
-#### b. Reference the design spec for consistency
-
-Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
-
-**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
-
-```bash
-npx annotask design-spec --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
-```
-
-For detailed tokens in a specific category:
-
-```bash
-npx annotask design-spec --category=colors --mcp
-```
-
-**When to use:**
-- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
-- **Typography changes** — Reference the font scale and families from the spec
-- **Responsive design** — Use detected breakpoints when adding media queries
-- **New components** — Match the design system when creating new UI
-
-**How to apply:**
-- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
-- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
-- For responsive design, use the detected breakpoints
-- Document the token reference in your resolution note (e.g., "Applied primary color token")
-
-#### c. Find relevant components (required when adding any UI element)
-
-If the task asks you to add, insert, or create a UI element of any kind — a table, button, card, modal, input, dropdown, form, list, nav, etc. — you **must** search the component library first before writing HTML from scratch. This applies to all task types: `section_request`, `annotation` with actions like `add_column`/`add_row`/`wrap_container`, and free-text `annotation` notes whose `description` implies new UI.
-
-**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
-
-```bash
-npx annotask components "button" --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
-```
-
-For a specific component, get its full prop signature:
-
-```bash
-npx annotask component Button --mcp
-```
-
-For **in-repo usage examples** (real prop combinations + import path this project actually uses), call `annotask_get_component_examples(name: "Button")` — or `npx annotask component-examples Button --mcp`. Prefer the example's import path and prop shape over reinventing: the examples show how *this* codebase uses the component, not just what the library exposes.
-
-#### c-ter. Find the data source (required for any task that adds or modifies data-driven UI)
-
-Before writing UI that renders data, check what's already wired. If the task's summary contains `data_context_summary` (e.g. `"hook:useUserQuery"` or `"store:useCounterStore"`), that's the primary data source powering the selected element. For the full picture:
-
-**MCP:** `annotask_get_data_context(task_id: "TASK_ID")` — returns the complete `DataContext`: every data reference in the enclosing file (`sources`, sorted with the primary source at index 0 — closest to `task.line`, tie-broken by kind precedence), `rendered_identifiers` from the template/JSX (CSV), and `route_bindings` (CSV).
-
-```bash
-npx annotask data-context TASK_ID --mcp
-```
-
-To browse the project's catalog of hooks, stores, and fetch wrappers (sorted by `used_count` — most load-bearing first):
-
-**MCP:** `annotask_get_data_sources(used_only: true)` — filter to entries actually used elsewhere in the codebase.
-
-```bash
-npx annotask data-sources --used-only --mcp
-```
-
-To see **real in-repo usages** of a specific data source (destructuring patterns, parameter shape, common wrappers — parallel to `annotask_get_component_examples`):
-
-**MCP:** `annotask_get_data_source_examples(name: "useUserQuery", kind: "composable")`
-
-```bash
-npx annotask data-source-examples useUserQuery --kind=composable --mcp
-```
-
-To see **what shape comes back** from an API — cross-reference declared schemas (OpenAPI, GraphQL, tRPC) so you don't guess field names:
-
-**MCP:** `annotask_resolve_endpoint(url: "/api/cats")` → returns the best-match operation with a confidence score.
-
-```bash
-npx annotask resolve-endpoint /api/cats --mcp
-```
-
-**MCP:** `annotask_get_api_operation(path: "/api/cats", method: "GET")` — full request / response schema for a known path pattern.
-
-```bash
-npx annotask api-operation /api/cats --method=GET --mcp
-```
-
-**MCP:** `annotask_get_api_schemas(detail: true)` — browse every discovered schema source up front.
-
-```bash
-npx annotask api-schemas --detail --mcp
-```
-
-If a task summary shows `response_schema_ref: "Cat[]"`, the agent already knows a declared shape exists — `annotask_get_api_operation` or `annotask_resolve_endpoint` will surface the full JSON schema.
-
-**When to use:**
-- Any task where the user's description mentions adding, replacing, or rewiring data — "show the current user", "list orders", "filter by status", "fetch from the API".
-- Denied tasks where feedback mentions wrong or fake data.
-- Section requests that need to render real information.
-
-**How to apply:**
-- Prefer reusing a hook/store from `data_context.sources` or `data-sources` catalog over writing new fetch code.
-- Copy the import path and call-site shape from `data-source-examples`, not from library docs.
-- If `sources[0]` doesn't match the user's description (e.g. task says "user name" but `sources[0]` is `useOrdersQuery`), check the rest of the `sources` list — the right hook is usually there.
-
-**When to use:**
-- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
-- **UI additions** — Check if a table, button, card, modal, input, form, list, or nav component already exists before writing custom HTML
-- **Styling consistency** — Using library components ensures your changes match the design system
-
-**How to apply:**
-- Search for components matching the intent (e.g., "table" if adding tabular data, "dropdown" if adding a select menu)
-- Read the props to understand customization options (variant, size, disabled, etc.)
-- Call `annotask_get_component_examples` to see how the component is already used in this codebase; copy the import path and prop patterns from there
-- Use the component in your JSX/Vue/Svelte code with appropriate props
-- Document the component reference in your resolution note
-
-#### c-bis. Re-anchor older or retried tasks
-
-For **denied** tasks, tasks that have been sitting in the queue while you edited other files, or any task whose `file`/`line` you suspect has drifted: call `annotask_get_code_context(task_id)` before editing.
-
-```bash
-npx annotask code-context TASK_ID --mcp
-```
-
-Response:
-```json
-{"file":"src/components/Header.vue","line":42,"symbol":"Header","excerpt_start_line":27,"excerpt_end_line":57,"excerpt":"...","imports":["import ..."],"excerpt_hash":"ab12cd34ef56..."}
-```
-
-Use `symbol` + `excerpt` to locate the edit target; the `excerpt_hash` is a cheap drift check on subsequent retries (if the hash changes between attempts, the surrounding code moved). Skip this step for fresh pending tasks where `file`/`line` are known good.
-
-#### d. Apply the change
-
-Read the task type and apply accordingly:
-
-- **`annotation` with `action: "text_edit"`**: The `description` field says what text to change. Find the text in the source file and apply the edit.
-
-- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run step c first.
-
-- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run step c (component library search) before writing HTML.**
-
-- **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
-
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
-
-- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID, or the synthetic `tab-order` rule from Annotask's tab-order overlay), `impact`, `help`, `helpUrl`, and `elements` array with `html`, `selector`, `fix`, source `file`/`line`/`component`, and a per-element `a11y` block with computed accessibility metadata:
-
-  ```
-  elements[i].a11y = {
-    accessible_name, name_source,   // "Sign in", source: aria-label | labelledby | label | alt | text | placeholder | none
-    role, role_source,              // "button", source: explicit | implicit | none
-    tabindex, focusable,            // null | number, true/false
-    focus_indicator,                // "visible" | "none" | "unknown"
-    contrast,                       // { foreground, background, ratio, aa_normal, aa_large, ... } only when element has text
-    aria_attrs,                     // [{ name: "aria-expanded", value: "false" }, ...]
-  }
-  ```
-
-  If `screenshot_meta` is present (the user manually attached one with the snip tool), retrieve it via `annotask_get_screenshot` before proposing visual changes (color-contrast, focus rings).
-
-  **Per-rule playbook.** Most rules fall into one of these patterns — match by `context.rule`:
-
-  | Rule(s) | Fix layer | What to do |
-  |---|---|---|
-  | `color-contrast`, `color-contrast-enhanced` | Design tokens first | Read `elements[i].a11y.contrast` for the actual fg/bg hex + ratio. If the colors come from theme tokens (check `cssVar` lookups in the source), adjust the token. If the contrast comes from a one-off inline style or hardcoded class, fix the component, not the token (you'd regress every other consumer). |
-  | `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` referencing visible text. `a11y.accessible_name` shows what (if anything) the input currently exposes — when `name_source === 'placeholder'`, the input has no real label. |
-  | `button-name`, `link-name`, `input-button-name` | Markup | Add visible text content or `aria-label`. For icon-only buttons add a visually hidden `<span class="sr-only">` (or your project's equivalent). Don't add `title` — it's not reliable for SR users. |
-  | `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | `alt=""` for decorative imagery, descriptive `alt` for informational. For `<img>` that conveys text, use the text. For SVG icons that pair with visible text, use `aria-hidden="true"`. |
-  | `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These almost always live in a layout component (e.g. `App.vue`, `_layout.tsx`, `RootLayout`), not in leaf components. |
-  | `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert/promote `<h1>`; renumber subsequent levels so the outline is contiguous. Usually a layout/section component change, not a leaf change. |
-  | `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what's set. Reference the WAI-ARIA roles spec (`helpUrl`) for the role's allowed attributes. Remove disallowed attrs; add required ones. |
-  | `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Either remove `aria-hidden`, or move the focusable elements outside (or set `tabindex="-1"` and ensure they're never the focus target). |
-  | `tabindex`, **synthetic** `tab-order` | Markup | Remove positive `tabindex`; use 0 (focusable in DOM order) or -1 (programmatically focusable, not in tab order). For the synthetic `tab-order` rule, `context.tab_order.flag` is one of `positive` / `unreachable` / `reorder` — fix the source markup so DOM order matches visual order. |
-  | `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Single source of truth — usually `index.html` (Vite/CRA), `app/layout.tsx` (Next), `src/routes/+layout.svelte` (SvelteKit), or the framework's root document. |
-  | `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>`/`<span>`. Don't nest interactive elements (e.g. `<button>` inside `<a>`). |
-  | `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element of the layout. Style it with the visually-hidden pattern that becomes visible on `:focus`. |
-  | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="…"` and rename one. If the id is dynamic, ensure the generation key is unique per instance. |
-  | `frame-title`, `iframe-title` | Markup | Add `title="…"` describing the iframe's purpose. |
-
-  **General rules:**
-  - Prefer **pattern fixes** over instance fixes. When `elements` contains many entries that share the same `file`/`component`, change the source component once — don't paste the same fix N times.
-  - For the synthetic `tab-order` rule, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no `helpUrl` from axe — use the linked WCAG focus-order page in `context.helpUrl`.
-  - When `a11y.accessible_name` is empty and `a11y.focusable` is true, the element is unreachable for screen readers — naming is the highest-priority fix.
-
-- **`theme_update`**: One or more design token value changes committed together from the Theme page. A single task now covers every edit the user made in one Commit click — do not expect one task per token. The `context` object contains:
-  - `edits`: array of token edits. Each entry has:
-    - `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
-    - `role`: semantic role name (e.g. `primary`, `background`, `heading`)
-    - `cssVar`: CSS variable name if backed by one (e.g. `--color-primary`), or `null`
-    - `theme_variant`: the theme id this edit targets (e.g. `light`, `dark`)
-    - `theme_selector`: how that variant is activated in the DOM — `{kind:'default'}`, `{kind:'attribute',host,name,value}`, `{kind:'class',host,name}`, or `{kind:'media',media}` — tells you which CSS block owns this variable (`:root`, `:root[data-theme="dark"]`, `.dark`, `@media (prefers-color-scheme: dark)`)
-    - `before`: old value (`null` for new tokens)
-    - `after`: new value
-    - `sourceFile` / `sourceLine`: where the current declaration lives (both `null` for new tokens — you pick the location)
-    - `isNew`: `true` if this token didn't exist before
-  - `styling`: array of project styling methods (e.g. `["tailwind", "scoped-css"]`)
-  - `specFile`: relative path to the design spec (typically `.annotask/design-spec.json`)
-
-  **How to apply:**
-  1. **Group `context.edits` by `sourceFile`.** For each file (skipping `null`/`isNew` for now), open it once, apply every edit against its file in a single Edit-batch, save. Use `theme_selector` + `cssVar` to locate the right declaration block — e.g. an edit with `theme_selector: {kind:'attribute',host:'html',name:'data-theme',value:'dark'}` belongs inside `:root[data-theme="dark"] { … }`, a `{kind:'default'}` edit belongs in the base `:root { … }` block.
-  2. **Tailwind config edits:** if `cssVar` is `null` and `sourceFile` references `tailwind.config.*`, update the corresponding key. If edits span both Tailwind and raw CSS, handle each file independently.
-  3. **New tokens (`isNew: true`):** add the CSS variable to the declaration block matching `theme_selector`. If no block exists for that variant yet, create one (e.g. add `:root[data-theme="dark"] { --new-var: …; }` at the end of the main tokens file). After writing, remember the final file path and line for step 4.
-  4. **Patch `.annotask/design-spec.json` once at the end.** Resolve `context.specFile` against the MFE root (the directory containing `.annotask/`). For each edit:
-     - Existing token: find `spec.<category>` — note dotted categories like `typography.families` map to nested paths — locate the entry by `role`, then set `values[theme_variant] = after`.
-     - New token: append a token object with `role`, `values: { [theme_variant]: after }`, `cssVar`, and fresh `sourceFile` / `sourceLine` pointing at where you added the declaration in step 3.
-     - When writing, keep the existing JSON formatting (same indentation, trailing newline) so the file watcher's next broadcast is clean.
-  5. The server watches `design-spec.json`; saving it fires a `designspec:updated` push and the Theme page refetches automatically.
-
-  **Worked example:** `context.edits = [{ category:'colors', role:'background', cssVar:'--stress-bg', theme_variant:'light', theme_selector:{kind:'default'}, before:'#f4f7fb', after:'#ff00ff', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:12, isNew:false }, { category:'colors', role:'text', cssVar:'--stress-text', theme_variant:'dark', theme_selector:{kind:'attribute',host:'html',name:'data-theme',value:'dark'}, before:'#e7eefb', after:'#ffeb3b', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:65, isNew:false }]` → open `tokens.css` once, update `--stress-bg` in the `:root` block and `--stress-text` in the `:root[data-theme="dark"]` block, save. Then open `.annotask/design-spec.json`, set `colors[?role=='background'].values.light = '#ff00ff'` and `colors[?role=='text'].values.dark = '#ffeb3b'`, save. Mark the task `review` with resolution `"Updated 2 color tokens in tokens.css and design-spec.json"`.
-
-- **`api_update`**: In-repo backend-contract edit. Created from the shell's Data view when the user selects an internal data source (`schema_in_repo === true`) and fills in a desired change. Only valid for in-repo schemas — external APIs cannot be edited from Annotask and should be marked `blocked` with an explanation if a request implies one.
-
-  The `context` object carries:
-  - `data_source_name`: hook/store/query identifier (e.g. `useCatsQuery`)
-  - `data_source_kind`: one of `composable | signal | store | fetch | graphql | loader | rpc`
-  - `schema_location`: path to the schema file (e.g. `openapi.yaml`, `src/trpc/router.ts`)
-  - `schema_kind`: `openapi | graphql | trpc | jsonschema`
-  - `endpoint`: literal endpoint / query key when the source used one
-  - `operation`: `{ method, path }` from the matched schema operation, when a match exists
-  - `desired_change`: user's description of the needed contract change
-  - `rationale`: optional "why"
-
-  **How to apply:**
-  - Open the schema file at `context.schema_location`. Read the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`) and make the change described in `desired_change`.
-  - Update the handler / backend implementation that serves that operation (typical pairs: OpenAPI routes ↔ the framework-specific handler file, tRPC router ↔ its procedure body).
-  - Update the frontend data source at `file:line` if the shape change affects the consumer (e.g. return type, destructured fields).
-  - If the change is additive (new optional field), you usually don't need to change existing callers. If it's breaking (required field, renamed field), search for all usages with `annotask_get_data_source_examples` and update them.
-  - Record what you changed in the resolution note — mention which schema location, which operation, and any frontend call sites touched.
-
-- **`annotation` with cross-boundary API edits**: An annotation task may turn out to require an in-repo API change (e.g. "show expiration date on the tier badge" when the `Cat` schema does not currently return `expires_at`).
-
-  **Rule**: do **not** silently edit the backend. Ask the user first via a `needs_info` question:
-  > This change requires updating the internal API route `GET /api/cats` to add an `expires_at` field on the `Cat` response. Proceed with both frontend and backend edits? (yes / no)
-
-  If the user approves, continue the same task (do **not** spawn a separate `api_update` task). Record each API edit structurally in `task.context.api_edits[]`:
-  ```json
-  {
-    "api_edits": [
-      {
-        "schema_location": "openapi.yaml",
-        "schema_kind": "openapi",
-        "operation": { "method": "GET", "path": "/api/cats" },
-        "change_summary": "Added nullable expires_at: string (ISO date) to the Cat response schema and handler."
-      }
-    ]
-  }
-  ```
-  Annotask's summary lifting will surface `api_edits_count` on the triage view so the user sees this task crossed the frontend/backend line.
-
-  If the user denies, do the frontend-only thing you can, or mark the task `blocked` with an explanation pointing at the missing backend support.
-
-  If the data source is external (`schema_in_repo === false`) and the task requires a contract change, mark the task `blocked` immediately — Annotask cannot edit APIs outside the repo.
-
-#### e. Ask for clarification (only when stuck)
-
-If you are **genuinely stuck** — missing API context, unclear library usage, ambiguous intent that could lead to a wrong implementation — ask the user for clarification instead of guessing:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", questions: [{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}])`
-
-```bash
-npx annotask update-task TASK_ID --mcp --ask='{"message":"Optional markdown context","questions":[{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}]}'
-```
-
-This sets the task to `needs_info` status. The user sees your questions in the Annotask UI and responds there. When answered, the task returns to `in_progress` with answers in `agent_feedback`.
-
-**Question types:**
-- `text` — free-text answer from user
-- `choice` — user picks from your provided `options` array
-
-**Guidelines:**
-- Only ask when you truly cannot proceed — do not ask for confirmation on straightforward tasks
-- Be specific: "Which CSS framework should I use for the grid?" is better than "How should I do this?"
-- Combine related questions into a single ask rather than multiple rounds
-- After asking, move on to the next task. Come back to check answers later via `annotask_get_tasks` MCP tool or `npx annotask tasks --mcp`
-
-#### f. Mark as blocked (when the task can't be done)
-
-If the task is **fundamentally outside your control** — a performance issue in a third-party library, an accessibility bug in a dependency, a config change that requires infrastructure access, etc. — mark it as blocked with an explanation:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", blocked_reason: "This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone.")`
-
-```bash
-npx annotask update-task TASK_ID --mcp --blocked-reason="This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone."
-```
-
-This sets the task to `blocked` status automatically. The user sees your explanation and can either **dismiss** the task or **push back** (deny it with feedback asking you to try a different approach).
-
-**When to use blocked vs needs_info:**
-- `needs_info` = "I can do this, but I need more information from you"
-- `blocked` = "This can't be done through source code changes — here's why"
-
-#### g. Mark for review immediately
-
-As soon as you finish applying **this** task, mark it for review with a brief resolution note:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "review", resolution: "Swapped grid to flexbox, added gap-4 for spacing")`
-
-```bash
-npx annotask update-task TASK_ID --status=review --resolution="Swapped grid to flexbox, added gap-4 for spacing" --mcp
-```
-
-Keep resolutions short — one sentence describing what you changed, not why. The user sees it in the Annotask shell alongside the diff.
-
-#### h. Move to the next task in the group
-
-Repeat steps a–g for each remaining task in the current group, then move to the next group (or confirm parallel subagents have finished). Per-task review flipping is what powers incremental feedback — each task moves to `review` as soon as *its own* edit lands, even inside a batched group, so the user can accept or deny early while later tasks are still in flight.
-
-### 3. Second sweep — catch denies and new tasks that arrived mid-run
-
-Because tasks flip to `review` as soon as their edit lands, the user may have been reviewing (and denying) early tasks while you were still applying later ones. They may also have created brand-new tasks. Before reporting, re-fetch once:
-
-**MCP:** `annotask_get_tasks(status: "denied")` and `annotask_get_tasks(status: "pending")`
-
-```bash
-npx annotask tasks --mcp --status=denied
-npx annotask tasks --mcp --status=pending
-```
-
-If either query returns tasks you did not handle in step 2, loop back to step 2 and process them — re-triage, re-group, apply. Repeat step 3 after each sweep until both queries come back empty.
-
-**If a task keeps returning denied across multiple sweeps**, stop guessing and ask. Use step 2e (`annotask_update_task` with `questions`) to flip it to `needs_info` and let the user clarify what they actually want, rather than burning more sweeps on a misread requirement.
-
-### 4. Report to the user
-
-Tell the user:
-- Which tasks were applied
-- Which files were modified
-- Any tasks that couldn't be applied (and why)
-
-The user will review changes in Annotask and either **accept** (task removed) or **deny with feedback** (task stays denied for next apply).
-
-### Denied tasks
-
-Tasks with `status: "denied"` and a `feedback` field were rejected by the user. They are processed alongside pending tasks in step 2. Read the `feedback` carefully to understand what went wrong and re-apply with corrections.
-
-## Task lifecycle
-
-```
-pending → in_progress (agent working) → review (user checks) → accepted (removed)
-                  ↓                          ↓                → denied (with feedback → agent re-applies)
-             needs_info (waiting)        blocked (can't do)   → dismissed (user deletes)
-                  ↓                          ↓                → pushed back (denied → agent retries)
-             in_progress (resume)        user decides
-```
-
-## Important notes
-
-- Tasks are the source of truth — fetch tasks, not the report
-- The `feedback` field on denied tasks is critical — it tells you what the user didn't like
-- Tasks with `status: "review"` are waiting for user review — don't re-apply them
-- Tasks with `status: "needs_info"` are waiting for the user to answer your questions — skip them and check back later
-- Tasks with `status: "blocked"` have been flagged as not actionable — skip them unless the user pushes back with feedback
-- When a `needs_info` task returns to `in_progress`, check `agent_feedback` for the user's answers before resuming work
-- After applying, the user's page will hot-reload via Vite HMR showing the changes immediately
diff --git a/playgrounds/stress-test/apps/mfe-solid-component-lab/.claude/skills/annotask-init/SKILL.md b/playgrounds/stress-test/apps/mfe-solid-component-lab/.claude/skills/annotask-init/SKILL.md
deleted file mode 100644
index 63df6c7..0000000
--- a/playgrounds/stress-test/apps/mfe-solid-component-lab/.claude/skills/annotask-init/SKILL.md
+++ /dev/null
@@ -1,321 +0,0 @@
-# annotask-init
-
-Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
-
-## When to use
-
-Use this skill when the user says any of:
-- "initialize Annotask" / "init Annotask"
-- "set up Annotask" / "configure Annotask"
-- "scan my project for Annotask"
-- `/annotask-init`
-
-## What it does
-
-Scans the project to detect the framework, design tokens (colors, typography, spacing, borders), icon library, and component library. Writes `.annotask/design-spec.json` which Annotask reads to populate the Theme page with editable design tokens.
-
-## Output schema
-
-Every token carries resolved values for every detected theme variant via a
-`values` map keyed by theme id. Tokens that don't change across variants repeat
-the same value under each id — this keeps every token one uniform shape.
-
-```json
-{
-  "role": "primary",
-  "values": { "light": "#3b82f6", "dark": "#60a5fa" },
-  "cssVar": "--color-primary",
-  "source": "var(--color-primary)",
-  "sourceFile": "src/assets/main.css",
-  "sourceLine": 12
-}
-```
-
-- `role` — semantic name (see vocabularies below)
-- `values` — resolved value per theme variant, keyed by theme id (`light`, `dark`, or a named theme). Single-theme apps use `{ "default": "…" }`.
-- `cssVar` — the CSS custom property name, if backed by one. Omit if not a CSS variable.
-- `source` — human-readable provenance: `var(--x)`, `tailwind.config:colors.primary`, `@theme:--color-primary`
-- `sourceFile` — relative path to the file where the value is defined
-- `sourceLine` — line number in that file (the `:root` variant's definition is fine when multiple exist)
-
-Theme variants themselves are listed at the top of the spec under `themes`,
-with a `selector` describing how each variant is activated in the DOM so the
-Annotask shell can match it against the iframe's current state:
-
-```json
-"themes": [
-  { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-  { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-],
-"defaultTheme": "light"
-```
-
-`selector.kind` is one of `attribute` (with `name`, `value`, optional `host`), `class` (with `name`, optional `host`), `media` (with `media: '(prefers-color-scheme: dark)'`), or `default` (no selector — the base `:root` values). Apps with only one theme should emit a single `{ "id": "default", "name": "Default", "selector": { "kind": "default" } }` variant.
-
-## Steps
-
-### 1. Detect framework
-
-Check `package.json` dependencies:
-- `vue` → name "vue", read version
-- `react` / `react-dom` → name "react"
-- `svelte` → name "svelte"
-- `solid-js` → name "solid"
-
-Check for styling:
-- `tailwindcss` in devDependencies or dependencies → add "tailwind" to styling array
-- Look for `<style scoped>` in `.vue` files → add "scoped-css"
-- Look for CSS module imports (`.module.css`) → add "css-modules"
-
-### 2. Detect theme variants
-
-Before extracting any token values, determine which theme variants the project
-supports so you know which scopes to resolve values under. Check these signals
-in order and stop at the first match:
-
-1. **Tailwind `.dark` class** — If CSS files contain `.dark { … }` / `:root.dark { … }` / `html.dark { … }` blocks, or Tailwind v3 config has `darkMode: 'class'`, or Tailwind v4 CSS contains `@custom-variant dark (&:where(.dark, .dark *))`. Emit two variants:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }`
-
-2. **Data-attribute theming** — If CSS contains `[data-theme="…"]`, `[data-bs-theme="…"]`, `[data-mui-color-scheme="…"]`, `[data-mantine-color-scheme="…"]`, or `[data-color-scheme="…"]` selectors. Emit one variant per distinct attribute value:
-   - `{ "id": "<value>", "name": "<Value>", "scheme": "light|dark (if obvious)", "selector": { "kind": "attribute", "host": "html", "name": "<attr-name>", "value": "<value>" } }`
-
-3. **`@media (prefers-color-scheme: dark)` blocks** — If the project only switches via media queries. Emit:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "media", "media": "(prefers-color-scheme: dark)" } }`
-
-4. **Single theme** — If none of the above are present:
-   - `[ { "id": "default", "name": "Default", "selector": { "kind": "default" } } ]`
-
-Set `defaultTheme` to the variant id used when no selector matches — typically `"light"` or `"default"`.
-
-### 3. Scan colors
-
-**Find color sources:**
-
-1. **CSS variables**: Search for `:root`, `:root.dark`, `html.dark`, `[data-theme="…"]`, and `@media (prefers-color-scheme: dark) :root` declarations across CSS files and Vue `<style>` blocks. Extract `--variable-name: value` pairs, remembering which variant scope each came from.
-
-2. **Tailwind v4** (version >= 4): Search for `@theme` blocks in CSS files. Extract custom properties defined within them. `@theme` blocks without a variant selector apply to every variant.
-
-3. **Tailwind v3** (version < 4): Read `tailwind.config.js`, `tailwind.config.ts`, or `tailwind.config.mjs`. Extract `theme.extend.colors`. Convert to flat key-value pairs.
-
-**Resolve each color under every detected variant.** Produce a `values` map
-keyed by theme id. When a variant doesn't override the token, copy the base
-(`:root`/light/default) value so every token has a value for every variant.
-When a variant-specific block defines a new CSS variable that doesn't appear
-in the base scope, leave the missing variants blank (the server normalizer
-will fill them when the spec is read).
-
-**Classify into semantic roles using this fixed vocabulary:**
-
-| Role | Match heuristics (in variable/key name) |
-|------|----------------------------------------|
-| `primary` | primary, brand |
-| `secondary` | secondary |
-| `accent` | accent |
-| `background` | bg, background |
-| `surface` | surface, card |
-| `text` | text, foreground, fg (but not text-muted) |
-| `text-muted` | text-muted, muted, subtle |
-| `border` | border, divider, separator |
-| `danger` | danger, error, destructive, red |
-| `warning` | warning, amber, yellow (semantic) |
-| `success` | success, green (semantic) |
-| `info` | info, blue (semantic) |
-
-If a variable doesn't match any heuristic, use a descriptive role name derived from the variable name (e.g., `--sidebar-bg` → role `sidebar-bg`).
-
-**Limits**: Maximum 30 color tokens. Prioritize semantic roles first, then most-used custom colors.
-
-### 4. Scan typography
-
-Apply the same per-variant `values` map strategy used for colors: resolve each
-token under every detected variant, copying the base value for variants that
-don't override it.
-
-**Font families**: Search for:
-- CSS variables containing `font`, `family` in `:root` or `@theme`
-- `fontFamily` in Tailwind config
-- Direct `font-family` declarations on `body`, `html`, `h1`-`h6` elements
-
-Classify as:
-- `heading` — used on h1-h6 or named heading/display
-- `body` — used on body/html or named sans/body/base
-- `mono` — monospace, code, named mono
-
-**Font scale**: Search for:
-- CSS variables containing `font-size`, `text-` size names
-- `fontSize` in Tailwind config
-- `@theme` size definitions
-
-Use roles: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or by ascending size order).
-
-**Weights**: Scan component files for `font-weight` values and Tailwind weight classes (`font-bold`, `font-semibold`, etc.). List unique weights as strings: `["400", "500", "600", "700"]`.
-
-### 5. Scan spacing
-
-Search for:
-- CSS variables containing `space`, `gap`, `margin`, `padding`, `size`
-- `spacing` in Tailwind config
-- `@theme` spacing definitions
-
-Use roles: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or ascending size).
-
-**Limits**: Maximum 12 spacing tokens.
-
-### 6. Scan border radius
-
-Search for:
-- CSS variables containing `radius`, `rounded`
-- `borderRadius` in Tailwind config
-- `@theme` radius definitions
-
-Use roles: `sm`, `md`, `lg`, `xl`, `full` (match by name or ascending size).
-
-### 7. Scan breakpoints
-
-Detect responsive breakpoints from whatever styling system the project uses. Output as a flat object mapping name → min-width value.
-
-**Sources (check in order):**
-
-1. **Tailwind v4** (>= 4): Look in CSS files for `@theme` blocks defining `--breakpoint-*` custom properties, or `@custom-media` rules.
-
-2. **Tailwind v3** (< 4): Read `tailwind.config.{js,ts,mjs}`. Extract `theme.screens` or `theme.extend.screens`. Default Tailwind screens: `{ "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" }` — use these as fallback if Tailwind is detected but no custom screens are defined.
-
-3. **Bootstrap**: Check for `bootstrap` in package.json. Default Bootstrap breakpoints: `{ "sm": "576px", "md": "768px", "lg": "992px", "xl": "1200px", "xxl": "1400px" }`.
-
-4. **CSS custom properties**: Search `:root` for variables containing `breakpoint`, `screen`, `bp` in the name (e.g., `--bp-mobile: 480px`).
-
-5. **CSS `@media` patterns**: Scan `.css`, `.scss`, `.vue` files for `@media` queries with `min-width` or `max-width`. Extract the 3–6 most common breakpoint values and assign roles by ascending size: `sm`, `md`, `lg`, `xl`, `2xl`.
-
-**Output example:**
-```json
-"breakpoints": {
-  "sm": "640px",
-  "md": "768px",
-  "lg": "1024px",
-  "xl": "1280px",
-  "2xl": "1536px"
-}
-```
-
-If no breakpoints are detected, omit the `breakpoints` field (don't include an empty object).
-
-### 8. Detect icon library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `lucide-vue-next` or `lucide-react` | lucide |
-| `@heroicons/vue` or `@heroicons/react` | heroicons |
-| `@fortawesome/vue-fontawesome` or `@fortawesome/react-fontawesome` | fontawesome |
-| `@phosphor-icons/vue` or `@phosphor-icons/react` | phosphor |
-| `@tabler/icons-vue` or `@tabler/icons-react` | tabler |
-
-Read the version from package.json.
-
-### 9. Detect component library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `primevue` | PrimeVue |
-| `vuetify` | Vuetify |
-| `element-plus` | Element Plus |
-| `@headlessui/vue` | Headless UI |
-| `radix-vue` | Radix Vue |
-| `naive-ui` | Naive UI |
-| `@shadcn/ui` or `shadcn-vue` | shadcn/ui |
-
-If found, scan `src/` for import statements to find used components:
-```bash
-grep -rh "from '${package}" --include='*.vue' --include='*.ts' --include='*.js' src/ | sort -u
-```
-
-Extract component names from the imports. Read the version from package.json.
-
-### 10. Write design spec
-
-Create `.annotask/design-spec.json`:
-
-```json
-{
-  "version": "1.0",
-  "framework": {
-    "name": "vue",
-    "version": "3.5.0",
-    "styling": ["tailwind", "scoped-css"]
-  },
-  "themes": [
-    { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-    { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-  ],
-  "defaultTheme": "light",
-  "colors": [
-    { "role": "primary",    "values": { "light": "#3b82f6", "dark": "#60a5fa" }, "cssVar": "--color-primary", "source": "var(--color-primary)", "sourceFile": "src/assets/main.css", "sourceLine": 5 },
-    { "role": "background", "values": { "light": "#ffffff", "dark": "#0b1120" }, "cssVar": "--bg",            "source": "var(--bg)",            "sourceFile": "src/assets/main.css", "sourceLine": 3 }
-  ],
-  "typography": {
-    "families": [
-      { "role": "body", "values": { "light": "Inter, sans-serif", "dark": "Inter, sans-serif" }, "cssVar": "--font-sans", "source": "var(--font-sans)", "sourceFile": "src/assets/main.css", "sourceLine": 10 }
-    ],
-    "scale": [
-      { "role": "base", "values": { "light": "1rem", "dark": "1rem" }, "cssVar": "--text-base", "source": "var(--text-base)", "sourceFile": "src/assets/main.css", "sourceLine": 15 }
-    ],
-    "weights": ["400", "500", "600", "700"]
-  },
-  "spacing": [
-    { "role": "sm", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--space-sm", "source": "var(--space-sm)", "sourceFile": "src/assets/main.css", "sourceLine": 20 }
-  ],
-  "borders": {
-    "radius": [
-      { "role": "md", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--radius-md", "source": "var(--radius-md)", "sourceFile": "src/assets/main.css", "sourceLine": 25 }
-    ]
-  },
-  "breakpoints": {
-    "sm": "640px",
-    "md": "768px",
-    "lg": "1024px",
-    "xl": "1280px",
-    "2xl": "1536px"
-  },
-  "icons": {
-    "library": "lucide",
-    "version": "0.300.0"
-  },
-  "components": {
-    "library": "PrimeVue",
-    "version": "4.5.4",
-    "used": ["DataTable", "Column", "InputText", "Tag", "Button"]
-  }
-}
-```
-
-### 11. Clean up old config
-
-If `.annotask/config.json` exists, delete it — it's been replaced by `design-spec.json`.
-
-### 12. Update .gitignore
-
-Check if `.gitignore` contains `.annotask/`. If not, append:
-```
-# Annotask (generated)
-.annotask/
-```
-
-### 13. Report to user
-
-Tell the user:
-- What was detected (framework, number of color/typography/spacing tokens, libraries)
-- That they can open the **Theme** page in Annotask to view and edit tokens
-- That they can re-run `/annotask-init` to rescan
-
-## Notes
-
-- This skill is idempotent — re-running overwrites the design spec with fresh data
-- The design spec is gitignored because it's generated and may vary per developer
-- If detection fails for any section, use empty defaults (empty array, null) rather than omitting the field
-- All top-level fields are required — use empty values for missing data
-- When a token has a CSS variable backing, always populate the `cssVar` field — this enables live preview in the Theme page
diff --git a/playgrounds/stress-test/apps/mfe-solid-component-lab/.mcp.json b/playgrounds/stress-test/apps/mfe-solid-component-lab/.mcp.json
deleted file mode 100644
index 5527f21..0000000
--- a/playgrounds/stress-test/apps/mfe-solid-component-lab/.mcp.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "annotask": {
-      "command": "npx",
-      "args": [
-        "annotask",
-        "mcp"
-      ]
-    }
-  }
-}
diff --git a/playgrounds/stress-test/apps/mfe-svelte-streaming/.claude/skills/annotask-apply/SKILL.md b/playgrounds/stress-test/apps/mfe-svelte-streaming/.claude/skills/annotask-apply/SKILL.md
deleted file mode 100644
index 49921a2..0000000
--- a/playgrounds/stress-test/apps/mfe-svelte-streaming/.claude/skills/annotask-apply/SKILL.md
+++ /dev/null
@@ -1,460 +0,0 @@
-# annotask-apply
-
-Apply pending Annotask design tasks to the source code.
-
-## When to use
-
-Use this skill when the user says:
-- "apply the Annotask changes"
-- "apply my design changes"
-- "sync Annotask"
-- `/annotask-apply`
-
-## How it works
-
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
-
-## MCP preference
-
-If you have `annotask_*` MCP tools available, prefer them over CLI commands — they return structured data directly, are faster, and avoid shell/npx issues. If MCP tools are not available, use the CLI commands shown below.
-
-**Always pass `--mcp` to CLI commands.** The flag emits compact JSON that matches the MCP tool response shapes exactly (no ANSI colors, no human prefixes, `visual` stripped, `agent_feedback` trimmed). That way the same parsing logic works whether you're calling the MCP tool or the CLI fallback.
-
-## Steps
-
-### 0. Check server status
-
-**MCP:** If you have MCP tools, the server is already running — skip this step.
-
-```bash
-npx annotask status --mcp
-```
-
-If this fails, the Annotask dev server isn't running. Ask the user to start it.
-
-### 1. Fetch pending tasks
-
-**MCP:** `annotask_get_tasks(status: "pending")` — returns compact summaries. Use `detail: true` for full objects.
-
-```bash
-npx annotask tasks --mcp --status=pending
-```
-
-Response (compact task summaries):
-```json
-{"version":"1.0","count":1,"tasks":[{"id":"task-123","type":"annotation","status":"pending","description":"Change the header background to match the new brand colors","file":"src/components/Header.vue","line":5,"action":"text_edit","screenshot":"screenshot-1711800000-ab3kf.png"}]}
-```
-
-Each task summary has: `id`, `type`, `status`, `description`, `file`, `line`, and optionally `component`, `action`, `screenshot`, `feedback` (on denied tasks), `blocked_reason`, `resolution`.
-
-For full task details (context, viewport, interaction_history, agent_feedback), use `annotask_get_task` MCP tool or `npx annotask task <id> --mcp` for a single task (`npx annotask tasks --mcp --detail` for the full list). Only fetch full details when the summary doesn't provide enough context to apply the change.
-
-### Screenshot reference
-
-Some tasks include a `screenshot` field. The screenshot shows exactly what the user sees in the browser. To view it:
-
-**MCP:** `annotask_get_screenshot(task_id: "TASK_ID")` — returns base64-encoded PNG directly.
-
-```bash
-npx annotask screenshot TASK_ID
-```
-
-This downloads the PNG to `.annotask/screenshots/`. Use it as visual context alongside the task description and source code. (The screenshot command writes the file on disk — `--mcp` doesn't apply.)
-
-### 2. Triage, group, then apply
-
-Filter actionable tasks: `status: "pending"`, `status: "denied"` (with `feedback`), and `status: "in_progress"` tasks whose `agent_feedback` now contains answers to earlier questions. Skip `needs_info` (waiting for user) and `blocked` (marked not actionable).
-
-Before locking anything, **triage** — read all actionable task summaries and group them by touched resources:
-
-- **By file**: tasks whose `file` is the same go in one group (Edits batched on one Read).
-- **By shared state**: any task that writes `.annotask/design-spec.json`, `:root` CSS variables, `tailwind.config.*`, or a global stylesheet goes in the *shared-state* group regardless of which source file triggered it.
-- **By dependency**: if a `theme_update` adds or changes a token that a `style_update` in the same batch consumes, the `theme_update` goes in an earlier phase. If a `section_request` introduces the UI that an `a11y_fix` targets, the `section_request` goes first.
-
-Within each group: process serially, reading the file once and batching Edits. Across groups that are fully disjoint (no shared file, no shared state, no dependency edge), you may launch parallel subagents — one per group — to apply them concurrently. If in doubt, run serially.
-
-#### Parallelism rules
-
-- **Same file → same group, serial.** Never have two tasks editing the same file concurrently.
-- **Shared global state → one group, serial.** `.annotask/design-spec.json`, `:root` blocks in shared CSS, `tailwind.config.*`, shared layout files, i18n catalogs, route tables, barrel exports.
-- **Dependency order**: `theme_update` before any `style_update` that references the new/changed token; structural task (`section_request`, `annotation` with `wrap_container`/`add_row`/`add_column`) before an `a11y_fix` or `style_update` on the same new UI.
-- **Stale locators**: after edits land, the `file`/`line` on remaining tasks may drift. When in doubt, call `annotask_get_code_context(task_id)` before editing — it returns the current symbol, a ±15 line excerpt, and an `excerpt_hash` you can compare across retries. Otherwise, search by surrounding text/element context over trusting `line` from the original triage.
-- **Non-idempotent inserts**: `add_row`, `add_column`, `section_request`, and free-text "add this" notes can duplicate on retry. Before inserting, confirm the target isn't already present.
-- **If using parallel subagents**: each subagent receives only its group's task IDs plus project context. After all subagents finish, run a quick typecheck/build sanity pass before returning control to the user. If any subagent failed, surface it clearly — do not silently accept partial success.
-
-For each task in a group, follow this cycle:
-
-#### a. Lock the task
-
-Mark it `in_progress` so the user sees you're working on it:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "in_progress")`
-
-```bash
-npx annotask update-task TASK_ID --status=in_progress --mcp
-```
-
-#### b. Reference the design spec for consistency
-
-Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
-
-**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
-
-```bash
-npx annotask design-spec --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
-```
-
-For detailed tokens in a specific category:
-
-```bash
-npx annotask design-spec --category=colors --mcp
-```
-
-**When to use:**
-- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
-- **Typography changes** — Reference the font scale and families from the spec
-- **Responsive design** — Use detected breakpoints when adding media queries
-- **New components** — Match the design system when creating new UI
-
-**How to apply:**
-- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
-- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
-- For responsive design, use the detected breakpoints
-- Document the token reference in your resolution note (e.g., "Applied primary color token")
-
-#### c. Find relevant components (required when adding any UI element)
-
-If the task asks you to add, insert, or create a UI element of any kind — a table, button, card, modal, input, dropdown, form, list, nav, etc. — you **must** search the component library first before writing HTML from scratch. This applies to all task types: `section_request`, `annotation` with actions like `add_column`/`add_row`/`wrap_container`, and free-text `annotation` notes whose `description` implies new UI.
-
-**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
-
-```bash
-npx annotask components "button" --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
-```
-
-For a specific component, get its full prop signature:
-
-```bash
-npx annotask component Button --mcp
-```
-
-For **in-repo usage examples** (real prop combinations + import path this project actually uses), call `annotask_get_component_examples(name: "Button")` — or `npx annotask component-examples Button --mcp`. Prefer the example's import path and prop shape over reinventing: the examples show how *this* codebase uses the component, not just what the library exposes.
-
-#### c-ter. Find the data source (required for any task that adds or modifies data-driven UI)
-
-Before writing UI that renders data, check what's already wired. If the task's summary contains `data_context_summary` (e.g. `"hook:useUserQuery"` or `"store:useCounterStore"`), that's the primary data source powering the selected element. For the full picture:
-
-**MCP:** `annotask_get_data_context(task_id: "TASK_ID")` — returns the complete `DataContext`: every data reference in the enclosing file (`sources`, sorted with the primary source at index 0 — closest to `task.line`, tie-broken by kind precedence), `rendered_identifiers` from the template/JSX (CSV), and `route_bindings` (CSV).
-
-```bash
-npx annotask data-context TASK_ID --mcp
-```
-
-To browse the project's catalog of hooks, stores, and fetch wrappers (sorted by `used_count` — most load-bearing first):
-
-**MCP:** `annotask_get_data_sources(used_only: true)` — filter to entries actually used elsewhere in the codebase.
-
-```bash
-npx annotask data-sources --used-only --mcp
-```
-
-To see **real in-repo usages** of a specific data source (destructuring patterns, parameter shape, common wrappers — parallel to `annotask_get_component_examples`):
-
-**MCP:** `annotask_get_data_source_examples(name: "useUserQuery", kind: "composable")`
-
-```bash
-npx annotask data-source-examples useUserQuery --kind=composable --mcp
-```
-
-To see **what shape comes back** from an API — cross-reference declared schemas (OpenAPI, GraphQL, tRPC) so you don't guess field names:
-
-**MCP:** `annotask_resolve_endpoint(url: "/api/cats")` → returns the best-match operation with a confidence score.
-
-```bash
-npx annotask resolve-endpoint /api/cats --mcp
-```
-
-**MCP:** `annotask_get_api_operation(path: "/api/cats", method: "GET")` — full request / response schema for a known path pattern.
-
-```bash
-npx annotask api-operation /api/cats --method=GET --mcp
-```
-
-**MCP:** `annotask_get_api_schemas(detail: true)` — browse every discovered schema source up front.
-
-```bash
-npx annotask api-schemas --detail --mcp
-```
-
-If a task summary shows `response_schema_ref: "Cat[]"`, the agent already knows a declared shape exists — `annotask_get_api_operation` or `annotask_resolve_endpoint` will surface the full JSON schema.
-
-**When to use:**
-- Any task where the user's description mentions adding, replacing, or rewiring data — "show the current user", "list orders", "filter by status", "fetch from the API".
-- Denied tasks where feedback mentions wrong or fake data.
-- Section requests that need to render real information.
-
-**How to apply:**
-- Prefer reusing a hook/store from `data_context.sources` or `data-sources` catalog over writing new fetch code.
-- Copy the import path and call-site shape from `data-source-examples`, not from library docs.
-- If `sources[0]` doesn't match the user's description (e.g. task says "user name" but `sources[0]` is `useOrdersQuery`), check the rest of the `sources` list — the right hook is usually there.
-
-**When to use:**
-- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
-- **UI additions** — Check if a table, button, card, modal, input, form, list, or nav component already exists before writing custom HTML
-- **Styling consistency** — Using library components ensures your changes match the design system
-
-**How to apply:**
-- Search for components matching the intent (e.g., "table" if adding tabular data, "dropdown" if adding a select menu)
-- Read the props to understand customization options (variant, size, disabled, etc.)
-- Call `annotask_get_component_examples` to see how the component is already used in this codebase; copy the import path and prop patterns from there
-- Use the component in your JSX/Vue/Svelte code with appropriate props
-- Document the component reference in your resolution note
-
-#### c-bis. Re-anchor older or retried tasks
-
-For **denied** tasks, tasks that have been sitting in the queue while you edited other files, or any task whose `file`/`line` you suspect has drifted: call `annotask_get_code_context(task_id)` before editing.
-
-```bash
-npx annotask code-context TASK_ID --mcp
-```
-
-Response:
-```json
-{"file":"src/components/Header.vue","line":42,"symbol":"Header","excerpt_start_line":27,"excerpt_end_line":57,"excerpt":"...","imports":["import ..."],"excerpt_hash":"ab12cd34ef56..."}
-```
-
-Use `symbol` + `excerpt` to locate the edit target; the `excerpt_hash` is a cheap drift check on subsequent retries (if the hash changes between attempts, the surrounding code moved). Skip this step for fresh pending tasks where `file`/`line` are known good.
-
-#### d. Apply the change
-
-Read the task type and apply accordingly:
-
-- **`annotation` with `action: "text_edit"`**: The `description` field says what text to change. Find the text in the source file and apply the edit.
-
-- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run step c first.
-
-- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run step c (component library search) before writing HTML.**
-
-- **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
-
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
-
-- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID, or the synthetic `tab-order` rule from Annotask's tab-order overlay), `impact`, `help`, `helpUrl`, and `elements` array with `html`, `selector`, `fix`, source `file`/`line`/`component`, and a per-element `a11y` block with computed accessibility metadata:
-
-  ```
-  elements[i].a11y = {
-    accessible_name, name_source,   // "Sign in", source: aria-label | labelledby | label | alt | text | placeholder | none
-    role, role_source,              // "button", source: explicit | implicit | none
-    tabindex, focusable,            // null | number, true/false
-    focus_indicator,                // "visible" | "none" | "unknown"
-    contrast,                       // { foreground, background, ratio, aa_normal, aa_large, ... } only when element has text
-    aria_attrs,                     // [{ name: "aria-expanded", value: "false" }, ...]
-  }
-  ```
-
-  If `screenshot_meta` is present (the user manually attached one with the snip tool), retrieve it via `annotask_get_screenshot` before proposing visual changes (color-contrast, focus rings).
-
-  **Per-rule playbook.** Most rules fall into one of these patterns — match by `context.rule`:
-
-  | Rule(s) | Fix layer | What to do |
-  |---|---|---|
-  | `color-contrast`, `color-contrast-enhanced` | Design tokens first | Read `elements[i].a11y.contrast` for the actual fg/bg hex + ratio. If the colors come from theme tokens (check `cssVar` lookups in the source), adjust the token. If the contrast comes from a one-off inline style or hardcoded class, fix the component, not the token (you'd regress every other consumer). |
-  | `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` referencing visible text. `a11y.accessible_name` shows what (if anything) the input currently exposes — when `name_source === 'placeholder'`, the input has no real label. |
-  | `button-name`, `link-name`, `input-button-name` | Markup | Add visible text content or `aria-label`. For icon-only buttons add a visually hidden `<span class="sr-only">` (or your project's equivalent). Don't add `title` — it's not reliable for SR users. |
-  | `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | `alt=""` for decorative imagery, descriptive `alt` for informational. For `<img>` that conveys text, use the text. For SVG icons that pair with visible text, use `aria-hidden="true"`. |
-  | `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These almost always live in a layout component (e.g. `App.vue`, `_layout.tsx`, `RootLayout`), not in leaf components. |
-  | `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert/promote `<h1>`; renumber subsequent levels so the outline is contiguous. Usually a layout/section component change, not a leaf change. |
-  | `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what's set. Reference the WAI-ARIA roles spec (`helpUrl`) for the role's allowed attributes. Remove disallowed attrs; add required ones. |
-  | `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Either remove `aria-hidden`, or move the focusable elements outside (or set `tabindex="-1"` and ensure they're never the focus target). |
-  | `tabindex`, **synthetic** `tab-order` | Markup | Remove positive `tabindex`; use 0 (focusable in DOM order) or -1 (programmatically focusable, not in tab order). For the synthetic `tab-order` rule, `context.tab_order.flag` is one of `positive` / `unreachable` / `reorder` — fix the source markup so DOM order matches visual order. |
-  | `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Single source of truth — usually `index.html` (Vite/CRA), `app/layout.tsx` (Next), `src/routes/+layout.svelte` (SvelteKit), or the framework's root document. |
-  | `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>`/`<span>`. Don't nest interactive elements (e.g. `<button>` inside `<a>`). |
-  | `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element of the layout. Style it with the visually-hidden pattern that becomes visible on `:focus`. |
-  | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="…"` and rename one. If the id is dynamic, ensure the generation key is unique per instance. |
-  | `frame-title`, `iframe-title` | Markup | Add `title="…"` describing the iframe's purpose. |
-
-  **General rules:**
-  - Prefer **pattern fixes** over instance fixes. When `elements` contains many entries that share the same `file`/`component`, change the source component once — don't paste the same fix N times.
-  - For the synthetic `tab-order` rule, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no `helpUrl` from axe — use the linked WCAG focus-order page in `context.helpUrl`.
-  - When `a11y.accessible_name` is empty and `a11y.focusable` is true, the element is unreachable for screen readers — naming is the highest-priority fix.
-
-- **`theme_update`**: One or more design token value changes committed together from the Theme page. A single task now covers every edit the user made in one Commit click — do not expect one task per token. The `context` object contains:
-  - `edits`: array of token edits. Each entry has:
-    - `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
-    - `role`: semantic role name (e.g. `primary`, `background`, `heading`)
-    - `cssVar`: CSS variable name if backed by one (e.g. `--color-primary`), or `null`
-    - `theme_variant`: the theme id this edit targets (e.g. `light`, `dark`)
-    - `theme_selector`: how that variant is activated in the DOM — `{kind:'default'}`, `{kind:'attribute',host,name,value}`, `{kind:'class',host,name}`, or `{kind:'media',media}` — tells you which CSS block owns this variable (`:root`, `:root[data-theme="dark"]`, `.dark`, `@media (prefers-color-scheme: dark)`)
-    - `before`: old value (`null` for new tokens)
-    - `after`: new value
-    - `sourceFile` / `sourceLine`: where the current declaration lives (both `null` for new tokens — you pick the location)
-    - `isNew`: `true` if this token didn't exist before
-  - `styling`: array of project styling methods (e.g. `["tailwind", "scoped-css"]`)
-  - `specFile`: relative path to the design spec (typically `.annotask/design-spec.json`)
-
-  **How to apply:**
-  1. **Group `context.edits` by `sourceFile`.** For each file (skipping `null`/`isNew` for now), open it once, apply every edit against its file in a single Edit-batch, save. Use `theme_selector` + `cssVar` to locate the right declaration block — e.g. an edit with `theme_selector: {kind:'attribute',host:'html',name:'data-theme',value:'dark'}` belongs inside `:root[data-theme="dark"] { … }`, a `{kind:'default'}` edit belongs in the base `:root { … }` block.
-  2. **Tailwind config edits:** if `cssVar` is `null` and `sourceFile` references `tailwind.config.*`, update the corresponding key. If edits span both Tailwind and raw CSS, handle each file independently.
-  3. **New tokens (`isNew: true`):** add the CSS variable to the declaration block matching `theme_selector`. If no block exists for that variant yet, create one (e.g. add `:root[data-theme="dark"] { --new-var: …; }` at the end of the main tokens file). After writing, remember the final file path and line for step 4.
-  4. **Patch `.annotask/design-spec.json` once at the end.** Resolve `context.specFile` against the MFE root (the directory containing `.annotask/`). For each edit:
-     - Existing token: find `spec.<category>` — note dotted categories like `typography.families` map to nested paths — locate the entry by `role`, then set `values[theme_variant] = after`.
-     - New token: append a token object with `role`, `values: { [theme_variant]: after }`, `cssVar`, and fresh `sourceFile` / `sourceLine` pointing at where you added the declaration in step 3.
-     - When writing, keep the existing JSON formatting (same indentation, trailing newline) so the file watcher's next broadcast is clean.
-  5. The server watches `design-spec.json`; saving it fires a `designspec:updated` push and the Theme page refetches automatically.
-
-  **Worked example:** `context.edits = [{ category:'colors', role:'background', cssVar:'--stress-bg', theme_variant:'light', theme_selector:{kind:'default'}, before:'#f4f7fb', after:'#ff00ff', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:12, isNew:false }, { category:'colors', role:'text', cssVar:'--stress-text', theme_variant:'dark', theme_selector:{kind:'attribute',host:'html',name:'data-theme',value:'dark'}, before:'#e7eefb', after:'#ffeb3b', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:65, isNew:false }]` → open `tokens.css` once, update `--stress-bg` in the `:root` block and `--stress-text` in the `:root[data-theme="dark"]` block, save. Then open `.annotask/design-spec.json`, set `colors[?role=='background'].values.light = '#ff00ff'` and `colors[?role=='text'].values.dark = '#ffeb3b'`, save. Mark the task `review` with resolution `"Updated 2 color tokens in tokens.css and design-spec.json"`.
-
-- **`api_update`**: In-repo backend-contract edit. Created from the shell's Data view when the user selects an internal data source (`schema_in_repo === true`) and fills in a desired change. Only valid for in-repo schemas — external APIs cannot be edited from Annotask and should be marked `blocked` with an explanation if a request implies one.
-
-  The `context` object carries:
-  - `data_source_name`: hook/store/query identifier (e.g. `useCatsQuery`)
-  - `data_source_kind`: one of `composable | signal | store | fetch | graphql | loader | rpc`
-  - `schema_location`: path to the schema file (e.g. `openapi.yaml`, `src/trpc/router.ts`)
-  - `schema_kind`: `openapi | graphql | trpc | jsonschema`
-  - `endpoint`: literal endpoint / query key when the source used one
-  - `operation`: `{ method, path }` from the matched schema operation, when a match exists
-  - `desired_change`: user's description of the needed contract change
-  - `rationale`: optional "why"
-
-  **How to apply:**
-  - Open the schema file at `context.schema_location`. Read the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`) and make the change described in `desired_change`.
-  - Update the handler / backend implementation that serves that operation (typical pairs: OpenAPI routes ↔ the framework-specific handler file, tRPC router ↔ its procedure body).
-  - Update the frontend data source at `file:line` if the shape change affects the consumer (e.g. return type, destructured fields).
-  - If the change is additive (new optional field), you usually don't need to change existing callers. If it's breaking (required field, renamed field), search for all usages with `annotask_get_data_source_examples` and update them.
-  - Record what you changed in the resolution note — mention which schema location, which operation, and any frontend call sites touched.
-
-- **`annotation` with cross-boundary API edits**: An annotation task may turn out to require an in-repo API change (e.g. "show expiration date on the tier badge" when the `Cat` schema does not currently return `expires_at`).
-
-  **Rule**: do **not** silently edit the backend. Ask the user first via a `needs_info` question:
-  > This change requires updating the internal API route `GET /api/cats` to add an `expires_at` field on the `Cat` response. Proceed with both frontend and backend edits? (yes / no)
-
-  If the user approves, continue the same task (do **not** spawn a separate `api_update` task). Record each API edit structurally in `task.context.api_edits[]`:
-  ```json
-  {
-    "api_edits": [
-      {
-        "schema_location": "openapi.yaml",
-        "schema_kind": "openapi",
-        "operation": { "method": "GET", "path": "/api/cats" },
-        "change_summary": "Added nullable expires_at: string (ISO date) to the Cat response schema and handler."
-      }
-    ]
-  }
-  ```
-  Annotask's summary lifting will surface `api_edits_count` on the triage view so the user sees this task crossed the frontend/backend line.
-
-  If the user denies, do the frontend-only thing you can, or mark the task `blocked` with an explanation pointing at the missing backend support.
-
-  If the data source is external (`schema_in_repo === false`) and the task requires a contract change, mark the task `blocked` immediately — Annotask cannot edit APIs outside the repo.
-
-#### e. Ask for clarification (only when stuck)
-
-If you are **genuinely stuck** — missing API context, unclear library usage, ambiguous intent that could lead to a wrong implementation — ask the user for clarification instead of guessing:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", questions: [{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}])`
-
-```bash
-npx annotask update-task TASK_ID --mcp --ask='{"message":"Optional markdown context","questions":[{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}]}'
-```
-
-This sets the task to `needs_info` status. The user sees your questions in the Annotask UI and responds there. When answered, the task returns to `in_progress` with answers in `agent_feedback`.
-
-**Question types:**
-- `text` — free-text answer from user
-- `choice` — user picks from your provided `options` array
-
-**Guidelines:**
-- Only ask when you truly cannot proceed — do not ask for confirmation on straightforward tasks
-- Be specific: "Which CSS framework should I use for the grid?" is better than "How should I do this?"
-- Combine related questions into a single ask rather than multiple rounds
-- After asking, move on to the next task. Come back to check answers later via `annotask_get_tasks` MCP tool or `npx annotask tasks --mcp`
-
-#### f. Mark as blocked (when the task can't be done)
-
-If the task is **fundamentally outside your control** — a performance issue in a third-party library, an accessibility bug in a dependency, a config change that requires infrastructure access, etc. — mark it as blocked with an explanation:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", blocked_reason: "This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone.")`
-
-```bash
-npx annotask update-task TASK_ID --mcp --blocked-reason="This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone."
-```
-
-This sets the task to `blocked` status automatically. The user sees your explanation and can either **dismiss** the task or **push back** (deny it with feedback asking you to try a different approach).
-
-**When to use blocked vs needs_info:**
-- `needs_info` = "I can do this, but I need more information from you"
-- `blocked` = "This can't be done through source code changes — here's why"
-
-#### g. Mark for review immediately
-
-As soon as you finish applying **this** task, mark it for review with a brief resolution note:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "review", resolution: "Swapped grid to flexbox, added gap-4 for spacing")`
-
-```bash
-npx annotask update-task TASK_ID --status=review --resolution="Swapped grid to flexbox, added gap-4 for spacing" --mcp
-```
-
-Keep resolutions short — one sentence describing what you changed, not why. The user sees it in the Annotask shell alongside the diff.
-
-#### h. Move to the next task in the group
-
-Repeat steps a–g for each remaining task in the current group, then move to the next group (or confirm parallel subagents have finished). Per-task review flipping is what powers incremental feedback — each task moves to `review` as soon as *its own* edit lands, even inside a batched group, so the user can accept or deny early while later tasks are still in flight.
-
-### 3. Second sweep — catch denies and new tasks that arrived mid-run
-
-Because tasks flip to `review` as soon as their edit lands, the user may have been reviewing (and denying) early tasks while you were still applying later ones. They may also have created brand-new tasks. Before reporting, re-fetch once:
-
-**MCP:** `annotask_get_tasks(status: "denied")` and `annotask_get_tasks(status: "pending")`
-
-```bash
-npx annotask tasks --mcp --status=denied
-npx annotask tasks --mcp --status=pending
-```
-
-If either query returns tasks you did not handle in step 2, loop back to step 2 and process them — re-triage, re-group, apply. Repeat step 3 after each sweep until both queries come back empty.
-
-**If a task keeps returning denied across multiple sweeps**, stop guessing and ask. Use step 2e (`annotask_update_task` with `questions`) to flip it to `needs_info` and let the user clarify what they actually want, rather than burning more sweeps on a misread requirement.
-
-### 4. Report to the user
-
-Tell the user:
-- Which tasks were applied
-- Which files were modified
-- Any tasks that couldn't be applied (and why)
-
-The user will review changes in Annotask and either **accept** (task removed) or **deny with feedback** (task stays denied for next apply).
-
-### Denied tasks
-
-Tasks with `status: "denied"` and a `feedback` field were rejected by the user. They are processed alongside pending tasks in step 2. Read the `feedback` carefully to understand what went wrong and re-apply with corrections.
-
-## Task lifecycle
-
-```
-pending → in_progress (agent working) → review (user checks) → accepted (removed)
-                  ↓                          ↓                → denied (with feedback → agent re-applies)
-             needs_info (waiting)        blocked (can't do)   → dismissed (user deletes)
-                  ↓                          ↓                → pushed back (denied → agent retries)
-             in_progress (resume)        user decides
-```
-
-## Important notes
-
-- Tasks are the source of truth — fetch tasks, not the report
-- The `feedback` field on denied tasks is critical — it tells you what the user didn't like
-- Tasks with `status: "review"` are waiting for user review — don't re-apply them
-- Tasks with `status: "needs_info"` are waiting for the user to answer your questions — skip them and check back later
-- Tasks with `status: "blocked"` have been flagged as not actionable — skip them unless the user pushes back with feedback
-- When a `needs_info` task returns to `in_progress`, check `agent_feedback` for the user's answers before resuming work
-- After applying, the user's page will hot-reload via Vite HMR showing the changes immediately
diff --git a/playgrounds/stress-test/apps/mfe-svelte-streaming/.claude/skills/annotask-init/SKILL.md b/playgrounds/stress-test/apps/mfe-svelte-streaming/.claude/skills/annotask-init/SKILL.md
deleted file mode 100644
index 63df6c7..0000000
--- a/playgrounds/stress-test/apps/mfe-svelte-streaming/.claude/skills/annotask-init/SKILL.md
+++ /dev/null
@@ -1,321 +0,0 @@
-# annotask-init
-
-Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
-
-## When to use
-
-Use this skill when the user says any of:
-- "initialize Annotask" / "init Annotask"
-- "set up Annotask" / "configure Annotask"
-- "scan my project for Annotask"
-- `/annotask-init`
-
-## What it does
-
-Scans the project to detect the framework, design tokens (colors, typography, spacing, borders), icon library, and component library. Writes `.annotask/design-spec.json` which Annotask reads to populate the Theme page with editable design tokens.
-
-## Output schema
-
-Every token carries resolved values for every detected theme variant via a
-`values` map keyed by theme id. Tokens that don't change across variants repeat
-the same value under each id — this keeps every token one uniform shape.
-
-```json
-{
-  "role": "primary",
-  "values": { "light": "#3b82f6", "dark": "#60a5fa" },
-  "cssVar": "--color-primary",
-  "source": "var(--color-primary)",
-  "sourceFile": "src/assets/main.css",
-  "sourceLine": 12
-}
-```
-
-- `role` — semantic name (see vocabularies below)
-- `values` — resolved value per theme variant, keyed by theme id (`light`, `dark`, or a named theme). Single-theme apps use `{ "default": "…" }`.
-- `cssVar` — the CSS custom property name, if backed by one. Omit if not a CSS variable.
-- `source` — human-readable provenance: `var(--x)`, `tailwind.config:colors.primary`, `@theme:--color-primary`
-- `sourceFile` — relative path to the file where the value is defined
-- `sourceLine` — line number in that file (the `:root` variant's definition is fine when multiple exist)
-
-Theme variants themselves are listed at the top of the spec under `themes`,
-with a `selector` describing how each variant is activated in the DOM so the
-Annotask shell can match it against the iframe's current state:
-
-```json
-"themes": [
-  { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-  { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-],
-"defaultTheme": "light"
-```
-
-`selector.kind` is one of `attribute` (with `name`, `value`, optional `host`), `class` (with `name`, optional `host`), `media` (with `media: '(prefers-color-scheme: dark)'`), or `default` (no selector — the base `:root` values). Apps with only one theme should emit a single `{ "id": "default", "name": "Default", "selector": { "kind": "default" } }` variant.
-
-## Steps
-
-### 1. Detect framework
-
-Check `package.json` dependencies:
-- `vue` → name "vue", read version
-- `react` / `react-dom` → name "react"
-- `svelte` → name "svelte"
-- `solid-js` → name "solid"
-
-Check for styling:
-- `tailwindcss` in devDependencies or dependencies → add "tailwind" to styling array
-- Look for `<style scoped>` in `.vue` files → add "scoped-css"
-- Look for CSS module imports (`.module.css`) → add "css-modules"
-
-### 2. Detect theme variants
-
-Before extracting any token values, determine which theme variants the project
-supports so you know which scopes to resolve values under. Check these signals
-in order and stop at the first match:
-
-1. **Tailwind `.dark` class** — If CSS files contain `.dark { … }` / `:root.dark { … }` / `html.dark { … }` blocks, or Tailwind v3 config has `darkMode: 'class'`, or Tailwind v4 CSS contains `@custom-variant dark (&:where(.dark, .dark *))`. Emit two variants:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }`
-
-2. **Data-attribute theming** — If CSS contains `[data-theme="…"]`, `[data-bs-theme="…"]`, `[data-mui-color-scheme="…"]`, `[data-mantine-color-scheme="…"]`, or `[data-color-scheme="…"]` selectors. Emit one variant per distinct attribute value:
-   - `{ "id": "<value>", "name": "<Value>", "scheme": "light|dark (if obvious)", "selector": { "kind": "attribute", "host": "html", "name": "<attr-name>", "value": "<value>" } }`
-
-3. **`@media (prefers-color-scheme: dark)` blocks** — If the project only switches via media queries. Emit:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "media", "media": "(prefers-color-scheme: dark)" } }`
-
-4. **Single theme** — If none of the above are present:
-   - `[ { "id": "default", "name": "Default", "selector": { "kind": "default" } } ]`
-
-Set `defaultTheme` to the variant id used when no selector matches — typically `"light"` or `"default"`.
-
-### 3. Scan colors
-
-**Find color sources:**
-
-1. **CSS variables**: Search for `:root`, `:root.dark`, `html.dark`, `[data-theme="…"]`, and `@media (prefers-color-scheme: dark) :root` declarations across CSS files and Vue `<style>` blocks. Extract `--variable-name: value` pairs, remembering which variant scope each came from.
-
-2. **Tailwind v4** (version >= 4): Search for `@theme` blocks in CSS files. Extract custom properties defined within them. `@theme` blocks without a variant selector apply to every variant.
-
-3. **Tailwind v3** (version < 4): Read `tailwind.config.js`, `tailwind.config.ts`, or `tailwind.config.mjs`. Extract `theme.extend.colors`. Convert to flat key-value pairs.
-
-**Resolve each color under every detected variant.** Produce a `values` map
-keyed by theme id. When a variant doesn't override the token, copy the base
-(`:root`/light/default) value so every token has a value for every variant.
-When a variant-specific block defines a new CSS variable that doesn't appear
-in the base scope, leave the missing variants blank (the server normalizer
-will fill them when the spec is read).
-
-**Classify into semantic roles using this fixed vocabulary:**
-
-| Role | Match heuristics (in variable/key name) |
-|------|----------------------------------------|
-| `primary` | primary, brand |
-| `secondary` | secondary |
-| `accent` | accent |
-| `background` | bg, background |
-| `surface` | surface, card |
-| `text` | text, foreground, fg (but not text-muted) |
-| `text-muted` | text-muted, muted, subtle |
-| `border` | border, divider, separator |
-| `danger` | danger, error, destructive, red |
-| `warning` | warning, amber, yellow (semantic) |
-| `success` | success, green (semantic) |
-| `info` | info, blue (semantic) |
-
-If a variable doesn't match any heuristic, use a descriptive role name derived from the variable name (e.g., `--sidebar-bg` → role `sidebar-bg`).
-
-**Limits**: Maximum 30 color tokens. Prioritize semantic roles first, then most-used custom colors.
-
-### 4. Scan typography
-
-Apply the same per-variant `values` map strategy used for colors: resolve each
-token under every detected variant, copying the base value for variants that
-don't override it.
-
-**Font families**: Search for:
-- CSS variables containing `font`, `family` in `:root` or `@theme`
-- `fontFamily` in Tailwind config
-- Direct `font-family` declarations on `body`, `html`, `h1`-`h6` elements
-
-Classify as:
-- `heading` — used on h1-h6 or named heading/display
-- `body` — used on body/html or named sans/body/base
-- `mono` — monospace, code, named mono
-
-**Font scale**: Search for:
-- CSS variables containing `font-size`, `text-` size names
-- `fontSize` in Tailwind config
-- `@theme` size definitions
-
-Use roles: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or by ascending size order).
-
-**Weights**: Scan component files for `font-weight` values and Tailwind weight classes (`font-bold`, `font-semibold`, etc.). List unique weights as strings: `["400", "500", "600", "700"]`.
-
-### 5. Scan spacing
-
-Search for:
-- CSS variables containing `space`, `gap`, `margin`, `padding`, `size`
-- `spacing` in Tailwind config
-- `@theme` spacing definitions
-
-Use roles: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or ascending size).
-
-**Limits**: Maximum 12 spacing tokens.
-
-### 6. Scan border radius
-
-Search for:
-- CSS variables containing `radius`, `rounded`
-- `borderRadius` in Tailwind config
-- `@theme` radius definitions
-
-Use roles: `sm`, `md`, `lg`, `xl`, `full` (match by name or ascending size).
-
-### 7. Scan breakpoints
-
-Detect responsive breakpoints from whatever styling system the project uses. Output as a flat object mapping name → min-width value.
-
-**Sources (check in order):**
-
-1. **Tailwind v4** (>= 4): Look in CSS files for `@theme` blocks defining `--breakpoint-*` custom properties, or `@custom-media` rules.
-
-2. **Tailwind v3** (< 4): Read `tailwind.config.{js,ts,mjs}`. Extract `theme.screens` or `theme.extend.screens`. Default Tailwind screens: `{ "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" }` — use these as fallback if Tailwind is detected but no custom screens are defined.
-
-3. **Bootstrap**: Check for `bootstrap` in package.json. Default Bootstrap breakpoints: `{ "sm": "576px", "md": "768px", "lg": "992px", "xl": "1200px", "xxl": "1400px" }`.
-
-4. **CSS custom properties**: Search `:root` for variables containing `breakpoint`, `screen`, `bp` in the name (e.g., `--bp-mobile: 480px`).
-
-5. **CSS `@media` patterns**: Scan `.css`, `.scss`, `.vue` files for `@media` queries with `min-width` or `max-width`. Extract the 3–6 most common breakpoint values and assign roles by ascending size: `sm`, `md`, `lg`, `xl`, `2xl`.
-
-**Output example:**
-```json
-"breakpoints": {
-  "sm": "640px",
-  "md": "768px",
-  "lg": "1024px",
-  "xl": "1280px",
-  "2xl": "1536px"
-}
-```
-
-If no breakpoints are detected, omit the `breakpoints` field (don't include an empty object).
-
-### 8. Detect icon library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `lucide-vue-next` or `lucide-react` | lucide |
-| `@heroicons/vue` or `@heroicons/react` | heroicons |
-| `@fortawesome/vue-fontawesome` or `@fortawesome/react-fontawesome` | fontawesome |
-| `@phosphor-icons/vue` or `@phosphor-icons/react` | phosphor |
-| `@tabler/icons-vue` or `@tabler/icons-react` | tabler |
-
-Read the version from package.json.
-
-### 9. Detect component library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `primevue` | PrimeVue |
-| `vuetify` | Vuetify |
-| `element-plus` | Element Plus |
-| `@headlessui/vue` | Headless UI |
-| `radix-vue` | Radix Vue |
-| `naive-ui` | Naive UI |
-| `@shadcn/ui` or `shadcn-vue` | shadcn/ui |
-
-If found, scan `src/` for import statements to find used components:
-```bash
-grep -rh "from '${package}" --include='*.vue' --include='*.ts' --include='*.js' src/ | sort -u
-```
-
-Extract component names from the imports. Read the version from package.json.
-
-### 10. Write design spec
-
-Create `.annotask/design-spec.json`:
-
-```json
-{
-  "version": "1.0",
-  "framework": {
-    "name": "vue",
-    "version": "3.5.0",
-    "styling": ["tailwind", "scoped-css"]
-  },
-  "themes": [
-    { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-    { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-  ],
-  "defaultTheme": "light",
-  "colors": [
-    { "role": "primary",    "values": { "light": "#3b82f6", "dark": "#60a5fa" }, "cssVar": "--color-primary", "source": "var(--color-primary)", "sourceFile": "src/assets/main.css", "sourceLine": 5 },
-    { "role": "background", "values": { "light": "#ffffff", "dark": "#0b1120" }, "cssVar": "--bg",            "source": "var(--bg)",            "sourceFile": "src/assets/main.css", "sourceLine": 3 }
-  ],
-  "typography": {
-    "families": [
-      { "role": "body", "values": { "light": "Inter, sans-serif", "dark": "Inter, sans-serif" }, "cssVar": "--font-sans", "source": "var(--font-sans)", "sourceFile": "src/assets/main.css", "sourceLine": 10 }
-    ],
-    "scale": [
-      { "role": "base", "values": { "light": "1rem", "dark": "1rem" }, "cssVar": "--text-base", "source": "var(--text-base)", "sourceFile": "src/assets/main.css", "sourceLine": 15 }
-    ],
-    "weights": ["400", "500", "600", "700"]
-  },
-  "spacing": [
-    { "role": "sm", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--space-sm", "source": "var(--space-sm)", "sourceFile": "src/assets/main.css", "sourceLine": 20 }
-  ],
-  "borders": {
-    "radius": [
-      { "role": "md", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--radius-md", "source": "var(--radius-md)", "sourceFile": "src/assets/main.css", "sourceLine": 25 }
-    ]
-  },
-  "breakpoints": {
-    "sm": "640px",
-    "md": "768px",
-    "lg": "1024px",
-    "xl": "1280px",
-    "2xl": "1536px"
-  },
-  "icons": {
-    "library": "lucide",
-    "version": "0.300.0"
-  },
-  "components": {
-    "library": "PrimeVue",
-    "version": "4.5.4",
-    "used": ["DataTable", "Column", "InputText", "Tag", "Button"]
-  }
-}
-```
-
-### 11. Clean up old config
-
-If `.annotask/config.json` exists, delete it — it's been replaced by `design-spec.json`.
-
-### 12. Update .gitignore
-
-Check if `.gitignore` contains `.annotask/`. If not, append:
-```
-# Annotask (generated)
-.annotask/
-```
-
-### 13. Report to user
-
-Tell the user:
-- What was detected (framework, number of color/typography/spacing tokens, libraries)
-- That they can open the **Theme** page in Annotask to view and edit tokens
-- That they can re-run `/annotask-init` to rescan
-
-## Notes
-
-- This skill is idempotent — re-running overwrites the design spec with fresh data
-- The design spec is gitignored because it's generated and may vary per developer
-- If detection fails for any section, use empty defaults (empty array, null) rather than omitting the field
-- All top-level fields are required — use empty values for missing data
-- When a token has a CSS variable backing, always populate the `cssVar` field — this enables live preview in the Theme page
diff --git a/playgrounds/stress-test/apps/mfe-svelte-streaming/.mcp.json b/playgrounds/stress-test/apps/mfe-svelte-streaming/.mcp.json
deleted file mode 100644
index 5527f21..0000000
--- a/playgrounds/stress-test/apps/mfe-svelte-streaming/.mcp.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "annotask": {
-      "command": "npx",
-      "args": [
-        "annotask",
-        "mcp"
-      ]
-    }
-  }
-}
diff --git a/playgrounds/stress-test/apps/mfe-vue-data-lab/.claude/skills/annotask-apply/SKILL.md b/playgrounds/stress-test/apps/mfe-vue-data-lab/.claude/skills/annotask-apply/SKILL.md
deleted file mode 100644
index 49921a2..0000000
--- a/playgrounds/stress-test/apps/mfe-vue-data-lab/.claude/skills/annotask-apply/SKILL.md
+++ /dev/null
@@ -1,460 +0,0 @@
-# annotask-apply
-
-Apply pending Annotask design tasks to the source code.
-
-## When to use
-
-Use this skill when the user says:
-- "apply the Annotask changes"
-- "apply my design changes"
-- "sync Annotask"
-- `/annotask-apply`
-
-## How it works
-
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
-
-## MCP preference
-
-If you have `annotask_*` MCP tools available, prefer them over CLI commands — they return structured data directly, are faster, and avoid shell/npx issues. If MCP tools are not available, use the CLI commands shown below.
-
-**Always pass `--mcp` to CLI commands.** The flag emits compact JSON that matches the MCP tool response shapes exactly (no ANSI colors, no human prefixes, `visual` stripped, `agent_feedback` trimmed). That way the same parsing logic works whether you're calling the MCP tool or the CLI fallback.
-
-## Steps
-
-### 0. Check server status
-
-**MCP:** If you have MCP tools, the server is already running — skip this step.
-
-```bash
-npx annotask status --mcp
-```
-
-If this fails, the Annotask dev server isn't running. Ask the user to start it.
-
-### 1. Fetch pending tasks
-
-**MCP:** `annotask_get_tasks(status: "pending")` — returns compact summaries. Use `detail: true` for full objects.
-
-```bash
-npx annotask tasks --mcp --status=pending
-```
-
-Response (compact task summaries):
-```json
-{"version":"1.0","count":1,"tasks":[{"id":"task-123","type":"annotation","status":"pending","description":"Change the header background to match the new brand colors","file":"src/components/Header.vue","line":5,"action":"text_edit","screenshot":"screenshot-1711800000-ab3kf.png"}]}
-```
-
-Each task summary has: `id`, `type`, `status`, `description`, `file`, `line`, and optionally `component`, `action`, `screenshot`, `feedback` (on denied tasks), `blocked_reason`, `resolution`.
-
-For full task details (context, viewport, interaction_history, agent_feedback), use `annotask_get_task` MCP tool or `npx annotask task <id> --mcp` for a single task (`npx annotask tasks --mcp --detail` for the full list). Only fetch full details when the summary doesn't provide enough context to apply the change.
-
-### Screenshot reference
-
-Some tasks include a `screenshot` field. The screenshot shows exactly what the user sees in the browser. To view it:
-
-**MCP:** `annotask_get_screenshot(task_id: "TASK_ID")` — returns base64-encoded PNG directly.
-
-```bash
-npx annotask screenshot TASK_ID
-```
-
-This downloads the PNG to `.annotask/screenshots/`. Use it as visual context alongside the task description and source code. (The screenshot command writes the file on disk — `--mcp` doesn't apply.)
-
-### 2. Triage, group, then apply
-
-Filter actionable tasks: `status: "pending"`, `status: "denied"` (with `feedback`), and `status: "in_progress"` tasks whose `agent_feedback` now contains answers to earlier questions. Skip `needs_info` (waiting for user) and `blocked` (marked not actionable).
-
-Before locking anything, **triage** — read all actionable task summaries and group them by touched resources:
-
-- **By file**: tasks whose `file` is the same go in one group (Edits batched on one Read).
-- **By shared state**: any task that writes `.annotask/design-spec.json`, `:root` CSS variables, `tailwind.config.*`, or a global stylesheet goes in the *shared-state* group regardless of which source file triggered it.
-- **By dependency**: if a `theme_update` adds or changes a token that a `style_update` in the same batch consumes, the `theme_update` goes in an earlier phase. If a `section_request` introduces the UI that an `a11y_fix` targets, the `section_request` goes first.
-
-Within each group: process serially, reading the file once and batching Edits. Across groups that are fully disjoint (no shared file, no shared state, no dependency edge), you may launch parallel subagents — one per group — to apply them concurrently. If in doubt, run serially.
-
-#### Parallelism rules
-
-- **Same file → same group, serial.** Never have two tasks editing the same file concurrently.
-- **Shared global state → one group, serial.** `.annotask/design-spec.json`, `:root` blocks in shared CSS, `tailwind.config.*`, shared layout files, i18n catalogs, route tables, barrel exports.
-- **Dependency order**: `theme_update` before any `style_update` that references the new/changed token; structural task (`section_request`, `annotation` with `wrap_container`/`add_row`/`add_column`) before an `a11y_fix` or `style_update` on the same new UI.
-- **Stale locators**: after edits land, the `file`/`line` on remaining tasks may drift. When in doubt, call `annotask_get_code_context(task_id)` before editing — it returns the current symbol, a ±15 line excerpt, and an `excerpt_hash` you can compare across retries. Otherwise, search by surrounding text/element context over trusting `line` from the original triage.
-- **Non-idempotent inserts**: `add_row`, `add_column`, `section_request`, and free-text "add this" notes can duplicate on retry. Before inserting, confirm the target isn't already present.
-- **If using parallel subagents**: each subagent receives only its group's task IDs plus project context. After all subagents finish, run a quick typecheck/build sanity pass before returning control to the user. If any subagent failed, surface it clearly — do not silently accept partial success.
-
-For each task in a group, follow this cycle:
-
-#### a. Lock the task
-
-Mark it `in_progress` so the user sees you're working on it:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "in_progress")`
-
-```bash
-npx annotask update-task TASK_ID --status=in_progress --mcp
-```
-
-#### b. Reference the design spec for consistency
-
-Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
-
-**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
-
-```bash
-npx annotask design-spec --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
-```
-
-For detailed tokens in a specific category:
-
-```bash
-npx annotask design-spec --category=colors --mcp
-```
-
-**When to use:**
-- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
-- **Typography changes** — Reference the font scale and families from the spec
-- **Responsive design** — Use detected breakpoints when adding media queries
-- **New components** — Match the design system when creating new UI
-
-**How to apply:**
-- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
-- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
-- For responsive design, use the detected breakpoints
-- Document the token reference in your resolution note (e.g., "Applied primary color token")
-
-#### c. Find relevant components (required when adding any UI element)
-
-If the task asks you to add, insert, or create a UI element of any kind — a table, button, card, modal, input, dropdown, form, list, nav, etc. — you **must** search the component library first before writing HTML from scratch. This applies to all task types: `section_request`, `annotation` with actions like `add_column`/`add_row`/`wrap_container`, and free-text `annotation` notes whose `description` implies new UI.
-
-**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
-
-```bash
-npx annotask components "button" --mcp
-```
-
-Response example:
-```json
-{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
-```
-
-For a specific component, get its full prop signature:
-
-```bash
-npx annotask component Button --mcp
-```
-
-For **in-repo usage examples** (real prop combinations + import path this project actually uses), call `annotask_get_component_examples(name: "Button")` — or `npx annotask component-examples Button --mcp`. Prefer the example's import path and prop shape over reinventing: the examples show how *this* codebase uses the component, not just what the library exposes.
-
-#### c-ter. Find the data source (required for any task that adds or modifies data-driven UI)
-
-Before writing UI that renders data, check what's already wired. If the task's summary contains `data_context_summary` (e.g. `"hook:useUserQuery"` or `"store:useCounterStore"`), that's the primary data source powering the selected element. For the full picture:
-
-**MCP:** `annotask_get_data_context(task_id: "TASK_ID")` — returns the complete `DataContext`: every data reference in the enclosing file (`sources`, sorted with the primary source at index 0 — closest to `task.line`, tie-broken by kind precedence), `rendered_identifiers` from the template/JSX (CSV), and `route_bindings` (CSV).
-
-```bash
-npx annotask data-context TASK_ID --mcp
-```
-
-To browse the project's catalog of hooks, stores, and fetch wrappers (sorted by `used_count` — most load-bearing first):
-
-**MCP:** `annotask_get_data_sources(used_only: true)` — filter to entries actually used elsewhere in the codebase.
-
-```bash
-npx annotask data-sources --used-only --mcp
-```
-
-To see **real in-repo usages** of a specific data source (destructuring patterns, parameter shape, common wrappers — parallel to `annotask_get_component_examples`):
-
-**MCP:** `annotask_get_data_source_examples(name: "useUserQuery", kind: "composable")`
-
-```bash
-npx annotask data-source-examples useUserQuery --kind=composable --mcp
-```
-
-To see **what shape comes back** from an API — cross-reference declared schemas (OpenAPI, GraphQL, tRPC) so you don't guess field names:
-
-**MCP:** `annotask_resolve_endpoint(url: "/api/cats")` → returns the best-match operation with a confidence score.
-
-```bash
-npx annotask resolve-endpoint /api/cats --mcp
-```
-
-**MCP:** `annotask_get_api_operation(path: "/api/cats", method: "GET")` — full request / response schema for a known path pattern.
-
-```bash
-npx annotask api-operation /api/cats --method=GET --mcp
-```
-
-**MCP:** `annotask_get_api_schemas(detail: true)` — browse every discovered schema source up front.
-
-```bash
-npx annotask api-schemas --detail --mcp
-```
-
-If a task summary shows `response_schema_ref: "Cat[]"`, the agent already knows a declared shape exists — `annotask_get_api_operation` or `annotask_resolve_endpoint` will surface the full JSON schema.
-
-**When to use:**
-- Any task where the user's description mentions adding, replacing, or rewiring data — "show the current user", "list orders", "filter by status", "fetch from the API".
-- Denied tasks where feedback mentions wrong or fake data.
-- Section requests that need to render real information.
-
-**How to apply:**
-- Prefer reusing a hook/store from `data_context.sources` or `data-sources` catalog over writing new fetch code.
-- Copy the import path and call-site shape from `data-source-examples`, not from library docs.
-- If `sources[0]` doesn't match the user's description (e.g. task says "user name" but `sources[0]` is `useOrdersQuery`), check the rest of the `sources` list — the right hook is usually there.
-
-**When to use:**
-- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
-- **UI additions** — Check if a table, button, card, modal, input, form, list, or nav component already exists before writing custom HTML
-- **Styling consistency** — Using library components ensures your changes match the design system
-
-**How to apply:**
-- Search for components matching the intent (e.g., "table" if adding tabular data, "dropdown" if adding a select menu)
-- Read the props to understand customization options (variant, size, disabled, etc.)
-- Call `annotask_get_component_examples` to see how the component is already used in this codebase; copy the import path and prop patterns from there
-- Use the component in your JSX/Vue/Svelte code with appropriate props
-- Document the component reference in your resolution note
-
-#### c-bis. Re-anchor older or retried tasks
-
-For **denied** tasks, tasks that have been sitting in the queue while you edited other files, or any task whose `file`/`line` you suspect has drifted: call `annotask_get_code_context(task_id)` before editing.
-
-```bash
-npx annotask code-context TASK_ID --mcp
-```
-
-Response:
-```json
-{"file":"src/components/Header.vue","line":42,"symbol":"Header","excerpt_start_line":27,"excerpt_end_line":57,"excerpt":"...","imports":["import ..."],"excerpt_hash":"ab12cd34ef56..."}
-```
-
-Use `symbol` + `excerpt` to locate the edit target; the `excerpt_hash` is a cheap drift check on subsequent retries (if the hash changes between attempts, the surrounding code moved). Skip this step for fresh pending tasks where `file`/`line` are known good.
-
-#### d. Apply the change
-
-Read the task type and apply accordingly:
-
-- **`annotation` with `action: "text_edit"`**: The `description` field says what text to change. Find the text in the source file and apply the edit.
-
-- **`annotation` with other actions** (`add_column`, `add_row`, `wrap_container`, `delete`, `duplicate`, `move_up`, `move_down`): Apply the structural change described in `description`. If the action adds new UI (e.g. `add_row` into a table that doesn't exist yet, or `wrap_container` that introduces a new component), run step c first.
-
-- **`annotation` with no action**: This is a free-text note. Read `description` and apply your best judgment to the source code. If `context.to_element` is present, this is an arrow annotation referencing two elements. **If the description asks you to add, insert, or create any UI element (e.g. "add a table", "put a form here", "insert a card"), you must run step c (component library search) before writing HTML.**
-
-- **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
-
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
-
-- **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID, or the synthetic `tab-order` rule from Annotask's tab-order overlay), `impact`, `help`, `helpUrl`, and `elements` array with `html`, `selector`, `fix`, source `file`/`line`/`component`, and a per-element `a11y` block with computed accessibility metadata:
-
-  ```
-  elements[i].a11y = {
-    accessible_name, name_source,   // "Sign in", source: aria-label | labelledby | label | alt | text | placeholder | none
-    role, role_source,              // "button", source: explicit | implicit | none
-    tabindex, focusable,            // null | number, true/false
-    focus_indicator,                // "visible" | "none" | "unknown"
-    contrast,                       // { foreground, background, ratio, aa_normal, aa_large, ... } only when element has text
-    aria_attrs,                     // [{ name: "aria-expanded", value: "false" }, ...]
-  }
-  ```
-
-  If `screenshot_meta` is present (the user manually attached one with the snip tool), retrieve it via `annotask_get_screenshot` before proposing visual changes (color-contrast, focus rings).
-
-  **Per-rule playbook.** Most rules fall into one of these patterns — match by `context.rule`:
-
-  | Rule(s) | Fix layer | What to do |
-  |---|---|---|
-  | `color-contrast`, `color-contrast-enhanced` | Design tokens first | Read `elements[i].a11y.contrast` for the actual fg/bg hex + ratio. If the colors come from theme tokens (check `cssVar` lookups in the source), adjust the token. If the contrast comes from a one-off inline style or hardcoded class, fix the component, not the token (you'd regress every other consumer). |
-  | `label`, `form-field-multiple-labels` | Markup | Wrap input in `<label>` or add `aria-labelledby` referencing visible text. `a11y.accessible_name` shows what (if anything) the input currently exposes — when `name_source === 'placeholder'`, the input has no real label. |
-  | `button-name`, `link-name`, `input-button-name` | Markup | Add visible text content or `aria-label`. For icon-only buttons add a visually hidden `<span class="sr-only">` (or your project's equivalent). Don't add `title` — it's not reliable for SR users. |
-  | `image-alt`, `role-img-alt`, `svg-img-alt` | Markup | `alt=""` for decorative imagery, descriptive `alt` for informational. For `<img>` that conveys text, use the text. For SVG icons that pair with visible text, use `aria-hidden="true"`. |
-  | `landmark-one-main`, `region`, `landmark-no-duplicate-banner`, `landmark-no-duplicate-contentinfo` | Layout component | Wrap the page's primary content in `<main>`. Add `role="region"` + `aria-label` to top-level layout containers. These almost always live in a layout component (e.g. `App.vue`, `_layout.tsx`, `RootLayout`), not in leaf components. |
-  | `heading-order`, `page-has-heading-one`, `empty-heading` | Content/layout | Insert/promote `<h1>`; renumber subsequent levels so the outline is contiguous. Usually a layout/section component change, not a leaf change. |
-  | `aria-allowed-attr`, `aria-required-attr`, `aria-valid-attr-value`, `aria-roles`, `aria-required-children`, `aria-required-parent` | Markup | Read `elements[i].a11y.role` and `aria_attrs` to see exactly what's set. Reference the WAI-ARIA roles spec (`helpUrl`) for the role's allowed attributes. Remove disallowed attrs; add required ones. |
-  | `aria-hidden-focus`, `aria-hidden-body` | Markup | An element with `aria-hidden="true"` cannot contain focusable descendants. Either remove `aria-hidden`, or move the focusable elements outside (or set `tabindex="-1"` and ensure they're never the focus target). |
-  | `tabindex`, **synthetic** `tab-order` | Markup | Remove positive `tabindex`; use 0 (focusable in DOM order) or -1 (programmatically focusable, not in tab order). For the synthetic `tab-order` rule, `context.tab_order.flag` is one of `positive` / `unreachable` / `reorder` — fix the source markup so DOM order matches visual order. |
-  | `meta-viewport`, `html-has-lang`, `html-lang-valid`, `document-title`, `meta-refresh` | Document head | Single source of truth — usually `index.html` (Vite/CRA), `app/layout.tsx` (Next), `src/routes/+layout.svelte` (SvelteKit), or the framework's root document. |
-  | `focus-order-semantics`, `nested-interactive` | Markup | Use semantic interactive elements (`<button>`, `<a href>`, `<input>`) instead of clickable `<div>`/`<span>`. Don't nest interactive elements (e.g. `<button>` inside `<a>`). |
-  | `bypass`, `skip-link` | Layout component | Add a "Skip to main content" link as the first focusable element of the layout. Style it with the visually-hidden pattern that becomes visible on `:focus`. |
-  | `duplicate-id`, `duplicate-id-active`, `duplicate-id-aria` | Markup | Search the codebase for hardcoded `id="…"` and rename one. If the id is dynamic, ensure the generation key is unique per instance. |
-  | `frame-title`, `iframe-title` | Markup | Add `title="…"` describing the iframe's purpose. |
-
-  **General rules:**
-  - Prefer **pattern fixes** over instance fixes. When `elements` contains many entries that share the same `file`/`component`, change the source component once — don't paste the same fix N times.
-  - For the synthetic `tab-order` rule, the offending element is in `elements[0].a11y.eid` and the failure type is in `context.tab_order.flag`. There is no `helpUrl` from axe — use the linked WCAG focus-order page in `context.helpUrl`.
-  - When `a11y.accessible_name` is empty and `a11y.focusable` is true, the element is unreachable for screen readers — naming is the highest-priority fix.
-
-- **`theme_update`**: One or more design token value changes committed together from the Theme page. A single task now covers every edit the user made in one Commit click — do not expect one task per token. The `context` object contains:
-  - `edits`: array of token edits. Each entry has:
-    - `category`: `colors` | `typography.families` | `typography.scale` | `spacing` | `borders.radius`
-    - `role`: semantic role name (e.g. `primary`, `background`, `heading`)
-    - `cssVar`: CSS variable name if backed by one (e.g. `--color-primary`), or `null`
-    - `theme_variant`: the theme id this edit targets (e.g. `light`, `dark`)
-    - `theme_selector`: how that variant is activated in the DOM — `{kind:'default'}`, `{kind:'attribute',host,name,value}`, `{kind:'class',host,name}`, or `{kind:'media',media}` — tells you which CSS block owns this variable (`:root`, `:root[data-theme="dark"]`, `.dark`, `@media (prefers-color-scheme: dark)`)
-    - `before`: old value (`null` for new tokens)
-    - `after`: new value
-    - `sourceFile` / `sourceLine`: where the current declaration lives (both `null` for new tokens — you pick the location)
-    - `isNew`: `true` if this token didn't exist before
-  - `styling`: array of project styling methods (e.g. `["tailwind", "scoped-css"]`)
-  - `specFile`: relative path to the design spec (typically `.annotask/design-spec.json`)
-
-  **How to apply:**
-  1. **Group `context.edits` by `sourceFile`.** For each file (skipping `null`/`isNew` for now), open it once, apply every edit against its file in a single Edit-batch, save. Use `theme_selector` + `cssVar` to locate the right declaration block — e.g. an edit with `theme_selector: {kind:'attribute',host:'html',name:'data-theme',value:'dark'}` belongs inside `:root[data-theme="dark"] { … }`, a `{kind:'default'}` edit belongs in the base `:root { … }` block.
-  2. **Tailwind config edits:** if `cssVar` is `null` and `sourceFile` references `tailwind.config.*`, update the corresponding key. If edits span both Tailwind and raw CSS, handle each file independently.
-  3. **New tokens (`isNew: true`):** add the CSS variable to the declaration block matching `theme_selector`. If no block exists for that variant yet, create one (e.g. add `:root[data-theme="dark"] { --new-var: …; }` at the end of the main tokens file). After writing, remember the final file path and line for step 4.
-  4. **Patch `.annotask/design-spec.json` once at the end.** Resolve `context.specFile` against the MFE root (the directory containing `.annotask/`). For each edit:
-     - Existing token: find `spec.<category>` — note dotted categories like `typography.families` map to nested paths — locate the entry by `role`, then set `values[theme_variant] = after`.
-     - New token: append a token object with `role`, `values: { [theme_variant]: after }`, `cssVar`, and fresh `sourceFile` / `sourceLine` pointing at where you added the declaration in step 3.
-     - When writing, keep the existing JSON formatting (same indentation, trailing newline) so the file watcher's next broadcast is clean.
-  5. The server watches `design-spec.json`; saving it fires a `designspec:updated` push and the Theme page refetches automatically.
-
-  **Worked example:** `context.edits = [{ category:'colors', role:'background', cssVar:'--stress-bg', theme_variant:'light', theme_selector:{kind:'default'}, before:'#f4f7fb', after:'#ff00ff', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:12, isNew:false }, { category:'colors', role:'text', cssVar:'--stress-text', theme_variant:'dark', theme_selector:{kind:'attribute',host:'html',name:'data-theme',value:'dark'}, before:'#e7eefb', after:'#ffeb3b', sourceFile:'../../packages/shared-ui-tokens/tokens.css', sourceLine:65, isNew:false }]` → open `tokens.css` once, update `--stress-bg` in the `:root` block and `--stress-text` in the `:root[data-theme="dark"]` block, save. Then open `.annotask/design-spec.json`, set `colors[?role=='background'].values.light = '#ff00ff'` and `colors[?role=='text'].values.dark = '#ffeb3b'`, save. Mark the task `review` with resolution `"Updated 2 color tokens in tokens.css and design-spec.json"`.
-
-- **`api_update`**: In-repo backend-contract edit. Created from the shell's Data view when the user selects an internal data source (`schema_in_repo === true`) and fills in a desired change. Only valid for in-repo schemas — external APIs cannot be edited from Annotask and should be marked `blocked` with an explanation if a request implies one.
-
-  The `context` object carries:
-  - `data_source_name`: hook/store/query identifier (e.g. `useCatsQuery`)
-  - `data_source_kind`: one of `composable | signal | store | fetch | graphql | loader | rpc`
-  - `schema_location`: path to the schema file (e.g. `openapi.yaml`, `src/trpc/router.ts`)
-  - `schema_kind`: `openapi | graphql | trpc | jsonschema`
-  - `endpoint`: literal endpoint / query key when the source used one
-  - `operation`: `{ method, path }` from the matched schema operation, when a match exists
-  - `desired_change`: user's description of the needed contract change
-  - `rationale`: optional "why"
-
-  **How to apply:**
-  - Open the schema file at `context.schema_location`. Read the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`) and make the change described in `desired_change`.
-  - Update the handler / backend implementation that serves that operation (typical pairs: OpenAPI routes ↔ the framework-specific handler file, tRPC router ↔ its procedure body).
-  - Update the frontend data source at `file:line` if the shape change affects the consumer (e.g. return type, destructured fields).
-  - If the change is additive (new optional field), you usually don't need to change existing callers. If it's breaking (required field, renamed field), search for all usages with `annotask_get_data_source_examples` and update them.
-  - Record what you changed in the resolution note — mention which schema location, which operation, and any frontend call sites touched.
-
-- **`annotation` with cross-boundary API edits**: An annotation task may turn out to require an in-repo API change (e.g. "show expiration date on the tier badge" when the `Cat` schema does not currently return `expires_at`).
-
-  **Rule**: do **not** silently edit the backend. Ask the user first via a `needs_info` question:
-  > This change requires updating the internal API route `GET /api/cats` to add an `expires_at` field on the `Cat` response. Proceed with both frontend and backend edits? (yes / no)
-
-  If the user approves, continue the same task (do **not** spawn a separate `api_update` task). Record each API edit structurally in `task.context.api_edits[]`:
-  ```json
-  {
-    "api_edits": [
-      {
-        "schema_location": "openapi.yaml",
-        "schema_kind": "openapi",
-        "operation": { "method": "GET", "path": "/api/cats" },
-        "change_summary": "Added nullable expires_at: string (ISO date) to the Cat response schema and handler."
-      }
-    ]
-  }
-  ```
-  Annotask's summary lifting will surface `api_edits_count` on the triage view so the user sees this task crossed the frontend/backend line.
-
-  If the user denies, do the frontend-only thing you can, or mark the task `blocked` with an explanation pointing at the missing backend support.
-
-  If the data source is external (`schema_in_repo === false`) and the task requires a contract change, mark the task `blocked` immediately — Annotask cannot edit APIs outside the repo.
-
-#### e. Ask for clarification (only when stuck)
-
-If you are **genuinely stuck** — missing API context, unclear library usage, ambiguous intent that could lead to a wrong implementation — ask the user for clarification instead of guessing:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", questions: [{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}])`
-
-```bash
-npx annotask update-task TASK_ID --mcp --ask='{"message":"Optional markdown context","questions":[{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}]}'
-```
-
-This sets the task to `needs_info` status. The user sees your questions in the Annotask UI and responds there. When answered, the task returns to `in_progress` with answers in `agent_feedback`.
-
-**Question types:**
-- `text` — free-text answer from user
-- `choice` — user picks from your provided `options` array
-
-**Guidelines:**
-- Only ask when you truly cannot proceed — do not ask for confirmation on straightforward tasks
-- Be specific: "Which CSS framework should I use for the grid?" is better than "How should I do this?"
-- Combine related questions into a single ask rather than multiple rounds
-- After asking, move on to the next task. Come back to check answers later via `annotask_get_tasks` MCP tool or `npx annotask tasks --mcp`
-
-#### f. Mark as blocked (when the task can't be done)
-
-If the task is **fundamentally outside your control** — a performance issue in a third-party library, an accessibility bug in a dependency, a config change that requires infrastructure access, etc. — mark it as blocked with an explanation:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", blocked_reason: "This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone.")`
-
-```bash
-npx annotask update-task TASK_ID --mcp --blocked-reason="This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone."
-```
-
-This sets the task to `blocked` status automatically. The user sees your explanation and can either **dismiss** the task or **push back** (deny it with feedback asking you to try a different approach).
-
-**When to use blocked vs needs_info:**
-- `needs_info` = "I can do this, but I need more information from you"
-- `blocked` = "This can't be done through source code changes — here's why"
-
-#### g. Mark for review immediately
-
-As soon as you finish applying **this** task, mark it for review with a brief resolution note:
-
-**MCP:** `annotask_update_task(task_id: "TASK_ID", status: "review", resolution: "Swapped grid to flexbox, added gap-4 for spacing")`
-
-```bash
-npx annotask update-task TASK_ID --status=review --resolution="Swapped grid to flexbox, added gap-4 for spacing" --mcp
-```
-
-Keep resolutions short — one sentence describing what you changed, not why. The user sees it in the Annotask shell alongside the diff.
-
-#### h. Move to the next task in the group
-
-Repeat steps a–g for each remaining task in the current group, then move to the next group (or confirm parallel subagents have finished). Per-task review flipping is what powers incremental feedback — each task moves to `review` as soon as *its own* edit lands, even inside a batched group, so the user can accept or deny early while later tasks are still in flight.
-
-### 3. Second sweep — catch denies and new tasks that arrived mid-run
-
-Because tasks flip to `review` as soon as their edit lands, the user may have been reviewing (and denying) early tasks while you were still applying later ones. They may also have created brand-new tasks. Before reporting, re-fetch once:
-
-**MCP:** `annotask_get_tasks(status: "denied")` and `annotask_get_tasks(status: "pending")`
-
-```bash
-npx annotask tasks --mcp --status=denied
-npx annotask tasks --mcp --status=pending
-```
-
-If either query returns tasks you did not handle in step 2, loop back to step 2 and process them — re-triage, re-group, apply. Repeat step 3 after each sweep until both queries come back empty.
-
-**If a task keeps returning denied across multiple sweeps**, stop guessing and ask. Use step 2e (`annotask_update_task` with `questions`) to flip it to `needs_info` and let the user clarify what they actually want, rather than burning more sweeps on a misread requirement.
-
-### 4. Report to the user
-
-Tell the user:
-- Which tasks were applied
-- Which files were modified
-- Any tasks that couldn't be applied (and why)
-
-The user will review changes in Annotask and either **accept** (task removed) or **deny with feedback** (task stays denied for next apply).
-
-### Denied tasks
-
-Tasks with `status: "denied"` and a `feedback` field were rejected by the user. They are processed alongside pending tasks in step 2. Read the `feedback` carefully to understand what went wrong and re-apply with corrections.
-
-## Task lifecycle
-
-```
-pending → in_progress (agent working) → review (user checks) → accepted (removed)
-                  ↓                          ↓                → denied (with feedback → agent re-applies)
-             needs_info (waiting)        blocked (can't do)   → dismissed (user deletes)
-                  ↓                          ↓                → pushed back (denied → agent retries)
-             in_progress (resume)        user decides
-```
-
-## Important notes
-
-- Tasks are the source of truth — fetch tasks, not the report
-- The `feedback` field on denied tasks is critical — it tells you what the user didn't like
-- Tasks with `status: "review"` are waiting for user review — don't re-apply them
-- Tasks with `status: "needs_info"` are waiting for the user to answer your questions — skip them and check back later
-- Tasks with `status: "blocked"` have been flagged as not actionable — skip them unless the user pushes back with feedback
-- When a `needs_info` task returns to `in_progress`, check `agent_feedback` for the user's answers before resuming work
-- After applying, the user's page will hot-reload via Vite HMR showing the changes immediately
diff --git a/playgrounds/stress-test/apps/mfe-vue-data-lab/.claude/skills/annotask-init/SKILL.md b/playgrounds/stress-test/apps/mfe-vue-data-lab/.claude/skills/annotask-init/SKILL.md
deleted file mode 100644
index 63df6c7..0000000
--- a/playgrounds/stress-test/apps/mfe-vue-data-lab/.claude/skills/annotask-init/SKILL.md
+++ /dev/null
@@ -1,321 +0,0 @@
-# annotask-init
-
-Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
-
-## When to use
-
-Use this skill when the user says any of:
-- "initialize Annotask" / "init Annotask"
-- "set up Annotask" / "configure Annotask"
-- "scan my project for Annotask"
-- `/annotask-init`
-
-## What it does
-
-Scans the project to detect the framework, design tokens (colors, typography, spacing, borders), icon library, and component library. Writes `.annotask/design-spec.json` which Annotask reads to populate the Theme page with editable design tokens.
-
-## Output schema
-
-Every token carries resolved values for every detected theme variant via a
-`values` map keyed by theme id. Tokens that don't change across variants repeat
-the same value under each id — this keeps every token one uniform shape.
-
-```json
-{
-  "role": "primary",
-  "values": { "light": "#3b82f6", "dark": "#60a5fa" },
-  "cssVar": "--color-primary",
-  "source": "var(--color-primary)",
-  "sourceFile": "src/assets/main.css",
-  "sourceLine": 12
-}
-```
-
-- `role` — semantic name (see vocabularies below)
-- `values` — resolved value per theme variant, keyed by theme id (`light`, `dark`, or a named theme). Single-theme apps use `{ "default": "…" }`.
-- `cssVar` — the CSS custom property name, if backed by one. Omit if not a CSS variable.
-- `source` — human-readable provenance: `var(--x)`, `tailwind.config:colors.primary`, `@theme:--color-primary`
-- `sourceFile` — relative path to the file where the value is defined
-- `sourceLine` — line number in that file (the `:root` variant's definition is fine when multiple exist)
-
-Theme variants themselves are listed at the top of the spec under `themes`,
-with a `selector` describing how each variant is activated in the DOM so the
-Annotask shell can match it against the iframe's current state:
-
-```json
-"themes": [
-  { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-  { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-],
-"defaultTheme": "light"
-```
-
-`selector.kind` is one of `attribute` (with `name`, `value`, optional `host`), `class` (with `name`, optional `host`), `media` (with `media: '(prefers-color-scheme: dark)'`), or `default` (no selector — the base `:root` values). Apps with only one theme should emit a single `{ "id": "default", "name": "Default", "selector": { "kind": "default" } }` variant.
-
-## Steps
-
-### 1. Detect framework
-
-Check `package.json` dependencies:
-- `vue` → name "vue", read version
-- `react` / `react-dom` → name "react"
-- `svelte` → name "svelte"
-- `solid-js` → name "solid"
-
-Check for styling:
-- `tailwindcss` in devDependencies or dependencies → add "tailwind" to styling array
-- Look for `<style scoped>` in `.vue` files → add "scoped-css"
-- Look for CSS module imports (`.module.css`) → add "css-modules"
-
-### 2. Detect theme variants
-
-Before extracting any token values, determine which theme variants the project
-supports so you know which scopes to resolve values under. Check these signals
-in order and stop at the first match:
-
-1. **Tailwind `.dark` class** — If CSS files contain `.dark { … }` / `:root.dark { … }` / `html.dark { … }` blocks, or Tailwind v3 config has `darkMode: 'class'`, or Tailwind v4 CSS contains `@custom-variant dark (&:where(.dark, .dark *))`. Emit two variants:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }`
-
-2. **Data-attribute theming** — If CSS contains `[data-theme="…"]`, `[data-bs-theme="…"]`, `[data-mui-color-scheme="…"]`, `[data-mantine-color-scheme="…"]`, or `[data-color-scheme="…"]` selectors. Emit one variant per distinct attribute value:
-   - `{ "id": "<value>", "name": "<Value>", "scheme": "light|dark (if obvious)", "selector": { "kind": "attribute", "host": "html", "name": "<attr-name>", "value": "<value>" } }`
-
-3. **`@media (prefers-color-scheme: dark)` blocks** — If the project only switches via media queries. Emit:
-   - `{ "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } }`
-   - `{ "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "media", "media": "(prefers-color-scheme: dark)" } }`
-
-4. **Single theme** — If none of the above are present:
-   - `[ { "id": "default", "name": "Default", "selector": { "kind": "default" } } ]`
-
-Set `defaultTheme` to the variant id used when no selector matches — typically `"light"` or `"default"`.
-
-### 3. Scan colors
-
-**Find color sources:**
-
-1. **CSS variables**: Search for `:root`, `:root.dark`, `html.dark`, `[data-theme="…"]`, and `@media (prefers-color-scheme: dark) :root` declarations across CSS files and Vue `<style>` blocks. Extract `--variable-name: value` pairs, remembering which variant scope each came from.
-
-2. **Tailwind v4** (version >= 4): Search for `@theme` blocks in CSS files. Extract custom properties defined within them. `@theme` blocks without a variant selector apply to every variant.
-
-3. **Tailwind v3** (version < 4): Read `tailwind.config.js`, `tailwind.config.ts`, or `tailwind.config.mjs`. Extract `theme.extend.colors`. Convert to flat key-value pairs.
-
-**Resolve each color under every detected variant.** Produce a `values` map
-keyed by theme id. When a variant doesn't override the token, copy the base
-(`:root`/light/default) value so every token has a value for every variant.
-When a variant-specific block defines a new CSS variable that doesn't appear
-in the base scope, leave the missing variants blank (the server normalizer
-will fill them when the spec is read).
-
-**Classify into semantic roles using this fixed vocabulary:**
-
-| Role | Match heuristics (in variable/key name) |
-|------|----------------------------------------|
-| `primary` | primary, brand |
-| `secondary` | secondary |
-| `accent` | accent |
-| `background` | bg, background |
-| `surface` | surface, card |
-| `text` | text, foreground, fg (but not text-muted) |
-| `text-muted` | text-muted, muted, subtle |
-| `border` | border, divider, separator |
-| `danger` | danger, error, destructive, red |
-| `warning` | warning, amber, yellow (semantic) |
-| `success` | success, green (semantic) |
-| `info` | info, blue (semantic) |
-
-If a variable doesn't match any heuristic, use a descriptive role name derived from the variable name (e.g., `--sidebar-bg` → role `sidebar-bg`).
-
-**Limits**: Maximum 30 color tokens. Prioritize semantic roles first, then most-used custom colors.
-
-### 4. Scan typography
-
-Apply the same per-variant `values` map strategy used for colors: resolve each
-token under every detected variant, copying the base value for variants that
-don't override it.
-
-**Font families**: Search for:
-- CSS variables containing `font`, `family` in `:root` or `@theme`
-- `fontFamily` in Tailwind config
-- Direct `font-family` declarations on `body`, `html`, `h1`-`h6` elements
-
-Classify as:
-- `heading` — used on h1-h6 or named heading/display
-- `body` — used on body/html or named sans/body/base
-- `mono` — monospace, code, named mono
-
-**Font scale**: Search for:
-- CSS variables containing `font-size`, `text-` size names
-- `fontSize` in Tailwind config
-- `@theme` size definitions
-
-Use roles: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or by ascending size order).
-
-**Weights**: Scan component files for `font-weight` values and Tailwind weight classes (`font-bold`, `font-semibold`, etc.). List unique weights as strings: `["400", "500", "600", "700"]`.
-
-### 5. Scan spacing
-
-Search for:
-- CSS variables containing `space`, `gap`, `margin`, `padding`, `size`
-- `spacing` in Tailwind config
-- `@theme` spacing definitions
-
-Use roles: `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `4xl` (match by name or ascending size).
-
-**Limits**: Maximum 12 spacing tokens.
-
-### 6. Scan border radius
-
-Search for:
-- CSS variables containing `radius`, `rounded`
-- `borderRadius` in Tailwind config
-- `@theme` radius definitions
-
-Use roles: `sm`, `md`, `lg`, `xl`, `full` (match by name or ascending size).
-
-### 7. Scan breakpoints
-
-Detect responsive breakpoints from whatever styling system the project uses. Output as a flat object mapping name → min-width value.
-
-**Sources (check in order):**
-
-1. **Tailwind v4** (>= 4): Look in CSS files for `@theme` blocks defining `--breakpoint-*` custom properties, or `@custom-media` rules.
-
-2. **Tailwind v3** (< 4): Read `tailwind.config.{js,ts,mjs}`. Extract `theme.screens` or `theme.extend.screens`. Default Tailwind screens: `{ "sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px" }` — use these as fallback if Tailwind is detected but no custom screens are defined.
-
-3. **Bootstrap**: Check for `bootstrap` in package.json. Default Bootstrap breakpoints: `{ "sm": "576px", "md": "768px", "lg": "992px", "xl": "1200px", "xxl": "1400px" }`.
-
-4. **CSS custom properties**: Search `:root` for variables containing `breakpoint`, `screen`, `bp` in the name (e.g., `--bp-mobile: 480px`).
-
-5. **CSS `@media` patterns**: Scan `.css`, `.scss`, `.vue` files for `@media` queries with `min-width` or `max-width`. Extract the 3–6 most common breakpoint values and assign roles by ascending size: `sm`, `md`, `lg`, `xl`, `2xl`.
-
-**Output example:**
-```json
-"breakpoints": {
-  "sm": "640px",
-  "md": "768px",
-  "lg": "1024px",
-  "xl": "1280px",
-  "2xl": "1536px"
-}
-```
-
-If no breakpoints are detected, omit the `breakpoints` field (don't include an empty object).
-
-### 8. Detect icon library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `lucide-vue-next` or `lucide-react` | lucide |
-| `@heroicons/vue` or `@heroicons/react` | heroicons |
-| `@fortawesome/vue-fontawesome` or `@fortawesome/react-fontawesome` | fontawesome |
-| `@phosphor-icons/vue` or `@phosphor-icons/react` | phosphor |
-| `@tabler/icons-vue` or `@tabler/icons-react` | tabler |
-
-Read the version from package.json.
-
-### 9. Detect component library
-
-Check `package.json` dependencies for:
-
-| Package | Library name |
-|---------|-------------|
-| `primevue` | PrimeVue |
-| `vuetify` | Vuetify |
-| `element-plus` | Element Plus |
-| `@headlessui/vue` | Headless UI |
-| `radix-vue` | Radix Vue |
-| `naive-ui` | Naive UI |
-| `@shadcn/ui` or `shadcn-vue` | shadcn/ui |
-
-If found, scan `src/` for import statements to find used components:
-```bash
-grep -rh "from '${package}" --include='*.vue' --include='*.ts' --include='*.js' src/ | sort -u
-```
-
-Extract component names from the imports. Read the version from package.json.
-
-### 10. Write design spec
-
-Create `.annotask/design-spec.json`:
-
-```json
-{
-  "version": "1.0",
-  "framework": {
-    "name": "vue",
-    "version": "3.5.0",
-    "styling": ["tailwind", "scoped-css"]
-  },
-  "themes": [
-    { "id": "light", "name": "Light", "scheme": "light", "selector": { "kind": "default" } },
-    { "id": "dark",  "name": "Dark",  "scheme": "dark",  "selector": { "kind": "class", "host": "html", "name": "dark" } }
-  ],
-  "defaultTheme": "light",
-  "colors": [
-    { "role": "primary",    "values": { "light": "#3b82f6", "dark": "#60a5fa" }, "cssVar": "--color-primary", "source": "var(--color-primary)", "sourceFile": "src/assets/main.css", "sourceLine": 5 },
-    { "role": "background", "values": { "light": "#ffffff", "dark": "#0b1120" }, "cssVar": "--bg",            "source": "var(--bg)",            "sourceFile": "src/assets/main.css", "sourceLine": 3 }
-  ],
-  "typography": {
-    "families": [
-      { "role": "body", "values": { "light": "Inter, sans-serif", "dark": "Inter, sans-serif" }, "cssVar": "--font-sans", "source": "var(--font-sans)", "sourceFile": "src/assets/main.css", "sourceLine": 10 }
-    ],
-    "scale": [
-      { "role": "base", "values": { "light": "1rem", "dark": "1rem" }, "cssVar": "--text-base", "source": "var(--text-base)", "sourceFile": "src/assets/main.css", "sourceLine": 15 }
-    ],
-    "weights": ["400", "500", "600", "700"]
-  },
-  "spacing": [
-    { "role": "sm", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--space-sm", "source": "var(--space-sm)", "sourceFile": "src/assets/main.css", "sourceLine": 20 }
-  ],
-  "borders": {
-    "radius": [
-      { "role": "md", "values": { "light": "8px", "dark": "8px" }, "cssVar": "--radius-md", "source": "var(--radius-md)", "sourceFile": "src/assets/main.css", "sourceLine": 25 }
-    ]
-  },
-  "breakpoints": {
-    "sm": "640px",
-    "md": "768px",
-    "lg": "1024px",
-    "xl": "1280px",
-    "2xl": "1536px"
-  },
-  "icons": {
-    "library": "lucide",
-    "version": "0.300.0"
-  },
-  "components": {
-    "library": "PrimeVue",
-    "version": "4.5.4",
-    "used": ["DataTable", "Column", "InputText", "Tag", "Button"]
-  }
-}
-```
-
-### 11. Clean up old config
-
-If `.annotask/config.json` exists, delete it — it's been replaced by `design-spec.json`.
-
-### 12. Update .gitignore
-
-Check if `.gitignore` contains `.annotask/`. If not, append:
-```
-# Annotask (generated)
-.annotask/
-```
-
-### 13. Report to user
-
-Tell the user:
-- What was detected (framework, number of color/typography/spacing tokens, libraries)
-- That they can open the **Theme** page in Annotask to view and edit tokens
-- That they can re-run `/annotask-init` to rescan
-
-## Notes
-
-- This skill is idempotent — re-running overwrites the design spec with fresh data
-- The design spec is gitignored because it's generated and may vary per developer
-- If detection fails for any section, use empty defaults (empty array, null) rather than omitting the field
-- All top-level fields are required — use empty values for missing data
-- When a token has a CSS variable backing, always populate the `cssVar` field — this enables live preview in the Theme page
diff --git a/playgrounds/stress-test/apps/mfe-vue-data-lab/.mcp.json b/playgrounds/stress-test/apps/mfe-vue-data-lab/.mcp.json
deleted file mode 100644
index 5527f21..0000000
--- a/playgrounds/stress-test/apps/mfe-vue-data-lab/.mcp.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "annotask": {
-      "command": "npx",
-      "args": [
-        "annotask",
-        "mcp"
-      ]
-    }
-  }
-}
diff --git a/playgrounds/stress-test/apps/mfe-vue-data-lab/src/App.vue b/playgrounds/stress-test/apps/mfe-vue-data-lab/src/App.vue
index 37a4678..8624ba3 100644
--- a/playgrounds/stress-test/apps/mfe-vue-data-lab/src/App.vue
+++ b/playgrounds/stress-test/apps/mfe-vue-data-lab/src/App.vue
@@ -186,7 +186,7 @@ const STATUS_FILTERS: Array<WorkflowStatus | 'all'> = [
   <HealthDashboard v-if="view === 'health'" />
   <NConfigProvider v-else :theme="naiveTheme">
     <NLayout style="background: var(--stress-bg); min-height: 100%">
-      <NLayoutContent content-style="padding: 32px 40px;">
+      <NLayoutContent style="background-color: var(--stress-bg)" content-style="padding: 32px 40px;">
         <header class="header">
           <h1>Vue Data Lab</h1>
           <p class="sub">
diff --git a/playgrounds/stress-test/e2e/annotask/annotate.spec.ts b/playgrounds/stress-test/e2e/annotask/annotate.spec.ts
index 5e02d1b..e98aa8d 100644
--- a/playgrounds/stress-test/e2e/annotask/annotate.spec.ts
+++ b/playgrounds/stress-test/e2e/annotask/annotate.spec.ts
@@ -31,14 +31,14 @@ for (const app of APPS) {
       await expect(page.locator(SEL.tabAnnotate)).toHaveClass(/active/)
     })
 
-    for (const tool of ['pin', 'arrow', 'draw', 'highlight', 'select', 'interact'] as const) {
+    for (const tool of ['pin', 'arrow', 'highlight', 'select', 'interact'] as const) {
       test(`tool ${tool} activates`, async ({ page }) => {
         test.info().annotations.push({ type: 'matrix', description: `${app.id}/${FEATURE_GROUP}/tool-${tool}` })
         const shell = new AnnotaskShell(page, app)
         await shell.open()
         await shell.activateTool(tool)
         const map = {
-          pin: SEL.toolPin, arrow: SEL.toolArrow, draw: SEL.toolDraw,
+          pin: SEL.toolPin, arrow: SEL.toolArrow,
           highlight: SEL.toolHighlight, select: SEL.toolSelect, interact: SEL.toolInteract,
         } as const
         await expect(page.locator(map[tool])).toHaveClass(/active/)
diff --git a/playgrounds/stress-test/e2e/annotask/fixtures/annotask-page.ts b/playgrounds/stress-test/e2e/annotask/fixtures/annotask-page.ts
index c91010d..6f5b9dc 100644
--- a/playgrounds/stress-test/e2e/annotask/fixtures/annotask-page.ts
+++ b/playgrounds/stress-test/e2e/annotask/fixtures/annotask-page.ts
@@ -21,12 +21,11 @@ export class AnnotaskShell {
     await this.page.locator(sel).click()
   }
 
-  async activateTool(tool: 'pin' | 'arrow' | 'draw' | 'highlight' | 'select' | 'interact'): Promise<void> {
+  async activateTool(tool: 'pin' | 'arrow' | 'highlight' | 'select' | 'interact'): Promise<void> {
     await this.gotoTab('annotate')
     const map = {
       pin: SEL.toolPin,
       arrow: SEL.toolArrow,
-      draw: SEL.toolDraw,
       highlight: SEL.toolHighlight,
       select: SEL.toolSelect,
       interact: SEL.toolInteract,
diff --git a/playgrounds/stress-test/e2e/annotask/helpers/selectors.ts b/playgrounds/stress-test/e2e/annotask/helpers/selectors.ts
index ca96fe5..691b29e 100644
--- a/playgrounds/stress-test/e2e/annotask/helpers/selectors.ts
+++ b/playgrounds/stress-test/e2e/annotask/helpers/selectors.ts
@@ -20,7 +20,6 @@ export const SEL = {
   toolSelect: '[data-testid="tool-select"]',
   toolPin: '[data-testid="tool-pin"]',
   toolArrow: '[data-testid="tool-arrow"]',
-  toolDraw: '[data-testid="tool-draw"]',
   toolHighlight: '[data-testid="tool-highlight"]',
 
   btnTasksPanel: '[data-testid="btn-tasks-panel"]',
diff --git a/playgrounds/tsconfig.json b/playgrounds/tsconfig.json
new file mode 100644
index 0000000..0b8aea6
--- /dev/null
+++ b/playgrounds/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  }
+}
diff --git a/playwright.config.ts b/playwright.config.ts
index 4b6d680..7e6a21e 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -50,6 +50,15 @@ export default defineConfig({
       use: { ...devices['Desktop Chrome'], baseURL: 'http://localhost:5180' },
       testMatch: '**/mfe-vite*.test.ts',
     },
+    {
+      name: 'screenshots',
+      use: {
+        ...devices['Desktop Chrome'],
+        baseURL: 'http://localhost:5173',
+        viewport: { width: 1440, height: 900 },
+      },
+      testMatch: '**/screenshots.test.ts',
+    },
   ],
   webServer: [
     {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4ffe23f..4304167 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -8,18 +8,59 @@ overrides:
   follow-redirects: '>=1.16.0'
   defu: '>=6.1.5'
   lodash: '>=4.18.0'
-  dompurify: '>=3.4.0'
+  dompurify: '>=3.4.9'
+  shell-quote: '>=1.8.4'
+  fast-uri: '>=3.1.2'
+  devalue: '>=5.8.1'
+  undici: '>=7.28.0 <8'
+  react-router: '>=7.15.1 <8'
+  react-router-dom: '>=7.15.1 <8'
+  ws: '>=8.21.0'
+  vite: '>=6.4.3 <7'
+  postcss: '>=8.5.10'
+  svelte: '>=5.55.7 <6'
+  js-yaml: '>=4.2.0 <5'
+  qs: '>=6.15.2 <7'
+  uuid: '>=11.1.1 <12'
+  launch-editor: '>=2.14.1'
+  webpack-dev-server: '>=5.2.5 <6'
+  http-proxy-middleware: '>=2.0.10 <3'
+  '@babel/core': '>=7.29.6'
 
 importers:
 
   .:
     dependencies:
+      '@codemirror/commands':
+        specifier: ^6.10.3
+        version: 6.10.3
+      '@codemirror/lang-markdown':
+        specifier: ^6.5.0
+        version: 6.5.0
+      '@codemirror/language':
+        specifier: ^6.12.3
+        version: 6.12.3
+      '@codemirror/search':
+        specifier: ^6.7.0
+        version: 6.7.0
+      '@codemirror/state':
+        specifier: ^6.6.0
+        version: 6.6.0
+      '@codemirror/view':
+        specifier: ^6.43.0
+        version: 6.43.0
+      '@lezer/highlight':
+        specifier: ^1.2.3
+        version: 1.2.3
+      codemirror:
+        specifier: ^6.0.2
+        version: 6.0.2
       webpack:
         specifier: '>=5.0.0'
-        version: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)
+        version: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)
       ws:
-        specifier: ^8.20.0
-        version: 8.20.0
+        specifier: '>=8.21.0'
+        version: 8.21.0
       zod:
         specifier: ^4.3.6
         version: 4.3.6
@@ -39,6 +80,9 @@ importers:
       '@types/js-yaml':
         specifier: ^4.0.9
         version: 4.0.9
+      '@types/jsdom':
+        specifier: ^28.0.3
+        version: 28.0.3
       '@types/node':
         specifier: ^25.5.0
         version: 25.5.0
@@ -50,7 +94,7 @@ importers:
         version: 8.18.1
       '@vitejs/plugin-vue':
         specifier: ^5.0.0
-        version: 5.2.4(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
+        version: 5.2.4(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
       '@vue/compiler-dom':
         specifier: ^3.0.0
         version: 3.5.31
@@ -61,14 +105,14 @@ importers:
         specifier: 4.11.1
         version: 4.11.1
       dompurify:
-        specifier: '>=3.4.0'
-        version: 3.4.0
+        specifier: '>=3.4.9'
+        version: 3.4.11
       html2canvas-pro:
         specifier: 2.0.2
         version: 2.0.2
       js-yaml:
-        specifier: ^4.1.1
-        version: 4.1.1
+        specifier: '>=4.2.0 <5'
+        version: 4.2.0
       jsdom:
         specifier: ^29.0.1
         version: 29.0.1
@@ -82,20 +126,23 @@ importers:
         specifier: ^1.30.0
         version: 1.30.0
       svelte:
-        specifier: ^5.0.0
-        version: 5.55.0
+        specifier: '>=5.55.7 <6'
+        version: 5.56.3(@typescript-eslint/types@8.57.2)
+      testreel:
+        specifier: ^0.2.0
+        version: 0.2.0(@playwright/test@1.58.2)(@types/node@25.5.0)(playwright-core@1.58.2)
       tsup:
         specifier: ^8.0.0
-        version: 8.5.1(@swc/core@1.15.30(@swc/helpers@0.5.21))(jiti@1.21.7)(postcss@8.5.8)(typescript@5.9.3)(yaml@2.8.3)
+        version: 8.5.1(@swc/core@1.15.30(@swc/helpers@0.5.21))(jiti@1.21.7)(postcss@8.5.15)(typescript@5.9.3)(yaml@2.8.3)
       typescript:
         specifier: ^5.5.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
       vitest:
         specifier: ^4.1.2
-        version: 4.1.2(@types/node@25.5.0)(jsdom@29.0.1)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+        version: 4.1.2(@types/node@25.5.0)(jsdom@29.0.1)(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       vue:
         specifier: ^3.5.0
         version: 3.5.31(typescript@5.9.3)
@@ -122,10 +169,10 @@ importers:
         version: 8.18.0
       antenna-component-library:
         specifier: file:/home/kurt/code/antenna-component-library
-        version: file:../antenna-component-library(@fortawesome/fontawesome-svg-core@6.7.2)(@fortawesome/free-solid-svg-icons@6.7.2)(@fortawesome/vue-fontawesome@3.1.3(@fortawesome/fontawesome-svg-core@6.7.2)(vue@3.5.31(typescript@5.9.3)))(@vueup/vue-quill@1.2.0(vue@3.5.31(typescript@5.9.3)))(ace-builds@1.43.6)(ajv@8.18.0)(dompurify@3.4.0)(marked@15.0.12)(quill@2.0.3)(rollup@4.60.0)(vue3-click-away@1.2.4)(vue@3.5.31(typescript@5.9.3))
+        version: file:../antenna-component-library(@fortawesome/fontawesome-svg-core@6.7.2)(@fortawesome/free-solid-svg-icons@6.7.2)(@fortawesome/vue-fontawesome@3.1.3(@fortawesome/fontawesome-svg-core@6.7.2)(vue@3.5.31(typescript@5.9.3)))(@vueup/vue-quill@1.2.0(vue@3.5.31(typescript@5.9.3)))(ace-builds@1.43.6)(ajv@8.18.0)(dompurify@3.4.11)(marked@15.0.12)(quill@2.0.3)(rollup@4.60.0)(vue3-click-away@1.2.4)(vue@3.5.31(typescript@5.9.3))
       dompurify:
-        specifier: '>=3.4.0'
-        version: 3.4.0
+        specifier: '>=3.4.9'
+        version: 3.4.11
       lodash:
         specifier: '>=4.18.0'
         version: 4.18.1
@@ -144,28 +191,28 @@ importers:
     devDependencies:
       '@vitejs/plugin-vue':
         specifier: ^5.0.0
-        version: 5.2.4(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
+        version: 5.2.4(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
       annotask:
         specifier: workspace:*
         version: link:../../..
       autoprefixer:
         specifier: ^10.4.27
-        version: 10.4.27(postcss@8.5.8)
+        version: 10.4.27(postcss@8.5.15)
       postcss:
-        specifier: ^8.5.8
-        version: 8.5.8
+        specifier: '>=8.5.10'
+        version: 8.5.15
       tailwindcss:
         specifier: ^3.4.19
         version: 3.4.19(yaml@2.8.3)
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/simple/astro:
     dependencies:
       astro:
-        specifier: ^5.0.0
-        version: 5.18.1(@types/node@25.5.0)(jiti@1.21.7)(rollup@4.60.0)(terser@5.46.1)(typescript@5.9.3)(yaml@2.8.3)
+        specifier: ^6.0.0
+        version: 6.4.8(@types/node@25.5.0)(jiti@1.21.7)(rollup@4.60.0)(terser@5.46.1)(yaml@2.8.3)
     devDependencies:
       annotask:
         specifier: workspace:*
@@ -177,8 +224,8 @@ importers:
         specifier: workspace:*
         version: link:../../..
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/simple/htmx-vite:
     devDependencies:
@@ -186,8 +233,21 @@ importers:
         specifier: workspace:*
         version: link:../../..
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+
+  playgrounds/simple/marketing:
+    dependencies:
+      '@shoelace-style/shoelace':
+        specifier: ^2.20.1
+        version: 2.20.1(@floating-ui/utils@0.2.11)(@types/react@19.2.14)
+    devDependencies:
+      annotask:
+        specifier: workspace:*
+        version: link:../../..
+      vite:
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/simple/mfe-vite:
     dependencies:
@@ -200,13 +260,13 @@ importers:
     devDependencies:
       '@vitejs/plugin-vue':
         specifier: ^5.0.0
-        version: 5.2.4(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
+        version: 5.2.4(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
       annotask:
         specifier: workspace:*
         version: link:../../..
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/simple/react-radix:
     dependencies:
@@ -228,7 +288,7 @@ importers:
         version: 19.2.3(@types/react@19.2.14)
       '@vitejs/plugin-react':
         specifier: ^4.0.0
-        version: 4.7.0(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+        version: 4.7.0(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       annotask:
         specifier: workspace:*
         version: link:../../..
@@ -236,8 +296,8 @@ importers:
         specifier: ^5.5.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/simple/react-vite:
     dependencies:
@@ -248,8 +308,8 @@ importers:
         specifier: ^19.0.0
         version: 19.2.4(react@19.2.4)
       react-router-dom:
-        specifier: ^7.0.0
-        version: 7.13.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+        specifier: '>=7.15.1 <8'
+        version: 7.18.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
     devDependencies:
       '@types/react':
         specifier: ^19.0.0
@@ -259,7 +319,7 @@ importers:
         version: 19.2.3(@types/react@19.2.14)
       '@vitejs/plugin-react':
         specifier: ^4.0.0
-        version: 4.7.0(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+        version: 4.7.0(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       annotask:
         specifier: workspace:*
         version: link:../../..
@@ -267,8 +327,8 @@ importers:
         specifier: ^5.5.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/simple/solid-vite:
     dependencies:
@@ -283,27 +343,27 @@ importers:
         specifier: ^5.5.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
       vite-plugin-solid:
         specifier: ^2.11.0
-        version: 2.11.12(solid-js@1.9.12)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+        version: 2.11.12(solid-js@1.9.12)(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
 
   playgrounds/simple/svelte-vite:
     dependencies:
       svelte:
-        specifier: ^5.0.0
-        version: 5.55.0
+        specifier: '>=5.55.7 <6'
+        version: 5.56.3(@typescript-eslint/types@8.57.2)
     devDependencies:
       '@sveltejs/vite-plugin-svelte':
         specifier: ^5.0.0
-        version: 5.1.1(svelte@5.55.0)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+        version: 5.1.1(svelte@5.56.3(@typescript-eslint/types@8.57.2))(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       annotask:
         specifier: workspace:*
         version: link:../../..
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/simple/vue-primevue:
     dependencies:
@@ -322,19 +382,25 @@ importers:
     devDependencies:
       '@vitejs/plugin-vue':
         specifier: ^5.0.0
-        version: 5.2.4(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
+        version: 5.2.4(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
       annotask:
         specifier: workspace:*
         version: link:../../..
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/simple/vue-vite:
     dependencies:
+      '@primevue/themes':
+        specifier: ^4.5.4
+        version: 4.5.4
       primeicons:
         specifier: ^7.0.0
         version: 7.0.0
+      primevue:
+        specifier: ^4.5.4
+        version: 4.5.5(vue@3.5.31(typescript@5.9.3))
       vue:
         specifier: ^3.5.0
         version: 3.5.31(typescript@5.9.3)
@@ -344,13 +410,13 @@ importers:
     devDependencies:
       '@vitejs/plugin-vue':
         specifier: ^5.0.0
-        version: 5.2.4(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
+        version: 5.2.4(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
       annotask:
         specifier: workspace:*
         version: link:../../..
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/simple/vue-webpack:
     dependencies:
@@ -387,13 +453,13 @@ importers:
         version: 17.4.2(@vue/compiler-sfc@3.5.31)(vue@3.5.31(typescript@5.9.3))(webpack@5.105.4)
       webpack:
         specifier: ^5.90.0
-        version: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
+        version: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
       webpack-cli:
         specifier: ^6.0.0
-        version: 6.0.1(webpack-dev-server@5.2.3)(webpack@5.105.4)
+        version: 6.0.1(webpack-dev-server@5.2.5)(webpack@5.105.4)
       webpack-dev-server:
-        specifier: ^5.0.0
-        version: 5.2.3(tslib@2.8.1)(webpack-cli@6.0.1)(webpack@5.105.4)
+        specifier: '>=5.2.5 <6'
+        version: 5.2.5(tslib@2.8.1)(webpack-cli@6.0.1)(webpack@5.105.4)
 
   playgrounds/stress-test/apps/host-single-spa:
     dependencies:
@@ -420,7 +486,7 @@ importers:
         version: 3.3.0(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       bits-ui:
         specifier: ^1.0.0
-        version: 1.8.0(svelte@5.55.0)
+        version: 1.8.0(svelte@5.56.3(@typescript-eslint/types@8.57.2))
       naive-ui:
         specifier: ^2.40.1
         version: 2.44.1(vue@3.5.31(typescript@5.9.3))
@@ -437,15 +503,15 @@ importers:
         specifier: ^1.9.3
         version: 1.9.12
       svelte:
-        specifier: ^5.0.0
-        version: 5.55.0
+        specifier: '>=5.55.7 <6'
+        version: 5.56.3(@typescript-eslint/types@8.57.2)
       vue:
         specifier: ^3.5.0
         version: 3.5.31(typescript@5.9.3)
     devDependencies:
       '@vitejs/plugin-vue':
         specifier: ^5.0.0
-        version: 5.2.4(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
+        version: 5.2.4(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
       annotask:
         specifier: workspace:*
         version: link:../../../..
@@ -453,8 +519,8 @@ importers:
         specifier: ^5.5.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
       vue-tsc:
         specifier: ^2.0.0
         version: 2.2.12(typescript@5.9.3)
@@ -475,8 +541,8 @@ importers:
         specifier: workspace:*
         version: link:../../../..
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/stress-test/apps/mfe-react-sidebar:
     dependencies:
@@ -507,7 +573,7 @@ importers:
         version: 19.2.3(@types/react@19.2.14)
       '@vitejs/plugin-react-swc':
         specifier: ^3.7.0
-        version: 3.11.0(@swc/helpers@0.5.21)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+        version: 3.11.0(@swc/helpers@0.5.21)(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       annotask:
         specifier: workspace:*
         version: link:../../../..
@@ -515,8 +581,8 @@ importers:
         specifier: ^5.5.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/stress-test/apps/mfe-react-workflows:
     dependencies:
@@ -553,7 +619,7 @@ importers:
         version: 19.2.3(@types/react@19.2.14)
       '@vitejs/plugin-react-swc':
         specifier: ^3.7.0
-        version: 3.11.0(@swc/helpers@0.5.21)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+        version: 3.11.0(@swc/helpers@0.5.21)(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       annotask:
         specifier: workspace:*
         version: link:../../../..
@@ -561,8 +627,8 @@ importers:
         specifier: ^5.5.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/stress-test/apps/mfe-solid-component-lab:
     dependencies:
@@ -589,11 +655,11 @@ importers:
         specifier: ^5.5.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
       vite-plugin-solid:
         specifier: ^2.11.0
-        version: 2.11.12(solid-js@1.9.12)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+        version: 2.11.12(solid-js@1.9.12)(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
 
   playgrounds/stress-test/apps/mfe-svelte-streaming:
     dependencies:
@@ -608,20 +674,20 @@ importers:
         version: link:../../packages/shared-ui-tokens
       bits-ui:
         specifier: ^1.3.0
-        version: 1.8.0(svelte@5.55.0)
+        version: 1.8.0(svelte@5.56.3(@typescript-eslint/types@8.57.2))
       svelte:
-        specifier: ^5.0.0
-        version: 5.55.0
+        specifier: '>=5.55.7 <6'
+        version: 5.56.3(@typescript-eslint/types@8.57.2)
     devDependencies:
       '@sveltejs/vite-plugin-svelte':
         specifier: ^5.0.0
-        version: 5.1.1(svelte@5.55.0)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+        version: 5.1.1(svelte@5.56.3(@typescript-eslint/types@8.57.2))(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       annotask:
         specifier: workspace:*
         version: link:../../../..
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   playgrounds/stress-test/apps/mfe-vue-data-lab:
     dependencies:
@@ -646,7 +712,7 @@ importers:
     devDependencies:
       '@vitejs/plugin-vue':
         specifier: ^5.0.0
-        version: 5.2.4(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
+        version: 5.2.4(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))
       annotask:
         specifier: workspace:*
         version: link:../../../..
@@ -654,8 +720,8 @@ importers:
         specifier: ^5.5.0
         version: 5.9.3
       vite:
-        specifier: ^6.4.2
-        version: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+        specifier: '>=6.4.3 <7'
+        version: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
       vue-tsc:
         specifier: ^2.0.0
         version: 2.2.12(typescript@5.9.3)
@@ -716,47 +782,59 @@ packages:
   '@asamuzakjp/nwsapi@2.3.9':
     resolution: {integrity: sha512-n8GuYSrI9bF7FFZ/SjhwevlHc8xaVlb/7HmHelnc/PZXBD2ZR49NnN9sMMuDdEGPeeRQ5d0hqlSlEpgCX3Wl0Q==}
 
-  '@astrojs/compiler@2.13.1':
-    resolution: {integrity: sha512-f3FN83d2G/v32ipNClRKgYv30onQlMZX1vCeZMjPsMMPl1mDpmbl0+N5BYo4S/ofzqJyS5hvwacEo0CCVDn/Qg==}
+  '@astrojs/compiler@4.0.0':
+    resolution: {integrity: sha512-eouss7G8ygdZqHuke033VMcVw5HTZUu+PXd/h06DGDUg/jt5btPYPqh66ENWw/mU78rBrf/oeC4oqoBwMtDMNA==}
 
-  '@astrojs/internal-helpers@0.7.6':
-    resolution: {integrity: sha512-GOle7smBWKfMSP8osUIGOlB5kaHdQLV3foCsf+5Q9Wsuu+C6Fs3Ez/ttXmhjZ1HkSgsogcM1RXSjjOVieHq16Q==}
+  '@astrojs/internal-helpers@0.10.0':
+    resolution: {integrity: sha512-Ry2R3VPeIN4uPCSA4xQc+e+vsJXkalKpEbDc07hV+a/o5Bs2N/s/uDcPJH/05L19DKh9tAy7e6JM3YZ6Cxfezw==}
 
-  '@astrojs/markdown-remark@6.3.11':
-    resolution: {integrity: sha512-hcaxX/5aC6lQgHeGh1i+aauvSwIT6cfyFjKWvExYSxUhZZBBdvCliOtu06gbQyhbe0pGJNoNmqNlQZ5zYUuIyQ==}
+  '@astrojs/markdown-remark@7.2.0':
+    resolution: {integrity: sha512-+YxmVQu1Bd+MFfSzjq1rOJvD9+nIOJzz5YIIhdIH01RrxRkKbyKoEgyIqP3yv51MhzMDgd79QaPv+kCVPT8vHw==}
 
-  '@astrojs/prism@3.3.0':
-    resolution: {integrity: sha512-q8VwfU/fDZNoDOf+r7jUnMC2//H2l0TuQ6FkGJL8vD8nw/q5KiL3DS1KKBI3QhI9UQhpJ5dc7AtqfbXWuOgLCQ==}
-    engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0}
+  '@astrojs/prism@4.0.2':
+    resolution: {integrity: sha512-KTivpmnz6lDsC6o9H4+DNm2SrE/GHzw8cNAvEJwAvUT+eoaEnn/4NtbDNfRRaxaJHdp15gf+tfHAWiXR4wB3BA==}
+    engines: {node: '>=22.12.0'}
 
-  '@astrojs/telemetry@3.3.0':
-    resolution: {integrity: sha512-UFBgfeldP06qu6khs/yY+q1cDAaArM2/7AEIqQ9Cuvf7B1hNLq0xDrZkct+QoIGyjq56y8IaE2I3CTvG99mlhQ==}
+  '@astrojs/telemetry@3.3.2':
+    resolution: {integrity: sha512-j8DNruA8ors99Al39RYZPJK4DC1bKkoNm93mAMuBhY9TCNC4R8n1q7ovFnJ5qhGh5Lsh7pa1gpQVpYpsJPeTHQ==}
     engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0}
 
   '@babel/code-frame@7.29.0':
     resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/compat-data@7.29.0':
-    resolution: {integrity: sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==}
-    engines: {node: '>=6.9.0'}
+  '@babel/code-frame@8.0.0':
+    resolution: {integrity: sha512-dYYg153EyN2Ekbqw2zAsbd6/JR+9N2SEoC7YV2GyyqMM7x9bLDTjBD6XBhSMLH0wtIVyJj03jWNriQhaN+eoCw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
 
-  '@babel/core@7.29.0':
-    resolution: {integrity: sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==}
-    engines: {node: '>=6.9.0'}
+  '@babel/compat-data@8.0.0':
+    resolution: {integrity: sha512-DOjnob/cXOUgDOozCDeq/aK2p5y8dUIVdf6tNhEV1HQRd6I8aQ4f4fbtHRVEvb6lP3BGomrKHiS8ICAASSVQSw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/core@8.0.1':
+    resolution: {integrity: sha512-5FgxM4dLQpMJHSiVATk8foW263dVHQHBVpXYiimNECVWG01f4nFyEbQixeT6Mwvg7TayREJ2gpKl3o2RoMdnqw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
 
   '@babel/generator@7.29.1':
     resolution: {integrity: sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helper-compilation-targets@7.28.6':
-    resolution: {integrity: sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==}
-    engines: {node: '>=6.9.0'}
+  '@babel/generator@8.0.0':
+    resolution: {integrity: sha512-NT9NrVwJsbSV6Y2FSstWa71EETOnzrjkL5/wX3D2mYHtKM+qvqB1DvR4D0Setb/gDBsHzRICifwEWMO8CnTF6g==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helper-compilation-targets@8.0.0':
+    resolution: {integrity: sha512-JwculLABZvyPvyLBpwU/E/IbH2uM3mnxNtIJpxnIfb24y1PrdVxK5Dqjle4DpgqpGRnwgC7G8IkzPdSXZrO1Ew==}
+    engines: {node: ^22.18.0 || >=24.11.0}
 
   '@babel/helper-globals@7.28.0':
     resolution: {integrity: sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/helper-globals@8.0.0':
+    resolution: {integrity: sha512-lLozHOM6sWWlxNo8CYqHy4MBZeTvHXNgVPBfPOGsjPKUzHC2Az9QwB6gxdQmpwHl6GlQtbGgS+lj5887guDiLw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
   '@babel/helper-module-imports@7.18.6':
     resolution: {integrity: sha512-0NFvs3VkuSYbFi1x2Vd6tKrywq+z/cLeYC/RJNFrIX/30Bf5aiGYbtvGXolEktzJH8o5E5KJ3tT+nkxuuZFVlA==}
     engines: {node: '>=6.9.0'}
@@ -765,12 +843,6 @@ packages:
     resolution: {integrity: sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helper-module-transforms@7.28.6':
-    resolution: {integrity: sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==}
-    engines: {node: '>=6.9.0'}
-    peerDependencies:
-      '@babel/core': ^7.0.0
-
   '@babel/helper-plugin-utils@7.28.6':
     resolution: {integrity: sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug==}
     engines: {node: '>=6.9.0'}
@@ -779,40 +851,53 @@ packages:
     resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/helper-string-parser@8.0.0':
+    resolution: {integrity: sha512-6mJgmFFFIIO82vvoLt9XtRC7/TkzXfts1t/SpRX4IHSzMgqoPYCWesVu1udUPUWioAE/2fcG6WuI8zrkE1gwrg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
   '@babel/helper-validator-identifier@7.28.5':
     resolution: {integrity: sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==}
     engines: {node: '>=6.9.0'}
 
-  '@babel/helper-validator-option@7.27.1':
-    resolution: {integrity: sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==}
-    engines: {node: '>=6.9.0'}
+  '@babel/helper-validator-identifier@8.0.2':
+    resolution: {integrity: sha512-9Fr9QeyCAyi1BR1jKZ6uYQ24EIhQUx5ReHfQU7drOE+TPOb+w11/dsqLkMOT2U29OdCT71XajrOT8xDc1C7orA==}
+    engines: {node: ^22.18.0 || >=24.11.0}
 
-  '@babel/helpers@7.29.2':
-    resolution: {integrity: sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==}
-    engines: {node: '>=6.9.0'}
+  '@babel/helper-validator-option@8.0.0':
+    resolution: {integrity: sha512-U4Dybxh4WESWHt5XhBeExi4DrY0/DNK1aHpQbsrQXCUbFHuMweT0TpLEWKvaraV2Y6fS+ZXunsZ8zIuZIgvF2Q==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helpers@8.0.0':
+    resolution: {integrity: sha512-wfbi91pM3py96oIiJEz7qIpyXDytgr9zQC1HEWwlGNVRAEmItuU/0a41ZUKu1sJGyhhOIpc4t5vk4PYzt8wpsg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
 
   '@babel/parser@7.29.2':
     resolution: {integrity: sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA==}
     engines: {node: '>=6.0.0'}
     hasBin: true
 
+  '@babel/parser@8.0.0':
+    resolution: {integrity: sha512-aLxAE+imI9bCcyaPrUDjBv3uSkWieifjLe0kuFOZF0zli0L6GCsTmsePnTr55adbIAgYz2zhN1vnFimCBUYcRQ==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+    hasBin: true
+
   '@babel/plugin-syntax-jsx@7.28.6':
     resolution: {integrity: sha512-wgEmr06G6sIpqr8YDwA2dSRTE3bJ+V0IfpzfSY3Lfgd7YWOaAdlykvJi13ZKBt8cZHfgH1IXN+CL656W3uUa4w==}
     engines: {node: '>=6.9.0'}
     peerDependencies:
-      '@babel/core': ^7.0.0-0
+      '@babel/core': '>=7.29.6'
 
   '@babel/plugin-transform-react-jsx-self@7.27.1':
     resolution: {integrity: sha512-6UzkCs+ejGdZ5mFFC/OCUrv028ab2fp1znZmCZjAOBKiBK2jXD1O+BPSfX8X2qjJ75fZBMSnQn3Rq2mrBJK2mw==}
     engines: {node: '>=6.9.0'}
     peerDependencies:
-      '@babel/core': ^7.0.0-0
+      '@babel/core': '>=7.29.6'
 
   '@babel/plugin-transform-react-jsx-source@7.27.1':
     resolution: {integrity: sha512-zbwoTsBruTeKB9hSq73ha66iFeJHuaFkUbwvqElnygoNbj/jHRsSeokowZFN3CZ64IvEqcmmkVe89OPXc7ldAw==}
     engines: {node: '>=6.9.0'}
     peerDependencies:
-      '@babel/core': ^7.0.0-0
+      '@babel/core': '>=7.29.6'
 
   '@babel/runtime@7.29.2':
     resolution: {integrity: sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==}
@@ -822,14 +907,26 @@ packages:
     resolution: {integrity: sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/template@8.0.0':
+    resolution: {integrity: sha512-eAD0QW/AlbamBbw0FeGiwasbCVPq5ncW0HNVyLP3B9czqLyh4gvw+5JTSNt6le9+ziAU7mqDZsKTHf3jTb4chQ==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
   '@babel/traverse@7.29.0':
     resolution: {integrity: sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/traverse@8.0.0':
+    resolution: {integrity: sha512-bxTj/W2VclGE6CctlfQOpxg8MPDzXArRqkOBePw8EHfebcjF7fETWSS3BriEECo+UiU/Yblq+xUtSImFu7cTbw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
   '@babel/types@7.29.0':
     resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==}
     engines: {node: '>=6.9.0'}
 
+  '@babel/types@8.0.0':
+    resolution: {integrity: sha512-K8ponJDxBwDHigkeFqaqT5wLGl4bTlwMafR8k7b5CPxr6Ww+UG9ls8Yx6Tcpboxu97eeGVEEyKcHmEyOwN1vSw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
   '@bramus/specificity@2.4.2':
     resolution: {integrity: sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==}
     hasBin: true
@@ -838,6 +935,47 @@ packages:
     resolution: {integrity: sha512-VERIM64vtTP1C4mxQ5thVT9fK0apjPFobqybMtA1UdUujWka24ERHbRHFGmpbbhp73MhV+KSsHQH9C6uOTdEQA==}
     engines: {node: '>=18'}
 
+  '@clack/core@1.4.2':
+    resolution: {integrity: sha512-0Ty/1Gfm+Kb07sXcuESjyKfwEhSy4Ns1AgeEisHb/bDY5fWme0tTeTkU14T1Gmcs17YIjB/teiDe4uaCghbYqQ==}
+    engines: {node: '>= 20.12.0'}
+
+  '@clack/prompts@1.6.0':
+    resolution: {integrity: sha512-EYlRokl8szrP9Z25qT5aepMdBjzBvHF9ZEhzIiUBc9guz/T31EqRgvD0QSgZcpE93xiwrr+OkB4nz0BZyF6fSA==}
+    engines: {node: '>= 20.12.0'}
+
+  '@codemirror/autocomplete@6.20.2':
+    resolution: {integrity: sha512-G5FPkgIiLjOgZMjqVjvuKQ1rGPtHogLldJr33eFJdVLtmwY+giGrlv/ewljLz6b9BSQLkjxuwBc6g6omDM+YxQ==}
+
+  '@codemirror/commands@6.10.3':
+    resolution: {integrity: sha512-JFRiqhKu+bvSkDLI+rUhJwSxQxYb759W5GBezE8Uc8mHLqC9aV/9aTC7yJSqCtB3F00pylrLCwnyS91Ap5ej4Q==}
+
+  '@codemirror/lang-css@6.3.1':
+    resolution: {integrity: sha512-kr5fwBGiGtmz6l0LSJIbno9QrifNMUusivHbnA1H6Dmqy4HZFte3UAICix1VuKo0lMPKQr2rqB+0BkKi/S3Ejg==}
+
+  '@codemirror/lang-html@6.4.11':
+    resolution: {integrity: sha512-9NsXp7Nwp891pQchI7gPdTwBuSuT3K65NGTHWHNJ55HjYcHLllr0rbIZNdOzas9ztc1EUVBlHou85FFZS4BNnw==}
+
+  '@codemirror/lang-javascript@6.2.5':
+    resolution: {integrity: sha512-zD4e5mS+50htS7F+TYjBPsiIFGanfVqg4HyUz6WNFikgOPf2BgKlx+TQedI1w6n/IqRBVBbBWmGFdLB/7uxO4A==}
+
+  '@codemirror/lang-markdown@6.5.0':
+    resolution: {integrity: sha512-0K40bZ35jpHya6FriukbgaleaqzBLZfOh7HuzqbMxBXkbYMJDxfF39c23xOgxFezR+3G+tR2/Mup+Xk865OMvw==}
+
+  '@codemirror/language@6.12.3':
+    resolution: {integrity: sha512-QwCZW6Tt1siP37Jet9Tb02Zs81TQt6qQrZR2H+eGMcFsL1zMrk2/b9CLC7/9ieP1fjIUMgviLWMmgiHoJrj+ZA==}
+
+  '@codemirror/lint@6.9.6':
+    resolution: {integrity: sha512-6Kp7r6XfCi/D/5sdXieMfg9pJU1bUEx96WITuLU6ESaKizCz0QHFMjY/TaFSbigDdEAIgi93itLBIUETP4oK+A==}
+
+  '@codemirror/search@6.7.0':
+    resolution: {integrity: sha512-ZvGm99wc/s2cITtMT15LFdn8aH/aS+V+DqyGq/N5ZlV5vWtH+nILvC2nw0zX7ByNoHHDZ2IxxdW38O0tc5nVHg==}
+
+  '@codemirror/state@6.6.0':
+    resolution: {integrity: sha512-4nbvra5R5EtiCzr9BTHiTLc+MLXK2QGiAVYMyi8PkQd3SR+6ixar/Q/01Fa21TBIDOZXgeWV4WppsQolSreAPQ==}
+
+  '@codemirror/view@6.43.0':
+    resolution: {integrity: sha512-V7ZCLQO3Jus9hzh2jVCCPW3mO4IBMr43O37PqSUYautJSnnJF41YlgLw21x0fLJTYvJ+Vkm6Gp+qKGH9pltgXA==}
+
   '@corvu/utils@0.4.2':
     resolution: {integrity: sha512-Ox2kYyxy7NoXdKWdHeDEjZxClwzO4SKM8plAaVwmAJPxHMqA0rLOoAsa+hBDwRLpctf+ZRnAd/ykguuJidnaTA==}
     peerDependencies:
@@ -889,6 +1027,14 @@ packages:
     resolution: {integrity: sha512-QxULHAm7cNu72w97JUNCBFODFaXpbDg+dP8b/oWFAZ2MTRppA3U00Y2L1HqaS4J6yBqxwa/Y3nMBaxVKbB/NsA==}
     engines: {node: '>=20.19.0'}
 
+  '@ctrl/tinycolor@4.2.0':
+    resolution: {integrity: sha512-kzyuwOAQnXJNLS9PSyrk0CWk35nWJW/zl/6KvnTBMFK65gm7U1/Z5BqjxeapjZCIhQcM/DsrEmcbRwDyXyXK4A==}
+    engines: {node: '>=14'}
+
+  '@derhuerst/http-basic@8.2.4':
+    resolution: {integrity: sha512-F9rL9k9Xjf5blCz8HsJRO4diy111cayL2vkY2XE4r4t3n0yPXVYy3KD3nJ1qbrSn9743UWSXH4IwuCa/HWlGFw==}
+    engines: {node: '>=6.0.0'}
+
   '@discoveryjs/json-ext@0.6.3':
     resolution: {integrity: sha512-4B4OijXeVNOPZlYA2oEwWOTkzyltLao+xbotHQeqN++Rv27Y6s818+n2Qkp8q+Fxhn0t/5lA5X1Mxktud8eayQ==}
     engines: {node: '>=14.17.0'}
@@ -905,8 +1051,8 @@ packages:
     cpu: [ppc64]
     os: [aix]
 
-  '@esbuild/aix-ppc64@0.27.4':
-    resolution: {integrity: sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==}
+  '@esbuild/aix-ppc64@0.27.7':
+    resolution: {integrity: sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==}
     engines: {node: '>=18'}
     cpu: [ppc64]
     os: [aix]
@@ -917,8 +1063,8 @@ packages:
     cpu: [arm64]
     os: [android]
 
-  '@esbuild/android-arm64@0.27.4':
-    resolution: {integrity: sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==}
+  '@esbuild/android-arm64@0.27.7':
+    resolution: {integrity: sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [android]
@@ -929,8 +1075,8 @@ packages:
     cpu: [arm]
     os: [android]
 
-  '@esbuild/android-arm@0.27.4':
-    resolution: {integrity: sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==}
+  '@esbuild/android-arm@0.27.7':
+    resolution: {integrity: sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==}
     engines: {node: '>=18'}
     cpu: [arm]
     os: [android]
@@ -941,8 +1087,8 @@ packages:
     cpu: [x64]
     os: [android]
 
-  '@esbuild/android-x64@0.27.4':
-    resolution: {integrity: sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==}
+  '@esbuild/android-x64@0.27.7':
+    resolution: {integrity: sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [android]
@@ -953,8 +1099,8 @@ packages:
     cpu: [arm64]
     os: [darwin]
 
-  '@esbuild/darwin-arm64@0.27.4':
-    resolution: {integrity: sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==}
+  '@esbuild/darwin-arm64@0.27.7':
+    resolution: {integrity: sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [darwin]
@@ -965,8 +1111,8 @@ packages:
     cpu: [x64]
     os: [darwin]
 
-  '@esbuild/darwin-x64@0.27.4':
-    resolution: {integrity: sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==}
+  '@esbuild/darwin-x64@0.27.7':
+    resolution: {integrity: sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [darwin]
@@ -977,8 +1123,8 @@ packages:
     cpu: [arm64]
     os: [freebsd]
 
-  '@esbuild/freebsd-arm64@0.27.4':
-    resolution: {integrity: sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==}
+  '@esbuild/freebsd-arm64@0.27.7':
+    resolution: {integrity: sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [freebsd]
@@ -989,8 +1135,8 @@ packages:
     cpu: [x64]
     os: [freebsd]
 
-  '@esbuild/freebsd-x64@0.27.4':
-    resolution: {integrity: sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==}
+  '@esbuild/freebsd-x64@0.27.7':
+    resolution: {integrity: sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [freebsd]
@@ -1001,8 +1147,8 @@ packages:
     cpu: [arm64]
     os: [linux]
 
-  '@esbuild/linux-arm64@0.27.4':
-    resolution: {integrity: sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==}
+  '@esbuild/linux-arm64@0.27.7':
+    resolution: {integrity: sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [linux]
@@ -1013,8 +1159,8 @@ packages:
     cpu: [arm]
     os: [linux]
 
-  '@esbuild/linux-arm@0.27.4':
-    resolution: {integrity: sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==}
+  '@esbuild/linux-arm@0.27.7':
+    resolution: {integrity: sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==}
     engines: {node: '>=18'}
     cpu: [arm]
     os: [linux]
@@ -1025,8 +1171,8 @@ packages:
     cpu: [ia32]
     os: [linux]
 
-  '@esbuild/linux-ia32@0.27.4':
-    resolution: {integrity: sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==}
+  '@esbuild/linux-ia32@0.27.7':
+    resolution: {integrity: sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==}
     engines: {node: '>=18'}
     cpu: [ia32]
     os: [linux]
@@ -1037,8 +1183,8 @@ packages:
     cpu: [loong64]
     os: [linux]
 
-  '@esbuild/linux-loong64@0.27.4':
-    resolution: {integrity: sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==}
+  '@esbuild/linux-loong64@0.27.7':
+    resolution: {integrity: sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==}
     engines: {node: '>=18'}
     cpu: [loong64]
     os: [linux]
@@ -1049,8 +1195,8 @@ packages:
     cpu: [mips64el]
     os: [linux]
 
-  '@esbuild/linux-mips64el@0.27.4':
-    resolution: {integrity: sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==}
+  '@esbuild/linux-mips64el@0.27.7':
+    resolution: {integrity: sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==}
     engines: {node: '>=18'}
     cpu: [mips64el]
     os: [linux]
@@ -1061,8 +1207,8 @@ packages:
     cpu: [ppc64]
     os: [linux]
 
-  '@esbuild/linux-ppc64@0.27.4':
-    resolution: {integrity: sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==}
+  '@esbuild/linux-ppc64@0.27.7':
+    resolution: {integrity: sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==}
     engines: {node: '>=18'}
     cpu: [ppc64]
     os: [linux]
@@ -1073,8 +1219,8 @@ packages:
     cpu: [riscv64]
     os: [linux]
 
-  '@esbuild/linux-riscv64@0.27.4':
-    resolution: {integrity: sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==}
+  '@esbuild/linux-riscv64@0.27.7':
+    resolution: {integrity: sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==}
     engines: {node: '>=18'}
     cpu: [riscv64]
     os: [linux]
@@ -1085,8 +1231,8 @@ packages:
     cpu: [s390x]
     os: [linux]
 
-  '@esbuild/linux-s390x@0.27.4':
-    resolution: {integrity: sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==}
+  '@esbuild/linux-s390x@0.27.7':
+    resolution: {integrity: sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==}
     engines: {node: '>=18'}
     cpu: [s390x]
     os: [linux]
@@ -1097,8 +1243,8 @@ packages:
     cpu: [x64]
     os: [linux]
 
-  '@esbuild/linux-x64@0.27.4':
-    resolution: {integrity: sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==}
+  '@esbuild/linux-x64@0.27.7':
+    resolution: {integrity: sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [linux]
@@ -1109,8 +1255,8 @@ packages:
     cpu: [arm64]
     os: [netbsd]
 
-  '@esbuild/netbsd-arm64@0.27.4':
-    resolution: {integrity: sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==}
+  '@esbuild/netbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [netbsd]
@@ -1121,8 +1267,8 @@ packages:
     cpu: [x64]
     os: [netbsd]
 
-  '@esbuild/netbsd-x64@0.27.4':
-    resolution: {integrity: sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==}
+  '@esbuild/netbsd-x64@0.27.7':
+    resolution: {integrity: sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [netbsd]
@@ -1133,8 +1279,8 @@ packages:
     cpu: [arm64]
     os: [openbsd]
 
-  '@esbuild/openbsd-arm64@0.27.4':
-    resolution: {integrity: sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==}
+  '@esbuild/openbsd-arm64@0.27.7':
+    resolution: {integrity: sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [openbsd]
@@ -1145,8 +1291,8 @@ packages:
     cpu: [x64]
     os: [openbsd]
 
-  '@esbuild/openbsd-x64@0.27.4':
-    resolution: {integrity: sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==}
+  '@esbuild/openbsd-x64@0.27.7':
+    resolution: {integrity: sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [openbsd]
@@ -1157,8 +1303,8 @@ packages:
     cpu: [arm64]
     os: [openharmony]
 
-  '@esbuild/openharmony-arm64@0.27.4':
-    resolution: {integrity: sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==}
+  '@esbuild/openharmony-arm64@0.27.7':
+    resolution: {integrity: sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [openharmony]
@@ -1169,8 +1315,8 @@ packages:
     cpu: [x64]
     os: [sunos]
 
-  '@esbuild/sunos-x64@0.27.4':
-    resolution: {integrity: sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==}
+  '@esbuild/sunos-x64@0.27.7':
+    resolution: {integrity: sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [sunos]
@@ -1181,8 +1327,8 @@ packages:
     cpu: [arm64]
     os: [win32]
 
-  '@esbuild/win32-arm64@0.27.4':
-    resolution: {integrity: sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==}
+  '@esbuild/win32-arm64@0.27.7':
+    resolution: {integrity: sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==}
     engines: {node: '>=18'}
     cpu: [arm64]
     os: [win32]
@@ -1193,8 +1339,8 @@ packages:
     cpu: [ia32]
     os: [win32]
 
-  '@esbuild/win32-ia32@0.27.4':
-    resolution: {integrity: sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==}
+  '@esbuild/win32-ia32@0.27.7':
+    resolution: {integrity: sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==}
     engines: {node: '>=18'}
     cpu: [ia32]
     os: [win32]
@@ -1205,8 +1351,8 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@esbuild/win32-x64@0.27.4':
-    resolution: {integrity: sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==}
+  '@esbuild/win32-x64@0.27.7':
+    resolution: {integrity: sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==}
     engines: {node: '>=18'}
     cpu: [x64]
     os: [win32]
@@ -1321,105 +1467,89 @@ packages:
     resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-libvips-linux-arm@1.2.4':
     resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==}
     cpu: [arm]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-libvips-linux-ppc64@1.2.4':
     resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==}
     cpu: [ppc64]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-libvips-linux-riscv64@1.2.4':
     resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==}
     cpu: [riscv64]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-libvips-linux-s390x@1.2.4':
     resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==}
     cpu: [s390x]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-libvips-linux-x64@1.2.4':
     resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-libvips-linuxmusl-arm64@1.2.4':
     resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@img/sharp-libvips-linuxmusl-x64@1.2.4':
     resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@img/sharp-linux-arm64@0.34.5':
     resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-linux-arm@0.34.5':
     resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-linux-ppc64@0.34.5':
     resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [ppc64]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-linux-riscv64@0.34.5':
     resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [riscv64]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-linux-s390x@0.34.5':
     resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [s390x]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-linux-x64@0.34.5':
     resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@img/sharp-linuxmusl-arm64@0.34.5':
     resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@img/sharp-linuxmusl-x64@0.34.5':
     resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==}
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@img/sharp-wasm32@0.34.5':
     resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==}
@@ -1444,6 +1574,140 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@inquirer/ansi@2.0.5':
+    resolution: {integrity: sha512-doc2sWgJpbFQ64UflSVd17ibMGDuxO1yKgOgLMwavzESnXjFWJqUeG8saYosqKpHp4kWiM5x1nXvEjbpx90gzw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+
+  '@inquirer/checkbox@5.1.5':
+    resolution: {integrity: sha512-Jmf9tgBHIEK5SAOB7swYfStqmtkZb00xOTpSQmkoGEpdxOTpJi9RS0A8bkfDPHTTItZRJrRdZrEMu25wyj0VfQ==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/confirm@6.0.13':
+    resolution: {integrity: sha512-wkGPC7yJ5WJk1DJ5SX7fzk+gfj4BM8cf5dDDi71B/551xHrdsZVRJOC0WyikXd0pEsb/9cLniuE4atbsMqmFkw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/core@11.1.10':
+    resolution: {integrity: sha512-a4Q5BXHQAHa9eO202sTaFCHFYVB3x5fauDuThEAdZ9gfn76pSxiKU7wWcEH0N1O0XmQvNfQNU6QXpiRxmYQx+A==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/editor@5.1.2':
+    resolution: {integrity: sha512-Y3Nor7S/DhIPo+8Ym/dSY4efwKI4BsflKDwXh0jNeXJsSF3dteS/3Yf+z4wkibVZDvYMyCgknSTQlNahfunGHg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/expand@5.0.14':
+    resolution: {integrity: sha512-qyY9zcIX2eKYwaAUiQo9zORd61Lc3sXeM72fVbeHkYnDkqfr8/armcRbmVAIrExeJhI2puk+uomeKtWrpUVUmQ==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/external-editor@3.0.0':
+    resolution: {integrity: sha512-lDSwMgg+M5rq6JKBYaJwSX6T9e/HK2qqZ1oxmOwn4AQoJE5D+7TumsxLGC02PWS//rkIVqbZv3XA3ejsc9FYvg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/figures@2.0.5':
+    resolution: {integrity: sha512-NsSs4kzfm12lNetHwAn3GEuH317IzpwrMCbOuMIVytpjnJ90YYHNwdRgYGuKmVxwuIqSgqk3M5qqQt1cDk0tGQ==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+
+  '@inquirer/input@5.0.13':
+    resolution: {integrity: sha512-0l0jCHlJnXIV8CTxwQC0C+5Ziq8WP22edWgmciW2xYvoeoSck4v5FvCS1ctKdqLLR0dUo93uAHgWHywgBSoRyw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/number@4.0.13':
+    resolution: {integrity: sha512-WHmkYnnJAou5gx7RgcvAfUggnHNM1zWfoh0dFPl3dxVssuqt+dK5rIbaOYQXNyOegvFnopbKupjnhw2O8gANNg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/password@5.0.13':
+    resolution: {integrity: sha512-XDGu64ROHZjOOXLAANvJN7iIxWKhOSCG5VakrZ5kaScVR+snVJCFglD/hL3/677awtWcu4pXoWa280CDIYcBeg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/prompts@8.4.3':
+    resolution: {integrity: sha512-ai5LseTw9HhegupIgmo4cn7RpnCGznjjXu4OI+7jMR8vu7T1ZCCNMzFFAovUCjL1fl0cceksIN1++yQE59SmZw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/rawlist@5.2.9':
+    resolution: {integrity: sha512-a1ErXEfgjfPYpyQ89dp+7n2IISjH9oQg3ygvF5adz8B7aHn4n2PjEgu1wpVTp69K3bj3lVLxP0qJ2b1clk1Whw==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/search@4.1.9':
+    resolution: {integrity: sha512-ZlbM28Q9lmLkFPNAIv+ZuY530n5Km8U1WW48oYEvDhe9yc2uL3m3t+JSdRUkQlk5fuIuskgiIVjcb7czFzQpuA==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/select@5.1.5':
+    resolution: {integrity: sha512-6SRg6kHfK/sjLXOsuqNebuir+sjwrf/iWuRUnXgB2slzEewppI1WfzeS16XxDcOQmXBruMmmB9Cgrz7wsAxqMg==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/type@4.0.5':
+    resolution: {integrity: sha512-aetVUNeKNc/VriqXlw1NRSW0zhMBB0W4bNbWRJgzRl/3d0QNDQFfk0GO5SDdtjMZVg6o8ZKEiadd7SCCzoOn5Q==}
+    engines: {node: '>=23.5.0 || ^22.13.0 || ^21.7.0 || ^20.12.0'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
   '@internationalized/date@3.12.1':
     resolution: {integrity: sha512-6IedsVWXyq4P9Tj+TxuU8WGWM70hYLl12nbYU8jkikVpa6WXapFazPUcHUMDMoWftIDE2ILDkFFte6W2nFCkRQ==}
 
@@ -1605,6 +1869,38 @@ packages:
   '@leichtgewicht/ip-codec@2.0.5':
     resolution: {integrity: sha512-Vo+PSpZG2/fmgmiNzYK9qWRh8h/CHrwD0mo1h1DzL4yzHNSfWYujGTYsWGreD000gcgmZ7K4Ys6Tx9TxtsKdDw==}
 
+  '@lezer/common@1.5.2':
+    resolution: {integrity: sha512-sxQE460fPZyU3sdc8lafxiPwJHBzZRy/udNFynGQky1SePYBdhkBl1kOagA9uT3pxR8K09bOrmTUqA9wb/PjSQ==}
+
+  '@lezer/css@1.3.3':
+    resolution: {integrity: sha512-RzBo8r+/6QJeow7aPHIpGVIH59xTcJXp399820gZoMo9noQDRVpJLheIBUicYwKcsbOYoBRoLZlf2720dG/4Tg==}
+
+  '@lezer/highlight@1.2.3':
+    resolution: {integrity: sha512-qXdH7UqTvGfdVBINrgKhDsVTJTxactNNxLk7+UMwZhU13lMHaOBlJe9Vqp907ya56Y3+ed2tlqzys7jDkTmW0g==}
+
+  '@lezer/html@1.3.13':
+    resolution: {integrity: sha512-oI7n6NJml729m7pjm9lvLvmXbdoMoi2f+1pwSDJkl9d68zGr7a9Btz8NdHTGQZtW2DA25ybeuv/SyDb9D5tseg==}
+
+  '@lezer/javascript@1.5.4':
+    resolution: {integrity: sha512-vvYx3MhWqeZtGPwDStM2dwgljd5smolYD2lR2UyFcHfxbBQebqx8yjmFmxtJ/E6nN6u1D9srOiVWm3Rb4tmcUA==}
+
+  '@lezer/lr@1.4.10':
+    resolution: {integrity: sha512-rnCpTIBafOx4mRp43xOxDJbFipJm/c0cia/V5TiGlhmMa+wsSdoGmUN3w5Bqrks/09Q/D4tNAmWaT8p6NRi77A==}
+
+  '@lezer/markdown@1.6.3':
+    resolution: {integrity: sha512-jpGm5Ps+XErS+xA4urw7ogEGkeZOahVQF21Z6oECF0sj+2liwZopd2+I8uH5I/vZsRuuze3OxBREIANLf6KKUw==}
+
+  '@lit-labs/ssr-dom-shim@1.6.0':
+    resolution: {integrity: sha512-VHb0ALPMTlgKjM6yIxxoQNnpKyUKLD04VzeQdsiXkMqkvYlAHxq9glGLmgbb889/1GsohSOAjvQYoiBppXFqrQ==}
+
+  '@lit/react@1.0.8':
+    resolution: {integrity: sha512-p2+YcF+JE67SRX3mMlJ1TKCSTsgyOVdAwd/nxp3NuV1+Cb6MWALbN6nT7Ld4tpmYofcE5kcaSY1YBB9erY+6fw==}
+    peerDependencies:
+      '@types/react': 17 || 18 || 19
+
+  '@lit/reactive-element@2.1.2':
+    resolution: {integrity: sha512-pbCDiVMnne1lYUIaYNN5wrwQXDtHaYtg7YEFPeW+hws6U47WeFvISGUWekPGKWOP1ygrs0ef0o1VJMk1exos5A==}
+
   '@mantine/core@7.17.8':
     resolution: {integrity: sha512-42sfdLZSCpsCYmLCjSuntuPcDg3PLbakSmmYfz5Auea8gZYLr+8SS5k647doVu0BRAecqYOytkX2QC5/u/8VHw==}
     peerDependencies:
@@ -1617,6 +1913,9 @@ packages:
     peerDependencies:
       react: ^18.x || ^19.x
 
+  '@marijn/find-cluster-break@1.0.2':
+    resolution: {integrity: sha512-l0h88YhZFyKdXIFNfSWpyjStDjGHwZ/U7iobcK1cQQD8sejsONdQtTVU+1wVN1PBw40PiiHB1vA5S7VTfQiP9g==}
+
   '@noble/hashes@1.4.0':
     resolution: {integrity: sha512-V1JJ1WTRUqHHrOSh597hURcMqVKVGL/ea3kv0gSnEdsEZ0/+VyPghM1lMNGc00z7CIQorSvbKpuJkxvuHbvdbg==}
     engines: {node: '>= 16'}
@@ -2476,79 +2775,66 @@ packages:
     resolution: {integrity: sha512-RzeBwv0B3qtVBWtcuABtSuCzToo2IEAIQrcyB/b2zMvBWVbjo8bZDjACUpnaafaxhTw2W+imQbP2BD1usasK4g==}
     cpu: [arm]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-arm-musleabihf@4.60.0':
     resolution: {integrity: sha512-Sf7zusNI2CIU1HLzuu9Tc5YGAHEZs5Lu7N1ssJG4Tkw6e0MEsN7NdjUDDfGNHy2IU+ENyWT+L2obgWiguWibWQ==}
     cpu: [arm]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-arm64-gnu@4.60.0':
     resolution: {integrity: sha512-DX2x7CMcrJzsE91q7/O02IJQ5/aLkVtYFryqCjduJhUfGKG6yJV8hxaw8pZa93lLEpPTP/ohdN4wFz7yp/ry9A==}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-arm64-musl@4.60.0':
     resolution: {integrity: sha512-09EL+yFVbJZlhcQfShpswwRZ0Rg+z/CsSELFCnPt3iK+iqwGsI4zht3secj5vLEs957QvFFXnzAT0FFPIxSrkQ==}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-loong64-gnu@4.60.0':
     resolution: {integrity: sha512-i9IcCMPr3EXm8EQg5jnja0Zyc1iFxJjZWlb4wr7U2Wx/GrddOuEafxRdMPRYVaXjgbhvqalp6np07hN1w9kAKw==}
     cpu: [loong64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-loong64-musl@4.60.0':
     resolution: {integrity: sha512-DGzdJK9kyJ+B78MCkWeGnpXJ91tK/iKA6HwHxF4TAlPIY7GXEvMe8hBFRgdrR9Ly4qebR/7gfUs9y2IoaVEyog==}
     cpu: [loong64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-ppc64-gnu@4.60.0':
     resolution: {integrity: sha512-RwpnLsqC8qbS8z1H1AxBA1H6qknR4YpPR9w2XX0vo2Sz10miu57PkNcnHVaZkbqyw/kUWfKMI73jhmfi9BRMUQ==}
     cpu: [ppc64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-ppc64-musl@4.60.0':
     resolution: {integrity: sha512-Z8pPf54Ly3aqtdWC3G4rFigZgNvd+qJlOE52fmko3KST9SoGfAdSRCwyoyG05q1HrrAblLbk1/PSIV+80/pxLg==}
     cpu: [ppc64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-riscv64-gnu@4.60.0':
     resolution: {integrity: sha512-3a3qQustp3COCGvnP4SvrMHnPQ9d1vzCakQVRTliaz8cIp/wULGjiGpbcqrkv0WrHTEp8bQD/B3HBjzujVWLOA==}
     cpu: [riscv64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-riscv64-musl@4.60.0':
     resolution: {integrity: sha512-pjZDsVH/1VsghMJ2/kAaxt6dL0psT6ZexQVrijczOf+PeP2BUqTHYejk3l6TlPRydggINOeNRhvpLa0AYpCWSQ==}
     cpu: [riscv64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-linux-s390x-gnu@4.60.0':
     resolution: {integrity: sha512-3ObQs0BhvPgiUVZrN7gqCSvmFuMWvWvsjG5ayJ3Lraqv+2KhOsp+pUbigqbeWqueGIsnn+09HBw27rJ+gYK4VQ==}
     cpu: [s390x]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-x64-gnu@4.60.0':
     resolution: {integrity: sha512-EtylprDtQPdS5rXvAayrNDYoJhIz1/vzN2fEubo3yLE7tfAw+948dO0g4M0vkTVFhKojnF+n6C8bDNe+gDRdTg==}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@rollup/rollup-linux-x64-musl@4.60.0':
     resolution: {integrity: sha512-k09oiRCi/bHU9UVFqD17r3eJR9bn03TyKraCrlz5ULFJGdJGi7VOmm9jl44vOJvRJ6P7WuBi/s2A97LxxHGIdw==}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@rollup/rollup-openbsd-x64@4.60.0':
     resolution: {integrity: sha512-1o/0/pIhozoSaDJoDcec+IVLbnRtQmHwPV730+AOD29lHEEo4F5BEUB24H0OBdhbBBDwIOSuf7vgg0Ywxdfiiw==}
@@ -2580,27 +2866,47 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@shikijs/core@3.23.0':
-    resolution: {integrity: sha512-NSWQz0riNb67xthdm5br6lAkvpDJRTgB36fxlo37ZzM2yq0PQFFzbd8psqC2XMPgCzo1fW6cVi18+ArJ44wqgA==}
+  '@shikijs/core@4.2.0':
+    resolution: {integrity: sha512-Hc87Ab1Ld/vEbZRCbwx344I5v+4RU8CVToUTRkqXL1+TjbuOp9U5Xa0M23V4GEWHxVn+yO5otb+HkQVm3ptWQQ==}
+    engines: {node: '>=20'}
 
-  '@shikijs/engine-javascript@3.23.0':
-    resolution: {integrity: sha512-aHt9eiGFobmWR5uqJUViySI1bHMqrAgamWE1TYSUoftkAeCCAiGawPMwM+VCadylQtF4V3VNOZ5LmfItH5f3yA==}
+  '@shikijs/engine-javascript@4.2.0':
+    resolution: {integrity: sha512-fjETeq1k5ffyXqRgS6+3hpvqseLalp1kjNfRbXpUgWR8FpZ1CmQfiNHovc5lncYjt/Vg5JK/WJEmLahjwMa0og==}
+    engines: {node: '>=20'}
 
-  '@shikijs/engine-oniguruma@3.23.0':
-    resolution: {integrity: sha512-1nWINwKXxKKLqPibT5f4pAFLej9oZzQTsby8942OTlsJzOBZ0MWKiwzMsd+jhzu8YPCHAswGnnN1YtQfirL35g==}
+  '@shikijs/engine-oniguruma@4.2.0':
+    resolution: {integrity: sha512-hTorK1dffPkpbMUk6Z+828PgRo7d07HbnizoP0hNPFjhxMHctj0Px/qoHeGMYafc6ju+u9iMldN4JbVzNQM++g==}
+    engines: {node: '>=20'}
+
+  '@shikijs/langs@4.2.0':
+    resolution: {integrity: sha512-bwrVRlJ0wUhZxAbVdvBbv2TTC9yLsh4C/IO5Ofz0T8MQntgDvyVnkbjw9vi50r1kx7RCIJdnJnjZAwmAsXFLZQ==}
+    engines: {node: '>=20'}
 
-  '@shikijs/langs@3.23.0':
-    resolution: {integrity: sha512-2Ep4W3Re5aB1/62RSYQInK9mM3HsLeB91cHqznAJMuylqjzNVAVCMnNWRHFtcNHXsoNRayP9z1qj4Sq3nMqYXg==}
+  '@shikijs/primitive@4.2.0':
+    resolution: {integrity: sha512-NOq+DtUkVBJtZMVXL5A0vI0Xk8nvDYaXetFHSJFlOqjDZIVhIPRYFdGkSoElDqNuegikcc3A76SNUa8dTqtAYA==}
+    engines: {node: '>=20'}
 
-  '@shikijs/themes@3.23.0':
-    resolution: {integrity: sha512-5qySYa1ZgAT18HR/ypENL9cUSGOeI2x+4IvYJu4JgVJdizn6kG4ia5Q1jDEOi7gTbN4RbuYtmHh0W3eccOrjMA==}
+  '@shikijs/themes@4.2.0':
+    resolution: {integrity: sha512-RX8IHYeLv8Cu2W6ruc3RxUqWn0IYCqSrMBzi/uRGAmfyDNOnNO5BF/Px7o97n4XTpmFTo5GbRaazuOWj+2ak2w==}
+    engines: {node: '>=20'}
 
-  '@shikijs/types@3.23.0':
-    resolution: {integrity: sha512-3JZ5HXOZfYjsYSk0yPwBrkupyYSLpAE26Qc0HLghhZNGTZg/SKxXIIgoxOpmmeQP0RRSDJTk1/vPfw9tbw+jSQ==}
+  '@shikijs/types@4.2.0':
+    resolution: {integrity: sha512-VT/MKtlpOhEPZloSH3Pb9WCZEBDoQVMa9jedp5UAwmJOar1DVc9DRODAxmYPW9M93IK4ryuqRejFfmlvlVDemw==}
+    engines: {node: '>=20'}
 
   '@shikijs/vscode-textmate@10.0.2':
     resolution: {integrity: sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==}
 
+  '@shoelace-style/animations@1.2.0':
+    resolution: {integrity: sha512-avvo1xxkLbv2dgtabdewBbqcJfV0e0zCwFqkPMnHFGbJbBHorRFfMAHh1NG9ymmXn0jW95ibUVH03E1NYXD6Gw==}
+
+  '@shoelace-style/localize@3.2.2':
+    resolution: {integrity: sha512-h3+2/cFWGaw3KQUwintkP4Cy3PtrVW//ysr9DM5nOfIXYekgrHwsELk/nyxc8hmjVP/Kcon7KCzvUtSwUBipfQ==}
+
+  '@shoelace-style/shoelace@2.20.1':
+    resolution: {integrity: sha512-FSghU95jZPGbwr/mybVvk66qRZYpx5FkXL+vLNpy1Vp8UsdwSxXjIHE3fsvMbKWTKi9UFfewHTkc5e7jAqRYoQ==}
+    engines: {node: '>=14.17.0'}
+
   '@solid-primitives/event-listener@2.4.5':
     resolution: {integrity: sha512-nwRV558mIabl4yVAhZKY8cb6G+O1F0M6Z75ttTu5hk+SxdOnKSGj+eetDIu7Oax1P138ZdUU01qnBPR8rnxaEA==}
     peerDependencies:
@@ -2662,8 +2968,8 @@ packages:
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
-  '@sveltejs/acorn-typescript@1.0.9':
-    resolution: {integrity: sha512-lVJX6qEgs/4DOcRTpo56tmKzVPtoWAaVbL4hfO7t7NVwl9AAXzQR6cihesW1BmNMPl+bK6dreu2sOKBP2Q9CIA==}
+  '@sveltejs/acorn-typescript@1.0.10':
+    resolution: {integrity: sha512-4WfKk68eTih+MiJD4fSbxN7E8kVBmTMPWHUPYjvl2N0rMs53YLTT8/YjKU5Dtnz5LqDjl7LEw4U7lXR2W3J5WA==}
     peerDependencies:
       acorn: ^8.9.0
 
@@ -2672,15 +2978,15 @@ packages:
     engines: {node: ^18.0.0 || ^20.0.0 || >=22}
     peerDependencies:
       '@sveltejs/vite-plugin-svelte': ^5.0.0
-      svelte: ^5.0.0
-      vite: ^6.0.0
+      svelte: '>=5.55.7 <6'
+      vite: '>=6.4.3 <7'
 
   '@sveltejs/vite-plugin-svelte@5.1.1':
     resolution: {integrity: sha512-Y1Cs7hhTc+a5E9Va/xwKlAJoariQyHY+5zBgCZg4PFWNYQ1nMN9sjK1zhw1gK69DuqVP++sht/1GZg1aRwmAXQ==}
     engines: {node: ^18.0.0 || ^20.0.0 || >=22}
     peerDependencies:
-      svelte: ^5.0.0
-      vite: ^6.0.0
+      svelte: '>=5.55.7 <6'
+      vite: '>=6.4.3 <7'
 
   '@swc/core-darwin-arm64@1.15.30':
     resolution: {integrity: sha512-VvpP+vq08HmGYewMWvrdsxh9s2lthz/808zXm8Yu5kaqeR8Yia2b0eYXleHQ3VAjoStUDk6LzTheBW9KXYQdMA==}
@@ -2705,42 +3011,36 @@ packages:
     engines: {node: '>=10'}
     cpu: [arm64]
     os: [linux]
-    libc: [glibc]
 
   '@swc/core-linux-arm64-musl@1.15.30':
     resolution: {integrity: sha512-1SYGs2l0Yyyi0pR/P/NKz/x0kqxkoiw+BXeJjLUdecSk/KasncWlJrc6hOvFSgKHOBrzgM5jwuluKtlT8dnrcA==}
     engines: {node: '>=10'}
     cpu: [arm64]
     os: [linux]
-    libc: [musl]
 
   '@swc/core-linux-ppc64-gnu@1.15.30':
     resolution: {integrity: sha512-TXREtiXeRhbfDFbmhnkIsXpKfzbfT73YkV2ZF6w0sfxgjC5zI2ZAbaCOq25qxvegofj2K93DtOpm9RLaBgqR2g==}
     engines: {node: '>=10'}
     cpu: [ppc64]
     os: [linux]
-    libc: [glibc]
 
   '@swc/core-linux-s390x-gnu@1.15.30':
     resolution: {integrity: sha512-DCR2YYeyd6DQE4OuDhImouuNcjXEiEdnn1Y0DyGteugPEDvVuvYk8Xddi+4o2SgWH6jiW8/I+3emZvbep1NC+g==}
     engines: {node: '>=10'}
     cpu: [s390x]
     os: [linux]
-    libc: [glibc]
 
   '@swc/core-linux-x64-gnu@1.15.30':
     resolution: {integrity: sha512-5Pizw3NgfOJ5BJOBK8TIRa59xFW2avESTOBDPTAYwZYa1JNDs+KMF9lUfjJiJLM5HiMs/wPheA9eiT0q9m2AoA==}
     engines: {node: '>=10'}
     cpu: [x64]
     os: [linux]
-    libc: [glibc]
 
   '@swc/core-linux-x64-musl@1.15.30':
     resolution: {integrity: sha512-qyqydP/wyH8alcIP4a2hnGSjHLJjm9H7yDFup+CPy9oTahFgLLwnNcv5UHXqO2Qs3AIND+cls5f/Bb6hqpxdgA==}
     engines: {node: '>=10'}
     cpu: [x64]
     os: [linux]
-    libc: [musl]
 
   '@swc/core-win32-arm64-msvc@1.15.30':
     resolution: {integrity: sha512-CaQENgDHVGOg1mSF5sQVgvfFHG9kjMor2rkLMLeLOkfZYNj13ppnJ9+lfaBZLZUMMbnlGQnavCJb8PVBUOso7Q==}
@@ -2826,6 +3126,9 @@ packages:
   '@types/express@4.17.25':
     resolution: {integrity: sha512-dVd04UKsfpINUnK0yBoYHDF3xu7xVH4BuDotC/xGuycx4CgbP48X/KF/586bcObxT0HENHXEU8Nqtu6NR+eKhw==}
 
+  '@types/gensync@1.0.5':
+    resolution: {integrity: sha512-MbsRCT7mTikHwKZ0X+LVUTLRrZZRLipTuXEO9qOYO+zmjMVk81axyClMROf6uoPD9MRVu46bx8zoR0Ad9q3NAg==}
+
   '@types/hast@3.0.4':
     resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
 
@@ -2841,6 +3144,12 @@ packages:
   '@types/js-yaml@4.0.9':
     resolution: {integrity: sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==}
 
+  '@types/jsdom@28.0.3':
+    resolution: {integrity: sha512-/HQ2uFoetFTXuye8vzIcHw2z6Fwi7Hi/qcgC+RoS9NCyewiqxhVGqlG+ViGB6lkax481R6dmhf1I7lIGlzJStQ==}
+
+  '@types/jsesc@2.5.1':
+    resolution: {integrity: sha512-9VN+6yxLOPLOav+7PwjZbxiID2bVaeq0ED4qSQmdQTdjnXJSaCVKTR58t15oqH1H5t8Ng2ZX1SabJVoN9Q34bw==}
+
   '@types/json-schema@7.0.15':
     resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
 
@@ -2862,6 +3171,9 @@ packages:
   '@types/nlcst@2.0.3':
     resolution: {integrity: sha512-vSYNSDe6Ix3q+6Z7ri9lyWqgGhJTmzRjZRqyq15N0Z/1/UnVsno9G/N40NBijoYx2seFDIl0+B2mgAb9mezUCA==}
 
+  '@types/node@10.17.60':
+    resolution: {integrity: sha512-F0KIgDJfy2nA3zMLmWGKxcH2ZVEtCZXHHdOQs2gSaQ27+lNeEfGxzkIw90aXswATX7AZ33tahPbzy6KAfUreVw==}
+
   '@types/node@25.5.0':
     resolution: {integrity: sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw==}
 
@@ -2900,6 +3212,9 @@ packages:
   '@types/sockjs@0.3.36':
     resolution: {integrity: sha512-MK9V6NzAS1+Ud7JV9lJLFqW85VbC9dq3LmwZCuBe4wBDgKC0Kj/jd8Xl+nSviU+Qc3+m7umHHyHg//2KSa0a0Q==}
 
+  '@types/tough-cookie@4.0.5':
+    resolution: {integrity: sha512-/Ad8+nIOV7Rl++6f1BdKxFSMgmoqEoYbHRpPcx3JEfv8VRsQe9Z4mCXeJBzxs7mbHY/XOZZuXlRNfhpVPbs6ZA==}
+
   '@types/trusted-types@2.0.7':
     resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
 
@@ -2915,23 +3230,24 @@ packages:
 
   '@ungap/structured-clone@1.3.0':
     resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==}
+    deprecated: Potential CWE-502 - Update to 1.3.1 or higher
 
   '@vitejs/plugin-react-swc@3.11.0':
     resolution: {integrity: sha512-YTJCGFdNMHCMfjODYtxRNVAYmTWQ1Lb8PulP/2/f/oEEtglw8oKxKIZmmRkyXrVrHfsKOaVkAc3NT9/dMutO5w==}
     peerDependencies:
-      vite: ^4 || ^5 || ^6 || ^7
+      vite: '>=6.4.3 <7'
 
   '@vitejs/plugin-react@4.7.0':
     resolution: {integrity: sha512-gUu9hwfWvvEDBBmgtAowQCojwZmJ5mcLn3aufeCsitijs3+f2NsrPtlAWIR6OPiqljl96GVCUbLe0HyqIpVaoA==}
     engines: {node: ^14.18.0 || >=16.0.0}
     peerDependencies:
-      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
+      vite: '>=6.4.3 <7'
 
   '@vitejs/plugin-vue@5.2.4':
     resolution: {integrity: sha512-7Yx/SXSOcQq5HiiV3orevHUFn+pmMB4cgbEkDYgnkUWb0WfeQ/wa2yFv6D5ICiCQOVpjA7vYDXrC7AGO8yjDHA==}
     engines: {node: ^18.0.0 || >=20.0.0}
     peerDependencies:
-      vite: ^5.0.0 || ^6.0.0
+      vite: '>=6.4.3 <7'
       vue: ^3.2.25
 
   '@vitest/expect@4.1.2':
@@ -2941,7 +3257,7 @@ packages:
     resolution: {integrity: sha512-Ize4iQtEALHDttPRCmN+FKqOl2vxTiNUhzobQFFt/BM1lRUTG7zRCLOykG/6Vo4E4hnUdfVLo5/eqKPukcWW7Q==}
     peerDependencies:
       msw: ^2.4.9
-      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+      vite: '>=6.4.3 <7'
     peerDependenciesMeta:
       msw:
         optional: true
@@ -3135,6 +3451,10 @@ packages:
     engines: {node: '>=0.4.0'}
     hasBin: true
 
+  agent-base@6.0.2:
+    resolution: {integrity: sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==}
+    engines: {node: '>= 6.0.0'}
+
   ajv-formats@2.1.1:
     resolution: {integrity: sha512-Wx0Kx52hxE7C18hkMEggYlEifqWZtYaRgouJor+WMdPnQyEK13vgEWyVNup7SoeeoLMsr4kf5h6dOW11I15MUA==}
     peerDependencies:
@@ -3162,9 +3482,6 @@ packages:
   alien-signals@1.0.13:
     resolution: {integrity: sha512-OGj9yyTnJEttvzhTUWuscOvtqxq5vrhF7vL9oS0xJ2mK0ItPYP1/y+vCFebfxoEyAz0++1AIwJ5CMr+Fk3nDmg==}
 
-  ansi-align@3.0.1:
-    resolution: {integrity: sha512-IOfwwBF5iczOjp/WeY4YxyjqAFMQoZufdQWDd19SEExbVLNXqvpzSJ/M7Za4/sCPmQ0+GRquoA7bGcINcxew6w==}
-
   ansi-html-community@0.0.8:
     resolution: {integrity: sha512-1APHAyr3+PCamwNw3bXCPp4HFLONZt/yIH0sZp0/469KWNTEy+qN5jQ3GVX6DMZ1UXAi34yVwtTeaG/HpBuuzw==}
     engines: {'0': node >= 0.8.0}
@@ -3174,18 +3491,10 @@ packages:
     resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
     engines: {node: '>=8'}
 
-  ansi-regex@6.2.2:
-    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
-    engines: {node: '>=12'}
-
   ansi-styles@4.3.0:
     resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
     engines: {node: '>=8'}
 
-  ansi-styles@6.2.3:
-    resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
-    engines: {node: '>=12'}
-
   antenna-component-library@file:../antenna-component-library:
     resolution: {directory: ../antenna-component-library, type: directory}
     peerDependencies:
@@ -3195,7 +3504,7 @@ packages:
       '@vueup/vue-quill': ^1.x
       ace-builds: ^1.x
       ajv: ^8.x
-      dompurify: '>=3.4.0'
+      dompurify: '>=3.4.9'
       marked: ^15.x
       quill: ^2.x
       vue: ^3.5.18
@@ -3248,9 +3557,9 @@ packages:
     resolution: {integrity: sha512-cbdCP0PGOBq0ASG+sjnKIoYkWMKhhz+F/h9pRexUdX2Hd38+WOlBkRKlqkGOSm0YQpcFMQBJeK4WspUAkwsEdg==}
     engines: {node: '>=20.19.0'}
 
-  astro@5.18.1:
-    resolution: {integrity: sha512-m4VWilWZ+Xt6NPoYzC4CgGZim/zQUO7WFL0RHCH0AiEavF1153iC3+me2atDvXpf/yX4PyGUeD8wZLq1cirT3g==}
-    engines: {node: 18.20.8 || ^20.3.0 || >=22.0.0, npm: '>=9.6.5', pnpm: '>=7.1.0'}
+  astro@6.4.8:
+    resolution: {integrity: sha512-KK5lX90uU9EeVaTjINyj3sy9/NFXVa59aowaqbWBDDKLXZh4rr7GwIaCFYVetE22MJtsCNFerQXn0vlCLmpP/Q==}
+    engines: {node: '>=22.12.0', npm: '>=9.6.5', pnpm: '>=7.1.0'}
     hasBin: true
 
   async-validator@4.2.5:
@@ -3265,7 +3574,7 @@ packages:
     engines: {node: ^10 || ^12 || >=14}
     hasBin: true
     peerDependencies:
-      postcss: ^8.1.0
+      postcss: '>=8.5.10'
 
   avvio@9.2.0:
     resolution: {integrity: sha512-2t/sy01ArdHHE0vRH5Hsay+RtCZt3dLPji7W7/MMOCEgze5b7SNDC4j5H6FnVgPkI1MTNFGzHdHrVXDDl7QSSQ==}
@@ -3281,12 +3590,12 @@ packages:
   babel-plugin-jsx-dom-expressions@0.40.6:
     resolution: {integrity: sha512-v3P1MW46Lm7VMpAkq0QfyzLWWkC8fh+0aE5Km4msIgDx5kjenHU0pF2s+4/NH8CQn/kla6+Hvws+2AF7bfV5qQ==}
     peerDependencies:
-      '@babel/core': ^7.20.12
+      '@babel/core': '>=7.29.6'
 
   babel-preset-solid@1.9.12:
     resolution: {integrity: sha512-LLqnuKVDlKpyBlMPcH6qEvs/wmS9a+NczppxJ3ryS/c0O5IiSFOIBQi9GzyiGDSbcJpx4Gr87jyFTos1MyEuWg==}
     peerDependencies:
-      '@babel/core': ^7.0.0
+      '@babel/core': '>=7.29.6'
       solid-js: ^1.9.12
     peerDependenciesMeta:
       solid-js:
@@ -3298,9 +3607,6 @@ packages:
   balanced-match@1.0.2:
     resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
 
-  base-64@1.0.0:
-    resolution: {integrity: sha512-kwDPIFCGx0NZHog36dj+tHiwP4QMzsZ3AgMViUBKI0+V5n4U0ufTCUMhnQ04diaRI8EX/QcPfql7zlhZ7j4zgg==}
-
   base64-arraybuffer@1.0.2:
     resolution: {integrity: sha512-I3yl4r9QB5ZRY3XuJVEPfc2XhZO6YweFPI+UovAzn+8/hb3oJ6lnysaFcjVpkCPfVWFUDvoZ8kmVDP7WyRtYtQ==}
     engines: {node: '>= 0.6.0'}
@@ -3327,7 +3633,7 @@ packages:
     resolution: {integrity: sha512-CXD6Orp7l8QevNDcRPLXc/b8iMVgxDWT2LyTwsdLzJKh9CxesOmPuNePSPqAxKoT59FIdU4aFPS1k7eBdbaCxg==}
     engines: {node: '>=18', pnpm: '>=8.7.0'}
     peerDependencies:
-      svelte: ^5.11.0
+      svelte: '>=5.55.7 <6'
 
   body-parser@1.20.4:
     resolution: {integrity: sha512-ZTgYYLMOXY9qKU/57FAo8F+HA2dGX7bqGc71txDRC1rS4frdFI5R7NhluHxH6M0YItAP0sHB4uqAOcYKxO6uGA==}
@@ -3339,10 +3645,6 @@ packages:
   boolbase@1.0.0:
     resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==}
 
-  boxen@8.0.1:
-    resolution: {integrity: sha512-F3PH5k5juxom4xktynS7MoFY+NUWH5LC4CnH11YB8NPew+HLpmBLCybSAEyb2F+4pRXhuhWqFesoQd6DAyc2hw==}
-    engines: {node: '>=18'}
-
   brace-expansion@2.0.3:
     resolution: {integrity: sha512-MCV/fYJEbqx68aE58kv2cA/kiky1G8vux3OR6/jbS+jIMe/6fJWa0DTzJU7dqijOWYwHi1t29FlfYI9uytqlpA==}
 
@@ -3402,13 +3704,12 @@ packages:
     resolution: {integrity: sha512-QOSvevhslijgYwRx6Rv7zKdMF8lbRmx+uQGx2+vDc+KI/eBnsy9kit5aj23AgGu3pa4t9AgwbnXWqS+iOY+2aA==}
     engines: {node: '>= 6'}
 
-  camelcase@8.0.0:
-    resolution: {integrity: sha512-8WB3Jcas3swSvjIeA2yvCJ+Miyz5l1ZmB6HFb9R1317dt9LCQoswg/BGrmAmkWVEszSrrg4RwmO46qIm2OEnSA==}
-    engines: {node: '>=16'}
-
   caniuse-lite@1.0.30001781:
     resolution: {integrity: sha512-RdwNCyMsNBftLjW6w01z8bKEvT6e/5tpPVEgtn22TiLGlstHOVecsX2KHFkD5e/vRnIE4EGzpuIODb3mtswtkw==}
 
+  caseless@0.12.0:
+    resolution: {integrity: sha512-4tYFyifaFfGacoiObjJegolkwSU4xQNGbVgUiNYVUxbQ2x2lUsFvY4hVgVzGiIe6WLOPqycWXA40l+PWsxthUw==}
+
   ccount@2.0.1:
     resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
 
@@ -3420,10 +3721,6 @@ packages:
     resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
     engines: {node: '>=10'}
 
-  chalk@5.6.2:
-    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
-    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
-
   character-entities-html4@2.1.0:
     resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
 
@@ -3433,6 +3730,9 @@ packages:
   character-entities@2.0.2:
     resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
 
+  chardet@2.1.1:
+    resolution: {integrity: sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ==}
+
   chokidar@3.6.0:
     resolution: {integrity: sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==}
     engines: {node: '>= 8.10.0'}
@@ -3460,9 +3760,9 @@ packages:
     resolution: {integrity: sha512-D5J+kHaVb/wKSFcyyV75uCn8fiY4sV38XJoe4CUyGQ+mOU/fMVYUdH1hJC+CJQ5uY3EnW27SbJYS4X8BiLrAFg==}
     engines: {node: '>= 10.0'}
 
-  cli-boxes@3.0.0:
-    resolution: {integrity: sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==}
-    engines: {node: '>=10'}
+  cli-width@4.1.0:
+    resolution: {integrity: sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==}
+    engines: {node: '>= 12'}
 
   clone-deep@4.0.1:
     resolution: {integrity: sha512-neHB9xuzh/wk0dIHweyAXv2aPGZIVk3pLMe+/RNzINf17fe0OG96QroktYAUm7SM1PBnzTabaLboqqxDyMU+SQ==}
@@ -3476,6 +3776,9 @@ packages:
     resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
     engines: {node: '>=6'}
 
+  codemirror@6.0.2:
+    resolution: {integrity: sha512-VhydHotNW5w1UGK0Qj96BwSk/Zqbp9WbnyK2W/eVMv4QyF41INRGpjUhFJY7/uDNuudSc33a/PKr4iDqRduvHw==}
+
   color-convert@2.0.1:
     resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
     engines: {node: '>=7.0.0'}
@@ -3497,6 +3800,10 @@ packages:
     resolution: {integrity: sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==}
     engines: {node: '>=18'}
 
+  commander@14.0.3:
+    resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
+    engines: {node: '>=20'}
+
   commander@2.20.3:
     resolution: {integrity: sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==}
 
@@ -3508,8 +3815,14 @@ packages:
     resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==}
     engines: {node: '>= 12'}
 
-  common-ancestor-path@1.0.1:
-    resolution: {integrity: sha512-L3sHRo1pXXEqX8VU28kfgUY+YGsk09hPqZiZmLacNib6XNTCM8ubYeT7ryXQw8asB1sKgcU5lkB7ONug08aB8w==}
+  common-ancestor-path@2.0.0:
+    resolution: {integrity: sha512-dnN3ibLeoRf2HNC+OlCiNc5d2zxbLJXOtiZUudNFSXZrNSydxcCsSpRzXwfu7BBWCIfHPw+xTayeBvJCP/D8Ng==}
+    engines: {node: '>= 18'}
+
+  composed-offset-position@0.0.6:
+    resolution: {integrity: sha512-Q7dLompI6lUwd7LWyIcP66r4WcS9u7AL2h8HaeipiRfCRPLMWqRx8fYsjb4OHi6UQFifO7XtNC2IlEJ1ozIFxw==}
+    peerDependencies:
+      '@floating-ui/utils': ^0.2.5
 
   compressible@2.0.18:
     resolution: {integrity: sha512-AF3r7P5dWxL8MxyITRMlORQNaOA2IkAFaTr4k7BUumjPtRpGDTZpl0Pb1XCO6JeDCBdp126Cgs9sMxqSjgYyRg==}
@@ -3519,6 +3832,10 @@ packages:
     resolution: {integrity: sha512-9mAqGPHLakhCLeNyxPkK4xVo746zQ/czLH1Ky+vkitMnWfWZps8r0qXuwhwizagCRttsL4lfG4pIOvaWLpAP0w==}
     engines: {node: '>= 0.8.0'}
 
+  concat-stream@2.0.0:
+    resolution: {integrity: sha512-MWufYdFw53ccGjCA+Ol7XJYpAlW6/prSMzuPOTRnJGcGzuhLn4Scrz7qf6o8bROZ514ltazcIFJZevcfbo0x7A==}
+    engines: {'0': node >= 6.0}
+
   confbox@0.1.8:
     resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==}
 
@@ -3561,6 +3878,9 @@ packages:
   core-util-is@1.0.3:
     resolution: {integrity: sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==}
 
+  crelt@1.0.6:
+    resolution: {integrity: sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g==}
+
   cross-spawn@7.0.6:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
@@ -3720,12 +4040,8 @@ packages:
   detect-node@2.1.0:
     resolution: {integrity: sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==}
 
-  deterministic-object-hash@2.0.2:
-    resolution: {integrity: sha512-KxektNH63SrbfUyDiwXqRb1rLwKt33AmMv+5Nhsw1kqZ13SJBRTgZHtGbE+hH3a1mVW1cz+4pqSWVPAtLVXTzQ==}
-    engines: {node: '>=18'}
-
-  devalue@5.6.4:
-    resolution: {integrity: sha512-Gp6rDldRsFh/7XuouDbxMH3Mx8GMCcgzIb1pDTvNyn8pZGQ22u+Wa+lGV9dQCltFQ7uVw0MhRyb8XDskNFOReA==}
+  devalue@5.8.1:
+    resolution: {integrity: sha512-4CXDYRBGqN+57wVJkuXBYmpAVUSg3L6JAQa/DFqm238G73E1wuyc/JhGQJzN7vUf/CMphYau2zXbfWzDR5aTEw==}
 
   devlop@1.1.0:
     resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
@@ -3764,8 +4080,8 @@ packages:
     resolution: {integrity: sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==}
     engines: {node: '>= 4'}
 
-  dompurify@3.4.0:
-    resolution: {integrity: sha512-nolgK9JcaUXMSmW+j1yaSvaEaoXYHwWyGJlkoCTghc97KgGDDSnpoU/PlEnw63Ah+TGKFOyY+X5LnxaWbCSfXg==}
+  dompurify@3.4.11:
+    resolution: {integrity: sha512-zhlUV12GsaRzMsf9q5M254YhA4+VuF0fG+QFqu6aYpoGlKtz+w8//jBcGVYBgQkR5GHjUomejY84AV+/uPbWdw==}
 
   domutils@2.8.0:
     resolution: {integrity: sha512-w96Cjofp72M5IIhpjgobBimYEfoPjx1Vx0BSX9P30WBdZW2WIKU0T1Bd0kz2eNZ9ikjKgHbEyKx8BB6H1L3h3A==}
@@ -3790,11 +4106,9 @@ packages:
   electron-to-chromium@1.5.328:
     resolution: {integrity: sha512-QNQ5l45DzYytThO21403XN3FvK0hOkWDG8viNf6jqS42msJ8I4tGDSpBCgvDRRPnkffafiwAym2X2eHeGD2V0w==}
 
-  emoji-regex@10.6.0:
-    resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
-
-  emoji-regex@8.0.0:
-    resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
+  empathic@2.0.1:
+    resolution: {integrity: sha512-YGRs8knHhKHVShLkFET/rWAU8kmHbOV5LwN938RHI0pljAJ1Gf6SzXsSmRaEzcXTtOOmVqJ5+WtQPL5uigY50Q==}
+    engines: {node: '>=14'}
 
   encodeurl@2.0.0:
     resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
@@ -3819,6 +4133,10 @@ packages:
     resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==}
     engines: {node: '>=0.12'}
 
+  env-paths@2.2.1:
+    resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==}
+    engines: {node: '>=6'}
+
   envinfo@7.21.0:
     resolution: {integrity: sha512-Lw7I8Zp5YKHFCXL7+Dz95g4CcbMEpgvqZNNq3AmlT5XAV6CgAAk6gyAMqn2zjw08K9BHfcNuKrMiCPLByGafow==}
     engines: {node: '>=4'}
@@ -3832,9 +4150,6 @@ packages:
     resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
     engines: {node: '>= 0.4'}
 
-  es-module-lexer@1.7.0:
-    resolution: {integrity: sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==}
-
   es-module-lexer@2.0.0:
     resolution: {integrity: sha512-5POEcUuZybH7IdmGsD8wlf0AI55wMecM9rVBTI/qEAy2c1kTOm3DjFYjrBdI2K3BaJjJYfYFeRtM0t9ssnRuxw==}
 
@@ -3847,8 +4162,8 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
-  esbuild@0.27.4:
-    resolution: {integrity: sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==}
+  esbuild@0.27.7:
+    resolution: {integrity: sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==}
     engines: {node: '>=18'}
     hasBin: true
 
@@ -3870,8 +4185,13 @@ packages:
   esm-env@1.2.2:
     resolution: {integrity: sha512-Epxrv+Nr/CaL4ZcFGPJIYLWFom+YeV1DqMLHJoEd9SYRxNbaFruBwfEX/kkHUJf55j2+TUbmDcmuilbP1TmXHA==}
 
-  esrap@2.2.4:
-    resolution: {integrity: sha512-suICpxAmZ9A8bzJjEl/+rLJiDKC0X4gYWUxT6URAWBLvlXmtbZd5ySMu/N2ZGEtMCAmflUDPSehrP9BQcsGcSg==}
+  esrap@2.2.12:
+    resolution: {integrity: sha512-On0QbLyaiAkVC4eXtgnXK9Kh2opit+3rcUSOc45DqJ2s/X2eXAHsGOKRSJ6IDagQEW5vPyivANfXUiqgXC67Rw==}
+    peerDependencies:
+      '@typescript-eslint/types': ^8.2.0
+    peerDependenciesMeta:
+      '@typescript-eslint/types':
+        optional: true
 
   esrecurse@4.3.0:
     resolution: {integrity: sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==}
@@ -3953,8 +4273,17 @@ packages:
   fast-sha256@1.3.0:
     resolution: {integrity: sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ==}
 
-  fast-uri@3.1.0:
-    resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==}
+  fast-string-truncated-width@3.0.3:
+    resolution: {integrity: sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g==}
+
+  fast-string-width@3.0.2:
+    resolution: {integrity: sha512-gX8LrtNEI5hq8DVUfRQMbr5lpaS4nMIWV+7XEbXk2b8kiQIizgnlr12B4dA3ZEx3308ze0O4Q1R+cHts8kyUJg==}
+
+  fast-uri@4.0.0:
+    resolution: {integrity: sha512-l90y339r2DkZs/ldcWQXcwTjkbp/NbuJDGYoQ3awBgaT3GXOFkm3OkVpz6Z86TywYcya0eVP2r1kTV90f3krGQ==}
+
+  fast-wrap-ansi@0.2.2:
+    resolution: {integrity: sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q==}
 
   fastest-levenshtein@1.0.16:
     resolution: {integrity: sha512-eRnCtTTtGZFpQCwhJiUOuxPQWRXVKYDn0b2PeHfXL6/Zi53SLAzAHfVhVWK2AryC/WH05kGfxhFIPvTF0SXQzg==}
@@ -3982,6 +4311,10 @@ packages:
       picomatch:
         optional: true
 
+  ffmpeg-static@5.3.0:
+    resolution: {integrity: sha512-H+K6sW6TiIX6VGend0KQwthe+kaceeH/luE8dIZyOP35ik7ahYojDuqlTV1bOrtEwl01sy2HFNGQfi5IDJvotg==}
+    engines: {node: '>=16'}
+
   fill-range@7.1.1:
     resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
     engines: {node: '>=8'}
@@ -4056,10 +4389,6 @@ packages:
     resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
     engines: {node: '>=6.9.0'}
 
-  get-east-asian-width@1.5.0:
-    resolution: {integrity: sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA==}
-    engines: {node: '>=18'}
-
   get-intrinsic@1.3.0:
     resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
     engines: {node: '>= 0.4'}
@@ -4072,6 +4401,10 @@ packages:
     resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}
     engines: {node: '>= 0.4'}
 
+  get-tsconfig@5.0.0-beta.4:
+    resolution: {integrity: sha512-7nF7C9fIPFEMHgEMEfgIlO9wDdZ8CyHw27rWciFZfHvHDReIiPhsYuzPRXsfvBCqFy1l8RRyyWV7QLM+ZhUJsQ==}
+    engines: {node: '>=20.20.0'}
+
   github-slugger@2.0.0:
     resolution: {integrity: sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==}
 
@@ -4228,8 +4561,8 @@ packages:
   http-parser-js@0.5.10:
     resolution: {integrity: sha512-Pysuw9XpUq5dVc/2SMHpuTY01RFl8fttgcyunjL7eEMhGM3cI4eOmiCycJDVCo/7O7ClfQD3SaI6ftDzqOXYMA==}
 
-  http-proxy-middleware@2.0.9:
-    resolution: {integrity: sha512-c1IyJYLYppU574+YI7R4QyX2ystMtVXZwIdzazUIPIJsHuWNd+mho2j+bKoHftndicGj9yh+xjd+l0yj7VeT1Q==}
+  http-proxy-middleware@2.0.10:
+    resolution: {integrity: sha512-RKzRWNPxUZqbuk3BC5mGVJbBnWgr+diEnjJexIOytFbBzDy88Fbh/YvBr3DsNrl1jYAfjWfpATEv0NO35FDuPQ==}
     engines: {node: '>=12.0.0'}
     peerDependencies:
       '@types/express': ^4.17.13
@@ -4241,6 +4574,13 @@ packages:
     resolution: {integrity: sha512-7mz/721AbnJwIVbnaSv1Cz3Am0ZLT/UBwkC92VlxhXv/k/BBQfM2fXElQNC27BVGr0uwUpplYPQM9LnaBMR5NQ==}
     engines: {node: '>=8.0.0'}
 
+  http-response-object@3.0.2:
+    resolution: {integrity: sha512-bqX0XTF6fnXSQcEJ2Iuyr75yVakyjIDCqroJQ/aHfSdlM743Cwqoi2nDYMzLGWUcuTWGWy8AAvOKXTfiv6q9RA==}
+
+  https-proxy-agent@5.0.1:
+    resolution: {integrity: sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==}
+    engines: {node: '>= 6'}
+
   hyperdyperid@1.2.0:
     resolution: {integrity: sha512-Y93lCzHYgGWdrJ66yIktxiaGULYc6oGiABxhcO5AufBeOyoIdZF7bIfLaOrbM0iGIOXQQgxxRrFEnb+Y6w1n4A==}
     engines: {node: '>=10.18'}
@@ -4249,11 +4589,15 @@ packages:
     resolution: {integrity: sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==}
     engines: {node: '>=0.10.0'}
 
+  iconv-lite@0.7.2:
+    resolution: {integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==}
+    engines: {node: '>=0.10.0'}
+
   icss-utils@5.1.0:
     resolution: {integrity: sha512-soFhflCVWLfRNOPU3iv5Z9VUdT44xFRbzjLsEzSr5AQmgqPMTHdU3PMT1Cf1ssx8fLNJDA1juftYl+PUcv3MqA==}
     engines: {node: ^10 || ^12 || >= 14}
     peerDependencies:
-      postcss: ^8.1.0
+      postcss: '>=8.5.10'
 
   import-local@3.2.0:
     resolution: {integrity: sha512-2SPlun1JUPWoM6t3F0dw0FkCF/jWY8kttcY4f599GLTSjh2OCuuhdTkJQsEcZzBqbXZGKMK2OqW1oZsjtf/gQA==}
@@ -4305,14 +4649,15 @@ packages:
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
     hasBin: true
 
+  is-docker@4.0.0:
+    resolution: {integrity: sha512-LHE+wROyG/Y/0ZnbktRCoTix2c1RhgWaZraMZ8o1Q7zCh0VSrICJQO5oqIIISrcSBtrXv0o233w1IYwsWCjTzA==}
+    engines: {node: '>=20'}
+    hasBin: true
+
   is-extglob@2.1.1:
     resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
     engines: {node: '>=0.10.0'}
 
-  is-fullwidth-code-point@3.0.0:
-    resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
-    engines: {node: '>=8'}
-
   is-glob@4.0.3:
     resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
     engines: {node: '>=0.10.0'}
@@ -4382,11 +4727,14 @@ packages:
     resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==}
     engines: {node: '>=10'}
 
+  js-tokens@10.0.0:
+    resolution: {integrity: sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==}
+
   js-tokens@4.0.0:
     resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
 
-  js-yaml@4.1.1:
-    resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
+  js-yaml@4.2.0:
+    resolution: {integrity: sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==}
     hasBin: true
 
   jsdom@29.0.1:
@@ -4425,20 +4773,19 @@ packages:
     engines: {node: '>=6'}
     hasBin: true
 
+  jsonc-parser@3.3.1:
+    resolution: {integrity: sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==}
+
   kind-of@6.0.3:
     resolution: {integrity: sha512-dcS1ul+9tmeD95T+x28/ehLgd9mENa3LsvDTtzm3vyBEO7RPptvAD+t44WVXaUjTBRcrpFeFlC8WCruUR456hw==}
     engines: {node: '>=0.10.0'}
 
-  kleur@3.0.3:
-    resolution: {integrity: sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w==}
-    engines: {node: '>=6'}
-
   kleur@4.1.5:
     resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==}
     engines: {node: '>=6'}
 
-  launch-editor@2.13.2:
-    resolution: {integrity: sha512-4VVDnbOpLXy/s8rdRCSXb+zfMeFR0WlJWpET1iA9CQdlZDfwyLjUuGQzXU4VeOoey6AicSAluWan7Etga6Kcmg==}
+  launch-editor@2.14.1:
+    resolution: {integrity: sha512-QWBrQsMpH7gPr965dsKD/3cKWiNoTjpATQf++Xq63N6sKRGMwlVXz41O1IZTMfZQgBctD/K5Zt06+/I6pP6+HA==}
 
   light-my-request@6.6.0:
     resolution: {integrity: sha512-CHYbu8RtboSIoVsHZ6Ye4cj4Aw/yg2oAFimlF7mNvfDV192LR7nDiKtSIfCuLT7KokPSTn/9kfVLm5OGN0A28A==}
@@ -4450,6 +4797,15 @@ packages:
   lines-and-columns@1.2.4:
     resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==}
 
+  lit-element@4.2.2:
+    resolution: {integrity: sha512-aFKhNToWxoyhkNDmWZwEva2SlQia+jfG0fjIWV//YeTaWrVnOxD89dPKfigCUspXFmjzOEUQpOkejH5Ly6sG0w==}
+
+  lit-html@3.3.3:
+    resolution: {integrity: sha512-el8M6jK2o3RXBnrSHX3ZKrsN8zEV63pSExTO1wYJz7QndGYZ8353e2a5PPX+qHe2aGayfnchQmkAojaWAREOIA==}
+
+  lit@3.3.3:
+    resolution: {integrity: sha512-fycuvZg/hkpozL00lm1pEJH5nN/lr9ZXd6mJI2HSN4+Bzc+LDNdEApJ6HFbPkdFNHLvOplIIuJvxkS4XUxqirw==}
+
   load-tsconfig@0.2.5:
     resolution: {integrity: sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
@@ -4492,9 +4848,6 @@ packages:
     resolution: {integrity: sha512-aY/R+aEsRelme17KGQa/1ZSIpLpNYYrhcrepKTZgE+W3WM16YMCaPwOHLHsmopZHELU0Ojin1lPVxKR0MihncA==}
     engines: {node: 20 || >=22}
 
-  lru-cache@5.1.1:
-    resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
-
   lucide-vue-next@1.0.0:
     resolution: {integrity: sha512-V6SPvx1IHTj/UY+FrIYWV5faISsPSb8BnWSFDxAtezWKvWc9ZZ40PDrdu1/Qb5vg4lHWr1hs1BAMGVGm6V1Xdg==}
     peerDependencies:
@@ -4738,6 +5091,10 @@ packages:
     resolution: {integrity: sha512-2eznPJP8z2BFLX50tf0LuODrpINqP1RVIm/CObbTcBRITQgmC/TjcREF1NeTBzIcR5XO/ukWo+YHOjBbFwIupg==}
     hasBin: true
 
+  mute-stream@3.0.0:
+    resolution: {integrity: sha512-dkEJPVvun4FryqBmZ5KhDo0K9iDXAwn08tMLDinNdRBNPcYEDiWYysLcc6k3mjTMlbP9KyylvRpd4wFtwrT9rw==}
+    engines: {node: ^20.17.0 || >=22.9.0}
+
   mz@2.7.0:
     resolution: {integrity: sha512-z81GNO7nnYMEhrGh9LeymoE4+Yr0Wn5McHIZMK5cfQCl+NDX08sCZgUc9/6MHni9IWuFLm1Z3HTCXu2z9fN62Q==}
 
@@ -4747,8 +5104,8 @@ packages:
     peerDependencies:
       vue: ^3.0.0
 
-  nanoid@3.3.11:
-    resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==}
+  nanoid@3.3.15:
+    resolution: {integrity: sha512-y7Wygv/7mEOvxTuEQDB8StXdMRBWf1kR/tlhAzBRUFkB2jfcLOAxO/SHmOO2zgz1pVgK29/kyupn059/bCHdjA==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
     hasBin: true
 
@@ -4836,11 +5193,11 @@ packages:
     resolution: {integrity: sha512-737ZY3yNnXy37FHkQxPzt4UZ2UWPWiCZWLvFZ4fu5cueciegX0zGPnrlY6bwRg4FdQOe9YU8MkmJwGhoMybl8A==}
     engines: {node: '>= 0.8'}
 
-  oniguruma-parser@0.12.1:
-    resolution: {integrity: sha512-8Unqkvk1RYc6yq2WBYRj4hdnsAxVze8i7iPfQr8e4uSP3tRv0rpZcbGUDvxfQQcdwHt/e9PrMvGCsa8OqG9X3w==}
+  oniguruma-parser@0.12.2:
+    resolution: {integrity: sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw==}
 
-  oniguruma-to-es@4.3.5:
-    resolution: {integrity: sha512-Zjygswjpsewa0NLTsiizVuMQZbp0MDyM6lIt66OxsF21npUDlzpHi1Mgb/qhQdkb+dWFTzJmFbEWdvZgRho8eQ==}
+  oniguruma-to-es@4.3.6:
+    resolution: {integrity: sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA==}
 
   open@10.2.0:
     resolution: {integrity: sha512-YgBpdJHPyQ2UE5x+hlSXcnejzAvD0b22U2OuAP+8OnlJT+PjWPxtgmGqKKc+RgTM63U9gN0YzrYc71R2WT/hTA==}
@@ -4853,25 +5210,25 @@ packages:
     resolution: {integrity: sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==}
     engines: {node: '>=6'}
 
-  p-limit@6.2.0:
-    resolution: {integrity: sha512-kuUqqHNUqoIWp/c467RI4X6mmyuojY5jGutNU0wVTmEOOfcuwLqyMVoAi9MKi2Ak+5i9+nhmrK4ufZE8069kHA==}
-    engines: {node: '>=18'}
+  p-limit@7.3.0:
+    resolution: {integrity: sha512-7cIXg/Z0M5WZRblrsOla88S4wAK+zOQQWeBYfV3qJuJXMr+LnbYjaadrFaS0JILfEDPVqHyKnZ1Z/1d6J9VVUw==}
+    engines: {node: '>=20'}
 
   p-locate@4.1.0:
     resolution: {integrity: sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==}
     engines: {node: '>=8'}
 
-  p-queue@8.1.1:
-    resolution: {integrity: sha512-aNZ+VfjobsWryoiPnEApGGmf5WmNsCo9xu8dfaYamG5qaLP7ClhLN6NgsFe6SwJ2UbLEBK5dv9x8Mn5+RVhMWQ==}
-    engines: {node: '>=18'}
+  p-queue@9.3.0:
+    resolution: {integrity: sha512-7NED7xhQ74Ngp4JP/2e0VZHp7vSWfJfqeiR92jPgxsz6m0Se4P03YoTKa9dDXyZ3r6P616gUXttrB6nnHYKang==}
+    engines: {node: '>=20'}
 
   p-retry@6.2.1:
     resolution: {integrity: sha512-hEt02O4hUct5wtwg4H4KcWgDdm+l1bOaEy/hWzd8xtXB9BqxTWBBhb+2ImAtH4Cv4rPjV76xN3Zumqk3k3AhhQ==}
     engines: {node: '>=16.17'}
 
-  p-timeout@6.1.4:
-    resolution: {integrity: sha512-MyIV3ZA/PmyBN/ud8vV9XzwTrNtR4jFrObymZYnZqMmW0zA8Z17vnT0rBgFE/TlohB+YCHqXMgZzb3Csp49vqg==}
-    engines: {node: '>=14.16'}
+  p-timeout@7.0.1:
+    resolution: {integrity: sha512-AxTM2wDGORHGEkPCt8yqxOTMgpfbEHqF51f/5fJCmwFC3C/zNcGT63SymH2ttOAaiIws2zVg4+izQCjrakcwHg==}
+    engines: {node: '>=20'}
 
   p-try@2.2.0:
     resolution: {integrity: sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==}
@@ -4889,6 +5246,9 @@ packages:
   parchment@3.0.0:
     resolution: {integrity: sha512-HUrJFQ/StvgmXRcQ1ftY6VEZUq3jA2t9ncFN4F84J/vN0/FPpQF+8FKXb3l6fLces6q0uOHj6NJn+2xvZnxO6A==}
 
+  parse-cache-control@1.0.1:
+    resolution: {integrity: sha512-60zvsJReQPX5/QP0Kzfd/VrpjScIQ7SHBW6bFCYfEP+fp0Eppr1SHhIO5nd1PjZtvclzSzES9D/p5nFJurwfWg==}
+
   parse-latin@7.0.0:
     resolution: {integrity: sha512-mhHgobPPua5kZ98EF4HWiH167JWBfl4pvAIXXdbaVohtK7a6YBOy56kvhCqduqyo/f3yrHFWmqmiMg/BkBkYYQ==}
 
@@ -4988,20 +5348,20 @@ packages:
     resolution: {integrity: sha512-hpr+J05B2FVYUAXHeK1YyI267J/dDDhMU6B6civm8hSY1jYJnBXxzKDKDswzJmtLHryrjhnDjqqp/49t8FALew==}
     engines: {node: '>=14.0.0'}
     peerDependencies:
-      postcss: ^8.0.0
+      postcss: '>=8.5.10'
 
   postcss-js@4.1.0:
     resolution: {integrity: sha512-oIAOTqgIo7q2EOwbhb8UalYePMvYoIeRY2YKntdpFQXNosSu3vLrniGgmH9OKs/qAkfoj5oB3le/7mINW1LCfw==}
     engines: {node: ^12 || ^14 || >= 16}
     peerDependencies:
-      postcss: ^8.4.21
+      postcss: '>=8.5.10'
 
   postcss-load-config@6.0.1:
     resolution: {integrity: sha512-oPtTM4oerL+UXmx+93ytZVN82RrlY/wPUV8IeDxFrzIjXOLF1pN+EmKPLbubvKHT2HC20xXsCAH2Z+CKV6Oz/g==}
     engines: {node: '>= 18'}
     peerDependencies:
       jiti: '>=1.21.0'
-      postcss: '>=8.0.9'
+      postcss: '>=8.5.10'
       tsx: ^4.8.1
       yaml: ^2.4.2
     peerDependenciesMeta:
@@ -5018,31 +5378,31 @@ packages:
     resolution: {integrity: sha512-k3kNe0aNFQDAZGbin48pL2VNidTF0w4/eASDsxlyspobzU3wZQLOGj7L9gfRe0Jo9/4uud09DsjFNH7winGv8Q==}
     engines: {node: ^10 || ^12 || >= 14}
     peerDependencies:
-      postcss: ^8.1.0
+      postcss: '>=8.5.10'
 
   postcss-modules-local-by-default@4.2.0:
     resolution: {integrity: sha512-5kcJm/zk+GJDSfw+V/42fJ5fhjL5YbFDl8nVdXkJPLLW+Vf9mTD5Xe0wqIaDnLuL2U6cDNpTr+UQ+v2HWIBhzw==}
     engines: {node: ^10 || ^12 || >= 14}
     peerDependencies:
-      postcss: ^8.1.0
+      postcss: '>=8.5.10'
 
   postcss-modules-scope@3.2.1:
     resolution: {integrity: sha512-m9jZstCVaqGjTAuny8MdgE88scJnCiQSlSrOWcTQgM2t32UBe+MUmFSO5t7VMSfAf/FJKImAxBav8ooCHJXCJA==}
     engines: {node: ^10 || ^12 || >= 14}
     peerDependencies:
-      postcss: ^8.1.0
+      postcss: '>=8.5.10'
 
   postcss-modules-values@4.0.0:
     resolution: {integrity: sha512-RDxHkAiEGI78gS2ofyvCsu7iycRv7oqw5xMWn9iMoR0N/7mf9D50ecQqUo5BZ9Zh2vH4bCUR/ktCqbB9m8vJjQ==}
     engines: {node: ^10 || ^12 || >= 14}
     peerDependencies:
-      postcss: ^8.1.0
+      postcss: '>=8.5.10'
 
   postcss-nested@6.2.0:
     resolution: {integrity: sha512-HQbt28KulC5AJzG+cZtj9kvKB93CFCdLvog1WFLf1D+xmMvPGlBstkpTEZfK5+AN9hfJocyBFCNiqyS48bpgzQ==}
     engines: {node: '>=12.0'}
     peerDependencies:
-      postcss: ^8.2.14
+      postcss: '>=8.5.10'
 
   postcss-selector-parser@6.1.2:
     resolution: {integrity: sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==}
@@ -5055,8 +5415,8 @@ packages:
   postcss-value-parser@4.2.0:
     resolution: {integrity: sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==}
 
-  postcss@8.5.8:
-    resolution: {integrity: sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==}
+  postcss@8.5.15:
+    resolution: {integrity: sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==}
     engines: {node: ^10 || ^12 || >=14}
 
   pretty-error@4.0.0:
@@ -5082,9 +5442,9 @@ packages:
   process-warning@5.0.0:
     resolution: {integrity: sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA==}
 
-  prompts@2.4.2:
-    resolution: {integrity: sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==}
-    engines: {node: '>= 6'}
+  progress@2.0.3:
+    resolution: {integrity: sha512-7PiHtLll5LdnKIMw100I+8xJXR5gW2QwWYkT6iJva0bXitZKa/XMrSbdmg3r2Xnaidz9Qumd0VPaMrZlF9V9sA==}
+    engines: {node: '>=0.4.0'}
 
   property-information@7.1.0:
     resolution: {integrity: sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==}
@@ -5104,8 +5464,11 @@ packages:
     resolution: {integrity: sha512-KTqnxsgGiQ6ZAzZCVlJH5eOjSnvlyEgx1m8bkRJfOhmGRqfo5KLvmAlACQkrjEtOQ4B7wF9TdSLIs9O90MX9xA==}
     engines: {node: '>=16.0.0'}
 
-  qs@6.14.2:
-    resolution: {integrity: sha512-V/yCWTTF7VJ9hIh18Ugr2zhJMP01MY7c5kh4J870L7imm6/DIzBsNLTXzMwUA3yZ5b/KBqLx8Kp3uRvd7xSe3Q==}
+  qr-creator@1.0.0:
+    resolution: {integrity: sha512-C0cqfbS1P5hfqN4NhsYsUXePlk9BO+a45bAQ3xLYjBL3bOIFzoVEjs79Fado9u9BPBD3buHi3+vY+C8tHh4qMQ==}
+
+  qs@6.15.2:
+    resolution: {integrity: sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==}
     engines: {node: '>=0.6'}
 
   quansync@0.2.11:
@@ -5194,15 +5557,15 @@ packages:
       '@types/react':
         optional: true
 
-  react-router-dom@7.13.2:
-    resolution: {integrity: sha512-aR7SUORwTqAW0JDeiWF07e9SBE9qGpByR9I8kJT5h/FrBKxPMS6TiC7rmVO+gC0q52Bx7JnjWe8Z1sR9faN4YA==}
+  react-router-dom@7.18.0:
+    resolution: {integrity: sha512-Fi0yY6kgtKae/Th2xibdWK0KSdYZ4B53Gyf6wRtomOKWgpNm7H7+DyfDhncdz9FKbpS+1jmDhg3F4WoGJ+yFOA==}
     engines: {node: '>=20.0.0'}
     peerDependencies:
       react: '>=18'
       react-dom: '>=18'
 
-  react-router@7.13.2:
-    resolution: {integrity: sha512-tX1Aee+ArlKQP+NIUd7SE6Li+CiGKwQtbS+FfRxPX6Pe4vHOo6nr9d++u5cwg+Z8K/x8tP+7qLmujDtfrAoUJA==}
+  react-router@7.18.0:
+    resolution: {integrity: sha512-pTTGt8J+ji1NOmYnjzT+bAJy/1zD+Jp4ziO6cL7T3ZLvXKtusO7BpFqlRXitqpcPVqllsIXFHRMt+2/k3Xn6HQ==}
     engines: {node: '>=20.0.0'}
     peerDependencies:
       react: '>=18'
@@ -5327,6 +5690,9 @@ packages:
     resolution: {integrity: sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==}
     engines: {node: '>=8'}
 
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
   resolve@1.22.11:
     resolution: {integrity: sha512-RfqAvLnMl313r7c9oclB1HhUEAezcpLjz95wFH4LVuhk9JF/r22qmVP9AMmOU4vMX7Q8pN8jwNg/CSpdFnMjTQ==}
     engines: {node: '>= 0.4'}
@@ -5374,7 +5740,7 @@ packages:
   runed@0.23.4:
     resolution: {integrity: sha512-9q8oUiBYeXIDLWNK5DfCWlkL0EW3oGbk845VdKlPeia28l751VpfesaB/+7pI6rnbx1I6rqoZ2fZxptOJLxILA==}
     peerDependencies:
-      svelte: ^5.7.0
+      svelte: '>=5.55.7 <6'
 
   safe-buffer@5.1.2:
     resolution: {integrity: sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==}
@@ -5424,10 +5790,6 @@ packages:
     resolution: {integrity: sha512-ftnu3TW4+3eBfLRFnDEkzGxSF/10BJBkaLJuBHZX0kiPS7bRdlpZGu6YGt4KngMkdTwJE6MbjavFpqHvqVt+Ew==}
     engines: {node: '>=18'}
 
-  semver@6.3.1:
-    resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
-    hasBin: true
-
   semver@7.7.4:
     resolution: {integrity: sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==}
     engines: {node: '>=10'}
@@ -5485,12 +5847,13 @@ packages:
     resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
     engines: {node: '>=8'}
 
-  shell-quote@1.8.3:
-    resolution: {integrity: sha512-ObmnIF4hXNg1BqhnHmgbDETF8dLPCggZWBjkQfhZpbszZnYur5DUljTcCHii5LC3J5E0yeO/1LIMyH+UvHQgyw==}
+  shell-quote@1.8.4:
+    resolution: {integrity: sha512-VsC6n6vz1ihYYyZZwX7YZSF5l5x36ca17OC+a69h94YqB7X6XLwf+5MOgynYir2SLFUbl8gIYvBo8K8RoNQ6bQ==}
     engines: {node: '>= 0.4'}
 
-  shiki@3.23.0:
-    resolution: {integrity: sha512-55Dj73uq9ZXL5zyeRPzHQsK7Nbyt6Y10k5s7OjuFZGMhpp4r/rsLBH0o/0fstIzX1Lep9VxefWljK/SKCzygIA==}
+  shiki@4.2.0:
+    resolution: {integrity: sha512-hjNax6o/ylDy9lefQEaSDtzaT3iVNtZ3WmpQnbuQNoG4xvnSKf2kSKbihZVO4JRG1TTMejs7CmNRYlWgAL66pQ==}
+    engines: {node: '>=20'}
 
   side-channel-list@1.0.0:
     resolution: {integrity: sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==}
@@ -5511,6 +5874,10 @@ packages:
   siginfo@2.0.0:
     resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
 
+  signal-exit@4.1.0:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
+    engines: {node: '>=14'}
+
   single-spa-react@6.0.2:
     resolution: {integrity: sha512-nRz5Izf57iYZXMXdTh+RmHnxxQojFL8NCIVUyA7PpXRib1ykmbat6JgT3yFPgXRs129BCC4+j+O5TLQOmLzF4Q==}
     peerDependencies:
@@ -5606,14 +5973,6 @@ packages:
   std-env@4.0.0:
     resolution: {integrity: sha512-zUMPtQ/HBY3/50VbpkupYHbRroTRZJPRLvreamgErJVys0ceuzMkD44J/QjqhHjOzK42GQ3QZIeFG1OYfOtKqQ==}
 
-  string-width@4.2.3:
-    resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
-    engines: {node: '>=8'}
-
-  string-width@7.2.0:
-    resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
-    engines: {node: '>=18'}
-
   string_decoder@1.1.1:
     resolution: {integrity: sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==}
 
@@ -5627,16 +5986,15 @@ packages:
     resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
     engines: {node: '>=8'}
 
-  strip-ansi@7.2.0:
-    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
-    engines: {node: '>=12'}
-
   style-loader@4.0.0:
     resolution: {integrity: sha512-1V4WqhhZZgjVAVJyt7TdDPZoPBPNHbekX4fWnCJL1yQukhCeZhJySUL+gL9y6sNdN95uEOS83Y55SqHcP7MzLA==}
     engines: {node: '>= 18.12.0'}
     peerDependencies:
       webpack: ^5.27.0
 
+  style-mod@4.1.3:
+    resolution: {integrity: sha512-i/n8VsZydrugj3Iuzll8+x/00GH2vnYsk1eomD8QiRrSAeW6ItbCQDtfXCeJHd0iwiNagqjQkvpvREEPtW3IoQ==}
+
   style-to-object@1.0.14:
     resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==}
 
@@ -5661,10 +6019,10 @@ packages:
     resolution: {integrity: sha512-HcBOcR17Vx9bjaOceUvxkY3nGmbBmCBBbuWLLEWO6jtmWH8f/QoWmbyUfQZrpDINH39en1b8mptfPQT9VKQ1xQ==}
     engines: {node: '>=18', pnpm: '>=8.7.0'}
     peerDependencies:
-      svelte: ^5.0.0
+      svelte: '>=5.55.7 <6'
 
-  svelte@5.55.0:
-    resolution: {integrity: sha512-SThllKq6TRMBwPtat7ASnm/9CDXnIhBR0NPGw0ujn2DVYx9rVwsPZxDaDQcYGdUz/3BYVsCzdq7pZarRQoGvtw==}
+  svelte@5.56.3:
+    resolution: {integrity: sha512-w7JvrM5IFl5cmfbY0TLik9o7mjRUJmRMhOR51tBPu708Gr/MjbGs7VnJnr/B0CaXeI4vtnOh7RKxDr0cwhMdDA==}
     engines: {node: '>=18'}
 
   svgo@4.0.1:
@@ -5708,6 +6066,17 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
+  testreel@0.2.0:
+    resolution: {integrity: sha512-/MPI77q2NH5bgp87J2pFVXOdV3NOvnOzfyTNc6yKcCDrTDYz0l5BZvSuksDIwDqt+nrIlhGejtJfvz9bwsre9A==}
+    engines: {node: '>=20'}
+    hasBin: true
+    peerDependencies:
+      '@playwright/test': '>=1.51.0'
+      playwright-core: '>=1.51.0'
+    peerDependenciesMeta:
+      '@playwright/test':
+        optional: true
+
   text-segmentation@1.0.3:
     resolution: {integrity: sha512-iOiPUo/BGnZ6+54OsWxZidGCsdU8YbE4PSpdPinp7DeMtUJNJBoJ/ouUSTJjHkh1KntHaltHl/gDs2FC4i5+Nw==}
 
@@ -5737,6 +6106,10 @@ packages:
   tinybench@2.9.0:
     resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
 
+  tinyclip@0.1.15:
+    resolution: {integrity: sha512-uo33abH+Ays0xYaDysoBt494Hb3hsEczMpcC0MwFl773pazORx4fmvKhclhR1wonUbB6vvpRsvVMwnhfqeMc+A==}
+    engines: {node: ^16.14.0 || >= 17.3.0}
+
   tinyexec@0.3.2:
     resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
 
@@ -5811,16 +6184,6 @@ packages:
       typescript: '*'
       webpack: ^5.0.0
 
-  tsconfck@3.1.6:
-    resolution: {integrity: sha512-ks6Vjr/jEw0P1gmOVwutM3B7fWxoWBL2KRDb1JfqGVawBmO5UsvmWOQFGHBPl5yxYz4eERr19E6L7NMv+Fej4w==}
-    engines: {node: ^18 || >=20}
-    hasBin: true
-    peerDependencies:
-      typescript: ^5.0.0
-    peerDependenciesMeta:
-      typescript:
-        optional: true
-
   tslib@1.14.1:
     resolution: {integrity: sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==}
 
@@ -5834,7 +6197,7 @@ packages:
     peerDependencies:
       '@microsoft/api-extractor': ^7.36.0
       '@swc/core': ^1
-      postcss: ^8.4.12
+      postcss: '>=8.5.10'
       typescript: '>=4.5.0'
     peerDependenciesMeta:
       '@microsoft/api-extractor':
@@ -5858,6 +6221,9 @@ packages:
     resolution: {integrity: sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g==}
     engines: {node: '>= 0.6'}
 
+  typedarray@0.0.6:
+    resolution: {integrity: sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==}
+
   typescript@5.9.3:
     resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
     engines: {node: '>=14.17'}
@@ -5875,8 +6241,11 @@ packages:
   undici-types@7.18.2:
     resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
 
-  undici@7.24.6:
-    resolution: {integrity: sha512-Xi4agocCbRzt0yYMZGMA6ApD7gvtUFaxm4ZmeacWI4cZxaF6C+8I8QfofC20NAePiB/IcvZmzkJ7XPa471AEtA==}
+  undici-types@7.27.2:
+    resolution: {integrity: sha512-cH9f42mHuljpNuoS47sWDDWXVxWnJgYCzHVUlr3tn7+HVx0L6QSO+VG5qgzT4kXkR2K8ZsReaT5bupam6RNAEQ==}
+
+  undici@7.28.0:
+    resolution: {integrity: sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==}
     engines: {node: '>=20.18.1'}
 
   unified@11.0.5:
@@ -6057,8 +6426,8 @@ packages:
   utrie@1.0.2:
     resolution: {integrity: sha512-1MLa5ouZiOmQzUbjbu9VmjLzn1QLXBhwpUa7kdLUQK+KQ5KA9I1vk5U4YHe/X2Ch7PYnJfWuWT+VbuxbGwljhw==}
 
-  uuid@8.3.2:
-    resolution: {integrity: sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==}
+  uuid@11.1.1:
+    resolution: {integrity: sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==}
     hasBin: true
 
   vary@1.1.2:
@@ -6084,13 +6453,13 @@ packages:
     peerDependencies:
       '@testing-library/jest-dom': ^5.16.6 || ^5.17.0 || ^6.*
       solid-js: ^1.7.2
-      vite: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
+      vite: '>=6.4.3 <7'
     peerDependenciesMeta:
       '@testing-library/jest-dom':
         optional: true
 
-  vite@6.4.2:
-    resolution: {integrity: sha512-2N/55r4JDJ4gdrCvGgINMy+HH3iRpNIz8K6SFwVsA+JbQScLiC+clmAxBgwiSPgcG9U15QmvqCGWzMbqda5zGQ==}
+  vite@6.4.3:
+    resolution: {integrity: sha512-NTKlcQjlAK7MlQoyb6LgaqHc8sso/pVyUJYWMws3jg21uTJw/LddqIFPcPqP6PzpgbIcZyKI85sFE4HBrQDA8A==}
     engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0}
     hasBin: true
     peerDependencies:
@@ -6132,7 +6501,7 @@ packages:
   vitefu@1.1.2:
     resolution: {integrity: sha512-zpKATdUbzbsycPFBN71nS2uzBUQiVnFoOrr2rvqv34S1lcAgMKKkjWleLGeiJlZ8lwCXvtWaRn7R3ZC16SYRuw==}
     peerDependencies:
-      vite: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-beta.0
+      vite: '>=6.4.3 <7'
     peerDependenciesMeta:
       vite:
         optional: true
@@ -6151,7 +6520,7 @@ packages:
       '@vitest/ui': 4.1.2
       happy-dom: '*'
       jsdom: '*'
-      vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+      vite: '>=6.4.3 <7'
     peerDependenciesMeta:
       '@edge-runtime/vm':
         optional: true
@@ -6234,6 +6603,9 @@ packages:
     peerDependencies:
       vue: ^3.0.11
 
+  w3c-keyname@2.2.8:
+    resolution: {integrity: sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==}
+
   w3c-xmlserializer@5.0.0:
     resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
     engines: {node: '>=18'}
@@ -6275,8 +6647,8 @@ packages:
       webpack:
         optional: true
 
-  webpack-dev-server@5.2.3:
-    resolution: {integrity: sha512-9Gyu2F7+bg4Vv+pjbovuYDhHX+mqdqITykfzdM9UyKqKHlsE5aAjRhR+oOEfXW5vBeu8tarzlJFIZva4ZjAdrQ==}
+  webpack-dev-server@5.2.5:
+    resolution: {integrity: sha512-4wZtCquSuv9CKX8oybo+mqxtxZqWz47uM1Ch94lxowBztOhWCbhqvRbfC/mODOwxgV2brY+JGZpHq58/SuVFYg==}
     engines: {node: '>= 18.12.0'}
     hasBin: true
     peerDependencies:
@@ -6339,19 +6711,11 @@ packages:
     engines: {node: '>=8'}
     hasBin: true
 
-  widest-line@5.0.0:
-    resolution: {integrity: sha512-c9bZp7b5YtRj2wOe6dlj32MK+Bx/M/d+9VB2SHM1OtsUHR0aV0tdP6DWh/iMt0kWi1t5g1Iudu6hQRNd1A4PVA==}
-    engines: {node: '>=18'}
-
   wildcard@2.0.1:
     resolution: {integrity: sha512-CC1bOL87PIWSBhDcTrdeLo6eGT7mCFtrg0uIJtqJUFyK+eJnzl8A1niH56uu7KMa5XFrtiV+AQuHO3n7DsHnLQ==}
 
-  wrap-ansi@9.0.2:
-    resolution: {integrity: sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==}
-    engines: {node: '>=18'}
-
-  ws@8.20.0:
-    resolution: {integrity: sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==}
+  ws@8.21.0:
+    resolution: {integrity: sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==}
     engines: {node: '>=10.0.0'}
     peerDependencies:
       bufferutil: ^4.0.1
@@ -6376,30 +6740,19 @@ packages:
   xxhash-wasm@1.1.0:
     resolution: {integrity: sha512-147y/6YNh+tlp6nd/2pWq38i9h6mz/EuQ6njIrmW8D1BS5nCqs0P6DG+m6zTGnNz5I+uhZ0SHxBs9BsPrwcKDA==}
 
-  yallist@3.1.1:
-    resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
-
   yaml@2.8.3:
     resolution: {integrity: sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==}
     engines: {node: '>= 14.6'}
     hasBin: true
 
-  yargs-parser@21.1.1:
-    resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
-    engines: {node: '>=12'}
+  yargs-parser@22.0.0:
+    resolution: {integrity: sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==}
+    engines: {node: ^20.19.0 || ^22.12.0 || >=23}
 
   yocto-queue@1.2.2:
     resolution: {integrity: sha512-4LCcse/U2MHZ63HAJVE+v71o7yOdIe4cZ70Wpf8D/IyjDKYQLV5GD46B+hSTjJsvV5PztjvHoU580EftxjDZFQ==}
     engines: {node: '>=12.20'}
 
-  yocto-spinner@0.2.3:
-    resolution: {integrity: sha512-sqBChb33loEnkoXte1bLg45bEBsOP9N1kzQh5JZNKj/0rik4zAPTNSAVPj3uQAdc6slYJ0Ksc403G2XgxsJQFQ==}
-    engines: {node: '>=18.19'}
-
-  yoctocolors@2.1.2:
-    resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
-    engines: {node: '>=18'}
-
   zimmerframe@1.1.4:
     resolution: {integrity: sha512-B58NGBEoc8Y9MWWCQGl/gq9xBCe4IiKM0a2x7GZdQKOW5Exr8S1W24J6OgM1njK8xCRGvAJIL/MxXHf6SkmQKQ==}
 
@@ -6408,15 +6761,6 @@ packages:
     peerDependencies:
       zod: ^3.25.28 || ^4
 
-  zod-to-ts@1.2.0:
-    resolution: {integrity: sha512-x30XE43V+InwGpvTySRNz9kB7qFU8DlyEy7BsSTCHPH1R0QasMmHWZDCzYm6bVXtj/9NNJAZF3jW8rzFvH5OFA==}
-    peerDependencies:
-      typescript: ^4.9.4 || ^5.0.2
-      zod: ^3
-
-  zod@3.25.76:
-    resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
-
   zod@4.3.6:
     resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}
 
@@ -6452,19 +6796,26 @@ snapshots:
 
   '@asamuzakjp/nwsapi@2.3.9': {}
 
-  '@astrojs/compiler@2.13.1': {}
+  '@astrojs/compiler@4.0.0': {}
 
-  '@astrojs/internal-helpers@0.7.6': {}
+  '@astrojs/internal-helpers@0.10.0':
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      js-yaml: 4.2.0
+      picomatch: 4.0.4
+      retext-smartypants: 6.2.0
+      shiki: 4.2.0
+      smol-toml: 1.6.1
+      unified: 11.0.5
 
-  '@astrojs/markdown-remark@6.3.11':
+  '@astrojs/markdown-remark@7.2.0':
     dependencies:
-      '@astrojs/internal-helpers': 0.7.6
-      '@astrojs/prism': 3.3.0
+      '@astrojs/internal-helpers': 0.10.0
+      '@astrojs/prism': 4.0.2
       github-slugger: 2.0.0
       hast-util-from-html: 2.0.3
       hast-util-to-text: 4.0.2
-      import-meta-resolve: 4.2.0
-      js-yaml: 4.1.1
       mdast-util-definitions: 6.0.0
       rehype-raw: 7.0.0
       rehype-stringify: 10.0.1
@@ -6472,8 +6823,6 @@ snapshots:
       remark-parse: 11.0.0
       remark-rehype: 11.1.2
       remark-smartypants: 3.0.2
-      shiki: 3.23.0
-      smol-toml: 1.6.1
       unified: 11.0.5
       unist-util-remove-position: 5.0.0
       unist-util-visit: 5.1.0
@@ -6482,21 +6831,17 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@astrojs/prism@3.3.0':
+  '@astrojs/prism@4.0.2':
     dependencies:
       prismjs: 1.30.0
 
-  '@astrojs/telemetry@3.3.0':
+  '@astrojs/telemetry@3.3.2':
     dependencies:
       ci-info: 4.4.0
-      debug: 4.4.3
-      dlv: 1.1.3
       dset: 3.1.4
-      is-docker: 3.0.0
+      is-docker: 4.0.0
       is-wsl: 3.1.1
       which-pm-runs: 1.1.0
-    transitivePeerDependencies:
-      - supports-color
 
   '@babel/code-frame@7.29.0':
     dependencies:
@@ -6504,27 +6849,31 @@ snapshots:
       js-tokens: 4.0.0
       picocolors: 1.1.1
 
-  '@babel/compat-data@7.29.0': {}
+  '@babel/code-frame@8.0.0':
+    dependencies:
+      '@babel/helper-validator-identifier': 8.0.2
+      js-tokens: 10.0.0
+
+  '@babel/compat-data@8.0.0': {}
 
-  '@babel/core@7.29.0':
+  '@babel/core@8.0.1':
     dependencies:
-      '@babel/code-frame': 7.29.0
-      '@babel/generator': 7.29.1
-      '@babel/helper-compilation-targets': 7.28.6
-      '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
-      '@babel/helpers': 7.29.2
-      '@babel/parser': 7.29.2
-      '@babel/template': 7.28.6
-      '@babel/traverse': 7.29.0
-      '@babel/types': 7.29.0
-      '@jridgewell/remapping': 2.3.5
+      '@babel/code-frame': 8.0.0
+      '@babel/generator': 8.0.0
+      '@babel/helper-compilation-targets': 8.0.0
+      '@babel/helpers': 8.0.0
+      '@babel/parser': 8.0.0
+      '@babel/template': 8.0.0
+      '@babel/traverse': 8.0.0
+      '@babel/types': 8.0.0
+      '@types/gensync': 1.0.5
       convert-source-map: 2.0.0
-      debug: 4.4.3
+      empathic: 2.0.1
       gensync: 1.0.0-beta.2
+      import-meta-resolve: 4.2.0
       json5: 2.2.3
-      semver: 6.3.1
-    transitivePeerDependencies:
-      - supports-color
+      obug: 2.1.1
+      semver: 7.7.4
 
   '@babel/generator@7.29.1':
     dependencies:
@@ -6534,16 +6883,27 @@ snapshots:
       '@jridgewell/trace-mapping': 0.3.31
       jsesc: 3.1.0
 
-  '@babel/helper-compilation-targets@7.28.6':
+  '@babel/generator@8.0.0':
+    dependencies:
+      '@babel/parser': 8.0.0
+      '@babel/types': 8.0.0
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      '@types/jsesc': 2.5.1
+      jsesc: 3.1.0
+
+  '@babel/helper-compilation-targets@8.0.0':
     dependencies:
-      '@babel/compat-data': 7.29.0
-      '@babel/helper-validator-option': 7.27.1
+      '@babel/compat-data': 8.0.0
+      '@babel/helper-validator-option': 8.0.0
       browserslist: 4.28.1
-      lru-cache: 5.1.1
-      semver: 6.3.1
+      lru-cache: 11.2.7
+      semver: 7.7.4
 
   '@babel/helper-globals@7.28.0': {}
 
+  '@babel/helper-globals@8.0.0': {}
+
   '@babel/helper-module-imports@7.18.6':
     dependencies:
       '@babel/types': 7.29.0
@@ -6555,79 +6915,197 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  '@babel/helper-module-transforms@7.28.6(@babel/core@7.29.0)':
-    dependencies:
-      '@babel/core': 7.29.0
-      '@babel/helper-module-imports': 7.28.6
-      '@babel/helper-validator-identifier': 7.28.5
-      '@babel/traverse': 7.29.0
-    transitivePeerDependencies:
-      - supports-color
-
   '@babel/helper-plugin-utils@7.28.6': {}
 
   '@babel/helper-string-parser@7.27.1': {}
 
+  '@babel/helper-string-parser@8.0.0': {}
+
   '@babel/helper-validator-identifier@7.28.5': {}
 
-  '@babel/helper-validator-option@7.27.1': {}
+  '@babel/helper-validator-identifier@8.0.2': {}
+
+  '@babel/helper-validator-option@8.0.0': {}
 
-  '@babel/helpers@7.29.2':
+  '@babel/helpers@8.0.0':
     dependencies:
-      '@babel/template': 7.28.6
-      '@babel/types': 7.29.0
+      '@babel/template': 8.0.0
+      '@babel/types': 8.0.0
 
   '@babel/parser@7.29.2':
     dependencies:
       '@babel/types': 7.29.0
 
-  '@babel/plugin-syntax-jsx@7.28.6(@babel/core@7.29.0)':
+  '@babel/parser@8.0.0':
+    dependencies:
+      '@babel/types': 8.0.0
+
+  '@babel/plugin-syntax-jsx@7.28.6(@babel/core@8.0.1)':
+    dependencies:
+      '@babel/core': 8.0.1
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/plugin-transform-react-jsx-self@7.27.1(@babel/core@8.0.1)':
+    dependencies:
+      '@babel/core': 8.0.1
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/plugin-transform-react-jsx-source@7.27.1(@babel/core@8.0.1)':
     dependencies:
-      '@babel/core': 7.29.0
+      '@babel/core': 8.0.1
       '@babel/helper-plugin-utils': 7.28.6
 
-  '@babel/plugin-transform-react-jsx-self@7.27.1(@babel/core@7.29.0)':
+  '@babel/runtime@7.29.2': {}
+
+  '@babel/template@7.28.6':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+
+  '@babel/template@8.0.0':
+    dependencies:
+      '@babel/code-frame': 8.0.0
+      '@babel/parser': 8.0.0
+      '@babel/types': 8.0.0
+
+  '@babel/traverse@7.29.0':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/helper-globals': 7.28.0
+      '@babel/parser': 7.29.2
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/traverse@8.0.0':
+    dependencies:
+      '@babel/code-frame': 8.0.0
+      '@babel/generator': 8.0.0
+      '@babel/helper-globals': 8.0.0
+      '@babel/parser': 8.0.0
+      '@babel/template': 8.0.0
+      '@babel/types': 8.0.0
+      obug: 2.1.1
+
+  '@babel/types@7.29.0':
+    dependencies:
+      '@babel/helper-string-parser': 7.27.1
+      '@babel/helper-validator-identifier': 7.28.5
+
+  '@babel/types@8.0.0':
+    dependencies:
+      '@babel/helper-string-parser': 8.0.0
+      '@babel/helper-validator-identifier': 8.0.2
+
+  '@bramus/specificity@2.4.2':
+    dependencies:
+      css-tree: 3.2.1
+
+  '@capsizecss/unpack@4.0.0':
+    dependencies:
+      fontkitten: 1.0.3
+
+  '@clack/core@1.4.2':
+    dependencies:
+      fast-wrap-ansi: 0.2.2
+      sisteransi: 1.0.5
+
+  '@clack/prompts@1.6.0':
+    dependencies:
+      '@clack/core': 1.4.2
+      fast-string-width: 3.0.2
+      fast-wrap-ansi: 0.2.2
+      sisteransi: 1.0.5
+
+  '@codemirror/autocomplete@6.20.2':
+    dependencies:
+      '@codemirror/language': 6.12.3
+      '@codemirror/state': 6.6.0
+      '@codemirror/view': 6.43.0
+      '@lezer/common': 1.5.2
+
+  '@codemirror/commands@6.10.3':
+    dependencies:
+      '@codemirror/language': 6.12.3
+      '@codemirror/state': 6.6.0
+      '@codemirror/view': 6.43.0
+      '@lezer/common': 1.5.2
+
+  '@codemirror/lang-css@6.3.1':
+    dependencies:
+      '@codemirror/autocomplete': 6.20.2
+      '@codemirror/language': 6.12.3
+      '@codemirror/state': 6.6.0
+      '@lezer/common': 1.5.2
+      '@lezer/css': 1.3.3
+
+  '@codemirror/lang-html@6.4.11':
     dependencies:
-      '@babel/core': 7.29.0
-      '@babel/helper-plugin-utils': 7.28.6
+      '@codemirror/autocomplete': 6.20.2
+      '@codemirror/lang-css': 6.3.1
+      '@codemirror/lang-javascript': 6.2.5
+      '@codemirror/language': 6.12.3
+      '@codemirror/state': 6.6.0
+      '@codemirror/view': 6.43.0
+      '@lezer/common': 1.5.2
+      '@lezer/css': 1.3.3
+      '@lezer/html': 1.3.13
 
-  '@babel/plugin-transform-react-jsx-source@7.27.1(@babel/core@7.29.0)':
+  '@codemirror/lang-javascript@6.2.5':
     dependencies:
-      '@babel/core': 7.29.0
-      '@babel/helper-plugin-utils': 7.28.6
+      '@codemirror/autocomplete': 6.20.2
+      '@codemirror/language': 6.12.3
+      '@codemirror/lint': 6.9.6
+      '@codemirror/state': 6.6.0
+      '@codemirror/view': 6.43.0
+      '@lezer/common': 1.5.2
+      '@lezer/javascript': 1.5.4
 
-  '@babel/runtime@7.29.2': {}
+  '@codemirror/lang-markdown@6.5.0':
+    dependencies:
+      '@codemirror/autocomplete': 6.20.2
+      '@codemirror/lang-html': 6.4.11
+      '@codemirror/language': 6.12.3
+      '@codemirror/state': 6.6.0
+      '@codemirror/view': 6.43.0
+      '@lezer/common': 1.5.2
+      '@lezer/markdown': 1.6.3
 
-  '@babel/template@7.28.6':
+  '@codemirror/language@6.12.3':
     dependencies:
-      '@babel/code-frame': 7.29.0
-      '@babel/parser': 7.29.2
-      '@babel/types': 7.29.0
+      '@codemirror/state': 6.6.0
+      '@codemirror/view': 6.43.0
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+      '@lezer/lr': 1.4.10
+      style-mod: 4.1.3
 
-  '@babel/traverse@7.29.0':
+  '@codemirror/lint@6.9.6':
     dependencies:
-      '@babel/code-frame': 7.29.0
-      '@babel/generator': 7.29.1
-      '@babel/helper-globals': 7.28.0
-      '@babel/parser': 7.29.2
-      '@babel/template': 7.28.6
-      '@babel/types': 7.29.0
-      debug: 4.4.3
-    transitivePeerDependencies:
-      - supports-color
+      '@codemirror/state': 6.6.0
+      '@codemirror/view': 6.43.0
+      crelt: 1.0.6
 
-  '@babel/types@7.29.0':
+  '@codemirror/search@6.7.0':
     dependencies:
-      '@babel/helper-string-parser': 7.27.1
-      '@babel/helper-validator-identifier': 7.28.5
+      '@codemirror/state': 6.6.0
+      '@codemirror/view': 6.43.0
+      crelt: 1.0.6
 
-  '@bramus/specificity@2.4.2':
+  '@codemirror/state@6.6.0':
     dependencies:
-      css-tree: 3.2.1
+      '@marijn/find-cluster-break': 1.0.2
 
-  '@capsizecss/unpack@4.0.0':
+  '@codemirror/view@6.43.0':
     dependencies:
-      fontkitten: 1.0.3
+      '@codemirror/state': 6.6.0
+      crelt: 1.0.6
+      style-mod: 4.1.3
+      w3c-keyname: 2.2.8
 
   '@corvu/utils@0.4.2(solid-js@1.9.12)':
     dependencies:
@@ -6666,6 +7144,15 @@ snapshots:
 
   '@csstools/css-tokenizer@4.0.0': {}
 
+  '@ctrl/tinycolor@4.2.0': {}
+
+  '@derhuerst/http-basic@8.2.4':
+    dependencies:
+      caseless: 0.12.0
+      concat-stream: 2.0.0
+      http-response-object: 3.0.2
+      parse-cache-control: 1.0.1
+
   '@discoveryjs/json-ext@0.6.3': {}
 
   '@emnapi/runtime@1.9.1':
@@ -6678,157 +7165,157 @@ snapshots:
   '@esbuild/aix-ppc64@0.25.12':
     optional: true
 
-  '@esbuild/aix-ppc64@0.27.4':
+  '@esbuild/aix-ppc64@0.27.7':
     optional: true
 
   '@esbuild/android-arm64@0.25.12':
     optional: true
 
-  '@esbuild/android-arm64@0.27.4':
+  '@esbuild/android-arm64@0.27.7':
     optional: true
 
   '@esbuild/android-arm@0.25.12':
     optional: true
 
-  '@esbuild/android-arm@0.27.4':
+  '@esbuild/android-arm@0.27.7':
     optional: true
 
   '@esbuild/android-x64@0.25.12':
     optional: true
 
-  '@esbuild/android-x64@0.27.4':
+  '@esbuild/android-x64@0.27.7':
     optional: true
 
   '@esbuild/darwin-arm64@0.25.12':
     optional: true
 
-  '@esbuild/darwin-arm64@0.27.4':
+  '@esbuild/darwin-arm64@0.27.7':
     optional: true
 
   '@esbuild/darwin-x64@0.25.12':
     optional: true
 
-  '@esbuild/darwin-x64@0.27.4':
+  '@esbuild/darwin-x64@0.27.7':
     optional: true
 
   '@esbuild/freebsd-arm64@0.25.12':
     optional: true
 
-  '@esbuild/freebsd-arm64@0.27.4':
+  '@esbuild/freebsd-arm64@0.27.7':
     optional: true
 
   '@esbuild/freebsd-x64@0.25.12':
     optional: true
 
-  '@esbuild/freebsd-x64@0.27.4':
+  '@esbuild/freebsd-x64@0.27.7':
     optional: true
 
   '@esbuild/linux-arm64@0.25.12':
     optional: true
 
-  '@esbuild/linux-arm64@0.27.4':
+  '@esbuild/linux-arm64@0.27.7':
     optional: true
 
   '@esbuild/linux-arm@0.25.12':
     optional: true
 
-  '@esbuild/linux-arm@0.27.4':
+  '@esbuild/linux-arm@0.27.7':
     optional: true
 
   '@esbuild/linux-ia32@0.25.12':
     optional: true
 
-  '@esbuild/linux-ia32@0.27.4':
+  '@esbuild/linux-ia32@0.27.7':
     optional: true
 
   '@esbuild/linux-loong64@0.25.12':
     optional: true
 
-  '@esbuild/linux-loong64@0.27.4':
+  '@esbuild/linux-loong64@0.27.7':
     optional: true
 
   '@esbuild/linux-mips64el@0.25.12':
     optional: true
 
-  '@esbuild/linux-mips64el@0.27.4':
+  '@esbuild/linux-mips64el@0.27.7':
     optional: true
 
   '@esbuild/linux-ppc64@0.25.12':
     optional: true
 
-  '@esbuild/linux-ppc64@0.27.4':
+  '@esbuild/linux-ppc64@0.27.7':
     optional: true
 
   '@esbuild/linux-riscv64@0.25.12':
     optional: true
 
-  '@esbuild/linux-riscv64@0.27.4':
+  '@esbuild/linux-riscv64@0.27.7':
     optional: true
 
   '@esbuild/linux-s390x@0.25.12':
     optional: true
 
-  '@esbuild/linux-s390x@0.27.4':
+  '@esbuild/linux-s390x@0.27.7':
     optional: true
 
   '@esbuild/linux-x64@0.25.12':
     optional: true
 
-  '@esbuild/linux-x64@0.27.4':
+  '@esbuild/linux-x64@0.27.7':
     optional: true
 
   '@esbuild/netbsd-arm64@0.25.12':
     optional: true
 
-  '@esbuild/netbsd-arm64@0.27.4':
+  '@esbuild/netbsd-arm64@0.27.7':
     optional: true
 
   '@esbuild/netbsd-x64@0.25.12':
     optional: true
 
-  '@esbuild/netbsd-x64@0.27.4':
+  '@esbuild/netbsd-x64@0.27.7':
     optional: true
 
   '@esbuild/openbsd-arm64@0.25.12':
     optional: true
 
-  '@esbuild/openbsd-arm64@0.27.4':
+  '@esbuild/openbsd-arm64@0.27.7':
     optional: true
 
   '@esbuild/openbsd-x64@0.25.12':
     optional: true
 
-  '@esbuild/openbsd-x64@0.27.4':
+  '@esbuild/openbsd-x64@0.27.7':
     optional: true
 
   '@esbuild/openharmony-arm64@0.25.12':
     optional: true
 
-  '@esbuild/openharmony-arm64@0.27.4':
+  '@esbuild/openharmony-arm64@0.27.7':
     optional: true
 
   '@esbuild/sunos-x64@0.25.12':
     optional: true
 
-  '@esbuild/sunos-x64@0.27.4':
+  '@esbuild/sunos-x64@0.27.7':
     optional: true
 
   '@esbuild/win32-arm64@0.25.12':
     optional: true
 
-  '@esbuild/win32-arm64@0.27.4':
+  '@esbuild/win32-arm64@0.27.7':
     optional: true
 
   '@esbuild/win32-ia32@0.25.12':
     optional: true
 
-  '@esbuild/win32-ia32@0.27.4':
+  '@esbuild/win32-ia32@0.27.7':
     optional: true
 
   '@esbuild/win32-x64@0.25.12':
     optional: true
 
-  '@esbuild/win32-x64@0.27.4':
+  '@esbuild/win32-x64@0.27.7':
     optional: true
 
   '@exodus/bytes@1.15.0': {}
@@ -6837,7 +7324,7 @@ snapshots:
     dependencies:
       ajv: 8.18.0
       ajv-formats: 3.0.1(ajv@8.18.0)
-      fast-uri: 3.1.0
+      fast-uri: 4.0.0
 
   '@fastify/cors@10.1.0':
     dependencies:
@@ -7016,6 +7503,125 @@ snapshots:
   '@img/sharp-win32-x64@0.34.5':
     optional: true
 
+  '@inquirer/ansi@2.0.5': {}
+
+  '@inquirer/checkbox@5.1.5(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/ansi': 2.0.5
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/figures': 2.0.5
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/confirm@6.0.13(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/core@11.1.10(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/ansi': 2.0.5
+      '@inquirer/figures': 2.0.5
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+      cli-width: 4.1.0
+      fast-wrap-ansi: 0.2.2
+      mute-stream: 3.0.0
+      signal-exit: 4.1.0
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/editor@5.1.2(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/external-editor': 3.0.0(@types/node@25.5.0)
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/expand@5.0.14(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/external-editor@3.0.0(@types/node@25.5.0)':
+    dependencies:
+      chardet: 2.1.1
+      iconv-lite: 0.7.2
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/figures@2.0.5': {}
+
+  '@inquirer/input@5.0.13(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/number@4.0.13(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/password@5.0.13(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/ansi': 2.0.5
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/prompts@8.4.3(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/checkbox': 5.1.5(@types/node@25.5.0)
+      '@inquirer/confirm': 6.0.13(@types/node@25.5.0)
+      '@inquirer/editor': 5.1.2(@types/node@25.5.0)
+      '@inquirer/expand': 5.0.14(@types/node@25.5.0)
+      '@inquirer/input': 5.0.13(@types/node@25.5.0)
+      '@inquirer/number': 4.0.13(@types/node@25.5.0)
+      '@inquirer/password': 5.0.13(@types/node@25.5.0)
+      '@inquirer/rawlist': 5.2.9(@types/node@25.5.0)
+      '@inquirer/search': 4.1.9(@types/node@25.5.0)
+      '@inquirer/select': 5.1.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/rawlist@5.2.9(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/search@4.1.9(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/figures': 2.0.5
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/select@5.1.5(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/ansi': 2.0.5
+      '@inquirer/core': 11.1.10(@types/node@25.5.0)
+      '@inquirer/figures': 2.0.5
+      '@inquirer/type': 4.0.5(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/type@4.0.5(@types/node@25.5.0)':
+    optionalDependencies:
+      '@types/node': 25.5.0
+
   '@internationalized/date@3.12.1':
     dependencies:
       '@swc/helpers': 0.5.21
@@ -7202,6 +7808,49 @@ snapshots:
 
   '@leichtgewicht/ip-codec@2.0.5': {}
 
+  '@lezer/common@1.5.2': {}
+
+  '@lezer/css@1.3.3':
+    dependencies:
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+      '@lezer/lr': 1.4.10
+
+  '@lezer/highlight@1.2.3':
+    dependencies:
+      '@lezer/common': 1.5.2
+
+  '@lezer/html@1.3.13':
+    dependencies:
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+      '@lezer/lr': 1.4.10
+
+  '@lezer/javascript@1.5.4':
+    dependencies:
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+      '@lezer/lr': 1.4.10
+
+  '@lezer/lr@1.4.10':
+    dependencies:
+      '@lezer/common': 1.5.2
+
+  '@lezer/markdown@1.6.3':
+    dependencies:
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+
+  '@lit-labs/ssr-dom-shim@1.6.0': {}
+
+  '@lit/react@1.0.8(@types/react@19.2.14)':
+    dependencies:
+      '@types/react': 19.2.14
+
+  '@lit/reactive-element@2.1.2':
+    dependencies:
+      '@lit-labs/ssr-dom-shim': 1.6.0
+
   '@mantine/core@7.17.8(@mantine/hooks@7.17.8(react@19.2.4))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
     dependencies:
       '@floating-ui/react': 0.26.28(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
@@ -7220,6 +7869,8 @@ snapshots:
     dependencies:
       react: 19.2.4
 
+  '@marijn/find-cluster-break@1.0.2': {}
+
   '@noble/hashes@1.4.0': {}
 
   '@nodelib/fs.scandir@2.1.5':
@@ -8220,39 +8871,64 @@ snapshots:
   '@rollup/rollup-win32-x64-msvc@4.60.0':
     optional: true
 
-  '@shikijs/core@3.23.0':
+  '@shikijs/core@4.2.0':
     dependencies:
-      '@shikijs/types': 3.23.0
+      '@shikijs/primitive': 4.2.0
+      '@shikijs/types': 4.2.0
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.4
       hast-util-to-html: 9.0.5
 
-  '@shikijs/engine-javascript@3.23.0':
+  '@shikijs/engine-javascript@4.2.0':
     dependencies:
-      '@shikijs/types': 3.23.0
+      '@shikijs/types': 4.2.0
       '@shikijs/vscode-textmate': 10.0.2
-      oniguruma-to-es: 4.3.5
+      oniguruma-to-es: 4.3.6
 
-  '@shikijs/engine-oniguruma@3.23.0':
+  '@shikijs/engine-oniguruma@4.2.0':
     dependencies:
-      '@shikijs/types': 3.23.0
+      '@shikijs/types': 4.2.0
       '@shikijs/vscode-textmate': 10.0.2
 
-  '@shikijs/langs@3.23.0':
+  '@shikijs/langs@4.2.0':
     dependencies:
-      '@shikijs/types': 3.23.0
+      '@shikijs/types': 4.2.0
 
-  '@shikijs/themes@3.23.0':
+  '@shikijs/primitive@4.2.0':
     dependencies:
-      '@shikijs/types': 3.23.0
+      '@shikijs/types': 4.2.0
+      '@shikijs/vscode-textmate': 10.0.2
+      '@types/hast': 3.0.4
+
+  '@shikijs/themes@4.2.0':
+    dependencies:
+      '@shikijs/types': 4.2.0
 
-  '@shikijs/types@3.23.0':
+  '@shikijs/types@4.2.0':
     dependencies:
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.4
 
   '@shikijs/vscode-textmate@10.0.2': {}
 
+  '@shoelace-style/animations@1.2.0': {}
+
+  '@shoelace-style/localize@3.2.2': {}
+
+  '@shoelace-style/shoelace@2.20.1(@floating-ui/utils@0.2.11)(@types/react@19.2.14)':
+    dependencies:
+      '@ctrl/tinycolor': 4.2.0
+      '@floating-ui/dom': 1.7.6
+      '@lit/react': 1.0.8(@types/react@19.2.14)
+      '@shoelace-style/animations': 1.2.0
+      '@shoelace-style/localize': 3.2.2
+      composed-offset-position: 0.0.6(@floating-ui/utils@0.2.11)
+      lit: 3.3.3
+      qr-creator: 1.0.0
+    transitivePeerDependencies:
+      - '@floating-ui/utils'
+      - '@types/react'
+
   '@solid-primitives/event-listener@2.4.5(solid-js@1.9.12)':
     dependencies:
       '@solid-primitives/utils': 6.4.0(solid-js@1.9.12)
@@ -8316,29 +8992,29 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
-  '@sveltejs/acorn-typescript@1.0.9(acorn@8.16.0)':
+  '@sveltejs/acorn-typescript@1.0.10(acorn@8.16.0)':
     dependencies:
       acorn: 8.16.0
 
-  '@sveltejs/vite-plugin-svelte-inspector@4.0.1(@sveltejs/vite-plugin-svelte@5.1.1(svelte@5.55.0)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)))(svelte@5.55.0)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
+  '@sveltejs/vite-plugin-svelte-inspector@4.0.1(@sveltejs/vite-plugin-svelte@5.1.1(svelte@5.56.3(@typescript-eslint/types@8.57.2))(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)))(svelte@5.56.3(@typescript-eslint/types@8.57.2))(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
     dependencies:
-      '@sveltejs/vite-plugin-svelte': 5.1.1(svelte@5.55.0)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+      '@sveltejs/vite-plugin-svelte': 5.1.1(svelte@5.56.3(@typescript-eslint/types@8.57.2))(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       debug: 4.4.3
-      svelte: 5.55.0
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+      svelte: 5.56.3(@typescript-eslint/types@8.57.2)
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
     transitivePeerDependencies:
       - supports-color
 
-  '@sveltejs/vite-plugin-svelte@5.1.1(svelte@5.55.0)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
+  '@sveltejs/vite-plugin-svelte@5.1.1(svelte@5.56.3(@typescript-eslint/types@8.57.2))(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
     dependencies:
-      '@sveltejs/vite-plugin-svelte-inspector': 4.0.1(@sveltejs/vite-plugin-svelte@5.1.1(svelte@5.55.0)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)))(svelte@5.55.0)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+      '@sveltejs/vite-plugin-svelte-inspector': 4.0.1(@sveltejs/vite-plugin-svelte@5.1.1(svelte@5.56.3(@typescript-eslint/types@8.57.2))(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)))(svelte@5.56.3(@typescript-eslint/types@8.57.2))(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       debug: 4.4.3
       deepmerge: 4.3.1
       kleur: 4.1.5
       magic-string: 0.30.21
-      svelte: 5.55.0
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
-      vitefu: 1.1.2(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+      svelte: 5.56.3(@typescript-eslint/types@8.57.2)
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+      vitefu: 1.1.2(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
     transitivePeerDependencies:
       - supports-color
 
@@ -8483,6 +9159,8 @@ snapshots:
       '@types/qs': 6.15.0
       '@types/serve-static': 1.15.10
 
+  '@types/gensync@1.0.5': {}
+
   '@types/hast@3.0.4':
     dependencies:
       '@types/unist': 3.0.3
@@ -8497,6 +9175,15 @@ snapshots:
 
   '@types/js-yaml@4.0.9': {}
 
+  '@types/jsdom@28.0.3':
+    dependencies:
+      '@types/node': 25.5.0
+      '@types/tough-cookie': 4.0.5
+      parse5: 8.0.0
+      undici-types: 7.27.2
+
+  '@types/jsesc@2.5.1': {}
+
   '@types/json-schema@7.0.15': {}
 
   '@types/lodash-es@4.17.12':
@@ -8517,6 +9204,8 @@ snapshots:
     dependencies:
       '@types/unist': 3.0.3
 
+  '@types/node@10.17.60': {}
+
   '@types/node@25.5.0':
     dependencies:
       undici-types: 7.18.2
@@ -8560,6 +9249,8 @@ snapshots:
     dependencies:
       '@types/node': 25.5.0
 
+  '@types/tough-cookie@4.0.5': {}
+
   '@types/trusted-types@2.0.7': {}
 
   '@types/unist@3.0.3': {}
@@ -8568,33 +9259,32 @@ snapshots:
     dependencies:
       '@types/node': 25.5.0
 
-  '@typescript-eslint/types@8.57.2': {}
+  '@typescript-eslint/types@8.57.2':
+    optional: true
 
   '@ungap/structured-clone@1.3.0': {}
 
-  '@vitejs/plugin-react-swc@3.11.0(@swc/helpers@0.5.21)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
+  '@vitejs/plugin-react-swc@3.11.0(@swc/helpers@0.5.21)(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
     dependencies:
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@swc/core': 1.15.30(@swc/helpers@0.5.21)
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
     transitivePeerDependencies:
       - '@swc/helpers'
 
-  '@vitejs/plugin-react@4.7.0(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
+  '@vitejs/plugin-react@4.7.0(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
     dependencies:
-      '@babel/core': 7.29.0
-      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
-      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@7.29.0)
+      '@babel/core': 8.0.1
+      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@8.0.1)
+      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@8.0.1)
       '@rolldown/pluginutils': 1.0.0-beta.27
       '@types/babel__core': 7.20.5
       react-refresh: 0.17.0
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
-    transitivePeerDependencies:
-      - supports-color
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
-  '@vitejs/plugin-vue@5.2.4(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))':
+  '@vitejs/plugin-vue@5.2.4(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))(vue@3.5.31(typescript@5.9.3))':
     dependencies:
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
       vue: 3.5.31(typescript@5.9.3)
 
   '@vitest/expect@4.1.2':
@@ -8606,13 +9296,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.1.0
 
-  '@vitest/mocker@4.1.2(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
+  '@vitest/mocker@4.1.2(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))':
     dependencies:
       '@vitest/spy': 4.1.2
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
   '@vitest/pretty-format@4.1.2':
     dependencies:
@@ -8682,7 +9372,7 @@ snapshots:
       '@vue/shared': 3.5.31
       estree-walker: 2.0.2
       magic-string: 0.30.21
-      postcss: 8.5.8
+      postcss: 8.5.15
       source-map-js: 1.2.1
 
   '@vue/compiler-ssr@3.5.31':
@@ -8831,20 +9521,20 @@ snapshots:
 
   '@webpack-cli/configtest@3.0.1(webpack-cli@6.0.1)(webpack@5.105.4)':
     dependencies:
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
-      webpack-cli: 6.0.1(webpack-dev-server@5.2.3)(webpack@5.105.4)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
+      webpack-cli: 6.0.1(webpack-dev-server@5.2.5)(webpack@5.105.4)
 
   '@webpack-cli/info@3.0.1(webpack-cli@6.0.1)(webpack@5.105.4)':
     dependencies:
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
-      webpack-cli: 6.0.1(webpack-dev-server@5.2.3)(webpack@5.105.4)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
+      webpack-cli: 6.0.1(webpack-dev-server@5.2.5)(webpack@5.105.4)
 
-  '@webpack-cli/serve@3.0.1(webpack-cli@6.0.1)(webpack-dev-server@5.2.3)(webpack@5.105.4)':
+  '@webpack-cli/serve@3.0.1(webpack-cli@6.0.1)(webpack-dev-server@5.2.5)(webpack@5.105.4)':
     dependencies:
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
-      webpack-cli: 6.0.1(webpack-dev-server@5.2.3)(webpack@5.105.4)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
+      webpack-cli: 6.0.1(webpack-dev-server@5.2.5)(webpack@5.105.4)
     optionalDependencies:
-      webpack-dev-server: 5.2.3(tslib@2.8.1)(webpack-cli@6.0.1)(webpack@5.105.4)
+      webpack-dev-server: 5.2.5(tslib@2.8.1)(webpack-cli@6.0.1)(webpack@5.105.4)
 
   '@xtuc/ieee754@1.2.0': {}
 
@@ -8865,6 +9555,12 @@ snapshots:
 
   acorn@8.16.0: {}
 
+  agent-base@6.0.2:
+    dependencies:
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
   ajv-formats@2.1.1(ajv@8.18.0):
     optionalDependencies:
       ajv: 8.18.0
@@ -8881,29 +9577,21 @@ snapshots:
   ajv@8.18.0:
     dependencies:
       fast-deep-equal: 3.1.3
-      fast-uri: 3.1.0
+      fast-uri: 4.0.0
       json-schema-traverse: 1.0.0
       require-from-string: 2.0.2
 
   alien-signals@1.0.13: {}
 
-  ansi-align@3.0.1:
-    dependencies:
-      string-width: 4.2.3
-
   ansi-html-community@0.0.8: {}
 
   ansi-regex@5.0.1: {}
 
-  ansi-regex@6.2.2: {}
-
   ansi-styles@4.3.0:
     dependencies:
       color-convert: 2.0.1
 
-  ansi-styles@6.2.3: {}
-
-  antenna-component-library@file:../antenna-component-library(@fortawesome/fontawesome-svg-core@6.7.2)(@fortawesome/free-solid-svg-icons@6.7.2)(@fortawesome/vue-fontawesome@3.1.3(@fortawesome/fontawesome-svg-core@6.7.2)(vue@3.5.31(typescript@5.9.3)))(@vueup/vue-quill@1.2.0(vue@3.5.31(typescript@5.9.3)))(ace-builds@1.43.6)(ajv@8.18.0)(dompurify@3.4.0)(marked@15.0.12)(quill@2.0.3)(rollup@4.60.0)(vue3-click-away@1.2.4)(vue@3.5.31(typescript@5.9.3)):
+  antenna-component-library@file:../antenna-component-library(@fortawesome/fontawesome-svg-core@6.7.2)(@fortawesome/free-solid-svg-icons@6.7.2)(@fortawesome/vue-fontawesome@3.1.3(@fortawesome/fontawesome-svg-core@6.7.2)(vue@3.5.31(typescript@5.9.3)))(@vueup/vue-quill@1.2.0(vue@3.5.31(typescript@5.9.3)))(ace-builds@1.43.6)(ajv@8.18.0)(dompurify@3.4.11)(marked@15.0.12)(quill@2.0.3)(rollup@4.60.0)(vue3-click-away@1.2.4)(vue@3.5.31(typescript@5.9.3)):
     dependencies:
       '@fortawesome/fontawesome-svg-core': 6.7.2
       '@fortawesome/free-brands-svg-icons': 6.7.2
@@ -8914,7 +9602,7 @@ snapshots:
       '@vueup/vue-quill': 1.2.0(vue@3.5.31(typescript@5.9.3))
       ace-builds: 1.43.6
       ajv: 8.18.0
-      dompurify: 3.4.0
+      dompurify: 3.4.11
       marked: 15.0.12
       quill: 2.0.3
       vue: 3.5.31(typescript@5.9.3)
@@ -8963,71 +9651,63 @@ snapshots:
       '@babel/parser': 7.29.2
       ast-kit: 2.2.0
 
-  astro@5.18.1(@types/node@25.5.0)(jiti@1.21.7)(rollup@4.60.0)(terser@5.46.1)(typescript@5.9.3)(yaml@2.8.3):
+  astro@6.4.8(@types/node@25.5.0)(jiti@1.21.7)(rollup@4.60.0)(terser@5.46.1)(yaml@2.8.3):
     dependencies:
-      '@astrojs/compiler': 2.13.1
-      '@astrojs/internal-helpers': 0.7.6
-      '@astrojs/markdown-remark': 6.3.11
-      '@astrojs/telemetry': 3.3.0
+      '@astrojs/compiler': 4.0.0
+      '@astrojs/internal-helpers': 0.10.0
+      '@astrojs/markdown-remark': 7.2.0
+      '@astrojs/telemetry': 3.3.2
       '@capsizecss/unpack': 4.0.0
+      '@clack/prompts': 1.6.0
       '@oslojs/encoding': 1.1.0
       '@rollup/pluginutils': 5.3.0(rollup@4.60.0)
-      acorn: 8.16.0
       aria-query: 5.3.2
       axobject-query: 4.1.0
-      boxen: 8.0.1
       ci-info: 4.4.0
       clsx: 2.1.1
-      common-ancestor-path: 1.0.1
+      common-ancestor-path: 2.0.0
       cookie: 1.1.1
-      cssesc: 3.0.0
-      debug: 4.4.3
-      deterministic-object-hash: 2.0.2
-      devalue: 5.6.4
+      devalue: 5.8.1
       diff: 8.0.4
-      dlv: 1.1.3
       dset: 3.1.4
-      es-module-lexer: 1.7.0
-      esbuild: 0.27.4
-      estree-walker: 3.0.3
+      es-module-lexer: 2.0.0
+      esbuild: 0.27.7
       flattie: 1.1.1
       fontace: 0.4.1
+      get-tsconfig: 5.0.0-beta.4
       github-slugger: 2.0.0
       html-escaper: 3.0.3
       http-cache-semantics: 4.2.0
-      import-meta-resolve: 4.2.0
-      js-yaml: 4.1.1
+      js-yaml: 4.2.0
+      jsonc-parser: 3.3.1
       magic-string: 0.30.21
       magicast: 0.5.2
       mrmime: 2.0.1
       neotraverse: 0.6.18
-      p-limit: 6.2.0
-      p-queue: 8.1.1
+      obug: 2.1.1
+      p-limit: 7.3.0
+      p-queue: 9.3.0
       package-manager-detector: 1.6.0
       piccolore: 0.1.3
       picomatch: 4.0.4
-      prompts: 2.4.2
       rehype: 13.0.2
       semver: 7.7.4
-      shiki: 3.23.0
+      shiki: 4.2.0
       smol-toml: 1.6.1
       svgo: 4.0.1
+      tinyclip: 0.1.15
       tinyexec: 1.0.4
       tinyglobby: 0.2.15
-      tsconfck: 3.1.6(typescript@5.9.3)
       ultrahtml: 1.6.0
       unifont: 0.7.4
       unist-util-visit: 5.1.0
       unstorage: 1.17.5
       vfile: 6.0.3
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
-      vitefu: 1.1.2(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+      vitefu: 1.1.2(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       xxhash-wasm: 1.1.0
-      yargs-parser: 21.1.1
-      yocto-spinner: 0.2.3
-      zod: 3.25.76
-      zod-to-json-schema: 3.25.2(zod@3.25.76)
-      zod-to-ts: 1.2.0(typescript@5.9.3)(zod@3.25.76)
+      yargs-parser: 22.0.0
+      zod: 4.3.6
     optionalDependencies:
       sharp: 0.34.5
     transitivePeerDependencies:
@@ -9061,7 +9741,6 @@ snapshots:
       - supports-color
       - terser
       - tsx
-      - typescript
       - uploadthing
       - yaml
 
@@ -9069,13 +9748,13 @@ snapshots:
 
   atomic-sleep@1.0.0: {}
 
-  autoprefixer@10.4.27(postcss@8.5.8):
+  autoprefixer@10.4.27(postcss@8.5.15):
     dependencies:
       browserslist: 4.28.1
       caniuse-lite: 1.0.30001781
       fraction.js: 5.3.4
       picocolors: 1.1.1
-      postcss: 8.5.8
+      postcss: 8.5.15
       postcss-value-parser: 4.2.0
 
   avvio@9.2.0:
@@ -9087,19 +9766,19 @@ snapshots:
 
   axobject-query@4.1.0: {}
 
-  babel-plugin-jsx-dom-expressions@0.40.6(@babel/core@7.29.0):
+  babel-plugin-jsx-dom-expressions@0.40.6(@babel/core@8.0.1):
     dependencies:
-      '@babel/core': 7.29.0
+      '@babel/core': 8.0.1
       '@babel/helper-module-imports': 7.18.6
-      '@babel/plugin-syntax-jsx': 7.28.6(@babel/core@7.29.0)
+      '@babel/plugin-syntax-jsx': 7.28.6(@babel/core@8.0.1)
       '@babel/types': 7.29.0
       html-entities: 2.3.3
       parse5: 7.3.0
 
-  babel-preset-solid@1.9.12(@babel/core@7.29.0)(solid-js@1.9.12):
+  babel-preset-solid@1.9.12(@babel/core@8.0.1)(solid-js@1.9.12):
     dependencies:
-      '@babel/core': 7.29.0
-      babel-plugin-jsx-dom-expressions: 0.40.6(@babel/core@7.29.0)
+      '@babel/core': 8.0.1
+      babel-plugin-jsx-dom-expressions: 0.40.6(@babel/core@8.0.1)
     optionalDependencies:
       solid-js: 1.9.12
 
@@ -9107,8 +9786,6 @@ snapshots:
 
   balanced-match@1.0.2: {}
 
-  base-64@1.0.0: {}
-
   base64-arraybuffer@1.0.2: {}
 
   baseline-browser-mapping@2.10.12: {}
@@ -9123,16 +9800,16 @@ snapshots:
 
   birpc@2.9.0: {}
 
-  bits-ui@1.8.0(svelte@5.55.0):
+  bits-ui@1.8.0(svelte@5.56.3(@typescript-eslint/types@8.57.2)):
     dependencies:
       '@floating-ui/core': 1.7.5
       '@floating-ui/dom': 1.7.6
       '@internationalized/date': 3.12.1
       css.escape: 1.5.1
       esm-env: 1.2.2
-      runed: 0.23.4(svelte@5.55.0)
-      svelte: 5.55.0
-      svelte-toolbelt: 0.7.1(svelte@5.55.0)
+      runed: 0.23.4(svelte@5.56.3(@typescript-eslint/types@8.57.2))
+      svelte: 5.56.3(@typescript-eslint/types@8.57.2)
+      svelte-toolbelt: 0.7.1(svelte@5.56.3(@typescript-eslint/types@8.57.2))
       tabbable: 6.4.0
 
   body-parser@1.20.4:
@@ -9145,7 +9822,7 @@ snapshots:
       http-errors: 2.0.1
       iconv-lite: 0.4.24
       on-finished: 2.4.1
-      qs: 6.14.2
+      qs: 6.15.2
       raw-body: 2.5.3
       type-is: 1.6.18
       unpipe: 1.0.0
@@ -9159,17 +9836,6 @@ snapshots:
 
   boolbase@1.0.0: {}
 
-  boxen@8.0.1:
-    dependencies:
-      ansi-align: 3.0.1
-      camelcase: 8.0.0
-      chalk: 5.6.2
-      cli-boxes: 3.0.0
-      string-width: 7.2.0
-      type-fest: 4.41.0
-      widest-line: 5.0.0
-      wrap-ansi: 9.0.2
-
   brace-expansion@2.0.3:
     dependencies:
       balanced-match: 1.0.2
@@ -9194,9 +9860,9 @@ snapshots:
     dependencies:
       run-applescript: 7.1.0
 
-  bundle-require@5.1.0(esbuild@0.27.4):
+  bundle-require@5.1.0(esbuild@0.27.7):
     dependencies:
-      esbuild: 0.27.4
+      esbuild: 0.27.7
       load-tsconfig: 0.2.5
 
   bytes@3.1.2: {}
@@ -9229,10 +9895,10 @@ snapshots:
 
   camelcase-css@2.0.1: {}
 
-  camelcase@8.0.0: {}
-
   caniuse-lite@1.0.30001781: {}
 
+  caseless@0.12.0: {}
+
   ccount@2.0.1: {}
 
   chai@6.2.2: {}
@@ -9242,14 +9908,14 @@ snapshots:
       ansi-styles: 4.3.0
       supports-color: 7.2.0
 
-  chalk@5.6.2: {}
-
   character-entities-html4@2.1.0: {}
 
   character-entities-legacy@3.0.0: {}
 
   character-entities@2.0.2: {}
 
+  chardet@2.1.1: {}
+
   chokidar@3.6.0:
     dependencies:
       anymatch: 3.1.3
@@ -9280,7 +9946,7 @@ snapshots:
     dependencies:
       source-map: 0.6.1
 
-  cli-boxes@3.0.0: {}
+  cli-width@4.1.0: {}
 
   clone-deep@4.0.1:
     dependencies:
@@ -9292,6 +9958,16 @@ snapshots:
 
   clsx@2.1.1: {}
 
+  codemirror@6.0.2:
+    dependencies:
+      '@codemirror/autocomplete': 6.20.2
+      '@codemirror/commands': 6.10.3
+      '@codemirror/language': 6.12.3
+      '@codemirror/lint': 6.9.6
+      '@codemirror/search': 6.7.0
+      '@codemirror/state': 6.6.0
+      '@codemirror/view': 6.43.0
+
   color-convert@2.0.1:
     dependencies:
       color-name: 1.1.4
@@ -9306,13 +9982,19 @@ snapshots:
 
   commander@12.1.0: {}
 
+  commander@14.0.3: {}
+
   commander@2.20.3: {}
 
   commander@4.1.1: {}
 
   commander@8.3.0: {}
 
-  common-ancestor-path@1.0.1: {}
+  common-ancestor-path@2.0.0: {}
+
+  composed-offset-position@0.0.6(@floating-ui/utils@0.2.11):
+    dependencies:
+      '@floating-ui/utils': 0.2.11
 
   compressible@2.0.18:
     dependencies:
@@ -9330,6 +10012,13 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  concat-stream@2.0.0:
+    dependencies:
+      buffer-from: 1.1.2
+      inherits: 2.0.4
+      readable-stream: 3.6.2
+      typedarray: 0.0.6
+
   confbox@0.1.8: {}
 
   confbox@0.2.4: {}
@@ -9356,6 +10045,8 @@ snapshots:
 
   core-util-is@1.0.3: {}
 
+  crelt@1.0.6: {}
+
   cross-spawn@7.0.6:
     dependencies:
       path-key: 3.1.1
@@ -9372,16 +10063,16 @@ snapshots:
 
   css-loader@7.1.4(webpack@5.105.4):
     dependencies:
-      icss-utils: 5.1.0(postcss@8.5.8)
-      postcss: 8.5.8
-      postcss-modules-extract-imports: 3.1.0(postcss@8.5.8)
-      postcss-modules-local-by-default: 4.2.0(postcss@8.5.8)
-      postcss-modules-scope: 3.2.1(postcss@8.5.8)
-      postcss-modules-values: 4.0.0(postcss@8.5.8)
+      icss-utils: 5.1.0(postcss@8.5.15)
+      postcss: 8.5.15
+      postcss-modules-extract-imports: 3.1.0(postcss@8.5.15)
+      postcss-modules-local-by-default: 4.2.0(postcss@8.5.15)
+      postcss-modules-scope: 3.2.1(postcss@8.5.15)
+      postcss-modules-values: 4.0.0(postcss@8.5.15)
       postcss-value-parser: 4.2.0
       semver: 7.7.4
     optionalDependencies:
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
 
   css-render@0.15.14:
     dependencies:
@@ -9508,11 +10199,7 @@ snapshots:
 
   detect-node@2.1.0: {}
 
-  deterministic-object-hash@2.0.2:
-    dependencies:
-      base-64: 1.0.0
-
-  devalue@5.6.4: {}
+  devalue@5.8.1: {}
 
   devlop@1.1.0:
     dependencies:
@@ -9554,7 +10241,7 @@ snapshots:
     dependencies:
       domelementtype: 2.3.0
 
-  dompurify@3.4.0:
+  dompurify@3.4.11:
     optionalDependencies:
       '@types/trusted-types': 2.0.7
 
@@ -9587,9 +10274,7 @@ snapshots:
 
   electron-to-chromium@1.5.328: {}
 
-  emoji-regex@10.6.0: {}
-
-  emoji-regex@8.0.0: {}
+  empathic@2.0.1: {}
 
   encodeurl@2.0.0: {}
 
@@ -9606,14 +10291,14 @@ snapshots:
 
   entities@7.0.1: {}
 
+  env-paths@2.2.1: {}
+
   envinfo@7.21.0: {}
 
   es-define-property@1.0.1: {}
 
   es-errors@1.3.0: {}
 
-  es-module-lexer@1.7.0: {}
-
   es-module-lexer@2.0.0: {}
 
   es-object-atoms@1.1.1:
@@ -9649,34 +10334,34 @@ snapshots:
       '@esbuild/win32-ia32': 0.25.12
       '@esbuild/win32-x64': 0.25.12
 
-  esbuild@0.27.4:
-    optionalDependencies:
-      '@esbuild/aix-ppc64': 0.27.4
-      '@esbuild/android-arm': 0.27.4
-      '@esbuild/android-arm64': 0.27.4
-      '@esbuild/android-x64': 0.27.4
-      '@esbuild/darwin-arm64': 0.27.4
-      '@esbuild/darwin-x64': 0.27.4
-      '@esbuild/freebsd-arm64': 0.27.4
-      '@esbuild/freebsd-x64': 0.27.4
-      '@esbuild/linux-arm': 0.27.4
-      '@esbuild/linux-arm64': 0.27.4
-      '@esbuild/linux-ia32': 0.27.4
-      '@esbuild/linux-loong64': 0.27.4
-      '@esbuild/linux-mips64el': 0.27.4
-      '@esbuild/linux-ppc64': 0.27.4
-      '@esbuild/linux-riscv64': 0.27.4
-      '@esbuild/linux-s390x': 0.27.4
-      '@esbuild/linux-x64': 0.27.4
-      '@esbuild/netbsd-arm64': 0.27.4
-      '@esbuild/netbsd-x64': 0.27.4
-      '@esbuild/openbsd-arm64': 0.27.4
-      '@esbuild/openbsd-x64': 0.27.4
-      '@esbuild/openharmony-arm64': 0.27.4
-      '@esbuild/sunos-x64': 0.27.4
-      '@esbuild/win32-arm64': 0.27.4
-      '@esbuild/win32-ia32': 0.27.4
-      '@esbuild/win32-x64': 0.27.4
+  esbuild@0.27.7:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.7
+      '@esbuild/android-arm': 0.27.7
+      '@esbuild/android-arm64': 0.27.7
+      '@esbuild/android-x64': 0.27.7
+      '@esbuild/darwin-arm64': 0.27.7
+      '@esbuild/darwin-x64': 0.27.7
+      '@esbuild/freebsd-arm64': 0.27.7
+      '@esbuild/freebsd-x64': 0.27.7
+      '@esbuild/linux-arm': 0.27.7
+      '@esbuild/linux-arm64': 0.27.7
+      '@esbuild/linux-ia32': 0.27.7
+      '@esbuild/linux-loong64': 0.27.7
+      '@esbuild/linux-mips64el': 0.27.7
+      '@esbuild/linux-ppc64': 0.27.7
+      '@esbuild/linux-riscv64': 0.27.7
+      '@esbuild/linux-s390x': 0.27.7
+      '@esbuild/linux-x64': 0.27.7
+      '@esbuild/netbsd-arm64': 0.27.7
+      '@esbuild/netbsd-x64': 0.27.7
+      '@esbuild/openbsd-arm64': 0.27.7
+      '@esbuild/openbsd-x64': 0.27.7
+      '@esbuild/openharmony-arm64': 0.27.7
+      '@esbuild/sunos-x64': 0.27.7
+      '@esbuild/win32-arm64': 0.27.7
+      '@esbuild/win32-ia32': 0.27.7
+      '@esbuild/win32-x64': 0.27.7
 
   escalade@3.2.0: {}
 
@@ -9691,9 +10376,10 @@ snapshots:
 
   esm-env@1.2.2: {}
 
-  esrap@2.2.4:
+  esrap@2.2.12(@typescript-eslint/types@8.57.2):
     dependencies:
       '@jridgewell/sourcemap-codec': 1.5.5
+    optionalDependencies:
       '@typescript-eslint/types': 8.57.2
 
   esrecurse@4.3.0:
@@ -9747,7 +10433,7 @@ snapshots:
       parseurl: 1.3.3
       path-to-regexp: 0.1.13
       proxy-addr: 2.0.7
-      qs: 6.14.2
+      qs: 6.15.2
       range-parser: 1.2.1
       safe-buffer: 5.2.1
       send: 0.19.2
@@ -9787,7 +10473,7 @@ snapshots:
       '@fastify/merge-json-schemas': 0.2.1
       ajv: 8.18.0
       ajv-formats: 3.0.1(ajv@8.18.0)
-      fast-uri: 3.1.0
+      fast-uri: 4.0.0
       json-schema-ref-resolver: 3.0.0
       rfdc: 1.4.1
 
@@ -9797,7 +10483,17 @@ snapshots:
 
   fast-sha256@1.3.0: {}
 
-  fast-uri@3.1.0: {}
+  fast-string-truncated-width@3.0.3: {}
+
+  fast-string-width@3.0.2:
+    dependencies:
+      fast-string-truncated-width: 3.0.3
+
+  fast-uri@4.0.0: {}
+
+  fast-wrap-ansi@0.2.2:
+    dependencies:
+      fast-string-width: 3.0.2
 
   fastest-levenshtein@1.0.16: {}
 
@@ -9833,6 +10529,15 @@ snapshots:
     optionalDependencies:
       picomatch: 4.0.4
 
+  ffmpeg-static@5.3.0:
+    dependencies:
+      '@derhuerst/http-basic': 8.2.4
+      env-paths: 2.2.1
+      https-proxy-agent: 5.0.1
+      progress: 2.0.3
+    transitivePeerDependencies:
+      - supports-color
+
   fill-range@7.1.1:
     dependencies:
       to-regex-range: 5.0.1
@@ -9898,8 +10603,6 @@ snapshots:
 
   gensync@1.0.0-beta.2: {}
 
-  get-east-asian-width@1.5.0: {}
-
   get-intrinsic@1.3.0:
     dependencies:
       call-bind-apply-helpers: 1.0.2
@@ -9920,6 +10623,10 @@ snapshots:
       dunder-proto: 1.0.1
       es-object-atoms: 1.1.1
 
+  get-tsconfig@5.0.0-beta.4:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
   github-slugger@2.0.0: {}
 
   glob-parent@5.1.2:
@@ -10102,7 +10809,7 @@ snapshots:
       pretty-error: 4.0.0
       tapable: 2.3.2
     optionalDependencies:
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
 
   html2canvas-pro@2.0.2:
     dependencies:
@@ -10140,7 +10847,7 @@ snapshots:
 
   http-parser-js@0.5.10: {}
 
-  http-proxy-middleware@2.0.9(@types/express@4.17.25):
+  http-proxy-middleware@2.0.10(@types/express@4.17.25):
     dependencies:
       '@types/http-proxy': 1.17.17
       http-proxy: 1.18.1
@@ -10160,15 +10867,30 @@ snapshots:
     transitivePeerDependencies:
       - debug
 
+  http-response-object@3.0.2:
+    dependencies:
+      '@types/node': 10.17.60
+
+  https-proxy-agent@5.0.1:
+    dependencies:
+      agent-base: 6.0.2
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
   hyperdyperid@1.2.0: {}
 
   iconv-lite@0.4.24:
     dependencies:
       safer-buffer: 2.1.2
 
-  icss-utils@5.1.0(postcss@8.5.8):
+  iconv-lite@0.7.2:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  icss-utils@5.1.0(postcss@8.5.15):
     dependencies:
-      postcss: 8.5.8
+      postcss: 8.5.15
 
   import-local@3.2.0:
     dependencies:
@@ -10209,9 +10931,9 @@ snapshots:
 
   is-docker@3.0.0: {}
 
-  is-extglob@2.1.1: {}
+  is-docker@4.0.0: {}
 
-  is-fullwidth-code-point@3.0.0: {}
+  is-extglob@2.1.1: {}
 
   is-glob@4.0.3:
     dependencies:
@@ -10268,9 +10990,11 @@ snapshots:
 
   joycon@3.1.1: {}
 
+  js-tokens@10.0.0: {}
+
   js-tokens@4.0.0: {}
 
-  js-yaml@4.1.1:
+  js-yaml@4.2.0:
     dependencies:
       argparse: 2.0.1
 
@@ -10291,7 +11015,7 @@ snapshots:
       saxes: 6.0.0
       symbol-tree: 3.2.4
       tough-cookie: 6.0.1
-      undici: 7.24.6
+      undici: 7.28.0
       w3c-xmlserializer: 5.0.0
       webidl-conversions: 8.0.1
       whatwg-mimetype: 5.0.0
@@ -10311,7 +11035,7 @@ snapshots:
   json-schema-resolver@3.0.0:
     dependencies:
       debug: 4.4.3
-      fast-uri: 3.1.0
+      fast-uri: 4.0.0
       rfdc: 1.4.1
     transitivePeerDependencies:
       - supports-color
@@ -10325,16 +11049,16 @@ snapshots:
 
   json5@2.2.3: {}
 
-  kind-of@6.0.3: {}
+  jsonc-parser@3.3.1: {}
 
-  kleur@3.0.3: {}
+  kind-of@6.0.3: {}
 
   kleur@4.1.5: {}
 
-  launch-editor@2.13.2:
+  launch-editor@2.14.1:
     dependencies:
       picocolors: 1.1.1
-      shell-quote: 1.8.3
+      shell-quote: 1.8.4
 
   light-my-request@6.6.0:
     dependencies:
@@ -10346,6 +11070,22 @@ snapshots:
 
   lines-and-columns@1.2.4: {}
 
+  lit-element@4.2.2:
+    dependencies:
+      '@lit-labs/ssr-dom-shim': 1.6.0
+      '@lit/reactive-element': 2.1.2
+      lit-html: 3.3.3
+
+  lit-html@3.3.3:
+    dependencies:
+      '@types/trusted-types': 2.0.7
+
+  lit@3.3.3:
+    dependencies:
+      '@lit/reactive-element': 2.1.2
+      lit-element: 4.2.2
+      lit-html: 3.3.3
+
   load-tsconfig@0.2.5: {}
 
   loader-runner@4.3.1: {}
@@ -10378,10 +11118,6 @@ snapshots:
 
   lru-cache@11.2.7: {}
 
-  lru-cache@5.1.1:
-    dependencies:
-      yallist: 3.1.1
-
   lucide-vue-next@1.0.0(vue@3.5.31(typescript@5.9.3)):
     dependencies:
       vue: 3.5.31(typescript@5.9.3)
@@ -10803,6 +11539,8 @@ snapshots:
       dns-packet: 5.6.1
       thunky: 1.1.0
 
+  mute-stream@3.0.0: {}
+
   mz@2.7.0:
     dependencies:
       any-promise: 1.3.0
@@ -10831,7 +11569,7 @@ snapshots:
       vue: 3.5.31(typescript@5.9.3)
       vueuc: 0.4.65(vue@3.5.31(typescript@5.9.3))
 
-  nanoid@3.3.11: {}
+  nanoid@3.3.15: {}
 
   negotiator@0.6.3: {}
 
@@ -10897,11 +11635,11 @@ snapshots:
 
   on-headers@1.1.0: {}
 
-  oniguruma-parser@0.12.1: {}
+  oniguruma-parser@0.12.2: {}
 
-  oniguruma-to-es@4.3.5:
+  oniguruma-to-es@4.3.6:
     dependencies:
-      oniguruma-parser: 0.12.1
+      oniguruma-parser: 0.12.2
       regex: 6.1.0
       regex-recursion: 6.0.2
 
@@ -10918,7 +11656,7 @@ snapshots:
     dependencies:
       p-try: 2.2.0
 
-  p-limit@6.2.0:
+  p-limit@7.3.0:
     dependencies:
       yocto-queue: 1.2.2
 
@@ -10926,10 +11664,10 @@ snapshots:
     dependencies:
       p-limit: 2.3.0
 
-  p-queue@8.1.1:
+  p-queue@9.3.0:
     dependencies:
       eventemitter3: 5.0.4
-      p-timeout: 6.1.4
+      p-timeout: 7.0.1
 
   p-retry@6.2.1:
     dependencies:
@@ -10937,7 +11675,7 @@ snapshots:
       is-network-error: 1.3.1
       retry: 0.13.1
 
-  p-timeout@6.1.4: {}
+  p-timeout@7.0.1: {}
 
   p-try@2.2.0: {}
 
@@ -10952,6 +11690,8 @@ snapshots:
 
   parchment@3.0.0: {}
 
+  parse-cache-control@1.0.1: {}
+
   parse-latin@7.0.0:
     dependencies:
       '@types/nlcst': 2.0.3
@@ -11055,50 +11795,50 @@ snapshots:
     optionalDependencies:
       fsevents: 2.3.2
 
-  postcss-import@15.1.0(postcss@8.5.8):
+  postcss-import@15.1.0(postcss@8.5.15):
     dependencies:
-      postcss: 8.5.8
+      postcss: 8.5.15
       postcss-value-parser: 4.2.0
       read-cache: 1.0.0
       resolve: 1.22.11
 
-  postcss-js@4.1.0(postcss@8.5.8):
+  postcss-js@4.1.0(postcss@8.5.15):
     dependencies:
       camelcase-css: 2.0.1
-      postcss: 8.5.8
+      postcss: 8.5.15
 
-  postcss-load-config@6.0.1(jiti@1.21.7)(postcss@8.5.8)(yaml@2.8.3):
+  postcss-load-config@6.0.1(jiti@1.21.7)(postcss@8.5.15)(yaml@2.8.3):
     dependencies:
       lilconfig: 3.1.3
     optionalDependencies:
       jiti: 1.21.7
-      postcss: 8.5.8
+      postcss: 8.5.15
       yaml: 2.8.3
 
-  postcss-modules-extract-imports@3.1.0(postcss@8.5.8):
+  postcss-modules-extract-imports@3.1.0(postcss@8.5.15):
     dependencies:
-      postcss: 8.5.8
+      postcss: 8.5.15
 
-  postcss-modules-local-by-default@4.2.0(postcss@8.5.8):
+  postcss-modules-local-by-default@4.2.0(postcss@8.5.15):
     dependencies:
-      icss-utils: 5.1.0(postcss@8.5.8)
-      postcss: 8.5.8
+      icss-utils: 5.1.0(postcss@8.5.15)
+      postcss: 8.5.15
       postcss-selector-parser: 7.1.1
       postcss-value-parser: 4.2.0
 
-  postcss-modules-scope@3.2.1(postcss@8.5.8):
+  postcss-modules-scope@3.2.1(postcss@8.5.15):
     dependencies:
-      postcss: 8.5.8
+      postcss: 8.5.15
       postcss-selector-parser: 7.1.1
 
-  postcss-modules-values@4.0.0(postcss@8.5.8):
+  postcss-modules-values@4.0.0(postcss@8.5.15):
     dependencies:
-      icss-utils: 5.1.0(postcss@8.5.8)
-      postcss: 8.5.8
+      icss-utils: 5.1.0(postcss@8.5.15)
+      postcss: 8.5.15
 
-  postcss-nested@6.2.0(postcss@8.5.8):
+  postcss-nested@6.2.0(postcss@8.5.15):
     dependencies:
-      postcss: 8.5.8
+      postcss: 8.5.15
       postcss-selector-parser: 6.1.2
 
   postcss-selector-parser@6.1.2:
@@ -11113,9 +11853,9 @@ snapshots:
 
   postcss-value-parser@4.2.0: {}
 
-  postcss@8.5.8:
+  postcss@8.5.15:
     dependencies:
-      nanoid: 3.3.11
+      nanoid: 3.3.15
       picocolors: 1.1.1
       source-map-js: 1.2.1
 
@@ -11144,10 +11884,7 @@ snapshots:
 
   process-warning@5.0.0: {}
 
-  prompts@2.4.2:
-    dependencies:
-      kleur: 3.0.3
-      sisteransi: 1.0.5
+  progress@2.0.3: {}
 
   property-information@7.1.0: {}
 
@@ -11164,7 +11901,9 @@ snapshots:
 
   pvutils@1.1.5: {}
 
-  qs@6.14.2:
+  qr-creator@1.0.0: {}
+
+  qs@6.15.2:
     dependencies:
       side-channel: 1.1.0
 
@@ -11313,13 +12052,13 @@ snapshots:
     optionalDependencies:
       '@types/react': 19.2.14
 
-  react-router-dom@7.13.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+  react-router-dom@7.18.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
-      react-router: 7.13.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react-router: 7.18.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
 
-  react-router@7.13.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+  react-router@7.18.0(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
     dependencies:
       cookie: 1.1.1
       react: 19.2.4
@@ -11487,6 +12226,8 @@ snapshots:
 
   resolve-from@5.0.0: {}
 
+  resolve-pkg-maps@1.0.0: {}
+
   resolve@1.22.11:
     dependencies:
       is-core-module: 2.16.1
@@ -11563,10 +12304,10 @@ snapshots:
     dependencies:
       queue-microtask: 1.2.3
 
-  runed@0.23.4(svelte@5.55.0):
+  runed@0.23.4(svelte@5.56.3(@typescript-eslint/types@8.57.2)):
     dependencies:
       esm-env: 1.2.2
-      svelte: 5.55.0
+      svelte: 5.56.3(@typescript-eslint/types@8.57.2)
 
   safe-buffer@5.1.2: {}
 
@@ -11608,8 +12349,6 @@ snapshots:
       '@peculiar/x509': 1.14.3
       pkijs: 3.4.0
 
-  semver@6.3.1: {}
-
   semver@7.7.4: {}
 
   send@0.19.2:
@@ -11719,16 +12458,16 @@ snapshots:
 
   shebang-regex@3.0.0: {}
 
-  shell-quote@1.8.3: {}
+  shell-quote@1.8.4: {}
 
-  shiki@3.23.0:
+  shiki@4.2.0:
     dependencies:
-      '@shikijs/core': 3.23.0
-      '@shikijs/engine-javascript': 3.23.0
-      '@shikijs/engine-oniguruma': 3.23.0
-      '@shikijs/langs': 3.23.0
-      '@shikijs/themes': 3.23.0
-      '@shikijs/types': 3.23.0
+      '@shikijs/core': 4.2.0
+      '@shikijs/engine-javascript': 4.2.0
+      '@shikijs/engine-oniguruma': 4.2.0
+      '@shikijs/langs': 4.2.0
+      '@shikijs/themes': 4.2.0
+      '@shikijs/types': 4.2.0
       '@shikijs/vscode-textmate': 10.0.2
       '@types/hast': 3.0.4
 
@@ -11762,6 +12501,8 @@ snapshots:
 
   siginfo@2.0.0: {}
 
+  signal-exit@4.1.0: {}
+
   single-spa-react@6.0.2(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react@19.2.4):
     dependencies:
       browserslist-config-single-spa: 1.0.1
@@ -11781,7 +12522,7 @@ snapshots:
   sockjs@0.3.24:
     dependencies:
       faye-websocket: 0.11.4
-      uuid: 8.3.2
+      uuid: 11.1.1
       websocket-driver: 0.7.4
 
   solid-js@1.9.12:
@@ -11862,18 +12603,6 @@ snapshots:
 
   std-env@4.0.0: {}
 
-  string-width@4.2.3:
-    dependencies:
-      emoji-regex: 8.0.0
-      is-fullwidth-code-point: 3.0.0
-      strip-ansi: 6.0.1
-
-  string-width@7.2.0:
-    dependencies:
-      emoji-regex: 10.6.0
-      get-east-asian-width: 1.5.0
-      strip-ansi: 7.2.0
-
   string_decoder@1.1.1:
     dependencies:
       safe-buffer: 5.1.2
@@ -11891,13 +12620,11 @@ snapshots:
     dependencies:
       ansi-regex: 5.0.1
 
-  strip-ansi@7.2.0:
-    dependencies:
-      ansi-regex: 6.2.2
-
   style-loader@4.0.0(webpack@5.105.4):
     dependencies:
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
+
+  style-mod@4.1.3: {}
 
   style-to-object@1.0.14:
     dependencies:
@@ -11923,31 +12650,33 @@ snapshots:
 
   supports-preserve-symlinks-flag@1.0.0: {}
 
-  svelte-toolbelt@0.7.1(svelte@5.55.0):
+  svelte-toolbelt@0.7.1(svelte@5.56.3(@typescript-eslint/types@8.57.2)):
     dependencies:
       clsx: 2.1.1
-      runed: 0.23.4(svelte@5.55.0)
+      runed: 0.23.4(svelte@5.56.3(@typescript-eslint/types@8.57.2))
       style-to-object: 1.0.14
-      svelte: 5.55.0
+      svelte: 5.56.3(@typescript-eslint/types@8.57.2)
 
-  svelte@5.55.0:
+  svelte@5.56.3(@typescript-eslint/types@8.57.2):
     dependencies:
       '@jridgewell/remapping': 2.3.5
       '@jridgewell/sourcemap-codec': 1.5.5
-      '@sveltejs/acorn-typescript': 1.0.9(acorn@8.16.0)
+      '@sveltejs/acorn-typescript': 1.0.10(acorn@8.16.0)
       '@types/estree': 1.0.8
       '@types/trusted-types': 2.0.7
       acorn: 8.16.0
       aria-query: 5.3.1
       axobject-query: 4.1.0
       clsx: 2.1.1
-      devalue: 5.6.4
+      devalue: 5.8.1
       esm-env: 1.2.2
-      esrap: 2.2.4
+      esrap: 2.2.12(@typescript-eslint/types@8.57.2)
       is-reference: 3.0.3
       locate-character: 3.0.0
       magic-string: 0.30.21
       zimmerframe: 1.1.4
+    transitivePeerDependencies:
+      - '@typescript-eslint/types'
 
   svgo@4.0.1:
     dependencies:
@@ -11979,11 +12708,11 @@ snapshots:
       normalize-path: 3.0.0
       object-hash: 3.0.0
       picocolors: 1.1.1
-      postcss: 8.5.8
-      postcss-import: 15.1.0(postcss@8.5.8)
-      postcss-js: 4.1.0(postcss@8.5.8)
-      postcss-load-config: 6.0.1(jiti@1.21.7)(postcss@8.5.8)(yaml@2.8.3)
-      postcss-nested: 6.2.0(postcss@8.5.8)
+      postcss: 8.5.15
+      postcss-import: 15.1.0(postcss@8.5.15)
+      postcss-js: 4.1.0(postcss@8.5.15)
+      postcss-load-config: 6.0.1(jiti@1.21.7)(postcss@8.5.15)(yaml@2.8.3)
+      postcss-nested: 6.2.0(postcss@8.5.15)
       postcss-selector-parser: 6.1.2
       resolve: 1.22.11
       sucrase: 3.35.1
@@ -11993,27 +12722,27 @@ snapshots:
 
   tapable@2.3.2: {}
 
-  terser-webpack-plugin@5.4.0(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack@5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)):
+  terser-webpack-plugin@5.4.0(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack@5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)):
     dependencies:
       '@jridgewell/trace-mapping': 0.3.31
       jest-worker: 27.5.1
       schema-utils: 4.3.3
       terser: 5.46.1
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)
     optionalDependencies:
       '@swc/core': 1.15.30(@swc/helpers@0.5.21)
-      esbuild: 0.27.4
+      esbuild: 0.27.7
 
-  terser-webpack-plugin@5.4.0(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack@5.105.4):
+  terser-webpack-plugin@5.4.0(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack@5.105.4):
     dependencies:
       '@jridgewell/trace-mapping': 0.3.31
       jest-worker: 27.5.1
       schema-utils: 4.3.3
       terser: 5.46.1
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
     optionalDependencies:
       '@swc/core': 1.15.30(@swc/helpers@0.5.21)
-      esbuild: 0.27.4
+      esbuild: 0.27.7
 
   terser@5.46.1:
     dependencies:
@@ -12022,6 +12751,23 @@ snapshots:
       commander: 2.20.3
       source-map-support: 0.5.21
 
+  testreel@0.2.0(@playwright/test@1.58.2)(@types/node@25.5.0)(playwright-core@1.58.2):
+    dependencies:
+      '@inquirer/prompts': 8.4.3(@types/node@25.5.0)
+      commander: 14.0.3
+      ffmpeg-static: 5.3.0
+      jsonc-parser: 3.3.1
+      playwright-core: 1.58.2
+      ws: 8.21.0
+      yaml: 2.8.3
+    optionalDependencies:
+      '@playwright/test': 1.58.2
+    transitivePeerDependencies:
+      - '@types/node'
+      - bufferutil
+      - supports-color
+      - utf-8-validate
+
   text-segmentation@1.0.3:
     dependencies:
       utrie: 1.0.2
@@ -12048,6 +12794,8 @@ snapshots:
 
   tinybench@2.9.0: {}
 
+  tinyclip@0.1.15: {}
+
   tinyexec@0.3.2: {}
 
   tinyexec@1.0.4: {}
@@ -12105,28 +12853,24 @@ snapshots:
       semver: 7.7.4
       source-map: 0.7.6
       typescript: 5.9.3
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
-
-  tsconfck@3.1.6(typescript@5.9.3):
-    optionalDependencies:
-      typescript: 5.9.3
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
 
   tslib@1.14.1: {}
 
   tslib@2.8.1: {}
 
-  tsup@8.5.1(@swc/core@1.15.30(@swc/helpers@0.5.21))(jiti@1.21.7)(postcss@8.5.8)(typescript@5.9.3)(yaml@2.8.3):
+  tsup@8.5.1(@swc/core@1.15.30(@swc/helpers@0.5.21))(jiti@1.21.7)(postcss@8.5.15)(typescript@5.9.3)(yaml@2.8.3):
     dependencies:
-      bundle-require: 5.1.0(esbuild@0.27.4)
+      bundle-require: 5.1.0(esbuild@0.27.7)
       cac: 6.7.14
       chokidar: 4.0.3
       consola: 3.4.2
       debug: 4.4.3
-      esbuild: 0.27.4
+      esbuild: 0.27.7
       fix-dts-default-cjs-exports: 1.0.1
       joycon: 3.1.1
       picocolors: 1.1.1
-      postcss-load-config: 6.0.1(jiti@1.21.7)(postcss@8.5.8)(yaml@2.8.3)
+      postcss-load-config: 6.0.1(jiti@1.21.7)(postcss@8.5.15)(yaml@2.8.3)
       resolve-from: 5.0.0
       rollup: 4.60.0
       source-map: 0.7.6
@@ -12136,7 +12880,7 @@ snapshots:
       tree-kill: 1.2.2
     optionalDependencies:
       '@swc/core': 1.15.30(@swc/helpers@0.5.21)
-      postcss: 8.5.8
+      postcss: 8.5.15
       typescript: 5.9.3
     transitivePeerDependencies:
       - jiti
@@ -12155,6 +12899,8 @@ snapshots:
       media-typer: 0.3.0
       mime-types: 2.1.35
 
+  typedarray@0.0.6: {}
+
   typescript@5.9.3: {}
 
   ufo@1.6.3: {}
@@ -12165,7 +12911,9 @@ snapshots:
 
   undici-types@7.18.2: {}
 
-  undici@7.24.6: {}
+  undici-types@7.27.2: {}
+
+  undici@7.28.0: {}
 
   unified@11.0.5:
     dependencies:
@@ -12303,7 +13051,7 @@ snapshots:
     dependencies:
       base64-arraybuffer: 1.0.2
 
-  uuid@8.3.2: {}
+  uuid@11.1.1: {}
 
   vary@1.1.2: {}
 
@@ -12327,25 +13075,25 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vite-plugin-solid@2.11.12(solid-js@1.9.12)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)):
+  vite-plugin-solid@2.11.12(solid-js@1.9.12)(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)):
     dependencies:
-      '@babel/core': 7.29.0
+      '@babel/core': 8.0.1
       '@types/babel__core': 7.20.5
-      babel-preset-solid: 1.9.12(@babel/core@7.29.0)(solid-js@1.9.12)
+      babel-preset-solid: 1.9.12(@babel/core@8.0.1)(solid-js@1.9.12)
       merge-anything: 5.1.7
       solid-js: 1.9.12
       solid-refresh: 0.6.3(solid-js@1.9.12)
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
-      vitefu: 1.1.2(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+      vitefu: 1.1.2(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
     transitivePeerDependencies:
       - supports-color
 
-  vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3):
+  vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3):
     dependencies:
       esbuild: 0.25.12
       fdir: 6.5.0(picomatch@4.0.4)
       picomatch: 4.0.4
-      postcss: 8.5.8
+      postcss: 8.5.15
       rollup: 4.60.0
       tinyglobby: 0.2.15
     optionalDependencies:
@@ -12355,14 +13103,14 @@ snapshots:
       terser: 5.46.1
       yaml: 2.8.3
 
-  vitefu@1.1.2(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)):
+  vitefu@1.1.2(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)):
     optionalDependencies:
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
 
-  vitest@4.1.2(@types/node@25.5.0)(jsdom@29.0.1)(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)):
+  vitest@4.1.2(@types/node@25.5.0)(jsdom@29.0.1)(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)):
     dependencies:
       '@vitest/expect': 4.1.2
-      '@vitest/mocker': 4.1.2(vite@6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
+      '@vitest/mocker': 4.1.2(vite@6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3))
       '@vitest/pretty-format': 4.1.2
       '@vitest/runner': 4.1.2
       '@vitest/snapshot': 4.1.2
@@ -12379,7 +13127,7 @@ snapshots:
       tinyexec: 1.0.4
       tinyglobby: 0.2.15
       tinyrainbow: 3.1.0
-      vite: 6.4.2(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
+      vite: 6.4.3(@types/node@25.5.0)(jiti@1.21.7)(terser@5.46.1)(yaml@2.8.3)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 25.5.0
@@ -12399,7 +13147,7 @@ snapshots:
       chalk: 4.1.2
       hash-sum: 2.0.0
       watchpack: 2.5.1
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
     optionalDependencies:
       '@vue/compiler-sfc': 3.5.31
       vue: 3.5.31(typescript@5.9.3)
@@ -12461,6 +13209,8 @@ snapshots:
       vooks: 0.2.12(vue@3.5.31(typescript@5.9.3))
       vue: 3.5.31(typescript@5.9.3)
 
+  w3c-keyname@2.2.8: {}
+
   w3c-xmlserializer@5.0.0:
     dependencies:
       xml-name-validator: 5.0.0
@@ -12478,12 +13228,12 @@ snapshots:
 
   webidl-conversions@8.0.1: {}
 
-  webpack-cli@6.0.1(webpack-dev-server@5.2.3)(webpack@5.105.4):
+  webpack-cli@6.0.1(webpack-dev-server@5.2.5)(webpack@5.105.4):
     dependencies:
       '@discoveryjs/json-ext': 0.6.3
       '@webpack-cli/configtest': 3.0.1(webpack-cli@6.0.1)(webpack@5.105.4)
       '@webpack-cli/info': 3.0.1(webpack-cli@6.0.1)(webpack@5.105.4)
-      '@webpack-cli/serve': 3.0.1(webpack-cli@6.0.1)(webpack-dev-server@5.2.3)(webpack@5.105.4)
+      '@webpack-cli/serve': 3.0.1(webpack-cli@6.0.1)(webpack-dev-server@5.2.5)(webpack@5.105.4)
       colorette: 2.0.20
       commander: 12.1.0
       cross-spawn: 7.0.6
@@ -12492,10 +13242,10 @@ snapshots:
       import-local: 3.2.0
       interpret: 3.1.1
       rechoir: 0.8.0
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
       webpack-merge: 6.0.1
     optionalDependencies:
-      webpack-dev-server: 5.2.3(tslib@2.8.1)(webpack-cli@6.0.1)(webpack@5.105.4)
+      webpack-dev-server: 5.2.5(tslib@2.8.1)(webpack-cli@6.0.1)(webpack@5.105.4)
 
   webpack-dev-middleware@7.4.5(tslib@2.8.1)(webpack@5.105.4):
     dependencies:
@@ -12506,11 +13256,11 @@ snapshots:
       range-parser: 1.2.1
       schema-utils: 4.3.3
     optionalDependencies:
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
     transitivePeerDependencies:
       - tslib
 
-  webpack-dev-server@5.2.3(tslib@2.8.1)(webpack-cli@6.0.1)(webpack@5.105.4):
+  webpack-dev-server@5.2.5(tslib@2.8.1)(webpack-cli@6.0.1)(webpack@5.105.4):
     dependencies:
       '@types/bonjour': 3.5.13
       '@types/connect-history-api-fallback': 1.5.4
@@ -12528,9 +13278,9 @@ snapshots:
       connect-history-api-fallback: 2.0.0
       express: 4.22.1
       graceful-fs: 4.2.11
-      http-proxy-middleware: 2.0.9(@types/express@4.17.25)
+      http-proxy-middleware: 2.0.10(@types/express@4.17.25)
       ipaddr.js: 2.3.0
-      launch-editor: 2.13.2
+      launch-editor: 2.14.1
       open: 10.2.0
       p-retry: 6.2.1
       schema-utils: 4.3.3
@@ -12539,10 +13289,10 @@ snapshots:
       sockjs: 0.3.24
       spdy: 4.0.2
       webpack-dev-middleware: 7.4.5(tslib@2.8.1)(webpack@5.105.4)
-      ws: 8.20.0
+      ws: 8.21.0
     optionalDependencies:
-      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1)
-      webpack-cli: 6.0.1(webpack-dev-server@5.2.3)(webpack@5.105.4)
+      webpack: 5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1)
+      webpack-cli: 6.0.1(webpack-dev-server@5.2.5)(webpack@5.105.4)
     transitivePeerDependencies:
       - bufferutil
       - debug
@@ -12560,7 +13310,7 @@ snapshots:
 
   webpack-virtual-modules@0.6.2: {}
 
-  webpack@5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4):
+  webpack@5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7):
     dependencies:
       '@types/eslint-scope': 3.7.7
       '@types/estree': 1.0.8
@@ -12584,7 +13334,7 @@ snapshots:
       neo-async: 2.6.2
       schema-utils: 4.3.3
       tapable: 2.3.2
-      terser-webpack-plugin: 5.4.0(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack@5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4))
+      terser-webpack-plugin: 5.4.0(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack@5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7))
       watchpack: 2.5.1
       webpack-sources: 3.3.4
     transitivePeerDependencies:
@@ -12592,7 +13342,7 @@ snapshots:
       - esbuild
       - uglify-js
 
-  webpack@5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack-cli@6.0.1):
+  webpack@5.105.4(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack-cli@6.0.1):
     dependencies:
       '@types/eslint-scope': 3.7.7
       '@types/estree': 1.0.8
@@ -12616,11 +13366,11 @@ snapshots:
       neo-async: 2.6.2
       schema-utils: 4.3.3
       tapable: 2.3.2
-      terser-webpack-plugin: 5.4.0(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.4)(webpack@5.105.4)
+      terser-webpack-plugin: 5.4.0(@swc/core@1.15.30(@swc/helpers@0.5.21))(esbuild@0.27.7)(webpack@5.105.4)
       watchpack: 2.5.1
       webpack-sources: 3.3.4
     optionalDependencies:
-      webpack-cli: 6.0.1(webpack-dev-server@5.2.3)(webpack@5.105.4)
+      webpack-cli: 6.0.1(webpack-dev-server@5.2.5)(webpack@5.105.4)
     transitivePeerDependencies:
       - '@swc/core'
       - esbuild
@@ -12655,19 +13405,9 @@ snapshots:
       siginfo: 2.0.0
       stackback: 0.0.2
 
-  widest-line@5.0.0:
-    dependencies:
-      string-width: 7.2.0
-
   wildcard@2.0.1: {}
 
-  wrap-ansi@9.0.2:
-    dependencies:
-      ansi-styles: 6.2.3
-      string-width: 7.2.0
-      strip-ansi: 7.2.0
-
-  ws@8.20.0: {}
+  ws@8.21.0: {}
 
   wsl-utils@0.1.0:
     dependencies:
@@ -12679,37 +13419,18 @@ snapshots:
 
   xxhash-wasm@1.1.0: {}
 
-  yallist@3.1.1: {}
-
   yaml@2.8.3: {}
 
-  yargs-parser@21.1.1: {}
+  yargs-parser@22.0.0: {}
 
   yocto-queue@1.2.2: {}
 
-  yocto-spinner@0.2.3:
-    dependencies:
-      yoctocolors: 2.1.2
-
-  yoctocolors@2.1.2: {}
-
   zimmerframe@1.1.4: {}
 
-  zod-to-json-schema@3.25.2(zod@3.25.76):
-    dependencies:
-      zod: 3.25.76
-
   zod-to-json-schema@3.25.2(zod@4.3.6):
     dependencies:
       zod: 4.3.6
 
-  zod-to-ts@1.2.0(typescript@5.9.3)(zod@3.25.76):
-    dependencies:
-      typescript: 5.9.3
-      zod: 3.25.76
-
-  zod@3.25.76: {}
-
   zod@4.3.6: {}
 
   zwitch@2.0.4: {}
diff --git a/scripts/demo-reset-hero.sh b/scripts/demo-reset-hero.sh
new file mode 100755
index 0000000..f5bad3e
--- /dev/null
+++ b/scripts/demo-reset-hero.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Reset the marketing playground for the wireframe hero demo
+# ("Freeze. Sketch. Real.").
+#
+# Unlike scripts/demo-reset.sh (which restores the DEGRADED `demo/marketing-before`
+# tag for the AI-first-draft clips), the hero's "before" state is simply HEAD:
+# the polished page with the live stats strip. This script undoes agent writes
+# and clears wireframe/design-session/conversation state, but keeps the
+# playground *initialized* (design-spec.json, agents.json, server.json) so the
+# InitWizard does not hijack the take.
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+MARKETING_REL="playgrounds/simple/marketing"
+MARKETING="$REPO_ROOT/$MARKETING_REL"
+STATE="$MARKETING/.annotask"
+
+echo "[demo-reset-hero] Restoring marketing sources to HEAD..."
+git -C "$REPO_ROOT" checkout HEAD -- \
+  "$MARKETING_REL/index.html" \
+  "$MARKETING_REL/src" \
+  "$MARKETING_REL/vite.config.js"
+# Agent-CREATED files under src/ are not reverted by checkout — drop them.
+# (-fd without -x leaves ignored files like node_modules alone.)
+git -C "$REPO_ROOT" clean -fdq -- "$MARKETING_REL/src" || true
+
+if [ -d "$STATE" ]; then
+  echo "[demo-reset-hero] Clearing wireframe / session / task state..."
+  echo '{"version":"1.0","tasks":[]}' > "$STATE/tasks.json"
+  rm -f "$STATE/wireframe.json" \
+        "$STATE/design-session.json" \
+        "$STATE/file-snapshots.json" \
+        "$STATE/usage.jsonl"
+  rm -rf "$STATE/conversations" \
+         "$STATE/wireframe-snapshots" \
+         "$STATE/screenshots" \
+         "$STATE/interaction-history" \
+         "$STATE/rendered-html"
+  # KEEP: server.json, design-spec.json, agents.json, runtime-endpoints.json,
+  # cache/ — the playground must stay initialized (no InitWizard on camera).
+fi
+
+# Best-effort: reap an embedded-agent CLI orphaned by an aborted take.
+pkill -f -- 'claude --print --output-format stream-json' 2>/dev/null || true
+
+echo "[demo-reset-hero] Done. Stage is clean — sketch state, tasks, and agent writes are gone."
+echo "[demo-reset-hero] Start the stage: just marketing   (auto-starts the API on :8888)"
diff --git a/scripts/demo-reset.sh b/scripts/demo-reset.sh
new file mode 100755
index 0000000..f534af3
--- /dev/null
+++ b/scripts/demo-reset.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+MARKETING="$REPO_ROOT/playgrounds/simple/marketing"
+
+echo "[demo-reset] Restoring marketing page to 'before' state..."
+
+# Restore marketing files from the tagged before state
+git checkout demo/marketing-before -- \
+  playgrounds/simple/marketing/index.html \
+  playgrounds/simple/marketing/src/style.css
+
+# Unstage so they show as working-tree modifications (HMR picks them up)
+git reset HEAD -- playgrounds/simple/marketing/ >/dev/null 2>&1
+
+# Clear tasks and sidecar files so the demo starts clean
+if [ -d "$MARKETING/.annotask" ]; then
+  echo '[]' > "$MARKETING/.annotask/tasks.json"
+  rm -rf "$MARKETING/.annotask/interaction-history" 2>/dev/null || true
+  rm -rf "$MARKETING/.annotask/rendered-html" 2>/dev/null || true
+  rm -rf "$MARKETING/.annotask/screenshots" 2>/dev/null || true
+fi
+
+echo "[demo-reset] Done. Marketing page is in AI first-draft state."
+echo "[demo-reset] Start the dev server: pnpm dev:marketing"
+echo "[demo-reset] To restore polished state: pnpm demo:restore"
diff --git a/scripts/demo-restore.sh b/scripts/demo-restore.sh
new file mode 100755
index 0000000..2e13846
--- /dev/null
+++ b/scripts/demo-restore.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[demo-restore] Restoring marketing page to polished state..."
+
+git checkout HEAD -- \
+  playgrounds/simple/marketing/index.html \
+  playgrounds/simple/marketing/src/style.css
+
+echo "[demo-restore] Done. Marketing page is back to polished state."
diff --git a/scripts/sync-skills.mjs b/scripts/sync-skills.mjs
new file mode 100644
index 0000000..71d5087
--- /dev/null
+++ b/scripts/sync-skills.mjs
@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Sync the canonical skills/ tree into the in-repo skill mirrors.
+ *
+ * `skills/` is the single source of truth for the published agent skills.
+ * Three directories carry copies that drift if they're edited by hand:
+ *
+ *   - .claude/skills/                                  (this repo's own Claude setup)
+ *   - .agents/skills/                                  (agents.md-style consumers)
+ *   - playgrounds/simple/vue-webpack/.claude/skills/   (playground that exercises init-skills)
+ *
+ * This script replaces each mirrored skill directory with a verbatim copy of
+ * the canonical one. Extra directories in a mirror that have NO canonical
+ * counterpart (the vue-webpack playground's hand-written `annotask-watch`
+ * skill) are left in place — they have no source to sync from.
+ *
+ * CI runs this script and fails on `git diff --exit-code` over the mirrors,
+ * so editing a mirror directly will break the build until the canonical copy
+ * is updated and re-synced. Run via `pnpm sync:skills`.
+ */
+import { cpSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..')
+const canonicalDir = path.join(repoRoot, 'skills')
+
+const mirrors = [
+  '.claude/skills',
+  '.agents/skills',
+  'playgrounds/simple/vue-webpack/.claude/skills',
+]
+
+let canonicalSkills
+try {
+  canonicalSkills = readdirSync(canonicalDir).filter((name) =>
+    statSync(path.join(canonicalDir, name)).isDirectory()
+  )
+} catch (err) {
+  console.error(`[sync-skills] Cannot read canonical skills dir ${canonicalDir}: ${err.message}`)
+  process.exit(1)
+}
+
+if (canonicalSkills.length === 0) {
+  console.error(`[sync-skills] No skill directories found under ${canonicalDir} — refusing to wipe mirrors.`)
+  process.exit(1)
+}
+
+for (const mirror of mirrors) {
+  const mirrorDir = path.join(repoRoot, mirror)
+  mkdirSync(mirrorDir, { recursive: true })
+
+  for (const skill of canonicalSkills) {
+    const src = path.join(canonicalDir, skill)
+    const dest = path.join(mirrorDir, skill)
+    // Remove-then-copy so files deleted from the canonical skill disappear
+    // from the mirror too (cpSync alone would leave orphans behind).
+    rmSync(dest, { recursive: true, force: true })
+    cpSync(src, dest, { recursive: true })
+    console.log(`[sync-skills] skills/${skill} → ${mirror}/${skill}`)
+  }
+
+  // Report (but keep) mirror-only skills — e.g. the vue-webpack playground's
+  // annotask-watch skill, which has no canonical source.
+  const extras = readdirSync(mirrorDir).filter(
+    (name) => statSync(path.join(mirrorDir, name)).isDirectory() && !canonicalSkills.includes(name)
+  )
+  for (const extra of extras) {
+    console.log(`[sync-skills] kept mirror-only skill ${mirror}/${extra} (no canonical source)`)
+  }
+}
diff --git a/skills/annotask-apply/ERROR_FIX.md b/skills/annotask-apply/ERROR_FIX.md
new file mode 100644
index 0000000..d6b598c
--- /dev/null
+++ b/skills/annotask-apply/ERROR_FIX.md
@@ -0,0 +1,40 @@
+# Error fix tasks
+
+`error_fix` tasks come from the Errors tab in the Annotask shell. Each task
+captures one or more console errors with their stack traces, the route where
+they happened, and the number of occurrences.
+
+## Read order
+
+1. **`task.context.level`** — `'error'` or `'warn'`. Errors block; warnings
+   often don't. Don't suppress warnings into errors and don't downgrade
+   errors into warnings just to make the panel quieter.
+2. **`task.context.errorId`** — stable hash. Use it to confirm you're
+   fixing what the user saw, not a sibling error from the same file.
+3. **`task.context.occurrences`** — when this is high (>50), the error is
+   firing on every render or interaction. Prioritize root-cause fixes over
+   try/catch wrappers.
+4. **Stack trace** — read the top frame to locate the throw, but read the
+   second and third frames to understand who called it. The fix usually
+   lives at the caller, not the throw site.
+
+## Fix patterns
+
+- **Undefined property access** (`Cannot read properties of undefined`) —
+  fix the producer, not the consumer. Adding `?.` everywhere hides the
+  real defect.
+- **Hydration mismatch** (React/Vue/Svelte SSR) — the server and client
+  rendered different output. Find the divergent branch (often
+  `typeof window !== 'undefined'`) and align them.
+- **Network errors** — surface to the user; don't swallow with a generic
+  toast unless the user explicitly asked for one.
+
+## Don't
+
+- Don't add `try/catch` around the call site just to silence the error.
+- Don't add `console.error` suppressions or noise filters.
+- Don't change the error to a warning to clear the panel.
+
+When you finish, set `status: 'review'` with a one-line resolution that
+states (a) the root cause and (b) the file you touched. The user will
+verify in the Errors tab that the count stays at zero.
diff --git a/skills/annotask-apply/PERF_FIX.md b/skills/annotask-apply/PERF_FIX.md
new file mode 100644
index 0000000..fd2259f
--- /dev/null
+++ b/skills/annotask-apply/PERF_FIX.md
@@ -0,0 +1,57 @@
+# Performance fix tasks
+
+`perf_fix` tasks come from the Perf tab. Each task points at one finding:
+a Web Vital that regressed, a heavy resource group, a heavy bundle
+package, or long main-thread tasks captured during a recording.
+
+## Read order
+
+1. **`task.context.category`** — what kind of finding this is:
+   `'vital' | 'resource' | 'long-task' | 'bundle'`. The fix surface
+   varies dramatically by category; don't apply a vitals recipe to a
+   bundle task.
+2. **`task.context.metric`** — present **only on `vital` findings**: the
+   uppercase Web Vital name (`'LCP'`, `'CLS'`, `'INP'`, `'TTFB'`,
+   `'FCP'`). Non-vital findings have no `metric`; key off `category`
+   and `findingId` instead.
+3. **`task.context.findingId`** — stable id that also encodes the
+   offender: `vital:LCP`, `resource:heavy-script`,
+   `bundle:lodash`, `blocking:long-tasks`.
+4. **`task.context.value`** + **`unit`** — the observed value (`'ms'`
+   for vitals and long tasks, `'bytes'` for resource/bundle findings,
+   empty unit for CLS which is unitless). Use this to verify your fix
+   in the Perf tab post-edit.
+5. **`task.context.severity`** — the Web Vitals rating scale:
+   `'good' | 'needs-improvement' | 'poor'`. `poor` CLS (>0.25) usually
+   means a single layout shift you can squash; `needs-improvement` may
+   be unfixable without redesign.
+6. **`task.context.detail`** / **`resources`** — human-readable summary,
+   and (on `resource` findings) the offending URLs with sizes and
+   durations. `context.metrics` carries the full snapshot when one was
+   captured.
+
+## Fix patterns
+
+- **LCP** — defer or preload the largest contentful element. Drop hero
+  images to the right format/size; preconnect to the right origins.
+- **CLS** — explicit dimensions on images, reserved space for async
+  content (banners, ads, late-loaded fonts).
+- **INP** — break long tasks, debounce input handlers, move work off the
+  main thread. `blocking:long-tasks` findings give you Total Blocking
+  Time and pair naturally with INP work.
+- **Resource / bundle size** — confirm the offender lives in user code,
+  not a vendor chunk. Tree-shake or lazy-load instead of swapping
+  libraries; the `bundle:<package>` finding's detail may already
+  suggest a lighter alternative.
+
+## Don't
+
+- Don't suppress the metric by changing what gets counted (e.g. excluding
+  a route from RUM).
+- Don't ship a "fix" that improves the metric in dev but regresses in
+  prod (e.g. removing `import.meta.hot` blocks).
+- Don't refactor unrelated code in a perf task.
+
+Set `status: 'review'` with a resolution that names the finding and the
+post-fix expected value (`'CLS dropped from 0.31 to ~0.05 — reserved space
+for hero image'`). The user re-runs the Perf scan to confirm.
diff --git a/skills/annotask-apply/SKILL.md b/skills/annotask-apply/SKILL.md
index 28701ac..49bca89 100644
--- a/skills/annotask-apply/SKILL.md
+++ b/skills/annotask-apply/SKILL.md
@@ -1,7 +1,14 @@
+---
+name: annotask-apply
+description: Apply pending Annotask design tasks to the source code. Use when the user asks to apply Annotask changes, apply design changes, sync Annotask, or runs /annotask-apply.
+---
+
 # annotask-apply
 
 Apply pending Annotask design tasks to the source code.
 
+> **For editor agents (Claude Code, Cursor, Windsurf).** Annotask's built-in agent runs apply directly through the shell — the user runs a task from the Conversation tab and the local-CLI provider edits files in place. This skill exists when the user prefers to drive apply from their own editor agent instead.
+
 ## When to use
 
 Use this skill when the user says:
@@ -12,7 +19,7 @@ Use this skill when the user says:
 
 ## How it works
 
-Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, text highlights, and drawn sections. These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
+Annotask is a visual markup tool that integrates with Vite and Webpack. The user annotates the page with pins, sticky notes, arrows, and text highlights (sections are wireframe sketch material — they arrive as `wireframe_apply` add directions, not Annotate tasks). These become **tasks** stored in `.annotask/tasks.json` and served via API. This skill fetches pending tasks, applies them, and marks them for review.
 
 ## MCP preference
 
@@ -196,18 +203,18 @@ Read the task type and apply accordingly:
 
 - **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
 
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and the relevant step-c lookups before writing custom HTML.
+  The same `context.changes` array may also carry these three **legacy** types — the current UI no longer emits them, but apply them per these rules when they appear in older tasks:
+  - `{"type": "component_prop_update", "element", "prop", "before", "after", "binding", "prop_type"?, "file", "line"}` — one prop value change at a component **usage site** (`file:line` is where `<Element …>` is written). Respect `binding`: `"literal"` means rewrite the plain attribute value (`label="Reset"` → `label="Clear"`); `"expression-literal"` means the literal is written through binding syntax — **keep the syntax** (`:count="3"` → `:count="4"`, `count={3}` → `count={4}`); `"new"` means the prop isn't present at the usage site — add it using the framework's idiomatic form for `prop_type`. Bound expressions never appear here (the UI refuses them) — if `before` doesn't match what you find in source, re-anchor via `annotask_get_code_context` instead of guessing, and never rewrite an expression that references variables.
+  - `{"type": "text_update", "element", "before", "after", "file", "line"}` — a literal text-content change. The element at `file:line` has a single literal text run equal to `before`; replace it with `after`. If the text there is an interpolation/expression or doesn't match `before`, the source drifted — re-anchor or ask, never overwrite a binding.
+  - `{"type": "component_move", "element": {"tag", "component"?, "from_file", "from_line"}, "move_to": {"target_file", "target_line", "position"}}` — relocate the element's source block from `from_file:from_line` to the given position (`before`/`after`/`append`/`prepend`) relative to `target_file:target_line`. Move the markup intact (including its bindings and children); adjust imports only if the move crosses files.
+
+- **`section_request`** (**legacy** — the current UI no longer emits these; sections now arrive as `wireframe_apply` `add` directions with an `md` body. Apply this rule when older task files carry one): Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and the relevant step-c lookups before writing custom HTML.
 
 - **`a11y_fix`**: Fix an accessibility violation. Read `A11Y_RULES.md` in this skill directory before applying the change. If you are working through multiple a11y tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: prefer pattern fixes over instance fixes, expect layout/head rules to live in root or layout files, and fetch the screenshot first when the issue is visual (contrast, focus ring, hidden text, similar).
 
 - **`theme_update`**: Apply batched design-token edits from the Theme page. Read `THEME_UPDATE.md` in this skill directory before applying the change. If you are working through multiple theme tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: one task may include many edits, update source files before `.annotask/design-spec.json`, and land `theme_update` before dependent `style_update` tasks.
 
-- **`api_update`**: Do **not** edit the API in this skill. Instead, inspect the task context and tell the user exactly what would need to change for the request to work. Open `context.schema_location`, inspect the referenced operation (`context.operation.method` + `context.operation.path`, or find it by `endpoint`), and identify:
-  - the schema change required
-  - the backend handler or router that would need updating
-  - any frontend data source or caller that would need follow-up changes if the contract changed
-
-  Then mark the task `blocked` with a concise explanation naming the schema location, operation, and required contract change. If the API is external, block it immediately and say Annotask cannot change APIs outside the repo.
+- **`wireframe_apply`**: Implement the user's wireframe — snapshot-sketch directions (`context.session` entries with `change.type: 'wireframe_direction'`) and/or palette placements (`context.wireframe.instances[]`) — in real source. Read `WIREFRAME_APPLY.md` in this skill directory before applying the change. If you are working through multiple wireframe tasks in one run, read it once for the batch, not once per task. Keep three defaults in mind even before you open the playbook: pixel geometry is a hint and the direction's `relations` are the contract (implement intent with idiomatic layout, never absolute positioning); placements/directions carry durable `anchor`s (`file`/`line`) — resolve component imports via `annotask_get_component_examples` rather than guessing; and never fabricate handlers/children/data — placeholders stay visibly placeholders.
 
 - **`annotation` with cross-boundary API edits**: Some frontend requests turn out to depend on backend work (for example, a field is not returned by the current response schema). Do **not** edit the backend and do **not** ask for permission to do so. If there is a meaningful frontend-only fallback, apply it and explain the missing backend support in the resolution note. Otherwise, mark the task `blocked` and tell the user which API/schema change would be required.
 
diff --git a/skills/annotask-apply/WIREFRAME_APPLY.md b/skills/annotask-apply/WIREFRAME_APPLY.md
new file mode 100644
index 0000000..dfbc207
--- /dev/null
+++ b/skills/annotask-apply/WIREFRAME_APPLY.md
@@ -0,0 +1,121 @@
+# Wireframe Apply
+
+Read this file for `wireframe_apply` tasks. If you are applying a batch, read it once for the batch, not once per instance.
+
+A `wireframe_apply` task arrives two ways:
+
+1. **"Implement this wireframe"** — the user froze a route into a snapshot sketch (per-block images of the real render), rearranged it freely, and asked you to implement the intent. The task carries **wireframe directions** in `context.session.entries[]` (`change.type === 'wireframe_direction'`) plus a labeled before/after composite screenshot.
+2. **"Build this route" / "Apply now"** — palette placements in `context.wireframe.instances[]` and/or design-session edits in `context.session.entries[]` (style/class/move/insert change types).
+
+A task may carry both halves. Handle directions with the rules below; handle placements and other session entries with the later sections.
+
+## Wireframe directions (`change.type: 'wireframe_direction'`)
+
+The user rearranged a SKETCH — images of the rendered page, not the live app. The server diffed the sketch against the original capture into one direction per changed block:
+
+- `op`: `move` | `resize` | `delete` | `add` | `note`.
+- `block`: `{ label, component?, tag? }` — the block's identity as captured. Tool-derived, never invented.
+- `file`/`line` (top level): the block's captured source anchor — or, for `add`, the nearest anchored NEIGHBOR block (see `added.position`).
+- `measured`: TOOL-MEASURED geometry. `before`/`after` rects, `dx`/`dy`, `wPct`/`hPct` (percent of original), and `relations[]` — order-flip / full-width / alignment facts computed from box geometry (e.g. `"now above the filters (was below)"`).
+- `added` (op `add` only): `kind` `component` (a real palette component — `componentName`/`library`/`module`/`props` are REAL scanner output) | `placeholder` (a user-drawn labeled box) | `duplicate` (another copy of a captured block's markup). `position` (`before`/`after`/`append`) is relative to the anchored neighbor. May carry `md` (the user's VERBATIM markdown spec for a drawn section) and/or `data` (a binding to a REAL catalog data source — see *Data bindings on adds* below).
+- `note`: the user's VERBATIM words for that block. `measured` is what the tool measured; `note` is what the user said — never conflate them, and never present a measured relation as a user request.
+
+### Intent over pixels
+
+**Pixel geometry is a hint; the relations are the contract.** `"now above the filters (was below)"` IS the instruction; `y 480→180` is evidence. Implement with idiomatic layout — reorder siblings, change flex/grid order, adjust column spans, use design tokens (`annotask_get_design_spec`) for sizes — never absolute positioning to hit coordinates. A resize of `+50% w` on a card grid usually means "fewer, larger columns", not `width: 1200px`.
+
+### Use the visuals
+
+The task screenshot (`annotask_get_screenshot`) is a labeled composite: **left = the captured render (truth at capture time); right = the user's sketch — rearranged images, not real UI.** Numbered badges on the right pane map 1:1 to the numbered directions in the task description. Look at it before writing code: spatial intent (what ended up next to what) is often clearer in the image than in prose.
+
+### Per-op rules
+
+- **move** — relocate the block's anchored markup to satisfy the relations. Apply per-file edits bottom-up (descending line); re-ground drifted anchors with `annotask_get_source_excerpt`. A loop-rendered block moves as the loop, not one iteration. An exploded container appears as both a container block and separate child blocks (each with finer anchors): directions on children mean restructuring INSIDE the container; a direction on the container means moving the whole thing, children included. (Explode-to-children is deferred this release — `WIREFRAME_EXPLODE_ENABLED=false` — so new tasks won't carry exploded child blocks; this guidance applies to legacy task files that already do.)
+- **resize** — prefer tokens/utility classes/grid-template changes over raw px. Say in the resolution what you chose and why.
+- **delete** — remove the anchored markup. Remove now-dead local bindings only when provably unused; never delete shared code.
+- **add / component** — resolve the real import via `annotask_get_component_examples` (proven specifier + export kind). No in-repo examples → fall back to `library`/`module` and say so. Apply `added.props` primitives only; never fabricate handlers, bindings, or children. When `added.data` is present, wire the REAL source per *Data bindings on adds* below — never sample data.
+- **add / placeholder** (bare — no `md`) — emit a *visibly labeled* placeholder element (e.g. `<div class="placeholder">pagination here</div>` styled per project conventions) or the minimal honest scaffold the label names. **Never fabricate data or content.**
+- **add / placeholder with `added.md` (a drawn SECTION)** — the markdown is the user's verbatim spec for the region: build what it describes per project conventions (component-library-first — run the SKILL.md step-c lookups before writing custom HTML; design tokens for styling). Use `added.data` for any data the section shows. Data-driven content with NO binding → visible placeholder slots or `needs_info` — **never fabricate data or fields.**
+- **add / duplicate** — duplicate the anchored block's markup. If it's loop-rendered, the user probably wants another ITEM or a second instance of the section — read the note/screenshot, ask via `needs_info` when ambiguous.
+- **note** — implement the user's verbatim ask. Ambiguous → `needs_info`, never guess silently.
+
+Before rewriting any expression or bound markup you encounter mid-edit, re-classify it against CURRENT source: `annotask_get_binding_classification` (CLI: `annotask binding-classify`). Never rewrite an expression that references variables.
+
+### Data bindings on adds (`added.data`)
+
+> **Gated off this release.** Wireframe data binding is DEFERRED (`WIREFRAME_DATA_BINDING_ENABLED=false` in `src/shell/wireframeFeatures.ts`), so new `wireframe_apply` tasks won't carry `added.data`. This section applies to legacy/older task files that already contain a binding — when one is present, wire it per the rules below.
+
+`added.data` means "wire THIS source" — it is REAL scanner-catalog identity, never invented:
+
+- `kind`/`name`/`module`/`endpoint`: the source as the project defines it (`module` is its defining file). `path` drills into the response shape (`planets[]` = the list; `data.user` = an object); `fields` are the keys the element should display.
+- `shape_source` is the honesty tag for where the drill-down shape came from:
+  - `api-schema` — a real API contract matched the source's endpoint; the path/fields were picked off the actual response schema. Trust the shape; `annotask_get_api_operation` returns the full operation when you need more.
+  - `source-details` — regex-inferred return-type hints only (no confidence score is carried — the tag is the only signal). Re-verify against the real definition before relying on field names.
+  - `none` — the user typed the path/fields blind. Ground them yourself before wiring.
+- **Re-grounding protocol (always):** call `annotask_get_data_source_details` for the definition and `annotask_get_data_source_examples` for the proven import + call pattern — wire the source the way the project already wires it (same import specifier, same destructuring, loops/`v-for` over the `path` collection, render the `fields`).
+- The binding contradicts current source (source renamed, field gone, shape changed)? → `needs_info` with what you found. **Never invent fields**; runtime endpoints carry no response shapes — don't pretend otherwise.
+
+### Verification & status
+
+Directions are spatial — the server does NOT verify them against source. When you set `review`, direction entries flip `written` on trust (bindings included — their wiring rides the trusted resolution); **your resolution is the only record of what actually landed**, so make it specific and honest per direction: which file(s), what structural change, for bindings the imported source + call site + rendered fields, any file you created (name new files explicitly — in git projects the server nets newly-created files into the undo batch, but your resolution is still the human-readable record). `blocked_reason` when a direction is impossible; `needs_info` for ambiguity; denied → read `feedback` and re-apply the same task.
+
+## Placements (`context.wireframe`)
+
+`context.wireframe` contains:
+
+- `route`: the iframe route the placements were made on (e.g. `/planets`).
+- `instances[]`: one entry per placement.
+
+Each instance contains:
+
+- `id`: stable placement id.
+- `kind`: `component` | `html` | `layout-preset`.
+- `anchor`: where it goes — `{ file, line, position, component, targetTag }`.
+  - `file`, `line`: the drop target's source location (`data-annotask-file` / `-line`). `line` is the target's **opening-tag** line.
+  - `position`: `before` | `after` | `append` | `prepend` — placement relative to the target element.
+  - `component`: the target's owning component (context).
+- `inserted`: what to add — `{ tag, componentName?, library?, props?, classes?, text_content? }`. `inserted.props` are the REAL props.
+- `previewProps` (optional): the display-only sample props the user actually saw rendered on the canvas (e.g. `{ label: "Button" }`). Use them as **hints** for sensible prop values and label text when `inserted.props` is empty or sparse — they show what the user previewed and approved. They are still samples: never lift fabricated event handlers, data bindings, or children from them.
+- `fidelity`: how faithfully it previewed — `live` (rendered in real context), `isolated-preview` (rendered detached, no provider tree), `placeholder` (could not render). Lower fidelity is a hint that the component needs context/props you may have to wire by hand; it is not a blocker.
+- `mounted`: whether the live preview produced output.
+- `status` / `taskId`: lifecycle bookkeeping (`building` + the owning task id while you work). Read-only for you — see the lifecycle section below.
+
+### Apply flow for placements
+
+1. Group `context.wireframe.instances` by `anchor.file`. Open each file once and apply all its placements in one pass, **bottom-up** (descending `anchor.line`): every insertion shifts the lines below it, so applying the highest line number first keeps the remaining anchors' line numbers valid without re-counting.
+2. Locate the anchor element at `anchor.line` in that file. Insert the new markup relative to it per `anchor.position` (`before`/`after` = sibling; `append`/`prepend` = first/last child of the target). Match the file's framework (read `annotask_get_design_spec` for `framework` once) and the surrounding indentation.
+3. Emit markup per `kind`:
+   - **html** → the raw element: `<tag class="…">text_content</tag>` using `inserted.classes` / `inserted.text_content`. Omit empty attributes.
+   - **layout-preset** → a styled wrapper (`<div class="…">` / `<section class="…">`) with `inserted.classes`. It has **no children** — leave it empty for the user to fill. Never fabricate children.
+   - **component** → resolve the real import first, then emit `<ComponentName …props />` (or framework equivalent) at the anchor and add the import if the file does not already import it.
+4. For a `component`, call `annotask_get_component_examples` with `inserted.componentName` (and `inserted.library`) to get the **proven** import specifier + export kind (named vs default) from real in-repo usage. Use that exact import path. If there are no in-repo examples, fall back to `inserted.library` / the scanner `module`, and say so in your resolution — do **not** invent an import path.
+5. Apply props from `inserted.props`, but only primitives that differ from the component's documented defaults. **Never fabricate** event handlers, data bindings, children, or named slots — if a component clearly needs them, note it in the resolution (or use `needs_info`).
+6. After all placements land, set status to `review` with a per-instance resolution (what you inserted, where, and any import you had to guess).
+
+## Other design-session edits (`context.session`)
+
+`context.session` may also carry non-direction entries — the user's design-session edits:
+
+- `session_id`: bookkeeping. The server owns `.annotask/design-session.json`, `.annotask/wireframe.json` (which also carries the canvas sketch), and `.annotask/file-snapshots.json` — **never edit, rewrite, or clean up those files yourself**. Apply through source code only; the server verifies your work and updates the session when you set `review`.
+- `entries[]`: each is `{ id, change, anchor, evidence?, instance_id? }`.
+  - `change` is one of the structured change types (`style_update`, `class_update`, `component_insert`, legacy `component_prop_update`/`text_update`/`component_move`, …) — apply each per the change-type rules in SKILL.md step d.
+  - `anchor` (`{ file, line, targetTag? }`) is where the edit was recorded. Your own earlier edits in the same run shift lines — apply **bottom-up per file** like placements, and re-ground via `annotask_get_source_excerpt` when an anchor doesn't match.
+  - `evidence.classification` (legacy `component_prop_update`/`text_update` entries only) is the round-trip-honesty proof from when the user made the edit: `literal` edits rewrite a plain literal in place; `expression-literal` edits keep the binding syntax (`:count="3"` → `:count="4"`); `bound` edits never appear (the UI refused them). If what you find at the anchor contradicts the evidence, the source drifted — re-anchor or ask via `needs_info`, never rewrite an expression.
+- Prefer idiomatic placement over literal transcription: if a `style_update` matches a design token (`token_role` present, or an obvious token in `annotask_get_design_spec`), apply the token/class rather than a raw value, and say so in the resolution.
+- After you set `review`, the server re-reads the source per entry and marks each `written` or `failed` (directions are trusted — see above) — a `failed` badge in the user's panel means your edit wasn't found where expected, so make resolutions specific about what landed where.
+
+## Lifecycle (do NOT edit .annotask files)
+
+- When the user **accepts** your task, the server removes its instances and the implemented canvas sketch from `wireframe.json` automatically.
+- When the user **deletes** the task, the server reverts instances to `placed` and unlocks the sketch (`building` → `sketch`) so the user can tweak and re-implement.
+- When the user **denies** the task, everything stays locked to your task — re-apply against the same task after reading `feedback`.
+
+## Edge cases
+
+- If an `anchor.file`/`line` no longer matches the described element (source drifted since the capture/placement), call `annotask_get_code_context` for the task to re-anchor; if you still can't place it, mark that instance/direction and use `needs_info`.
+- If a placement or direction requires data/state that doesn't exist yet (e.g. a list component with no data source on the route), use `blocked_reason` to explain what's missing rather than fabricating data.
+
+## Defaults
+
+- One `wireframe_apply` task may touch multiple files and multiple frameworks (MFEs) — handle each file independently.
+- The sketch is a wireframe, not a final design: prioritize correct structure, real imports, and the stated relations over pixel-perfect geometry.
diff --git a/skills/annotask-init/SKILL.md b/skills/annotask-init/SKILL.md
index 63df6c7..ac5d4e0 100644
--- a/skills/annotask-init/SKILL.md
+++ b/skills/annotask-init/SKILL.md
@@ -1,7 +1,14 @@
+---
+name: annotask-init
+description: Initialize Annotask for this project by scanning the codebase and generating .annotask/design-spec.json. Use when the user asks to initialize, set up, configure, or scan their project for Annotask, or runs /annotask-init.
+---
+
 # annotask-init
 
 Initialize Annotask for this project by scanning the codebase and generating `.annotask/design-spec.json`.
 
+> **For editor agents only.** Annotask's built-in agent runs init through the shell UI — open `http://localhost:5173/__annotask/` and the wizard walks the user through provider setup, project scan, and style guide. This skill exists for users who prefer their own editor agent (Claude Code, Cursor, Windsurf) to do the deeper token extraction the in-shell baseline doesn't cover.
+
 ## When to use
 
 Use this skill when the user says any of:
diff --git a/src/cli/__tests__/cli-mcp.test.ts b/src/cli/__tests__/cli-mcp.test.ts
new file mode 100644
index 0000000..2f6b119
--- /dev/null
+++ b/src/cli/__tests__/cli-mcp.test.ts
@@ -0,0 +1,264 @@
+import { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach, vi } from 'vitest'
+import http from 'node:http'
+import { AddressInfo } from 'node:net'
+import { createAPIMiddleware } from '../../server/api'
+import { runCli } from '../index'
+
+// ── Harness ───────────────────────────────────────────
+// Real createAPIMiddleware on an ephemeral port (same pattern as
+// src/plugin/__tests__/api.test.ts) + the CLI driven in-process via runCli.
+// stdout is captured through a console.log spy; `inProcess: true` makes the
+// CLI's exit() unwind into the resolved exit code instead of killing vitest.
+
+function createTestServer(options: Parameters<typeof createAPIMiddleware>[0]) {
+  const middleware = createAPIMiddleware(options)
+  return http.createServer((req, res) => {
+    middleware(req, res, () => {
+      res.statusCode = 404
+      res.end('Not found')
+    })
+  })
+}
+
+/** A task with every field the --mcp output is supposed to strip in list mode. */
+const seededTask = {
+  id: 'task-1',
+  type: 'annotation',
+  status: 'pending',
+  description: 'Make the header sticky',
+  file: 'src/App.vue',
+  line: 12,
+  visual: { x: 10, y: 20, marker: 'pin' },
+  interaction_history: { route_path: ['/'], actions: [{ kind: 'click', target: 'button' }] },
+  context: { rendered: '<div class="header">embedded outerHTML blob</div>', element_tag: 'div' },
+}
+
+function makeOptions() {
+  const tasks: Array<Record<string, unknown>> = [{ ...seededTask, context: { ...seededTask.context } }]
+  return {
+    // Repo root so source-excerpt can read real files through resolveProjectFile.
+    projectRoot: process.cwd(),
+    getReport: () => ({ version: '1.0', changes: [] }),
+    getConfig: () => ({ version: '1.0' }),
+    getDesignSpec: () => ({ version: '1.0', initialized: false }),
+    getTasks: () => ({ version: '1.0', tasks }),
+    addTask: (task: Record<string, unknown>) => {
+      const newTask = { id: `task-${Date.now()}`, status: 'pending', ...task }
+      tasks.push(newTask)
+      return newTask
+    },
+    updateTask: (id: string, updates: Record<string, unknown>) => {
+      const task = tasks.find(t => t.id === id)
+      if (!task) return { error: 'Task not found' }
+      Object.assign(task, updates)
+      return task
+    },
+    deleteTask: (id: string) => {
+      const idx = tasks.findIndex(t => t.id === id)
+      if (idx === -1) return { error: 'Task not found' }
+      tasks.splice(idx, 1)
+      return { deleted: id }
+    },
+    saveInteractionHistory: async (_id: string, _snapshot: unknown) => { /* no-op for tests */ },
+    readInteractionHistory: async (_id: string) => null,
+    saveRenderedHtml: async (_id: string, _html: string) => { /* no-op for tests */ },
+    readRenderedHtml: async (_id: string) => null,
+    getPerformance: () => null as unknown,
+    setPerformance: (_data: unknown) => { /* no-op for tests */ },
+    ingestNetworkCalls: (_calls: unknown[]) => { /* no-op for tests */ },
+    getRuntimeEndpointCatalog: () => ({ version: '1.0' as const, updatedAt: 0, endpoints: [] }),
+    clearRuntimeEndpoints: () => { /* no-op for tests */ },
+    taskThread: {
+      read: async (_id: string) => [],
+      append: async (_id: string, input: { role: 'user' | 'assistant' | 'system' | 'tool'; content: string }) => ({
+        id: 'msg-test', ts: 0, role: input.role, content: input.content,
+      }),
+      update: async (_id: string, msgId: string, patch: { content?: string }) => ({
+        id: msgId, ts: 0, role: 'assistant' as const, content: patch.content ?? '',
+      }),
+      subscribe: () => () => { /* no-op */ },
+      clear: async () => { /* no-op */ },
+    },
+    agentSpawn: {
+      registry: { abort: () => false, size: () => 0, taskRunning: () => false, killAll: () => { /* no-op */ } },
+      handleSpawn: async (_req: unknown, res: { statusCode: number; end: (s?: string) => void }) => {
+        res.statusCode = 501; res.end('not supported in this test')
+      },
+    },
+    agentDetect: {
+      detect: async () => ({
+        'claude-local': { found: false },
+        'codex-local': { found: false },
+        'opencode-local': { found: false },
+        'copilot-local': { found: false },
+        copilot: { found: false },
+        openrouter: { hasEnv: false },
+        ts: 0,
+      }),
+      invalidate: () => { /* no-op */ },
+    },
+    initRunner: {
+      start: () => ({ running: false, steps: [] }),
+      cancel: () => { /* no-op */ },
+      commit: async () => ({ running: false, steps: [], result: 'success' as const }),
+      skip: async () => ({ running: false, steps: [], result: 'success' as const }),
+      reset: () => ({ running: false, steps: [] }),
+      getState: () => ({ running: false, steps: [] }),
+    },
+    getAgentConfigs: async () => ({
+      version: 1 as const,
+      agents: { general: { projectDirections: 'Prefer composables over mixins' } },
+    }),
+    setAgentConfig: async () => ({ version: 1 as const, agents: {} }),
+    getWireframe: async () => ({ version: '1.0' as const, updatedAt: 0, routes: [] }),
+    setWireframe: async (doc: any) => doc,
+    getDesignSession: async () => ({ version: '1.0' as const, sessionId: 'ds-test', startedAt: 0, updatedAt: 0, entries: [] }),
+    setDesignSession: async (doc: any) => doc,
+    clearDesignSession: async () => ({ version: '1.0' as const, sessionId: 'ds-test', startedAt: 0, updatedAt: 0, entries: [] }),
+    snapshots: {
+      snapshotFiles: async () => undefined,
+      sealBatch: async () => undefined,
+      sealBatchByTask: async () => undefined,
+      revertBatch: async () => ({ reverted: [], skipped: [] }),
+      revertAll: async () => ({ reverted: [], skipped: [] }),
+      commit: async () => undefined,
+      detachFile: async () => undefined,
+      state: async () => ({ files: {}, batches: [] }),
+      flush: async () => undefined,
+    },
+    usageLedger: {
+      append: async (e: { scope: 'task' | 'init' | 'apply' | 'chat' }) => ({ ts: 0, scope: e.scope, inputTokens: 0, outputTokens: 0 }),
+      readAll: async () => [],
+      summary: async () => ({
+        totals: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+        byScope: {
+          task: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+          init: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+          apply: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+          chat: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+        },
+        byProvider: {},
+        firstAt: null,
+        lastAt: null,
+      }),
+      recent: async () => [],
+    },
+  }
+}
+
+describe('CLI --mcp parity and structured errors', () => {
+  let server: http.Server
+  let serverUrl = ''
+  let deadUrl = ''
+  let logs: string[] = []
+
+  beforeAll(async () => {
+    server = createTestServer(makeOptions() as Parameters<typeof createAPIMiddleware>[0])
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    serverUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
+
+    // A port that *was* bound and is now closed — guaranteed-dead endpoint
+    // without racing against other processes grabbing it.
+    const dead = http.createServer()
+    await new Promise<void>((resolve) => dead.listen(0, '127.0.0.1', resolve))
+    deadUrl = `http://127.0.0.1:${(dead.address() as AddressInfo).port}`
+    await new Promise<void>((resolve) => dead.close(() => resolve()))
+  })
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()))
+  })
+
+  beforeEach(() => {
+    logs = []
+    vi.spyOn(console, 'log').mockImplementation((...a: unknown[]) => { logs.push(a.join(' ')) })
+    vi.spyOn(console, 'error').mockImplementation(() => { /* silence human stderr */ })
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  /** Run the CLI in-process and parse its single-line JSON stdout. */
+  async function run(argv: string[]): Promise<{ code: number; out: any }> {
+    const code = await runCli([...argv, `--server=${serverUrl}`], { inProcess: true })
+    return { code, out: logs.length > 0 ? JSON.parse(logs[logs.length - 1]) : null }
+  }
+
+  it('tasks --mcp returns summaries with visual/context stripped', async () => {
+    const { code, out } = await run(['tasks', '--mcp'])
+    expect(code).toBe(0)
+    expect(out.count).toBe(1)
+    const task = out.tasks[0]
+    expect(task.id).toBe('task-1')
+    expect(task.visual).toBeUndefined()
+    expect(task.context).toBeUndefined()
+    // Summary lifting keeps the triage-relevant locator field.
+    expect(task.element_tag).toBe('div')
+  })
+
+  it('tasks --mcp --detail strips visual, interaction_history, and context.rendered', async () => {
+    const { code, out } = await run(['tasks', '--mcp', '--detail'])
+    expect(code).toBe(0)
+    const task = out.tasks[0]
+    expect(task.visual).toBeUndefined()
+    expect(task.interaction_history).toBeUndefined()
+    expect(task.context.rendered).toBeUndefined()
+    expect(task.context.element_tag).toBe('div')
+  })
+
+  it('source-excerpt --mcp grounds an arbitrary file/line', async () => {
+    const { code, out } = await run(['source-excerpt', '--file=src/schema.ts', '--line=10', '--context-lines=5', '--mcp'])
+    expect(code).toBe(0)
+    expect(out.file).toBe('src/schema.ts')
+    expect(out.error).toBeUndefined()
+    expect(out.excerpt).toBeTruthy()
+    expect(out.excerpt_hash).toMatch(/^[0-9a-f]{16}$/)
+  })
+
+  it('agent-directions --mcp returns one persona or not_configured', async () => {
+    const one = await run(['agent-directions', 'general', '--mcp'])
+    expect(one.code).toBe(0)
+    expect(one.out.persona_id).toBe('general')
+    expect(one.out.projectDirections).toBe('Prefer composables over mixins')
+
+    const missing = await run(['agent-directions', 'designer', '--mcp'])
+    expect(missing.code).toBe(0)
+    expect(missing.out.not_configured).toBe(true)
+  })
+
+  it('playbook --mcp serves the bundled companion without a dev server', async () => {
+    // No --server needed: playbook reads the packaged skill files directly.
+    const code = await runCli(['playbook', 'wireframe_apply', '--mcp'], { inProcess: true })
+    expect(code).toBe(0)
+    const out = JSON.parse(logs[logs.length - 1])
+    expect(out.task_type).toBe('wireframe_apply')
+    expect(out.file).toBe('WIREFRAME_APPLY.md')
+    expect(out.content).toContain('# Wireframe Apply')
+  })
+
+  it('prints a structured JSON error envelope when the server is down', async () => {
+    const code = await runCli(['tasks', '--mcp', `--server=${deadUrl}`], { inProcess: true })
+    expect(code).toBe(1)
+    const out = JSON.parse(logs[logs.length - 1])
+    expect(out.error.code).toBe('server_unreachable')
+    expect(typeof out.error.message).toBe('string')
+    expect(out.error.message).toMatch(/Failed to fetch tasks/)
+  })
+
+  it('prints a structured usage error under --mcp', async () => {
+    // source-excerpt without its required --file/--line flags.
+    const code = await runCli(['source-excerpt', '--mcp', `--server=${serverUrl}`], { inProcess: true })
+    expect(code).toBe(1)
+    const out = JSON.parse(logs[logs.length - 1])
+    expect(out.error.code).toBe('usage')
+    expect(out.error.message).toMatch(/Usage: annotask source-excerpt/)
+  })
+
+  it('not_found errors use the envelope too (task --mcp with bogus id)', async () => {
+    const { code, out } = await run(['task', 'nope-404', '--mcp'])
+    expect(code).toBe(1)
+    expect(out.error.code).toBe('not_found')
+    expect(out.error.message).toMatch(/Task not found: nope-404/)
+  })
+})
diff --git a/src/cli/index.ts b/src/cli/index.ts
index e44920e..b42e18c 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -1,24 +1,55 @@
 import WebSocket from 'ws'
-import { existsSync, mkdirSync, cpSync, readdirSync, symlinkSync, lstatSync, rmSync, readlinkSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, cpSync, readdirSync, symlinkSync, lstatSync, rmSync, readlinkSync, readFileSync, writeFileSync, realpathSync } from 'node:fs'
 import { resolve, dirname, relative } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { buildTaskSummary, stripTaskVisual, trimAgentFeedback, compactJson } from '../shared/task-summary.js'
-
-const args = process.argv.slice(2)
-const command = args[0] || 'watch'
-const portArg = args.find(a => a.startsWith('--port='))?.split('=')[1] || ''
-const hostArg = args.find(a => a.startsWith('--host='))?.split('=')[1] || ''
-const serverArg = args.find(a => a.startsWith('--server='))?.split('=')[1] || ''
-const mfeArg = args.find(a => a.startsWith('--mfe='))?.split('=')[1] || ''
-const prettyFlag = args.includes('--pretty')
-const detailFlag = args.includes('--detail')
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { buildTaskSummary, stripTaskVisual, stripTaskForList, trimAgentFeedback, compactJson } from '../shared/task-summary.js'
+import { loadSkill, TASK_TYPE_COMPANIONS } from '../skills/loader.js'
+import { TASK_TYPES } from '../schema.js'
+
+// ── Argv-derived state ────────────────────────────────
+// Module-level because every command reads it; `let` (not const) because
+// `runCli()` re-initializes it per invocation so the CLI can be driven
+// in-process (tests, embedding) as well as from the bin entry.
+
+let args: string[] = []
+let command = 'watch'
+let portArg = ''
+let hostArg = ''
+let serverArg = ''
+let mfeArg = ''
+let prettyFlag = false
+let detailFlag = false
 /**
  * --mcp forces agent-parity output: compact JSON on stdout, no ANSI colors,
  * no human-readable prefixes. The shape matches what the MCP server returns
  * for the equivalent `annotask_*` tool call, so skills that prefer MCP can
  * fall back to CLI invocations with identical parsing. Overrides --pretty.
  */
-const mcpFlag = args.includes('--mcp')
+let mcpFlag = false
+let baseUrl = 'http://localhost:5173'
+let baseUrlSource: BaseUrlSource = 'fallback'
+let mfeFilter = ''
+let wsUrl = ''
+let apiUrl = ''
+
+function initFlags(argv: string[]): void {
+  args = argv
+  command = args[0] || 'watch'
+  portArg = args.find(a => a.startsWith('--port='))?.split('=')[1] || ''
+  hostArg = args.find(a => a.startsWith('--host='))?.split('=')[1] || ''
+  serverArg = args.find(a => a.startsWith('--server='))?.split('=')[1] || ''
+  mfeArg = args.find(a => a.startsWith('--mfe='))?.split('=')[1] || ''
+  prettyFlag = args.includes('--pretty')
+  detailFlag = args.includes('--detail')
+  mcpFlag = args.includes('--mcp')
+
+  const discovered = discoverBaseUrl()
+  baseUrl = discovered.url
+  baseUrlSource = discovered.source
+  mfeFilter = mfeArg || discovered.mfe || ''
+  wsUrl = baseUrl.replace(/^http/, 'ws') + '/__annotask/ws'
+  apiUrl = baseUrl + '/__annotask/api'
+}
 
 /** Compact JSON for agent-facing output; strips null/undefined/empty arrays */
 function fmt(data: unknown): string {
@@ -35,6 +66,51 @@ function info(text: string): void {
   if (!mcpFlag) console.error(text)
 }
 
+// ── Exit / failure plumbing ───────────────────────────
+
+/** Thrown instead of terminating when `runCli` runs in-process. */
+class CliExit extends Error {
+  constructor(public readonly code: number) { super(`CLI exit ${code}`) }
+}
+
+let inProcess = false
+
+/**
+ * Exit indirection. From the bin entry this is `process.exit`; under
+ * `runCli(..., { inProcess: true })` it throws `CliExit` instead, so command
+ * bodies still stop at the exit point but the host process survives and
+ * `runCli` resolves with the code.
+ */
+function exit(code: number): never {
+  if (inProcess) throw new CliExit(code)
+  process.exit(code)
+}
+
+/**
+ * Shared failure path for every command. Under --mcp this prints a structured
+ * `{"error":{"code","message"}}` envelope to *stdout* and exits 1 — skills
+ * that fall back from the MCP server to `npx annotask ... --mcp` can parse
+ * failures exactly like successes instead of scraping ANSI stderr text.
+ * Without --mcp it keeps the human stderr behavior (plus optional hint lines).
+ */
+function fail(code: string, message: string, hint?: string): never {
+  if (mcpFlag) {
+    console.log(JSON.stringify({ error: { code, message } }))
+    exit(1)
+  }
+  console.error(`${color('31', '[Annotask]')} ${message}`)
+  if (hint) console.error(hint)
+  exit(1)
+}
+
+/** Classify a thrown fetch error into a stable machine code for `fail`.
+ *  Commands throw `HTTP <status>` for non-ok responses; anything else is a
+ *  transport failure (server down, wrong port, DNS). */
+function errCode(err: unknown): string {
+  const msg = err instanceof Error ? err.message : String(err)
+  return /^HTTP \d+/.test(msg) ? 'http_error' : 'server_unreachable'
+}
+
 /**
  * Discover the dev-server URL.
  *
@@ -65,15 +141,6 @@ function discoverBaseUrl(): { url: string; source: BaseUrlSource; mfe?: string }
   return { url: 'http://localhost:5173', source: 'fallback' }
 }
 
-const discovered = discoverBaseUrl()
-const baseUrl = discovered.url
-const baseUrlSource = discovered.source
-let mfeFilter = mfeArg
-if (!mfeFilter && discovered.mfe) mfeFilter = discovered.mfe
-
-const wsUrl = baseUrl.replace(/^http/, 'ws') + '/__annotask/ws'
-const apiUrl = baseUrl + '/__annotask/api'
-
 /** Human-readable hint for the agent when a connection fails. */
 function serverHint(): string {
   if (baseUrlSource === 'server-json' || baseUrlSource === 'flag') {
@@ -105,66 +172,111 @@ function parseTargets(): string[] {
   return DEFAULT_TARGETS
 }
 
-// ── Commands ──────────────────────────────────────────
-
-if (command === 'watch') {
-  watchChanges()
-} else if (command === 'report') {
-  fetchReport()
-} else if (command === 'status') {
-  checkStatus()
-} else if (command === 'init-skills') {
-  initSkills()
-} else if (command === 'init-mcp') {
-  initMcp()
-} else if (command === 'screenshot') {
-  fetchScreenshot()
-} else if (command === 'tasks') {
-  fetchTasks()
-} else if (command === 'task') {
-  fetchTask()
-} else if (command === 'design-spec') {
-  fetchDesignSpec()
-} else if (command === 'update-task') {
-  updateTask()
-} else if (command === 'components') {
-  listComponents()
-} else if (command === 'component') {
-  showComponent()
-} else if (command === 'code-context') {
-  fetchCodeContext()
-} else if (command === 'component-examples') {
-  fetchComponentExamples()
-} else if (command === 'data-context') {
-  fetchDataContext()
-} else if (command === 'interaction-history') {
-  fetchInteractionHistory()
-} else if (command === 'rendered-html') {
-  fetchRenderedHtml()
-} else if (command === 'data-sources') {
-  fetchDataSources()
-} else if (command === 'data-source-examples') {
-  fetchDataSourceExamples()
-} else if (command === 'data-source-details') {
-  fetchDataSourceDetails()
-} else if (command === 'api-schemas') {
-  fetchApiSchemas()
-} else if (command === 'api-operation') {
-  fetchApiOperation()
-} else if (command === 'resolve-endpoint') {
-  resolveEndpointCmd()
-} else if (command === 'runtime-endpoints') {
-  fetchRuntimeEndpoints()
-} else if (command === 'mcp') {
-  runMcpStdio()
-} else if (command === 'help' || command === '--help') {
-  printHelp()
-} else {
-  console.error(`Unknown command: ${command}`)
-  printHelp()
-  process.exit(1)
+// ── Entry points ──────────────────────────────────────
+
+export interface RunCliOptions {
+  /** Throw-based exit instead of process.exit — for in-process callers/tests. */
+  inProcess?: boolean
+}
+
+/**
+ * Programmatic CLI entry. Resolves with the exit code (0 on success). The bin
+ * entry calls this with `process.argv.slice(2)`; tests call it with
+ * `inProcess: true` so `exit()` unwinds via `CliExit` instead of killing the
+ * test runner.
+ */
+export async function runCli(argv: string[], opts: RunCliOptions = {}): Promise<number> {
+  initFlags(argv)
+  inProcess = opts.inProcess === true
+  try {
+    await dispatch()
+    return 0
+  } catch (err) {
+    if (err instanceof CliExit) return err.code
+    throw err
+  } finally {
+    inProcess = false
+  }
+}
+
+async function dispatch(): Promise<void> {
+  if (command === 'watch') {
+    watchChanges()
+  } else if (command === 'report') {
+    await fetchReport()
+  } else if (command === 'status') {
+    await checkStatus()
+  } else if (command === 'init-skills') {
+    initSkills()
+  } else if (command === 'init-mcp') {
+    initMcp()
+  } else if (command === 'screenshot') {
+    await fetchScreenshot()
+  } else if (command === 'tasks') {
+    await fetchTasks()
+  } else if (command === 'task') {
+    await fetchTask()
+  } else if (command === 'design-spec') {
+    await fetchDesignSpec()
+  } else if (command === 'update-task') {
+    await updateTask()
+  } else if (command === 'components') {
+    await listComponents()
+  } else if (command === 'component') {
+    await showComponent()
+  } else if (command === 'code-context') {
+    await fetchCodeContext()
+  } else if (command === 'source-excerpt') {
+    await fetchSourceExcerpt()
+  } else if (command === 'binding-classify') {
+    await fetchBindingClassification()
+  } else if (command === 'playbook') {
+    fetchPlaybook()
+  } else if (command === 'agent-directions') {
+    await fetchAgentDirections()
+  } else if (command === 'component-examples') {
+    await fetchComponentExamples()
+  } else if (command === 'data-context') {
+    await fetchDataContext()
+  } else if (command === 'interaction-history') {
+    await fetchInteractionHistory()
+  } else if (command === 'rendered-html') {
+    await fetchRenderedHtml()
+  } else if (command === 'data-sources') {
+    await fetchDataSources()
+  } else if (command === 'data-source-examples') {
+    await fetchDataSourceExamples()
+  } else if (command === 'data-source-details') {
+    await fetchDataSourceDetails()
+  } else if (command === 'api-schemas') {
+    await fetchApiSchemas()
+  } else if (command === 'api-operation') {
+    await fetchApiOperation()
+  } else if (command === 'resolve-endpoint') {
+    await resolveEndpointCmd()
+  } else if (command === 'runtime-endpoints') {
+    await fetchRuntimeEndpoints()
+  } else if (command === 'mcp') {
+    runMcpStdio()
+  } else if (command === 'help' || command === '--help') {
+    printHelp()
+  } else {
+    if (mcpFlag) fail('usage', `Unknown command: ${command}`)
+    console.error(`Unknown command: ${command}`)
+    printHelp()
+    exit(1)
+  }
 }
 
+// Run automatically only when executed as the bin entry (dist/cli.js, or a
+// node_modules/.bin symlink resolving to it) — importing `runCli` from tests
+// or other tooling must never trigger a command.
+const isMainModule = (() => {
+  if (!process.argv[1]) return false
+  try { return pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url } catch { return false }
+})()
+if (isMainModule) void runCli(process.argv.slice(2))
+
 // ── Watch: live stream of changes via WebSocket ──────
 
 const MAX_RETRIES = 20
@@ -259,9 +371,7 @@ async function fetchReport() {
     console.log(fmt(report))
     if (mfeFilter) info(`${color('36', '[Annotask]')} Filtered by MFE: ${mfeFilter}`)
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch report: ${err.message}`)
-    if (!mcpFlag) console.error(serverHint())
-    process.exit(1)
+    fail(errCode(err), `Failed to fetch report: ${err.message}`, serverHint())
   }
 }
 
@@ -279,13 +389,15 @@ async function checkStatus() {
     if (mfeFilter) console.log(`${color('36', '[Annotask]')} MFE filter: ${mfeFilter}`)
     console.log(JSON.stringify(data, null, 2))
   } catch {
+    // Deliberately NOT the fail() envelope: skills probe `status --mcp` and
+    // parse this richer unreachable payload (url/source/hint) to self-correct.
     if (mcpFlag) {
       console.log(fmt({ status: 'unreachable', url: baseUrl, source: baseUrlSource, hint: serverHint() }))
-      process.exit(1)
+      exit(1)
     }
     console.log(`${color('31', '[Annotask]')} No Annotask server found at ${baseUrl}`)
     console.log(serverHint())
-    process.exit(1)
+    exit(1)
   }
 }
 
@@ -294,8 +406,7 @@ async function checkStatus() {
 async function fetchScreenshot() {
   const taskId = args[1]
   if (!taskId) {
-    console.error('\x1b[31m[Annotask]\x1b[0m Usage: annotask screenshot <task-id> [--output=path.png]')
-    process.exit(1)
+    fail('usage', 'Usage: annotask screenshot <task-id> [--output=path.png]')
   }
 
   try {
@@ -303,13 +414,13 @@ async function fetchScreenshot() {
     const tasksRes = await fetch(`${apiUrl}/tasks`)
     const tasksData = await tasksRes.json()
     const task = tasksData.tasks.find((t: any) => t.id === taskId)
-    if (!task) { console.error(`\x1b[31m[Annotask]\x1b[0m Task not found: ${taskId}`); process.exit(1) }
-    if (!task.screenshot) { console.error(`\x1b[31m[Annotask]\x1b[0m Task has no screenshot`); process.exit(1) }
+    if (!task) fail('not_found', `Task not found: ${taskId}`)
+    if (!task.screenshot) fail('not_found', 'Task has no screenshot')
 
     // Download the screenshot
     const screenshotUrl = `${baseUrl}/__annotask/screenshots/${task.screenshot}`
     const res = await fetch(screenshotUrl)
-    if (!res.ok) { console.error(`\x1b[31m[Annotask]\x1b[0m Screenshot not found: ${task.screenshot}`); process.exit(1) }
+    if (!res.ok) fail('not_found', `Screenshot not found: ${task.screenshot}`)
     const buffer = Buffer.from(await res.arrayBuffer())
 
     const outputArg = args.find(a => a.startsWith('--output='))
@@ -319,10 +430,11 @@ async function fetchScreenshot() {
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
 
     writeFileSync(outputPath, buffer)
-    console.log(`\x1b[32m[Annotask]\x1b[0m Screenshot saved to ${outputPath}`)
+    if (mcpFlag) { console.log(fmt({ task_id: taskId, saved: outputPath })) }
+    else console.log(`\x1b[32m[Annotask]\x1b[0m Screenshot saved to ${outputPath}`)
   } catch (err: any) {
-    console.error(`\x1b[31m[Annotask]\x1b[0m Failed to fetch screenshot: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to fetch screenshot: ${err.message}`)
   }
 }
 
@@ -340,10 +452,12 @@ async function fetchTasks() {
     if (statusFilter) tasks = tasks.filter(t => t.status === statusFilter)
 
     // With --detail (or legacy --pretty without --mcp) we return full task
-    // objects. In MCP-parity mode we strip the shell-only `visual` field so
-    // the shape matches annotask_get_tasks(detail:true).
+    // objects. In MCP-parity mode we use the list strip so the shape matches
+    // annotask_get_tasks(detail:true): no shell-only `visual`, and the bulky
+    // `interaction_history` / `context.rendered` payloads come off too (each
+    // has its own retrieval command).
     if (detailFlag) {
-      data.tasks = mcpFlag ? tasks.map(stripTaskVisual) : tasks
+      data.tasks = mcpFlag ? tasks.map(stripTaskForList) : tasks
     } else if (prettyFlag && !mcpFlag) {
       data.tasks = tasks
     } else {
@@ -353,8 +467,7 @@ async function fetchTasks() {
 
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch tasks: ${err.message}`)
-    process.exit(1)
+    fail(errCode(err), `Failed to fetch tasks: ${err.message}`)
   }
 }
 
@@ -363,21 +476,17 @@ async function fetchTasks() {
 async function fetchTask() {
   const taskId = args[1]
   if (!taskId) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask task <task-id>`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask task <task-id>')
   }
   try {
     const res = await fetch(`${apiUrl}/tasks/${encodeURIComponent(taskId)}`)
-    if (res.status === 404) {
-      console.error(`${color('31', '[Annotask]')} Task not found: ${taskId}`)
-      process.exit(1)
-    }
+    if (res.status === 404) fail('not_found', `Task not found: ${taskId}`)
     if (!res.ok) throw new Error(`HTTP ${res.status}`)
     const task = await res.json() as Record<string, unknown>
     console.log(fmt(trimAgentFeedback(stripTaskVisual(task))))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch task: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to fetch task: ${err.message}`)
   }
 }
 
@@ -395,8 +504,7 @@ async function fetchDesignSpec() {
       const slice: Record<string, unknown> = { version: spec.version, framework: spec.framework }
       if (categoryArg !== 'framework') {
         if (!(categoryArg in spec)) {
-          console.error(`${color('31', '[Annotask]')} Unknown category: ${categoryArg}`)
-          process.exit(1)
+          fail('invalid_argument', `Unknown category: ${categoryArg}`)
         }
         slice[categoryArg] = spec[categoryArg]
       }
@@ -422,8 +530,8 @@ async function fetchDesignSpec() {
     }
     console.log(fmt(summary))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch design spec: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to fetch design spec: ${err.message}`)
   }
 }
 
@@ -438,11 +546,11 @@ async function updateTask() {
   const resolutionArg = args.find(a => a.startsWith('--resolution='))?.split('=').slice(1).join('=')
 
   if (!taskId || (!statusArg && !askArg && !blockedReasonArg)) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask update-task <task-id> --status=<status> [--feedback=<text>]`)
-    console.error('       annotask update-task <task-id> --ask=\'{"message":"...","questions":[...]}\'')
-    console.error('       annotask update-task <task-id> --blocked-reason="Cannot fix: issue is in third-party library"')
-    console.error('  Valid statuses: pending, in_progress, applied, review, accepted, denied, needs_info, blocked')
-    process.exit(1)
+    fail('usage', 'Usage: annotask update-task <task-id> --status=<status> [--feedback=<text>]', [
+      '       annotask update-task <task-id> --ask=\'{"message":"...","questions":[...]}\'',
+      '       annotask update-task <task-id> --blocked-reason="Cannot fix: issue is in third-party library"',
+      '  Valid statuses: pending, in_progress, applied, review, accepted, denied, needs_info, blocked',
+    ].join('\n'))
   }
 
   try {
@@ -453,7 +561,7 @@ async function updateTask() {
       const taskRes = await fetch(`${apiUrl}/tasks`)
       const taskData = await taskRes.json()
       const task = taskData.tasks.find((t: any) => t.id === taskId)
-      if (!task) { console.error(`${color('31', '[Annotask]')} Task not found: ${taskId}`); process.exit(1) }
+      if (!task) fail('not_found', `Task not found: ${taskId}`)
 
       const askData = JSON.parse(askArg)
       const entry = {
@@ -483,13 +591,15 @@ async function updateTask() {
     const data = await res.json()
     if (data.error) {
       const msg = typeof data.error === 'string' ? data.error : data.error.message ?? 'Unknown error'
-      console.error(`${color('31', '[Annotask]')} ${msg}`)
-      process.exit(1)
+      // The API's error body is already { error: { code, message } } — keep
+      // the server's code (e.g. invalid_transition) when it provides one.
+      const code = typeof data.error === 'object' && typeof data.error.code === 'string' ? data.error.code : 'http_error'
+      fail(code, msg)
     }
     console.log(fmt(mcpFlag ? stripTaskVisual(data) : data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to update task: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to update task: ${err.message}`)
   }
 }
 
@@ -503,7 +613,7 @@ function initSkills() {
 
   if (!existsSync(srcSkills)) {
     console.error(`\x1b[31m[Annotask]\x1b[0m Skills directory not found in package. Expected: ${srcSkills}`)
-    process.exit(1)
+    exit(1)
   }
 
   const skillNames = readdirSync(srcSkills).filter(name =>
@@ -512,7 +622,7 @@ function initSkills() {
 
   if (skillNames.length === 0) {
     console.error(`\x1b[31m[Annotask]\x1b[0m No skills found in ${srcSkills}`)
-    process.exit(1)
+    exit(1)
   }
 
   // Resolve target paths — known names map to dotfile dirs, anything else is used as-is
@@ -593,6 +703,7 @@ function initSkills() {
   if (secondaries.length > 0) {
     console.log(`\n  Files in \x1b[36m${KNOWN_TARGETS[primary.name] || primary.name}\x1b[0m, symlinked from ${secondaries.map(t => `\x1b[36m${KNOWN_TARGETS[t.name] || t.name}\x1b[0m`).join(', ')}`)
   }
+  console.log(`\n  \x1b[2mAnnotask's built-in agent runs init and apply in the shell UI — these skills are for external editor agents.\x1b[0m`)
 }
 
 function isSymlink(p: string): boolean {
@@ -628,7 +739,7 @@ function initMcp() {
 
   if (transportArg !== 'stdio' && transportArg !== 'http') {
     console.error(`\x1b[31m[Annotask]\x1b[0m Unknown --transport=${transportArg}. Valid: stdio, http`)
-    process.exit(1)
+    exit(1)
   }
 
   /**
@@ -645,7 +756,7 @@ function initMcp() {
   const unknown = targetKeys.filter(k => !MCP_EDITORS[k])
   if (unknown.length > 0) {
     console.error(`\x1b[31m[Annotask]\x1b[0m Unknown editor(s): ${unknown.join(', ')}. Valid: ${Object.keys(MCP_EDITORS).join(', ')}, all`)
-    process.exit(1)
+    exit(1)
   }
 
   let written = 0
@@ -760,8 +871,7 @@ async function listComponents() {
       }
     }
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch components: ${err.message}`)
-    process.exit(1)
+    fail(errCode(err), `Failed to fetch components: ${err.message}`)
   }
 }
 
@@ -770,8 +880,7 @@ async function listComponents() {
 async function showComponent() {
   const name = args[1]
   if (!name) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask component <ComponentName>`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask component <ComponentName>')
   }
 
   const jsonFlag = args.includes('--json') || mcpFlag
@@ -792,12 +901,12 @@ async function showComponent() {
     }
 
     if (matches.length === 0) {
-      if (mcpFlag) {
-        console.error(fmt({ error: `Component not found: ${name}${libraryArg ? ` (library: ${libraryArg})` : ''}` }))
-      } else {
-        console.error(`${color('31', '[Annotask]')} Component "${name}" not found. Use ${color('33', 'annotask components')} to list available components.`)
-      }
-      process.exit(1)
+      // Under --mcp this now goes through fail() so the envelope is the
+      // structured { error: { code, message } } shape on stdout — previously
+      // a bare { error } string landed on stderr and broke skill parsing.
+      fail('not_found', mcpFlag
+        ? `Component not found: ${name}${libraryArg ? ` (library: ${libraryArg})` : ''}`
+        : `Component "${name}" not found. Use ${color('33', 'annotask components')} to list available components.`)
     }
 
     if (matches.length > 1 && !libraryArg) {
@@ -810,7 +919,7 @@ async function showComponent() {
       if (jsonFlag) { console.log(JSON.stringify(ambiguous, null, 2)); return }
       console.error(`${color('31', '[Annotask]')} ${ambiguous.message}`)
       for (const c of ambiguous.candidates) console.error(`  ${c.library}: ${c.module}`)
-      process.exit(1)
+      exit(1)
     }
 
     const { library: libName, version, component: found } = matches[0]
@@ -838,8 +947,8 @@ async function showComponent() {
       }
     }
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch component: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to fetch component: ${err.message}`)
   }
 }
 
@@ -848,23 +957,122 @@ async function showComponent() {
 async function fetchCodeContext() {
   const taskId = args[1]
   if (!taskId) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask code-context <task-id> [--context-lines=N]`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask code-context <task-id> [--context-lines=N]')
   }
   const ctxLinesArg = args.find(a => a.startsWith('--context-lines='))?.split('=')[1]
   const qs = ctxLinesArg ? `?context_lines=${encodeURIComponent(ctxLinesArg)}` : ''
   try {
     const res = await fetch(`${apiUrl}/code-context/${encodeURIComponent(taskId)}${qs}`)
-    if (res.status === 404) {
-      console.error(`${color('31', '[Annotask]')} Task not found: ${taskId}`)
-      process.exit(1)
-    }
+    if (res.status === 404) fail('not_found', `Task not found: ${taskId}`)
     if (!res.ok) throw new Error(`HTTP ${res.status}`)
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch code context: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to fetch code context: ${err.message}`)
+  }
+}
+
+// ── Source excerpt: ground an arbitrary file/line ───────
+// File-keyed sibling of code-context — for locations beyond a task's own
+// file/line (wireframe_apply anchors, arrow to_element targets, …).
+
+async function fetchSourceExcerpt() {
+  const fileArg = args.find(a => a.startsWith('--file='))?.split('=')[1]
+  const lineArg = args.find(a => a.startsWith('--line='))?.split('=')[1]
+  if (!fileArg || !lineArg) {
+    fail('usage', 'Usage: annotask source-excerpt --file=PATH --line=N [--context-lines=N]')
+  }
+  const ctxLinesArg = args.find(a => a.startsWith('--context-lines='))?.split('=')[1]
+  const params = new URLSearchParams()
+  params.set('file', fileArg)
+  params.set('line', lineArg)
+  if (ctxLinesArg) params.set('context_lines', ctxLinesArg)
+  try {
+    const res = await fetch(`${apiUrl}/source-excerpt?${params.toString()}`)
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const data = await res.json()
+    console.log(fmt(data))
+  } catch (err: any) {
+    fail(errCode(err), `Failed to fetch source excerpt: ${err.message}`)
+  }
+}
+
+/** Round-trip-honesty classification of one element against current source —
+ *  same payload as the `annotask_get_binding_classification` MCP tool. */
+async function fetchBindingClassification() {
+  const fileArg = args.find(a => a.startsWith('--file='))?.split('=')[1]
+  const lineArg = args.find(a => a.startsWith('--line='))?.split('=')[1]
+  if (!fileArg || !lineArg) {
+    fail('usage', 'Usage: annotask binding-classify --file=PATH --line=N [--tag=NAME]')
+  }
+  const tagArg = args.find(a => a.startsWith('--tag='))?.split('=')[1]
+  const params = new URLSearchParams()
+  params.set('file', fileArg)
+  params.set('line', lineArg)
+  if (tagArg) params.set('tag', tagArg)
+  try {
+    const res = await fetch(`${apiUrl}/binding-classify?${params.toString()}`)
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const data = await res.json()
+    console.log(fmt(data))
+  } catch (err: any) {
+    fail(errCode(err), `Failed to classify bindings: ${err.message}`)
+  }
+}
+
+// ── Playbook: task-type companion apply instructions ────
+
+/**
+ * Served from the bundled skill files, no dev server needed — the same
+ * content the MCP annotask_get_playbook tool returns, so the CLI fallback
+ * gives agents identical material when the editor has no MCP registration.
+ */
+function fetchPlaybook() {
+  const taskType = args[1] && !args[1].startsWith('--') ? args[1] : ''
+  if (!taskType) {
+    fail('usage', `Usage: annotask playbook <task_type>  (one of: ${TASK_TYPES.join(', ')})`)
+  }
+  if (!(TASK_TYPES as readonly string[]).includes(taskType)) {
+    fail('invalid_argument', `Unknown task type: ${taskType}. Valid: ${TASK_TYPES.join(', ')}`)
+  }
+  const companion = TASK_TYPE_COMPANIONS[taskType]
+  if (!companion) {
+    const message = `No companion playbook for "${taskType}" — the base annotask-apply instructions cover this type.`
+    if (mcpFlag) { console.log(fmt({ task_type: taskType, message })); return }
+    console.log(`${color('33', '[Annotask]')} ${message}`)
+    return
+  }
+  let content: string | undefined
+  try {
+    content = loadSkill('annotask-apply').files[companion]
+  } catch (err: any) {
+    fail('skill_load_failed', `Could not load skill files: ${err.message}`)
+  }
+  if (!content) fail('not_found', `Playbook file missing from the installed package: ${companion}`)
+  if (mcpFlag) { console.log(fmt({ task_type: taskType, file: companion, content })); return }
+  console.log(content)
+}
+
+// ── Agent directions: per-persona project directions ────
+
+async function fetchAgentDirections() {
+  const personaId = args[1] && !args[1].startsWith('--') ? args[1] : ''
+  try {
+    const res = await fetch(`${apiUrl}/agent-configs`)
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const data = await res.json() as { version?: unknown; agents?: Record<string, Record<string, unknown>> }
+    if (personaId) {
+      const entry = data.agents?.[personaId]
+      // Match annotask_get_agent_directions: an unconfigured persona is not
+      // an error — agents just get empty directions plus a flag.
+      if (!entry) { console.log(fmt({ persona_id: personaId, projectDirections: '', not_configured: true })); return }
+      console.log(fmt({ persona_id: personaId, ...entry }))
+      return
+    }
+    console.log(fmt(data))
+  } catch (err: any) {
+    fail(errCode(err), `Failed to fetch agent directions: ${err.message}`)
   }
 }
 
@@ -873,8 +1081,7 @@ async function fetchCodeContext() {
 async function fetchComponentExamples() {
   const name = args[1]
   if (!name) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask component-examples <ComponentName> [--limit=N] [--library=NAME]`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask component-examples <ComponentName> [--limit=N] [--library=NAME]')
   }
   const limitArg = args.find(a => a.startsWith('--limit='))?.split('=')[1]
   const libraryArg = args.find(a => a.startsWith('--library='))?.split('=')[1]
@@ -888,8 +1095,7 @@ async function fetchComponentExamples() {
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch component examples: ${err.message}`)
-    process.exit(1)
+    fail(errCode(err), `Failed to fetch component examples: ${err.message}`)
   }
 }
 
@@ -898,8 +1104,7 @@ async function fetchComponentExamples() {
 async function fetchDataContext() {
   const taskId = args[1]
   if (!taskId) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask data-context <task-id> [--refresh]`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask data-context <task-id> [--refresh]')
   }
   const refresh = args.includes('--refresh')
   try {
@@ -909,28 +1114,22 @@ async function fetchDataContext() {
     let res: Response
     if (refresh) {
       const tasksRes = await fetch(`${apiUrl}/tasks/${encodeURIComponent(taskId)}`)
-      if (tasksRes.status === 404) {
-        console.error(`${color('31', '[Annotask]')} Task not found: ${taskId}`)
-        process.exit(1)
-      }
+      if (tasksRes.status === 404) fail('not_found', `Task not found: ${taskId}`)
       const task = await tasksRes.json() as Record<string, unknown>
       const file = typeof task.file === 'string' ? task.file : ''
       const line = typeof task.line === 'number' ? task.line : 0
-      if (!file) { console.error(`${color('31', '[Annotask]')} Task has no file reference`); process.exit(1) }
+      if (!file) fail('no_file_reference', 'Task has no file reference')
       res = await fetch(`${apiUrl}/data-context/resolve?file=${encodeURIComponent(file)}&line=${line}`)
     } else {
       res = await fetch(`${apiUrl}/data-context/${encodeURIComponent(taskId)}`)
-      if (res.status === 404) {
-        console.error(`${color('31', '[Annotask]')} Task not found: ${taskId}`)
-        process.exit(1)
-      }
+      if (res.status === 404) fail('not_found', `Task not found: ${taskId}`)
     }
     if (!res.ok) throw new Error(`HTTP ${res.status}`)
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch data context: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to fetch data context: ${err.message}`)
   }
 }
 
@@ -939,21 +1138,17 @@ async function fetchDataContext() {
 async function fetchInteractionHistory() {
   const taskId = args[1]
   if (!taskId) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask interaction-history <task-id>`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask interaction-history <task-id>')
   }
   try {
     const res = await fetch(`${apiUrl}/tasks/${encodeURIComponent(taskId)}/interaction-history`)
-    if (res.status === 404) {
-      console.error(`${color('31', '[Annotask]')} Task not found: ${taskId}`)
-      process.exit(1)
-    }
+    if (res.status === 404) fail('not_found', `Task not found: ${taskId}`)
     if (!res.ok) throw new Error(`HTTP ${res.status}`)
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch interaction history: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to fetch interaction history: ${err.message}`)
   }
 }
 
@@ -962,21 +1157,17 @@ async function fetchInteractionHistory() {
 async function fetchRenderedHtml() {
   const taskId = args[1]
   if (!taskId) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask rendered-html <task-id>`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask rendered-html <task-id>')
   }
   try {
     const res = await fetch(`${apiUrl}/tasks/${encodeURIComponent(taskId)}/rendered-html`)
-    if (res.status === 404) {
-      console.error(`${color('31', '[Annotask]')} Task not found: ${taskId}`)
-      process.exit(1)
-    }
+    if (res.status === 404) fail('not_found', `Task not found: ${taskId}`)
     if (!res.ok) throw new Error(`HTTP ${res.status}`)
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch rendered HTML: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to fetch rendered HTML: ${err.message}`)
   }
 }
 
@@ -999,8 +1190,7 @@ async function fetchDataSources() {
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch data sources: ${err.message}`)
-    process.exit(1)
+    fail(errCode(err), `Failed to fetch data sources: ${err.message}`)
   }
 }
 
@@ -1039,8 +1229,7 @@ async function fetchRuntimeEndpoints() {
     }
     console.log(fmt({ ...data, endpoints }))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch runtime endpoints: ${err.message}`)
-    process.exit(1)
+    fail(errCode(err), `Failed to fetch runtime endpoints: ${err.message}`)
   }
 }
 
@@ -1049,8 +1238,7 @@ async function fetchRuntimeEndpoints() {
 async function fetchDataSourceExamples() {
   const name = args[1]
   if (!name) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask data-source-examples <name> [--kind=composable|signal|store|fetch|graphql|loader|rpc] [--limit=N]`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask data-source-examples <name> [--kind=composable|signal|store|fetch|graphql|loader|rpc] [--limit=N]')
   }
   const kind = args.find(a => a.startsWith('--kind='))?.split('=')[1]
   const limit = args.find(a => a.startsWith('--limit='))?.split('=')[1]
@@ -1064,8 +1252,7 @@ async function fetchDataSourceExamples() {
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch data source examples: ${err.message}`)
-    process.exit(1)
+    fail(errCode(err), `Failed to fetch data source examples: ${err.message}`)
   }
 }
 
@@ -1074,8 +1261,7 @@ async function fetchDataSourceExamples() {
 async function fetchDataSourceDetails() {
   const name = args[1]
   if (!name) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask data-source-details <name> [--kind=K] [--file=PATH] [--context-lines=N]`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask data-source-details <name> [--kind=K] [--file=PATH] [--context-lines=N]')
   }
   const kind = args.find(a => a.startsWith('--kind='))?.split('=')[1]
   const file = args.find(a => a.startsWith('--file='))?.split('=')[1]
@@ -1091,8 +1277,7 @@ async function fetchDataSourceDetails() {
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch data source details: ${err.message}`)
-    process.exit(1)
+    fail(errCode(err), `Failed to fetch data source details: ${err.message}`)
   }
 }
 
@@ -1111,16 +1296,14 @@ async function fetchApiSchemas() {
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch api schemas: ${err.message}`)
-    process.exit(1)
+    fail(errCode(err), `Failed to fetch api schemas: ${err.message}`)
   }
 }
 
 async function fetchApiOperation() {
   const opPath = args[1]
   if (!opPath) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask api-operation <path> [--method=GET] [--schema-location=PATH]`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask api-operation <path> [--method=GET] [--schema-location=PATH]')
   }
   const method = args.find(a => a.startsWith('--method='))?.split('=')[1]
   const schemaLocation = args.find(a => a.startsWith('--schema-location='))?.split('=').slice(1).join('=')
@@ -1130,24 +1313,20 @@ async function fetchApiOperation() {
   if (schemaLocation) params.set('schema_location', schemaLocation)
   try {
     const res = await fetch(`${apiUrl}/api-operation?${params.toString()}`)
-    if (res.status === 404) {
-      console.error(`${color('31', '[Annotask]')} Operation not found: ${opPath}`)
-      process.exit(1)
-    }
+    if (res.status === 404) fail('not_found', `Operation not found: ${opPath}`)
     if (!res.ok) throw new Error(`HTTP ${res.status}`)
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to fetch api operation: ${err.message}`)
-    process.exit(1)
+    if (err instanceof CliExit) throw err
+    fail(errCode(err), `Failed to fetch api operation: ${err.message}`)
   }
 }
 
 async function resolveEndpointCmd() {
   const url = args[1]
   if (!url) {
-    console.error(`${color('31', '[Annotask]')} Usage: annotask resolve-endpoint <url> [--method=GET]`)
-    process.exit(1)
+    fail('usage', 'Usage: annotask resolve-endpoint <url> [--method=GET]')
   }
   const method = args.find(a => a.startsWith('--method='))?.split('=')[1]
   const params = new URLSearchParams()
@@ -1159,8 +1338,7 @@ async function resolveEndpointCmd() {
     const data = await res.json()
     console.log(fmt(data))
   } catch (err: any) {
-    console.error(`${color('31', '[Annotask]')} Failed to resolve endpoint: ${err.message}`)
-    process.exit(1)
+    fail(errCode(err), `Failed to resolve endpoint: ${err.message}`)
   }
 }
 
@@ -1297,6 +1475,14 @@ function printHelp() {
   update-task     Update a task's status / resolution / feedback
   screenshot      Download a task's screenshot
   code-context    Resolve a task to grounded source context (excerpt, symbol, imports, hash)
+  source-excerpt  Ground an arbitrary --file/--line to current source (same payload as
+                  code-context, but not task-keyed — for multi-file anchors)
+  binding-classify  Round-trip-honesty classification of one element (--file/--line[/--tag]):
+                  per-prop literal|bound|unknown, text kind, enclosing loop
+  playbook        Print the task-type companion playbook (a11y_fix, theme_update,
+                  error_fix, perf_fix, wireframe_apply). Reads bundled skill files;
+                  no dev server needed.
+  agent-directions  Fetch per-persona project directions (all personas, or one by id)
   component-examples  Find in-repo usages of a component (snippet + import path)
   data-context    Resolve (or return stored) data_context for a task (hooks/stores/fetch refs)
   interaction-history  Fetch the user's pre-task navigation + action trace for a task
@@ -1310,8 +1496,13 @@ function printHelp() {
   runtime-endpoints List endpoints the iframe has actually hit at runtime (fetch/XHR/beacon).
                     Aggregated per (origin, method, path pattern). Supplements the regex
                     scanner by capturing dynamic endpoints the static pass misses.
-  init-skills     Install AI agent skills to your project
-  init-mcp        Write editor MCP config (Claude Code / Cursor / VS Code / Windsurf)
+  init-skills     Install AI agent skills for an external editor agent
+                  (Claude Code / Cursor / VS Code / Windsurf). Skip this when
+                  using Annotask's built-in agent — the shell handles init
+                  in the UI and runs apply through local-CLI providers.
+  init-mcp        Write editor MCP config (Claude Code / Cursor / VS Code / Windsurf).
+                  Same audience as init-skills — only needed when an editor
+                  agent should reach Annotask's tool surface.
   mcp             Start MCP server (stdio transport, proxies to dev server)
   help            Show this help
 
@@ -1325,7 +1516,8 @@ function printHelp() {
   --mfe=NAME        Filter tasks by MFE identity (overrides server.json mfe)
   --mcp             Emit MCP-parity output: compact JSON, no ANSI, matches the
                     annotask_* tool shapes. Use in agent skills so responses
-                    are identical whether reached via MCP or the CLI.
+                    are identical whether reached via MCP or the CLI. Failures
+                    print {"error":{"code","message"}} to stdout and exit 1.
   --pretty          Pretty-print JSON output (ignored under --mcp)
   --detail          tasks: return full task objects instead of summaries
   --status=STATUS   tasks: filter by status (pending, review, denied, ...)
@@ -1335,9 +1527,11 @@ function printHelp() {
   --library=NAME    components / component: restrict to one library
   --limit=N         components / component-examples / data-source-examples: max results (default 50 / 3 / 3)
   --offset=N        components: skip the first N results (pagination)
-  --context-lines=N code-context: lines of context around task.line (default 15, max 200)
+  --context-lines=N code-context / source-excerpt: lines of context (default 15, max 200)
                     data-source-details: lines around the definition (default 15, max 40)
-  --file=PATH       data-source-details: disambiguate by file when multiple definitions share a name
+  --file=PATH       source-excerpt: project-relative file to excerpt (required)
+                    data-source-details: disambiguate by file when multiple definitions share a name
+  --line=N          source-excerpt: 1-based line to center the excerpt on (required)
   --refresh         data-context: force a fresh scan even if the task has stored data_context
   --used-only       data-sources: restrict project entries to used_count > 0
   --kind=K          data-sources / data-source-examples: filter by composable|signal|store|fetch|graphql|loader|rpc
@@ -1371,6 +1565,9 @@ function printHelp() {
   annotask components --mcp Button        # Compact JSON, filtered by name
   annotask component Button --mcp         # Full component JSON
   annotask update-task TASK_ID --status=in_progress --mcp
+  annotask source-excerpt --file=src/App.vue --line=42 --mcp
+  annotask playbook wireframe_apply --mcp # Companion playbook as JSON
+  annotask agent-directions designer --mcp
   annotask status --mcp                   # Compact JSON status
   annotask watch                          # Watch live changes (human)
   annotask init-skills                    # Install AI agent skills
diff --git a/src/embedded/__tests__/cli-local-provider.test.ts b/src/embedded/__tests__/cli-local-provider.test.ts
new file mode 100644
index 0000000..6b499ac
--- /dev/null
+++ b/src/embedded/__tests__/cli-local-provider.test.ts
@@ -0,0 +1,335 @@
+import { describe, it, expect } from 'vitest'
+import { mapClaudeEvent } from '../claude-local-provider.js'
+import { mapCodexEvent } from '../codex-local-provider.js'
+import { mapOpencodeEvent } from '../opencode-local-provider.js'
+import { mapCopilotEvent } from '../copilot-local-provider.js'
+import { ClaudeLocalProvider } from '../claude-local-provider.js'
+import type { ProviderEvent } from '../provider.js'
+
+describe('mapClaudeEvent', () => {
+  it('emits text events for assistant message content blocks', () => {
+    const out = mapClaudeEvent({
+      type: 'assistant',
+      message: { content: [{ type: 'text', text: 'hello world' }] },
+    })
+    expect(out).toEqual([{ type: 'text', text: 'hello world' }])
+  })
+
+  it('emits tool_call for assistant tool_use blocks', () => {
+    const out = mapClaudeEvent({
+      type: 'assistant',
+      message: {
+        content: [
+          { type: 'text', text: 'Let me read it.' },
+          { type: 'tool_use', id: 'toolu_01', name: 'Read', input: { file_path: 'App.vue' } },
+        ],
+      },
+    })
+    expect(out).toEqual([
+      { type: 'text', text: 'Let me read it.' },
+      { type: 'tool_call', id: 'toolu_01', name: 'Read', input: { file_path: 'App.vue' } },
+    ])
+  })
+
+  it('emits tool_result from synthetic user messages', () => {
+    const out = mapClaudeEvent({
+      type: 'user',
+      message: {
+        role: 'user',
+        content: [
+          { type: 'tool_result', tool_use_id: 'toolu_01', content: 'export default …', is_error: false },
+        ],
+      },
+    })
+    expect(out).toEqual([
+      { type: 'tool_result', toolUseId: 'toolu_01', content: 'export default …', isError: undefined },
+    ])
+  })
+
+  it('flattens block-array tool_result content into a single string', () => {
+    const out = mapClaudeEvent({
+      type: 'user',
+      message: {
+        content: [
+          {
+            type: 'tool_result',
+            tool_use_id: 'toolu_02',
+            content: [
+              { type: 'text', text: 'line one' },
+              { type: 'text', text: 'line two' },
+            ] as unknown as string, // wider field shape; runtime accepts arrays
+          },
+        ],
+      },
+    })
+    expect(out[0]).toMatchObject({ type: 'tool_result', toolUseId: 'toolu_02', content: 'line one\nline two' })
+  })
+
+  it('marks tool_result.isError true when is_error=true', () => {
+    const out = mapClaudeEvent({
+      type: 'user',
+      message: { content: [{ type: 'tool_result', tool_use_id: 't', content: 'oops', is_error: true }] },
+    })
+    expect(out[0]).toMatchObject({ type: 'tool_result', isError: true })
+  })
+
+  it('emits usage with cache buckets when present', () => {
+    const out = mapClaudeEvent({
+      type: 'assistant',
+      message: {
+        content: [],
+        usage: {
+          input_tokens: 100,
+          output_tokens: 50,
+          cache_read_input_tokens: 20,
+          cache_creation_input_tokens: 5,
+        },
+      },
+    })
+    expect(out).toContainEqual({
+      type: 'usage',
+      inputTokens: 100,
+      outputTokens: 50,
+      cacheReadTokens: 20,
+      cacheCreationTokens: 5,
+    })
+  })
+
+  it('ignores unrecognised event types', () => {
+    expect(mapClaudeEvent({ type: 'system' })).toEqual([])
+    expect(mapClaudeEvent({ type: 'unknown_future_type' })).toEqual([])
+  })
+})
+
+describe('mapCodexEvent', () => {
+  it('emits text for completed assistant_message items', () => {
+    const out = mapCodexEvent({
+      type: 'item.completed',
+      item: { item_type: 'assistant_message', text: 'codex says hi' },
+    })
+    expect(out).toEqual([{ type: 'text', text: 'codex says hi' }])
+  })
+
+  it('emits tool_call for function_call items with JSON arguments', () => {
+    const out = mapCodexEvent({
+      type: 'item.completed',
+      item: {
+        item_type: 'function_call',
+        id: 'call_42',
+        name: 'apply_patch',
+        arguments: '{"path":"src/App.vue"}',
+      },
+    })
+    expect(out).toEqual([
+      { type: 'tool_call', id: 'call_42', name: 'apply_patch', input: { path: 'src/App.vue' } },
+    ])
+  })
+
+  it('emits tool_result for function_call_output items', () => {
+    const out = mapCodexEvent({
+      type: 'item.completed',
+      item: { item_type: 'function_call_output', call_id: 'call_42', output: 'patched' },
+    })
+    expect(out).toEqual([
+      { type: 'tool_result', toolUseId: 'call_42', content: 'patched', isError: undefined },
+    ])
+  })
+
+  it('flags tool_result isError when exit_code is non-zero', () => {
+    const out = mapCodexEvent({
+      type: 'item.completed',
+      item: { item_type: 'function_call_output', call_id: 'c1', output: 'fail', exit_code: 1 },
+    })
+    expect(out[0]).toMatchObject({ type: 'tool_result', isError: true })
+  })
+
+  it('emits a Bash tool_call + tool_result pair for command_execution', () => {
+    const out = mapCodexEvent({
+      type: 'item.completed',
+      item: { item_type: 'command_execution', id: 'cmd_1', command: 'npm test', output: 'OK', exit_code: 0 },
+    })
+    expect(out).toEqual([
+      { type: 'tool_call', id: 'cmd_1', name: 'Bash', input: { command: 'npm test' } },
+      { type: 'tool_result', toolUseId: 'cmd_1', content: 'OK', isError: undefined },
+    ])
+  })
+
+  it('emits usage on turn.completed', () => {
+    const out = mapCodexEvent({
+      type: 'turn.completed',
+      usage: { input_tokens: 7, output_tokens: 11, cached_input_tokens: 3 },
+    })
+    expect(out).toEqual([{ type: 'usage', inputTokens: 7, outputTokens: 11, cacheReadTokens: 3 }])
+  })
+
+  it('ignores unrecognised item types', () => {
+    const out = mapCodexEvent({ type: 'item.completed', item: { item_type: 'weird_future_item' } })
+    expect(out).toEqual([])
+  })
+})
+
+describe('mapOpencodeEvent', () => {
+  it('accepts {type:"text", text}', () => {
+    expect(mapOpencodeEvent({ type: 'text', text: 'hi' })).toEqual([{ type: 'text', text: 'hi' }])
+  })
+
+  it('accepts string content', () => {
+    expect(mapOpencodeEvent({ type: 'message', content: 'hi' })).toEqual([{ type: 'text', text: 'hi' }])
+  })
+
+  it('emits tool_call + tool_result from content blocks', () => {
+    expect(mapOpencodeEvent({
+      type: 'message',
+      content: [
+        { type: 'text', text: 'a' },
+        { type: 'tool_use', id: 'u1', name: 'Read', input: { file_path: 'x' } },
+        { type: 'text', text: 'b' },
+        { type: 'tool_result', tool_use_id: 'u1', content: 'contents', is_error: false },
+      ],
+    })).toEqual([
+      { type: 'text', text: 'a' },
+      { type: 'tool_call', id: 'u1', name: 'Read', input: { file_path: 'x' } },
+      { type: 'text', text: 'b' },
+      { type: 'tool_result', toolUseId: 'u1', content: 'contents', isError: undefined },
+    ])
+  })
+
+  it('emits top-level tool_call / tool_result envelopes', () => {
+    expect(mapOpencodeEvent({ type: 'tool_call', id: 'a', name: 'Bash', input: { command: 'ls' } }))
+      .toEqual([{ type: 'tool_call', id: 'a', name: 'Bash', input: { command: 'ls' } }])
+    expect(mapOpencodeEvent({ type: 'tool_result', call_id: 'a', output: 'README.md' }))
+      .toEqual([{ type: 'tool_result', toolUseId: 'a', content: 'README.md', isError: undefined }])
+  })
+
+  it('reads text from the v1.14+ part envelope', () => {
+    expect(mapOpencodeEvent({
+      type: 'text',
+      part: { type: 'text', text: 'ok' },
+    })).toEqual([{ type: 'text', text: 'ok' }])
+  })
+
+  it('emits usage from a v1.14+ step_finish event', () => {
+    expect(mapOpencodeEvent({
+      type: 'step_finish',
+      part: {
+        type: 'step-finish',
+        tokens: { input: 1583, output: 7, cache: { read: 9728, write: 0 } },
+      },
+    })).toEqual([{
+      type: 'usage',
+      inputTokens: 1583,
+      outputTokens: 7,
+      cacheReadTokens: 9728,
+      cacheCreationTokens: 0,
+    }])
+  })
+})
+
+describe('mapCopilotEvent', () => {
+  it('emits text from a message_delta event', () => {
+    expect(mapCopilotEvent({
+      type: 'assistant.message_delta',
+      data: { messageId: 'm1', deltaContent: 'ok' },
+    })).toEqual([{ type: 'text', text: 'ok' }])
+  })
+
+  it('emits a tool_call from toolRequests on assistant.message', () => {
+    const out = mapCopilotEvent({
+      type: 'assistant.message',
+      data: {
+        messageId: 'm1',
+        content: '',
+        outputTokens: 4,
+        toolRequests: [{ id: 't1', name: 'Bash', arguments: '{"command":"ls"}' }],
+      },
+    })
+    expect(out).toEqual([
+      { type: 'tool_call', id: 't1', name: 'Bash', input: { command: 'ls' } },
+      { type: 'usage', inputTokens: 0, outputTokens: 4 },
+    ])
+  })
+
+  it('ignores noise events (session.*, user.message, …) silently', () => {
+    expect(mapCopilotEvent({ type: 'session.skills_loaded' })).toEqual([])
+    expect(mapCopilotEvent({ type: 'user.message', data: { content: 'hi' } })).toEqual([])
+    expect(mapCopilotEvent({ type: 'assistant.reasoning', data: {} })).toEqual([])
+  })
+})
+
+describe('ClaudeLocalProvider end-to-end via fake fetch', () => {
+  it('streams text + usage + done from a fixture SSE stream', async () => {
+    const sse = [
+      'event: stdout',
+      `data: ${JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: 'Hello' }] } })}`,
+      '',
+      'event: stdout',
+      `data: ${JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: ' world' }] } })}`,
+      '',
+      'event: stdout',
+      `data: ${JSON.stringify({
+        type: 'result',
+        usage: { input_tokens: 10, output_tokens: 2 },
+      })}`,
+      '',
+      'event: exit',
+      'data: {"code":0,"signal":null}',
+      '',
+      '',
+    ].join('\n')
+
+    const fakeResponse = new Response(new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new TextEncoder().encode(sse))
+        controller.close()
+      },
+    }), { status: 200, headers: { 'Content-Type': 'text/event-stream' } })
+
+    const fakeFetch: typeof fetch = async () => fakeResponse
+    const provider = new ClaudeLocalProvider({ fetchImpl: fakeFetch })
+
+    const events: ProviderEvent[] = []
+    for await (const ev of provider.stream(
+      [{ role: 'user', content: 'hi' }],
+      [],
+      { systemPrompt: '' },
+    )) {
+      events.push(ev)
+    }
+
+    // Text deltas in order, usage, done.
+    const texts = events.filter((e): e is { type: 'text'; text: string } => e.type === 'text').map((e) => e.text)
+    expect(texts.join('')).toBe('Hello world')
+    expect(events.some((e) => e.type === 'usage' && e.inputTokens === 10 && e.outputTokens === 2)).toBe(true)
+    expect(events[events.length - 1]).toMatchObject({ type: 'done' })
+  })
+
+  it('maps a 409 task_already_running to a benign done:already_running (never an error)', async () => {
+    // Another tab owns the live run. The losing run must NOT emit an error —
+    // an error reverts the task to pending and yanks the winner's run.
+    const body = JSON.stringify({ error: { code: 'task_already_running', message: 'Task task-1 is already running in another tab or session.' } })
+    const fakeFetch: typeof fetch = async () =>
+      new Response(body, { status: 409, headers: { 'Content-Type': 'application/json' } })
+    const provider = new ClaudeLocalProvider({ fetchImpl: fakeFetch })
+
+    const events: ProviderEvent[] = []
+    for await (const ev of provider.stream([{ role: 'user', content: 'hi' }], [], { systemPrompt: '', taskId: 'task-1' })) {
+      events.push(ev)
+    }
+
+    expect(events.some((e) => e.type === 'error')).toBe(false)
+    expect(events).toEqual([{ type: 'done', stopReason: 'already_running' }])
+  })
+
+  it('still maps other non-ok spawn responses to an error + done', async () => {
+    const fakeFetch: typeof fetch = async () =>
+      new Response('boom', { status: 500, headers: { 'Content-Type': 'text/plain' } })
+    const provider = new ClaudeLocalProvider({ fetchImpl: fakeFetch })
+
+    const events: ProviderEvent[] = []
+    for await (const ev of provider.stream([{ role: 'user', content: 'hi' }], [], { systemPrompt: '' })) {
+      events.push(ev)
+    }
+    expect(events.some((e) => e.type === 'error')).toBe(true)
+    expect(events[events.length - 1]).toMatchObject({ type: 'done', stopReason: 'error' })
+  })
+})
diff --git a/src/embedded/__tests__/cli-providers-live.test.ts b/src/embedded/__tests__/cli-providers-live.test.ts
new file mode 100644
index 0000000..8976319
--- /dev/null
+++ b/src/embedded/__tests__/cli-providers-live.test.ts
@@ -0,0 +1,182 @@
+/**
+ * Live provider streaming smoke pipeline.
+ *
+ * Connects to each CLI-backed provider for real (and Copilot via HTTP) and
+ * verifies that text deltas plus a terminal `done` event come back through
+ * the provider's stream(). Catches the failure mode the mocked tests can't:
+ * a CLI that spawns fine but doesn't stream, or whose JSON shape has drifted
+ * since the fixtures were written.
+ *
+ * Skipped by default. Enable with `ANNOTASK_LIVE_CLI=1`:
+ *
+ *   ANNOTASK_LIVE_CLI=1 pnpm test:live-providers
+ *
+ * Per-provider model overrides (see MODEL_CONFIG defaults below):
+ *   ANNOTASK_LIVE_CLAUDE_MODEL
+ *   ANNOTASK_LIVE_OPENCODE_MODEL
+ *   ANNOTASK_LIVE_CODEX_MODEL
+ *   ANNOTASK_LIVE_COPILOT_MODEL
+ *
+ * Filter which providers run (CSV, optional):
+ *   ANNOTASK_LIVE_ONLY=claude,opencode
+ */
+
+import * as http from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+
+import { ClaudeLocalProvider } from '../claude-local-provider.js'
+import { CodexLocalProvider } from '../codex-local-provider.js'
+import { OpencodeLocalProvider } from '../opencode-local-provider.js'
+import { CopilotLocalProvider } from '../copilot-local-provider.js'
+import type { LLMProvider, ProviderEvent } from '../provider.js'
+
+import { createAgentSpawnHandler } from '../../server/agent-spawn.js'
+import { createAgentDetector } from '../../server/agent-detect.js'
+import {
+  LIVE_CLI_ENABLED,
+  isLiveCliEnabled,
+  liveModelFor,
+  type LiveProviderKey,
+} from './live-cli-helpers.js'
+
+type ProviderKey = LiveProviderKey
+
+const isEnabled = isLiveCliEnabled
+const modelFor = liveModelFor
+
+const describeIf = LIVE_CLI_ENABLED ? describe : describe.skip
+
+describeIf('Live provider streaming smoke', () => {
+  let server: http.Server
+  let spawnUrl: string
+
+  beforeAll(async () => {
+    const handler = createAgentSpawnHandler()
+    server = http.createServer(async (req, res) => {
+      if (req.url !== '/__annotask/api/agent/spawn' || req.method !== 'POST') {
+        res.statusCode = 404
+        res.end()
+        return
+      }
+      const chunks: Buffer[] = []
+      for await (const c of req) chunks.push(c as Buffer)
+      let parsed: unknown
+      try { parsed = JSON.parse(Buffer.concat(chunks).toString('utf-8')) }
+      catch { res.statusCode = 400; res.end('bad json'); return }
+      await handler.handleSpawn(req, res, parsed, process.cwd())
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as AddressInfo
+    spawnUrl = `http://127.0.0.1:${port}/__annotask/api/agent/spawn`
+  })
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()))
+  })
+
+  const detector = createAgentDetector()
+
+  async function probe(key: ProviderKey): Promise<{ runnable: boolean; reason?: string }> {
+    const snap = await detector.detect()
+    const s = snap[key]
+    if (!s.found) return { runnable: false, reason: `${key} CLI not on PATH` }
+    if (!s.loggedIn) return { runnable: false, reason: `${key} CLI is installed but not logged in` }
+    return { runnable: true }
+  }
+
+  function buildProvider(key: ProviderKey, model: string): LLMProvider {
+    switch (key) {
+      case 'claude-local':   return new ClaudeLocalProvider({ model, spawnUrl })
+      case 'opencode-local': return new OpencodeLocalProvider({ model, spawnUrl })
+      case 'codex-local':    return new CodexLocalProvider({ model, spawnUrl })
+      case 'copilot-local':  return new CopilotLocalProvider({ model, spawnUrl })
+    }
+  }
+
+  async function runStreamingSmoke(key: ProviderKey): Promise<void> {
+    const probed = await probe(key)
+    if (!probed.runnable) {
+      console.warn(`[live] ${key} skipped: ${probed.reason}`)
+      return
+    }
+
+    const model = modelFor(key)
+    const provider = buildProvider(key, model)
+    const started = Date.now()
+    let firstTextAt: number | null = null
+    const textParts: string[] = []
+    let usageIn = 0
+    let usageOut = 0
+    let stopReason: string | undefined
+    let errorString: string | null = null
+    let sawDone = false
+
+    const iterable = provider.stream(
+      [{ role: 'user', content: 'Reply with only the single word ok.' }],
+      [],
+      {
+        systemPrompt: 'You are a terse echo bot. Reply with one word.',
+        // CopilotProvider reads model from StreamOptions; CLI providers
+        // ignore it and use their constructor-supplied model. Setting it
+        // for both is harmless.
+        model,
+      },
+    )
+
+    for await (const ev of iterable as AsyncIterable<ProviderEvent>) {
+      if (ev.type === 'text') {
+        if (firstTextAt === null) firstTextAt = Date.now()
+        textParts.push(ev.text)
+      } else if (ev.type === 'usage') {
+        usageIn += ev.inputTokens
+        usageOut += ev.outputTokens
+      } else if (ev.type === 'done') {
+        sawDone = true
+        stopReason = ev.stopReason
+      } else if (ev.type === 'error') {
+        errorString = ev.error
+      }
+    }
+
+    const elapsed = Date.now() - started
+    const firstTextMs = firstTextAt !== null ? firstTextAt - started : null
+    const joined = textParts.join('').trim()
+    console.log(
+      `[live] ${key} model=${model} first-text=${firstTextMs ?? 'n/a'}ms ` +
+      `total=${elapsed}ms tokens=${usageIn}/${usageOut} done=${stopReason ?? '?'} ` +
+      `text=${JSON.stringify(joined.slice(0, 80))}`,
+    )
+
+    if (errorString) {
+      throw new Error(`[${key}] provider emitted error: ${errorString}`)
+    }
+    expect(sawDone, `${key}: stream never emitted 'done'`).toBe(true)
+    expect(textParts.length, `${key}: stream emitted no 'text' events`).toBeGreaterThan(0)
+    expect(joined.length, `${key}: combined text was empty`).toBeGreaterThan(0)
+  }
+
+  it.runIf(isEnabled('claude-local'))(
+    'claude-local streams a reply',
+    () => runStreamingSmoke('claude-local'),
+    120_000,
+  )
+
+  it.runIf(isEnabled('opencode-local'))(
+    'opencode-local streams a reply',
+    () => runStreamingSmoke('opencode-local'),
+    120_000,
+  )
+
+  it.runIf(isEnabled('codex-local'))(
+    'codex-local streams a reply',
+    () => runStreamingSmoke('codex-local'),
+    120_000,
+  )
+
+  it.runIf(isEnabled('copilot-local'))(
+    'copilot-local streams a reply',
+    () => runStreamingSmoke('copilot-local'),
+    120_000,
+  )
+})
diff --git a/src/embedded/__tests__/copilot-provider.test.ts b/src/embedded/__tests__/copilot-provider.test.ts
deleted file mode 100644
index 6b49a03..0000000
--- a/src/embedded/__tests__/copilot-provider.test.ts
+++ /dev/null
@@ -1,147 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import * as fs from 'node:fs/promises'
-import * as os from 'node:os'
-import * as path from 'node:path'
-import {
-  CopilotProvider,
-  readOAuthToken,
-  type CopilotSessionToken,
-} from '../copilot-provider'
-
-function sseResponse(frames: string[]): Response {
-  return new Response(frames.map(f => `data: ${f}\n\n`).join(''), {
-    status: 200,
-    headers: { 'Content-Type': 'text/event-stream' },
-  })
-}
-
-describe('readOAuthToken', () => {
-  let tmpDir: string
-
-  beforeEach(async () => {
-    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'copilot-token-'))
-  })
-  afterEach(async () => {
-    await fs.rm(tmpDir, { recursive: true, force: true })
-  })
-
-  it('reads oauth_token from apps.json when present', async () => {
-    await fs.writeFile(
-      path.join(tmpDir, 'apps.json'),
-      JSON.stringify({ 'github.com:Iv1.b507': { oauth_token: 'ghu_apps' } }),
-    )
-    expect(await readOAuthToken(tmpDir)).toBe('ghu_apps')
-  })
-
-  it('falls back to hosts.json when apps.json is absent', async () => {
-    await fs.writeFile(
-      path.join(tmpDir, 'hosts.json'),
-      JSON.stringify({ 'github.com': { oauth_token: 'ghu_hosts' } }),
-    )
-    expect(await readOAuthToken(tmpDir)).toBe('ghu_hosts')
-  })
-
-  it('throws a directive error when neither file exists', async () => {
-    await expect(readOAuthToken(tmpDir)).rejects.toThrow(/No GitHub Copilot OAuth token/)
-  })
-})
-
-describe('CopilotProvider session token cache', () => {
-  it('reuses the session token across calls and refreshes only when it nears expiry', async () => {
-    const fixed = 1_700_000_000_000
-    vi.useFakeTimers()
-    vi.setSystemTime(fixed)
-
-    const issued: string[] = []
-    let nextExpiresIn = 300 // 5 minutes
-    const resolver = vi.fn(async (): Promise<CopilotSessionToken> => {
-      const token = `copilot-token-${issued.length + 1}`
-      issued.push(token)
-      return {
-        token,
-        expiresAt: Math.floor(Date.now() / 1000) + nextExpiresIn,
-        chatEndpoint: 'https://copilot.example/chat/completions',
-      }
-    })
-
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockImplementation(async () =>
-      sseResponse([
-        JSON.stringify({ choices: [{ index: 0, delta: { content: 'ok' } }] }),
-        JSON.stringify({ choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] }),
-        JSON.stringify({ usage: { prompt_tokens: 1, completion_tokens: 1 } }),
-        '[DONE]',
-      ]),
-    )
-
-    const provider = new CopilotProvider({ sessionTokenResolver: resolver })
-
-    async function drainTurn() {
-      const out = []
-      for await (const ev of provider.stream(
-        [{ role: 'user', content: 'hi' }],
-        [],
-        { systemPrompt: 'sys' },
-      )) out.push(ev)
-      return out
-    }
-
-    await drainTurn()
-    await drainTurn()
-    // Two turns, one issued token — cache hit on the second call.
-    expect(resolver).toHaveBeenCalledTimes(1)
-
-    // Jump past the near-expiry slack window and call again — the next
-    // request must trigger a refresh.
-    nextExpiresIn = 600
-    vi.setSystemTime(fixed + 5 * 60 * 1000) // +5min, inside slack window
-    await drainTurn()
-    expect(resolver).toHaveBeenCalledTimes(2)
-    expect(issued).toEqual(['copilot-token-1', 'copilot-token-2'])
-
-    fetchSpy.mockRestore()
-    vi.useRealTimers()
-  })
-
-  it('runs a full streaming turn through the default transport when a resolver is supplied', async () => {
-    const fixed = 1_700_000_000_000
-    vi.useFakeTimers()
-    vi.setSystemTime(fixed)
-    const resolver = vi.fn(async (): Promise<CopilotSessionToken> => ({
-      token: 'copilot-token-A',
-      expiresAt: Math.floor(fixed / 1000) + 300,
-      chatEndpoint: 'https://copilot.example/chat/completions',
-    }))
-
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
-      sseResponse([
-        JSON.stringify({ choices: [{ index: 0, delta: { content: 'ok' } }] }),
-        JSON.stringify({ choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] }),
-        JSON.stringify({ usage: { prompt_tokens: 1, completion_tokens: 1 } }),
-        '[DONE]',
-      ]),
-    )
-
-    const provider = new CopilotProvider({ sessionTokenResolver: resolver })
-    const events = []
-    for await (const ev of provider.stream(
-      [{ role: 'user', content: 'hi' }],
-      [],
-      { systemPrompt: 'sys' },
-    )) events.push(ev)
-    expect(resolver).toHaveBeenCalledTimes(1)
-    expect(fetchSpy).toHaveBeenCalledTimes(1)
-    const [calledUrl, init] = fetchSpy.mock.calls[0] as [string, RequestInit]
-    expect(calledUrl).toBe('https://copilot.example/chat/completions')
-    const headers = init.headers as Record<string, string>
-    expect(headers.Authorization).toBe('Bearer copilot-token-A')
-    expect(headers['Editor-Version']).toBeDefined()
-    expect(headers['Copilot-Integration-Id']).toBe('vscode-chat')
-    // Copilot strips stream_options.
-    const sent = JSON.parse(init.body as string)
-    expect(sent.stream_options).toBeUndefined()
-    expect(events.at(-1)?.type).toBe('done')
-
-    fetchSpy.mockRestore()
-    vi.useRealTimers()
-  })
-})
diff --git a/src/embedded/__tests__/copilot-smoke.test.ts b/src/embedded/__tests__/copilot-smoke.test.ts
deleted file mode 100644
index f7bd691..0000000
--- a/src/embedded/__tests__/copilot-smoke.test.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-/**
- * Copilot end-to-end smoke test.
- *
- * Hits the real GitHub session-token endpoint and the real Copilot chat
- * endpoint. Catches GitHub-side contract drift (auth flow changes, response
- * shape changes, model name renames) so we find out before users do.
- *
- * Skipped by default. Enable with `ANNOTASK_COPILOT_SMOKE=1` once the local
- * machine has Copilot signed in (the smoke test reads
- * `~/.config/github-copilot/apps.json` like the provider does in production).
- *
- *   ANNOTASK_COPILOT_SMOKE=1 pnpm vitest run src/embedded/__tests__/copilot-smoke.test.ts
- */
-
-import { describe, it, expect } from 'vitest'
-import {
-  CopilotProvider,
-  exchangeOAuthForSessionToken,
-  readOAuthToken,
-} from '../copilot-provider'
-
-const ENABLED = process.env.ANNOTASK_COPILOT_SMOKE === '1'
-const describeIf = ENABLED ? describe : describe.skip
-
-describeIf('Copilot smoke (real GitHub endpoints)', () => {
-  it('exchanges an OAuth token for a Copilot session token', async () => {
-    const oauth = await readOAuthToken()
-    const session = await exchangeOAuthForSessionToken(oauth)
-    expect(session.token).toMatch(/.+/)
-    expect(session.expiresAt).toBeGreaterThan(Math.floor(Date.now() / 1000))
-  }, 30_000)
-
-  it('streams a trivial completion through the chat endpoint', async () => {
-    const provider = new CopilotProvider({})
-    const out: string[] = []
-    let sawDone = false
-    let sawUsage = false
-    for await (const ev of provider.stream(
-      [{ role: 'user', content: 'Reply with the single word "pong". No punctuation.' }],
-      [],
-      { systemPrompt: 'You are a terse echo bot.', model: 'gpt-4o-mini' },
-    )) {
-      if (ev.type === 'text') out.push(ev.text)
-      if (ev.type === 'usage') sawUsage = true
-      if (ev.type === 'done') sawDone = true
-      if (ev.type === 'error') throw new Error(`Provider error: ${ev.error}`)
-    }
-    const joined = out.join('').trim().toLowerCase()
-    expect(joined).toContain('pong')
-    expect(sawDone).toBe(true)
-    // Copilot usage reporting is occasionally absent; assert presence but
-    // don't fail the smoke if GitHub omitted it.
-    if (!sawUsage) console.warn('[smoke] Copilot did not return a usage chunk; check contract.')
-  }, 60_000)
-})
diff --git a/src/embedded/__tests__/event-log.test.ts b/src/embedded/__tests__/event-log.test.ts
new file mode 100644
index 0000000..5911ba6
--- /dev/null
+++ b/src/embedded/__tests__/event-log.test.ts
@@ -0,0 +1,247 @@
+import { describe, it, expect, vi } from 'vitest'
+import { EventLog, type PersistenceSink } from '../event-log.js'
+
+function memorySink(): PersistenceSink & { store: Map<string, string> } {
+  const store = new Map<string, string>()
+  return {
+    store,
+    getItem: (k) => store.get(k) ?? null,
+    setItem: (k, v) => {
+      store.set(k, v)
+    },
+    removeItem: (k) => {
+      store.delete(k)
+    },
+  }
+}
+
+describe('EventLog', () => {
+  it('appends rows with monotonic ids and an injected clock', () => {
+    let t = 100
+    const log = new EventLog({ now: () => t++ })
+    const a = log.append({
+      kind: 'turn',
+      conversationId: 'c1',
+      provider: 'anthropic',
+      model: 'claude-sonnet-4-5',
+      inputTokens: 100,
+      outputTokens: 50,
+      latencyMs: 200,
+    })
+    const b = log.append({
+      kind: 'turn',
+      conversationId: 'c1',
+      provider: 'anthropic',
+      model: 'claude-sonnet-4-5',
+      inputTokens: 100,
+      outputTokens: 50,
+      latencyMs: 200,
+    })
+    expect(a.id).toBe(1)
+    expect(b.id).toBe(2)
+    expect(a.ts).toBe(100)
+    expect(b.ts).toBe(101)
+    expect(log.list()).toHaveLength(2)
+  })
+
+  it('appendToolCall captures top-level keys but not values', () => {
+    const log = new EventLog()
+    const row = log.appendToolCall({
+      conversationId: 'c1',
+      provider: 'anthropic',
+      model: 'claude-sonnet-4-5',
+      toolName: 'edit_file',
+      toolUseId: 'tu_1',
+      input: { path: '/secrets/x', text: 'sk-ant-…' },
+    })
+    expect(row.inputKeys.sort()).toEqual(['path', 'text'])
+    // No values stored anywhere on the row.
+    expect(JSON.stringify(row)).not.toContain('/secrets/x')
+    expect(JSON.stringify(row)).not.toContain('sk-ant-')
+  })
+
+  it('aggregates per-conversation token totals', () => {
+    const log = new EventLog()
+    log.append({
+      kind: 'turn',
+      conversationId: 'c1',
+      provider: 'anthropic',
+      model: 'm',
+      inputTokens: 100,
+      outputTokens: 50,
+      cacheReadTokens: 10,
+      cacheCreationTokens: 5,
+      latencyMs: 200,
+    })
+    log.append({
+      kind: 'turn',
+      conversationId: 'c1',
+      provider: 'anthropic',
+      model: 'm',
+      inputTokens: 40,
+      outputTokens: 30,
+      latencyMs: 200,
+    })
+    log.append({
+      kind: 'turn',
+      conversationId: 'c2',
+      provider: 'anthropic',
+      model: 'm',
+      inputTokens: 999,
+      outputTokens: 999,
+      latencyMs: 200,
+    })
+    const t = log.totalsByConversation('c1')
+    expect(t.inputTokens).toBe(140)
+    expect(t.outputTokens).toBe(80)
+    expect(t.cacheReadTokens).toBe(10)
+    expect(t.cacheCreationTokens).toBe(5)
+    expect(t.turns).toBe(2)
+  })
+
+  it('evicts oldest rows when capacity is exceeded', () => {
+    const log = new EventLog({ capacity: 3 })
+    for (let i = 0; i < 5; i++) {
+      log.append({
+        kind: 'turn',
+        conversationId: 'c',
+        provider: 'p',
+        model: 'm',
+        inputTokens: i,
+        outputTokens: 0,
+        latencyMs: 1,
+      })
+    }
+    const rows = log.list()
+    expect(rows).toHaveLength(3)
+    // The two oldest rows (ids 1 and 2) were evicted; we kept 3, 4, 5.
+    expect(rows.map((r) => r.id)).toEqual([3, 4, 5])
+  })
+
+  it('notifies subscribers on append and clear', () => {
+    const log = new EventLog()
+    const seen: number[] = []
+    const unsubscribe = log.subscribe((rows) => seen.push(rows.length))
+    log.append({
+      kind: 'turn',
+      conversationId: 'c',
+      provider: 'p',
+      model: 'm',
+      inputTokens: 1,
+      outputTokens: 1,
+      latencyMs: 1,
+    })
+    log.append({
+      kind: 'tool_result',
+      conversationId: 'c',
+      toolUseId: 'tu_1',
+      toolName: 'edit',
+      isError: false,
+      latencyMs: 5,
+    })
+    log.clear()
+    unsubscribe()
+    log.append({
+      kind: 'turn',
+      conversationId: 'c',
+      provider: 'p',
+      model: 'm',
+      inputTokens: 1,
+      outputTokens: 1,
+      latencyMs: 1,
+    })
+    expect(seen).toEqual([1, 2, 0])
+  })
+
+  it('persists to an injected sink and rehydrates on construction', () => {
+    const sink = memorySink()
+    const a = new EventLog({ persistence: sink })
+    a.append({
+      kind: 'turn',
+      conversationId: 'c1',
+      provider: 'anthropic',
+      model: 'm',
+      inputTokens: 100,
+      outputTokens: 50,
+      latencyMs: 200,
+    })
+    const b = new EventLog({ persistence: sink })
+    expect(b.list()).toHaveLength(1)
+    // Continue numbering from where we left off so reloads don't reset ids.
+    const next = b.append({
+      kind: 'turn',
+      conversationId: 'c1',
+      provider: 'anthropic',
+      model: 'm',
+      inputTokens: 100,
+      outputTokens: 50,
+      latencyMs: 200,
+    })
+    expect(next.id).toBeGreaterThan(1)
+  })
+
+  it('survives corrupt persisted state by clearing it', () => {
+    const sink = memorySink()
+    sink.store.set('annotask:ai:eventLog', '{not valid json')
+    const log = new EventLog({ persistence: sink })
+    expect(log.list()).toEqual([])
+    expect(sink.store.has('annotask:ai:eventLog')).toBe(false)
+  })
+
+  it('does NOT touch the network — listener-free fetch surface', () => {
+    // Sanity check that the module does not reach for `fetch`. We spy on
+    // the global; any call would fail this test.
+    const spy = vi.spyOn(globalThis, 'fetch').mockImplementation(() => {
+      throw new Error('EventLog touched the network')
+    })
+    try {
+      const log = new EventLog()
+      log.append({
+        kind: 'turn',
+        conversationId: 'c',
+        provider: 'p',
+        model: 'm',
+        inputTokens: 1,
+        outputTokens: 1,
+        latencyMs: 1,
+      })
+      log.append({
+        kind: 'error',
+        conversationId: 'c',
+        provider: 'p',
+        model: 'm',
+        reason: 'rate_limit',
+      })
+      log.clear()
+      expect(spy).not.toHaveBeenCalled()
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('filter returns matching rows', () => {
+    const log = new EventLog()
+    log.append({
+      kind: 'turn',
+      conversationId: 'c',
+      provider: 'p',
+      model: 'm',
+      inputTokens: 1,
+      outputTokens: 1,
+      latencyMs: 1,
+    })
+    log.append({
+      kind: 'error',
+      conversationId: 'c',
+      provider: 'p',
+      model: 'm',
+      reason: 'rate_limit',
+    })
+    expect(log.filter((r) => r.kind === 'error')).toHaveLength(1)
+  })
+
+  it('rejects capacity <= 0', () => {
+    expect(() => new EventLog({ capacity: 0 })).toThrow()
+    expect(() => new EventLog({ capacity: -10 })).toThrow()
+  })
+})
diff --git a/src/embedded/__tests__/live-cli-helpers.ts b/src/embedded/__tests__/live-cli-helpers.ts
new file mode 100644
index 0000000..2876c0e
--- /dev/null
+++ b/src/embedded/__tests__/live-cli-helpers.ts
@@ -0,0 +1,51 @@
+/**
+ * Shared env-flag contract for live-CLI test suites.
+ *
+ * Two suites consume this:
+ *   - `cli-providers-live.test.ts` (chat streaming smoke)
+ *   - `../../server/__tests__/init-cli-matrix-stress.test.ts` (init pipeline)
+ *
+ * Env vars:
+ *   ANNOTASK_LIVE_CLI=1        — enable the suite at all
+ *   ANNOTASK_LIVE_ONLY=csv     — optional filter, short or long names
+ *   ANNOTASK_LIVE_<CLI>_MODEL  — per-CLI model override (see MODEL_CONFIG)
+ *
+ * The defaults below match what the live chat suite shipped with — keep
+ * them in sync with the four embedded providers if you change them.
+ */
+
+export type LiveProviderKey =
+  | 'claude-local'
+  | 'opencode-local'
+  | 'codex-local'
+  | 'copilot-local'
+
+interface ModelEntry {
+  default: string
+  env: string
+}
+
+export const MODEL_CONFIG: Record<LiveProviderKey, ModelEntry> = {
+  'claude-local':   { default: 'claude-sonnet-4-6',      env: 'ANNOTASK_LIVE_CLAUDE_MODEL' },
+  'opencode-local': { default: 'github-copilot/gpt-5.4', env: 'ANNOTASK_LIVE_OPENCODE_MODEL' },
+  'codex-local':    { default: 'gpt-5.4',                env: 'ANNOTASK_LIVE_CODEX_MODEL' },
+  'copilot-local':  { default: 'gpt-5.3-codex',          env: 'ANNOTASK_LIVE_COPILOT_MODEL' },
+}
+
+export const LIVE_CLI_ENABLED = process.env.ANNOTASK_LIVE_CLI === '1'
+
+export const LIVE_CLI_ONLY = (process.env.ANNOTASK_LIVE_ONLY ?? '')
+  .split(',')
+  .map((s) => s.trim().toLowerCase())
+  .filter((s) => s.length > 0)
+
+export function isLiveCliEnabled(key: LiveProviderKey): boolean {
+  if (LIVE_CLI_ONLY.length === 0) return true
+  const short = key.replace(/-local$/, '')
+  return LIVE_CLI_ONLY.includes(short) || LIVE_CLI_ONLY.includes(key)
+}
+
+export function liveModelFor(key: LiveProviderKey): string {
+  const entry = MODEL_CONFIG[key]
+  return (process.env[entry.env] ?? '').trim() || entry.default
+}
diff --git a/src/embedded/__tests__/local-provider-history.test.ts b/src/embedded/__tests__/local-provider-history.test.ts
new file mode 100644
index 0000000..d266111
--- /dev/null
+++ b/src/embedded/__tests__/local-provider-history.test.ts
@@ -0,0 +1,211 @@
+/**
+ * Multi-turn history rollup for the one-shot positional-prompt CLIs.
+ *
+ * codex/opencode/copilot spawn a fresh subprocess per chat turn, so the only
+ * conversation memory they get is what `rollupHistoryAsPrompt` packs into the
+ * positional prompt. These tests pin:
+ *   - the rollup shape (prior turns in order, system prompt exactly once,
+ *     current request last),
+ *   - the argv-size budget (oldest turns dropped first, marker left behind),
+ *   - that each provider's buildSpawn actually threads the rollup through
+ *     to the spawned argv (captured via a fake spawn transport, same pattern
+ *     as provider-permission-matrix.test.ts),
+ *   - that claude keeps its stdin path (full flattened history, no rollup
+ *     headings) untouched.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  rollupHistoryAsPrompt,
+  withSystemPrompt,
+  lastUserMessageText,
+  POSITIONAL_PROMPT_MAX_CHARS,
+  HISTORY_TRUNCATED_MARKER,
+  type CliLocalProvider,
+  type SpawnRequest,
+} from '../cli-local-provider.js'
+import { ClaudeLocalProvider } from '../claude-local-provider.js'
+import { CodexLocalProvider } from '../codex-local-provider.js'
+import { OpencodeLocalProvider } from '../opencode-local-provider.js'
+import { CopilotLocalProvider } from '../copilot-local-provider.js'
+import type { ProviderMessage } from '../provider.js'
+
+const SYSTEM = 'SYSPROMPT_SENTINEL: be terse.'
+
+/** 3-turn conversation: one full prior exchange + the live follow-up. */
+const THREE_TURNS: ProviderMessage[] = [
+  { role: 'user', content: 'make the button red' },
+  { role: 'assistant', content: '[Tool] Editing Button.vue\nDone — the button is now red.' },
+  { role: 'user', content: 'actually make it blue instead' },
+]
+
+// ── Fake spawn transport: capture the POSTed SpawnRequest, return a trivial SSE ──
+function makeCapturingFetch(): { fetchImpl: typeof fetch; captured: () => SpawnRequest } {
+  let captured: SpawnRequest = { cli: 'claude', args: [] }
+  const fetchImpl = (async (_url: string, init?: RequestInit) => {
+    captured = JSON.parse(String(init?.body ?? '{}')) as SpawnRequest
+    const sse = ['event: exit', 'data: {"code":0,"signal":null}', '', ''].join('\n')
+    return new Response(
+      new ReadableStream<Uint8Array>({
+        start(c) { c.enqueue(new TextEncoder().encode(sse)); c.close() },
+      }),
+      { status: 200, headers: { 'Content-Type': 'text/event-stream' } },
+    )
+  }) as unknown as typeof fetch
+  return { fetchImpl, captured: () => captured }
+}
+
+async function captureSpawn(provider: CliLocalProvider, capture: () => SpawnRequest, messages: ProviderMessage[]): Promise<SpawnRequest> {
+  for await (const _ of provider.stream(messages, [], { systemPrompt: SYSTEM })) { /* drain */ }
+  return capture()
+}
+
+/** Assert the rolled-up prompt carries both prior turns + the live request, in order. */
+function expectFullHistoryInOrder(prompt: string): void {
+  const iUser1 = prompt.indexOf('User: make the button red')
+  const iAssistant = prompt.indexOf('Assistant: [Tool] Editing Button.vue')
+  const iCurrent = prompt.indexOf('actually make it blue instead')
+  expect(iUser1).toBeGreaterThan(-1)
+  expect(iAssistant).toBeGreaterThan(iUser1)
+  expect(iCurrent).toBeGreaterThan(iAssistant)
+  // System prompt present exactly once, ahead of the transcript.
+  expect(prompt.split('SYSPROMPT_SENTINEL').length - 1).toBe(1)
+  expect(prompt.indexOf(SYSTEM)).toBeLessThan(iUser1)
+}
+
+describe('rollupHistoryAsPrompt', () => {
+  it('keeps the exact single-shot shape on the first turn (no prior history)', () => {
+    const messages: ProviderMessage[] = [{ role: 'user', content: 'apply task t-1' }]
+    expect(rollupHistoryAsPrompt(messages, SYSTEM))
+      .toBe(withSystemPrompt(lastUserMessageText(messages), SYSTEM))
+  })
+
+  it('rolls up prior turns as a delimited transcript before the current request', () => {
+    const prompt = rollupHistoryAsPrompt(THREE_TURNS, SYSTEM)
+    expectFullHistoryInOrder(prompt)
+    expect(prompt).toContain('## Conversation so far')
+    expect(prompt).toContain('## Current request')
+    // The live request comes after the transcript section.
+    expect(prompt.indexOf('## Current request')).toBeGreaterThan(prompt.indexOf('## Conversation so far'))
+    expect(prompt).not.toContain(HISTORY_TRUNCATED_MARKER)
+  })
+
+  it('reads text out of content-block messages too', () => {
+    const messages: ProviderMessage[] = [
+      { role: 'user', content: [{ type: 'text', text: 'first ' }, { type: 'text', text: 'question' }] },
+      { role: 'assistant', content: [{ type: 'text', text: 'first answer' }] },
+      { role: 'user', content: 'second question' },
+    ]
+    const prompt = rollupHistoryAsPrompt(messages, SYSTEM)
+    expect(prompt).toContain('User: first question')
+    expect(prompt).toContain('Assistant: first answer')
+    expect(prompt).toContain('second question')
+  })
+
+  it('drops OLDEST turns first when the history exceeds the budget, leaving a marker', () => {
+    const messages: ProviderMessage[] = [
+      { role: 'user', content: `OLDEST_TURN ${'x'.repeat(200_000)}` },
+      { role: 'assistant', content: 'RECENT_REPLY still fits' },
+      { role: 'user', content: 'CURRENT_REQUEST' },
+    ]
+    const prompt = rollupHistoryAsPrompt(messages, SYSTEM)
+    expect(prompt.length).toBeLessThanOrEqual(POSITIONAL_PROMPT_MAX_CHARS)
+    expect(prompt).not.toContain('OLDEST_TURN')
+    expect(prompt).toContain(HISTORY_TRUNCATED_MARKER)
+    // The marker sits where the dropped turns were — before what survived.
+    expect(prompt.indexOf(HISTORY_TRUNCATED_MARKER)).toBeLessThan(prompt.indexOf('RECENT_REPLY'))
+    expect(prompt).toContain('RECENT_REPLY still fits')
+    expect(prompt).toContain('CURRENT_REQUEST')
+  })
+
+  it('stops keeping turns at the first one that does not fit (no out-of-order gaps)', () => {
+    // Newest-first walk: turn C fits, oversized turn B does not — so A (older
+    // than B) must be dropped too even though it would fit on its own.
+    const messages: ProviderMessage[] = [
+      { role: 'user', content: 'TURN_A tiny' },
+      { role: 'assistant', content: `TURN_B ${'y'.repeat(200_000)}` },
+      { role: 'user', content: 'TURN_C also tiny' },
+      { role: 'user', content: 'CURRENT' },
+    ]
+    const prompt = rollupHistoryAsPrompt(messages, SYSTEM)
+    expect(prompt).toContain('TURN_C also tiny')
+    expect(prompt).not.toContain('TURN_B')
+    expect(prompt).not.toContain('TURN_A')
+    expect(prompt).toContain(HISTORY_TRUNCATED_MARKER)
+  })
+
+  it('never truncates the current request, even when it alone exceeds the budget', () => {
+    const huge = `HUGE_SEED ${'z'.repeat(150_000)}`
+    const messages: ProviderMessage[] = [
+      { role: 'user', content: 'small prior turn' },
+      { role: 'assistant', content: 'small reply' },
+      { role: 'user', content: huge },
+    ]
+    const prompt = rollupHistoryAsPrompt(messages, SYSTEM)
+    expect(prompt).toContain(huge)
+    // All history gets dropped to make room; the marker says so.
+    expect(prompt).not.toContain('small prior turn')
+    expect(prompt).toContain(HISTORY_TRUNCATED_MARKER)
+  })
+})
+
+describe('positional-prompt providers thread the rollup into argv', () => {
+  // Codex/opencode pass the prompt as the positional after `--`; copilot
+  // passes it as the value of `-p`.
+  const cases: Array<{ name: string; make(fetchImpl: typeof fetch): CliLocalProvider; promptOf(req: SpawnRequest): string }> = [
+    {
+      name: 'codex',
+      make: (fetchImpl) => new CodexLocalProvider({ fetchImpl }),
+      promptOf: (req) => req.args[req.args.indexOf('--') + 1] ?? '',
+    },
+    {
+      name: 'opencode',
+      make: (fetchImpl) => new OpencodeLocalProvider({ fetchImpl }),
+      promptOf: (req) => req.args[req.args.indexOf('--') + 1] ?? '',
+    },
+    {
+      name: 'copilot',
+      make: (fetchImpl) => new CopilotLocalProvider({ fetchImpl }),
+      promptOf: (req) => req.args[req.args.indexOf('-p') + 1] ?? '',
+    },
+  ]
+
+  for (const c of cases) {
+    it(`${c.name}: a 3-turn conversation reaches the CLI with full history in order`, async () => {
+      const { fetchImpl, captured } = makeCapturingFetch()
+      const req = await captureSpawn(c.make(fetchImpl), captured, THREE_TURNS)
+      const prompt = c.promptOf(req)
+      expectFullHistoryInOrder(prompt)
+      expect(prompt).toContain('## Conversation so far')
+    })
+
+    it(`${c.name}: an oversized history is truncated to the argv budget`, async () => {
+      const { fetchImpl, captured } = makeCapturingFetch()
+      const messages: ProviderMessage[] = [
+        { role: 'user', content: `OLDEST_TURN ${'x'.repeat(200_000)}` },
+        { role: 'assistant', content: 'recent reply' },
+        { role: 'user', content: 'current request' },
+      ]
+      const req = await captureSpawn(c.make(fetchImpl), captured, messages)
+      const prompt = c.promptOf(req)
+      expect(prompt.length).toBeLessThanOrEqual(POSITIONAL_PROMPT_MAX_CHARS)
+      expect(prompt).not.toContain('OLDEST_TURN')
+      expect(prompt).toContain(HISTORY_TRUNCATED_MARKER)
+      expect(prompt).toContain('current request')
+    })
+  }
+})
+
+describe('claude keeps its stdin path', () => {
+  it('full flattened history rides on stdin, not the rollup headings', async () => {
+    const { fetchImpl, captured } = makeCapturingFetch()
+    const req = await captureSpawn(new ClaudeLocalProvider({ fetchImpl }), captured, THREE_TURNS)
+    expect(req.stdin).toBeDefined()
+    const stdin = req.stdin ?? ''
+    // Flatten shape: every turn prefixed, no transcript headings.
+    expect(stdin).toContain('User: make the button red')
+    expect(stdin).toContain('User: actually make it blue instead')
+    expect(stdin).not.toContain('## Conversation so far')
+    // No positional prompt in argv.
+    expect(req.args).not.toContain('--')
+  })
+})
diff --git a/src/embedded/__tests__/permission-mode-flags.test.ts b/src/embedded/__tests__/permission-mode-flags.test.ts
new file mode 100644
index 0000000..bb30a2a
--- /dev/null
+++ b/src/embedded/__tests__/permission-mode-flags.test.ts
@@ -0,0 +1,199 @@
+/**
+ * Locks the security-critical permission-flag surface: every (cli, mode) pair
+ * maps to an exact argv, and each provider's buildSpawn actually threads the
+ * resolved flag into the POSTed `args`. This is the guardrail that makes the
+ * default-permission-mode change safe — a regression that silently grants
+ * write access in plan mode, or drops the flag entirely, fails here.
+ */
+import { describe, it, expect } from 'vitest'
+import {
+  claudePermissionFlags,
+  codexPermissionFlags,
+  opencodePermissionFlags,
+  copilotPermissionFlags,
+  initPermissionModeFor,
+  initPermissionFlagsFor,
+  permissionModeSystemPromptPrefix,
+  normalizeHeadlessMode,
+  defaultPermissionModeFor,
+  type InitCliBin,
+} from '../permission-mode-flags.js'
+import { ClaudeLocalProvider } from '../claude-local-provider.js'
+import { CodexLocalProvider } from '../codex-local-provider.js'
+import { OpencodeLocalProvider } from '../opencode-local-provider.js'
+import { CopilotLocalProvider } from '../copilot-local-provider.js'
+import type { CliLocalProvider } from '../cli-local-provider.js'
+import type { PermissionMode } from '../../schema.js'
+import type { StreamOptions } from '../provider.js'
+
+describe('permission flag mapping', () => {
+  it('claude maps default/plan/bypass to its native flags', () => {
+    expect(claudePermissionFlags('default')).toEqual(['--permission-mode', 'default'])
+    expect(claudePermissionFlags('plan')).toEqual(['--permission-mode', 'plan'])
+    expect(claudePermissionFlags('bypass')).toEqual(['--dangerously-skip-permissions'])
+  })
+
+  it('codex maps to sandbox flags (default=full-auto, plan=read-only, bypass removes sandbox)', () => {
+    expect(codexPermissionFlags('default')).toEqual(['--full-auto'])
+    expect(codexPermissionFlags('plan')).toEqual(['--sandbox', 'read-only'])
+    expect(codexPermissionFlags('bypass')).toEqual(['--dangerously-bypass-approvals-and-sandbox'])
+  })
+
+  it('opencode only exposes the bypass toggle; default/plan emit no flag', () => {
+    expect(opencodePermissionFlags('default')).toEqual([])
+    expect(opencodePermissionFlags('plan')).toEqual([])
+    expect(opencodePermissionFlags('bypass')).toEqual(['--dangerously-skip-permissions'])
+  })
+
+  it('copilot always keeps --allow-all-tools for -p; bypass adds --allow-all', () => {
+    expect(copilotPermissionFlags('default')).toEqual(['--allow-all-tools', '--no-ask-user'])
+    expect(copilotPermissionFlags('plan')).toEqual(['--allow-all-tools', '--no-ask-user'])
+    expect(copilotPermissionFlags('bypass')).toEqual(['--allow-all', '--allow-all-tools', '--no-ask-user'])
+  })
+})
+
+describe('normalizeHeadlessMode (the safe-by-default escalation)', () => {
+  it("escalates 'default' to 'bypass' only on claude/opencode (no headless ask-mode)", () => {
+    expect(normalizeHeadlessMode('default', 'claude')).toBe('bypass')
+    expect(normalizeHeadlessMode('default', 'opencode')).toBe('bypass')
+  })
+
+  it("leaves 'default' intact on codex/copilot (they honor it headlessly)", () => {
+    expect(normalizeHeadlessMode('default', 'codex')).toBe('default')
+    expect(normalizeHeadlessMode('default', 'copilot')).toBe('default')
+  })
+
+  it('never rewrites plan or bypass on any CLI', () => {
+    for (const bin of ['claude', 'codex', 'opencode', 'copilot'] as InitCliBin[]) {
+      expect(normalizeHeadlessMode('plan', bin)).toBe('plan')
+      expect(normalizeHeadlessMode('bypass', bin)).toBe('bypass')
+    }
+  })
+
+  it('defaultPermissionModeFor is normalizeHeadlessMode(default, bin)', () => {
+    for (const bin of ['claude', 'codex', 'opencode', 'copilot'] as InitCliBin[]) {
+      expect(defaultPermissionModeFor(bin)).toBe(normalizeHeadlessMode('default', bin))
+    }
+    // The safe per-CLI default: codex/copilot sandboxed/minimal, others bypass.
+    expect(defaultPermissionModeFor('codex')).toBe('default')
+    expect(defaultPermissionModeFor('copilot')).toBe('default')
+    expect(defaultPermissionModeFor('claude')).toBe('bypass')
+    expect(defaultPermissionModeFor('opencode')).toBe('bypass')
+  })
+})
+
+describe('init permission mode', () => {
+  it('returns the least-permissive headless-capable write mode per CLI', () => {
+    expect(initPermissionModeFor('claude')).toBe('bypass')
+    expect(initPermissionModeFor('opencode')).toBe('bypass')
+    expect(initPermissionModeFor('codex')).toBe('default')
+    expect(initPermissionModeFor('copilot')).toBe('default')
+  })
+
+  it('initPermissionFlagsFor matches the resolved per-CLI flags', () => {
+    expect(initPermissionFlagsFor('claude')).toEqual(['--dangerously-skip-permissions'])
+    expect(initPermissionFlagsFor('codex')).toEqual(['--full-auto'])
+    expect(initPermissionFlagsFor('opencode')).toEqual(['--dangerously-skip-permissions'])
+    expect(initPermissionFlagsFor('copilot')).toEqual(['--allow-all-tools', '--no-ask-user'])
+  })
+})
+
+describe('permissionModeSystemPromptPrefix', () => {
+  it('is empty for default and bypass', () => {
+    expect(permissionModeSystemPromptPrefix('default')).toBe('')
+    expect(permissionModeSystemPromptPrefix('bypass')).toBe('')
+  })
+
+  it('emits a strong read-only directive for plan', () => {
+    const prefix = permissionModeSystemPromptPrefix('plan')
+    expect(prefix).toContain('PLAN MODE')
+    expect(prefix).toContain('Do NOT call any tool that')
+    expect(prefix.length).toBeGreaterThan(0)
+  })
+})
+
+/**
+ * Spin a provider's stream once with a fake fetch that captures the POSTed
+ * spawn body, then returns a trivial SSE stream so the generator completes.
+ * Returns the `args` the provider asked the server to spawn.
+ */
+async function captureSpawnArgs(
+  provider: CliLocalProvider,
+  options: StreamOptions,
+): Promise<string[]> {
+  for await (const _ of provider.stream([{ role: 'user', content: 'hi' }], [], options)) {
+    // drain — the fake fetch already captured the body on the POST
+  }
+  return capturedArgs
+}
+
+let capturedArgs: string[] = []
+function fakeSpawnFetch(): typeof fetch {
+  return (async (_url: string, init?: RequestInit) => {
+    const body = JSON.parse(String(init?.body ?? '{}')) as { args?: string[] }
+    capturedArgs = body.args ?? []
+    const sse = ['event: exit', 'data: {"code":0,"signal":null}', '', ''].join('\n')
+    return new Response(
+      new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode(sse))
+          controller.close()
+        },
+      }),
+      { status: 200, headers: { 'Content-Type': 'text/event-stream' } },
+    )
+  }) as unknown as typeof fetch
+}
+
+describe('providers thread the permission flag into spawn args', () => {
+  const fetchImpl = fakeSpawnFetch()
+
+  it('claude threads plan and bypass flags', async () => {
+    const p = new ClaudeLocalProvider({ fetchImpl })
+    expect(await captureSpawnArgs(p, { systemPrompt: '', permissionMode: 'plan' }))
+      .toEqual(expect.arrayContaining(['--permission-mode', 'plan']))
+    expect(await captureSpawnArgs(p, { systemPrompt: '', permissionMode: 'bypass' }))
+      .toContain('--dangerously-skip-permissions')
+  })
+
+  it('codex threads sandbox flags', async () => {
+    const p = new CodexLocalProvider({ fetchImpl })
+    expect(await captureSpawnArgs(p, { systemPrompt: '', permissionMode: 'plan' }))
+      .toEqual(expect.arrayContaining(['--sandbox', 'read-only']))
+    expect(await captureSpawnArgs(p, { systemPrompt: '', permissionMode: 'default' }))
+      .toContain('--full-auto')
+  })
+
+  it('opencode threads the bypass toggle only', async () => {
+    const p = new OpencodeLocalProvider({ fetchImpl })
+    expect(await captureSpawnArgs(p, { systemPrompt: '', permissionMode: 'bypass' }))
+      .toContain('--dangerously-skip-permissions')
+    expect(await captureSpawnArgs(p, { systemPrompt: '', permissionMode: 'plan' }))
+      .not.toContain('--dangerously-skip-permissions')
+  })
+
+  it('copilot always threads --allow-all-tools; bypass adds --allow-all', async () => {
+    const p = new CopilotLocalProvider({ fetchImpl })
+    expect(await captureSpawnArgs(p, { systemPrompt: '', permissionMode: 'plan' }))
+      .toContain('--allow-all-tools')
+    expect(await captureSpawnArgs(p, { systemPrompt: '', permissionMode: 'bypass' }))
+      .toContain('--allow-all')
+  })
+})
+
+// Exhaustiveness guard: every PermissionMode is handled by every flag fn.
+describe('flag functions are total over PermissionMode', () => {
+  const modes: PermissionMode[] = ['default', 'plan', 'bypass']
+  const bins: InitCliBin[] = ['claude', 'codex', 'opencode', 'copilot']
+  it('never throws and always returns string[]', () => {
+    for (const m of modes) {
+      expect(Array.isArray(claudePermissionFlags(m))).toBe(true)
+      expect(Array.isArray(codexPermissionFlags(m))).toBe(true)
+      expect(Array.isArray(opencodePermissionFlags(m))).toBe(true)
+      expect(Array.isArray(copilotPermissionFlags(m))).toBe(true)
+    }
+    for (const b of bins) {
+      expect(Array.isArray(initPermissionFlagsFor(b))).toBe(true)
+    }
+  })
+})
diff --git a/src/embedded/__tests__/provider-config.test.ts b/src/embedded/__tests__/provider-config.test.ts
new file mode 100644
index 0000000..bd37b77
--- /dev/null
+++ b/src/embedded/__tests__/provider-config.test.ts
@@ -0,0 +1,282 @@
+import { describe, it, expect } from 'vitest'
+import {
+  DEFAULT_PROVIDER_SETTINGS,
+  parseProviderSettings,
+  validateProviderConfig,
+  isActiveProviderReady,
+  redactForLogging,
+  ProviderSettingsSchema,
+  type ProviderSettings,
+} from '../provider-config.js'
+
+function withActiveProvider(
+  patch: Partial<ProviderSettings['providers']>,
+  active: ProviderSettings['activeProvider'],
+): ProviderSettings {
+  return {
+    ...DEFAULT_PROVIDER_SETTINGS,
+    activeProvider: active,
+    providers: {
+      ...DEFAULT_PROVIDER_SETTINGS.providers,
+      ...patch,
+    },
+  }
+}
+
+describe('ProviderSettingsSchema defaults', () => {
+  it('produces a complete default settings blob', () => {
+    const d = DEFAULT_PROVIDER_SETTINGS
+    expect(d.activeProvider).toBe('claude-local')
+    // Auto is the default — hands-free, tasks fire on create.
+    expect(d.agentMode).toBe('auto')
+    expect(d.onboardingDismissed).toBe(false)
+    expect(d.redactionEnabled).toBe(true)
+    expect(d.eventLogEnabled).toBe(true)
+    expect(d.providers.anthropic.apiKey).toBe('')
+    // Empty model means "auto" — the provider picks.
+    expect(d.providers.anthropic.model).toBe('')
+    expect(d.providers.openai.model).toBe('')
+    expect(d.providers.paperclip.companyId).toBe('')
+    expect(d.providers.anthropic.effort).toBe('auto')
+    expect(d.providers['claude-local'].effort).toBe('auto')
+  })
+
+  it('rejects unknown agentMode values', () => {
+    const bad = ProviderSettingsSchema.safeParse({
+      ...DEFAULT_PROVIDER_SETTINGS,
+      agentMode: 'on' as unknown as 'auto',
+    })
+    expect(bad.success).toBe(false)
+  })
+
+  it('accepts each of the three agent modes', () => {
+    for (const m of ['auto', 'manual', 'off'] as const) {
+      const r = ProviderSettingsSchema.safeParse({ ...DEFAULT_PROVIDER_SETTINGS, agentMode: m })
+      expect(r.success).toBe(true)
+    }
+  })
+})
+
+describe('parseProviderSettings', () => {
+  it('parses a JSON string', () => {
+    const blob = JSON.stringify(DEFAULT_PROVIDER_SETTINGS)
+    const out = parseProviderSettings(blob)
+    expect(out.activeProvider).toBe('claude-local')
+  })
+
+  it('falls back to defaults on invalid JSON', () => {
+    const out = parseProviderSettings('{not valid')
+    expect(out).toEqual(DEFAULT_PROVIDER_SETTINGS)
+  })
+
+  it('falls back to defaults on unknown shape', () => {
+    const out = parseProviderSettings({ foo: 'bar' })
+    expect(out.activeProvider).toBe('claude-local')
+  })
+
+  it('returns defaults when input is null/undefined', () => {
+    expect(parseProviderSettings(null)).toEqual(DEFAULT_PROVIDER_SETTINGS)
+    expect(parseProviderSettings(undefined)).toEqual(DEFAULT_PROVIDER_SETTINGS)
+  })
+
+  it('round-trips a populated config', () => {
+    const populated: ProviderSettings = {
+      ...DEFAULT_PROVIDER_SETTINGS,
+      activeProvider: 'openai',
+      providers: {
+        ...DEFAULT_PROVIDER_SETTINGS.providers,
+        openai: {
+          id: 'openai',
+          apiKey: 'sk-test',
+          organization: 'org-abc',
+          model: 'gpt-5',
+          effort: 'high',
+        },
+      },
+    }
+    const round = parseProviderSettings(JSON.stringify(populated))
+    expect(round.activeProvider).toBe('openai')
+    expect(round.providers.openai.apiKey).toBe('sk-test')
+    expect(round.providers.openai.organization).toBe('org-abc')
+    expect(round.providers.openai.effort).toBe('high')
+  })
+})
+
+describe('validateProviderConfig', () => {
+  it('accepts an anthropic config with a non-empty key', () => {
+    const r = validateProviderConfig({
+      id: 'anthropic',
+      apiKey: 'sk-ant-abc',
+      model: 'claude-sonnet-4-5',
+      effort: 'auto',
+    })
+    expect(r.ok).toBe(true)
+  })
+
+  it('accepts an openai-compatible endpoint at http://localhost', () => {
+    const r = validateProviderConfig({
+      id: 'openai-compatible',
+      endpointUrl: 'http://localhost:4096/v1',
+      apiKey: '',
+      model: 'qwen2.5-coder',
+      effort: 'auto',
+      label: 'opencode local',
+    })
+    expect(r.ok).toBe(true)
+  })
+
+  it('rejects an openai-compatible endpoint with embedded credentials', () => {
+    const r = validateProviderConfig({
+      id: 'openai-compatible',
+      endpointUrl: 'http://user:pass@localhost:4096/v1',
+      apiKey: '',
+      model: 'qwen2.5-coder',
+      effort: 'auto',
+      label: '',
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.errors.join('\n')).toMatch(/credentials/)
+    }
+  })
+
+  it('rejects an openai-compatible endpoint with a non-http(s) scheme', () => {
+    const r = validateProviderConfig({
+      id: 'openai-compatible',
+      endpointUrl: 'ftp://example.com',
+      apiKey: '',
+      model: 'q',
+      effort: 'auto',
+      label: '',
+    })
+    expect(r.ok).toBe(false)
+  })
+
+  it('rejects an openai-compatible endpoint that is not a URL', () => {
+    const r = validateProviderConfig({
+      id: 'openai-compatible',
+      endpointUrl: 'localhost',
+      apiKey: '',
+      model: 'q',
+      effort: 'auto',
+      label: '',
+    })
+    expect(r.ok).toBe(false)
+  })
+
+  it('returns human-readable error messages with field paths', () => {
+    const r = validateProviderConfig({
+      id: 'openai-compatible',
+      endpointUrl: '',
+      apiKey: '',
+      model: '',
+      effort: 'auto',
+      label: '',
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      const text = r.errors.join('\n')
+      expect(text).toContain('endpointUrl')
+      expect(text).toContain('model')
+    }
+  })
+})
+
+describe('isActiveProviderReady', () => {
+  it('false on default (no credentials)', () => {
+    expect(isActiveProviderReady(DEFAULT_PROVIDER_SETTINGS)).toBe(false)
+  })
+
+  it('true when Anthropic has a key', () => {
+    const s = withActiveProvider(
+      {
+        anthropic: { id: 'anthropic', apiKey: 'sk-ant-abc', model: 'claude-sonnet-4-5', effort: 'auto' },
+      },
+      'anthropic',
+    )
+    expect(isActiveProviderReady(s)).toBe(true)
+  })
+
+  it('true when Paperclip has a company key', () => {
+    const s = withActiveProvider(
+      {
+        paperclip: {
+          id: 'paperclip',
+          companyId: 'c1',
+          apiKey: 'pcli_x',
+          apiBaseUrl: '',
+          model: 'paperclip-default',
+          effort: 'auto',
+        },
+      },
+      'paperclip',
+    )
+    expect(isActiveProviderReady(s)).toBe(true)
+  })
+
+  it('false for openai-compatible without endpoint url', () => {
+    const s = withActiveProvider(
+      {
+        'openai-compatible': {
+          id: 'openai-compatible',
+          endpointUrl: '',
+          apiKey: '',
+          model: 'q',
+          effort: 'auto',
+          label: '',
+        },
+      },
+      'openai-compatible',
+    )
+    expect(isActiveProviderReady(s)).toBe(false)
+  })
+
+  it('true for openai-compatible with endpoint url and model', () => {
+    const s = withActiveProvider(
+      {
+        'openai-compatible': {
+          id: 'openai-compatible',
+          endpointUrl: 'http://localhost:4096/v1',
+          apiKey: '',
+          model: 'q',
+          effort: 'auto',
+          label: '',
+        },
+      },
+      'openai-compatible',
+    )
+    expect(isActiveProviderReady(s)).toBe(true)
+  })
+
+  it('respects the local-CLI probe for claude-local', () => {
+    const s = withActiveProvider({}, 'claude-local')
+    expect(isActiveProviderReady(s)).toBe(false)
+    expect(isActiveProviderReady(s, { 'claude-local': true })).toBe(true)
+  })
+})
+
+describe('redactForLogging', () => {
+  it('replaces every secret with a <set>/<unset> marker', () => {
+    const populated: ProviderSettings = {
+      ...DEFAULT_PROVIDER_SETTINGS,
+      providers: {
+        ...DEFAULT_PROVIDER_SETTINGS.providers,
+        anthropic: { id: 'anthropic', apiKey: 'sk-ant-secret', model: 'm', effort: 'auto' },
+        paperclip: {
+          id: 'paperclip',
+          companyId: 'c1',
+          apiKey: 'pcli_secret',
+          apiBaseUrl: '',
+          model: 'm',
+          effort: 'auto',
+        },
+      },
+    }
+    const out = JSON.stringify(redactForLogging(populated))
+    expect(out).not.toContain('sk-ant-secret')
+    expect(out).not.toContain('pcli_secret')
+    expect(out).toContain('<set>')
+    // Non-secret company id stays.
+    expect(out).toContain('c1')
+  })
+})
diff --git a/src/embedded/__tests__/provider-contract.test.ts b/src/embedded/__tests__/provider-contract.test.ts
index 0bb4269..987e28a 100644
--- a/src/embedded/__tests__/provider-contract.test.ts
+++ b/src/embedded/__tests__/provider-contract.test.ts
@@ -25,7 +25,6 @@ import {
 } from '../anthropic-provider'
 import { OpenAIProvider } from '../openai-provider'
 import { OpenAICompatibleProvider } from '../openai-compatible-provider'
-import { CopilotProvider } from '../copilot-provider'
 import { PaperclipProvider } from '../paperclip-provider'
 
 const TOOLS: ProviderTool[] = [
@@ -141,13 +140,6 @@ const VARIANTS: Variant[] = [
       transport: async () => makeChatCompletionsResponse(),
     }),
   },
-  {
-    name: 'CopilotProvider',
-    build: () => new CopilotProvider({
-      // The transport-injection path bypasses the OAuth/session exchange.
-      transport: async () => makeChatCompletionsResponse(),
-    }),
-  },
   {
     name: 'PaperclipProvider',
     build: () => new PaperclipProvider({
diff --git a/src/embedded/__tests__/provider-factory.test.ts b/src/embedded/__tests__/provider-factory.test.ts
new file mode 100644
index 0000000..31ddce1
--- /dev/null
+++ b/src/embedded/__tests__/provider-factory.test.ts
@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { makeProvider } from '../provider-factory.js'
+import { DEFAULT_PROVIDER_SETTINGS, type ProviderId, type ProviderSettings } from '../provider-config.js'
+
+/**
+ * The factory must return a distinct provider class for every value of
+ * `ProviderId`. A regression here means an unhandled `switch` branch and a
+ * runtime crash when the user picks that provider.
+ */
+
+const expected: Record<ProviderId, string> = {
+  'claude-local': 'claude-local',
+  'codex-local': 'codex-local',
+  'opencode-local': 'opencode-local',
+  'copilot-local': 'copilot-local',
+  anthropic: 'anthropic',
+  openai: 'openai',
+  openrouter: 'openrouter',
+  'openai-compatible': 'openai-compatible',
+  paperclip: 'paperclip',
+}
+
+describe('makeProvider', () => {
+  for (const [id, expectedName] of Object.entries(expected) as Array<[ProviderId, string]>) {
+    it(`returns a provider for ${id}`, () => {
+      const settings: ProviderSettings = {
+        ...DEFAULT_PROVIDER_SETTINGS,
+        activeProvider: id,
+        providers: {
+          ...DEFAULT_PROVIDER_SETTINGS.providers,
+          // Provide minimum credentials for branches that throw at construction
+          // when they're missing — keeps the factory itself unit-testable.
+          anthropic: { id: 'anthropic', apiKey: 'sk-ant', model: 'claude-sonnet-4-5', effort: 'auto' },
+          openai: { id: 'openai', apiKey: 'sk-openai', organization: '', model: 'gpt-5', effort: 'auto' },
+          openrouter: { id: 'openrouter', apiKey: 'sk-or', baseUrl: '', model: 'openai/gpt-4o-mini', effort: 'auto' },
+          'openai-compatible': {
+            id: 'openai-compatible',
+            endpointUrl: 'http://localhost:4096',
+            apiKey: '',
+            model: 'llama',
+            effort: 'auto',
+            label: '',
+          },
+          paperclip: {
+            id: 'paperclip',
+            companyId: 'co_test',
+            apiKey: 'pc_test',
+            apiBaseUrl: '',
+            model: 'paperclip-default',
+            effort: 'auto',
+          },
+        },
+      }
+      const provider = makeProvider(settings)
+      expect(provider.name).toBe(expectedName)
+    })
+  }
+})
diff --git a/src/embedded/__tests__/provider-permission-matrix.test.ts b/src/embedded/__tests__/provider-permission-matrix.test.ts
new file mode 100644
index 0000000..d29525f
--- /dev/null
+++ b/src/embedded/__tests__/provider-permission-matrix.test.ts
@@ -0,0 +1,138 @@
+/**
+ * Cross-provider permission WORKFLOW matrix — all 4 local CLIs × all 3 modes,
+ * hermetic (no CLI install needed, runs in CI).
+ *
+ * This exercises the real end-to-end path a user triggers when they pick a
+ * permission mode in the UI:
+ *
+ *   selected mode  --normalizeHeadlessMode(mode, bin)-->  effective mode
+ *                  --provider.buildSpawn()-->             spawned argv
+ *                  --exceedsPermissionCap()-->            server-side floor
+ *
+ * It pins the headline "Auto" (`default`) safety behavior per CLI (codex/
+ * copilot stay sandboxed/minimal; claude/opencode escalate to bypass) and
+ * proves the ANNOTASK_MAX_PERMISSION clamp would gate the right providers.
+ */
+import { describe, it, expect, afterEach } from 'vitest'
+import { ClaudeLocalProvider } from '../claude-local-provider.js'
+import { CodexLocalProvider } from '../codex-local-provider.js'
+import { OpencodeLocalProvider } from '../opencode-local-provider.js'
+import { CopilotLocalProvider } from '../copilot-local-provider.js'
+import {
+  normalizeHeadlessMode,
+  claudePermissionFlags,
+  codexPermissionFlags,
+  opencodePermissionFlags,
+  copilotPermissionFlags,
+  type InitCliBin,
+} from '../permission-mode-flags.js'
+import { exceedsPermissionCap } from '../../server/agent-spawn.js'
+import type { CliLocalProvider } from '../cli-local-provider.js'
+import type { PermissionMode } from '../../schema.js'
+
+// ── Fake spawn transport: capture the POSTed argv, return a trivial SSE ──────
+let capturedArgs: string[] = []
+const fetchImpl = (async (_url: string, init?: RequestInit) => {
+  capturedArgs = (JSON.parse(String(init?.body ?? '{}')) as { args?: string[] }).args ?? []
+  const sse = ['event: exit', 'data: {"code":0,"signal":null}', '', ''].join('\n')
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      start(c) { c.enqueue(new TextEncoder().encode(sse)); c.close() },
+    }),
+    { status: 200, headers: { 'Content-Type': 'text/event-stream' } },
+  )
+}) as unknown as typeof fetch
+
+async function spawnArgsFor(provider: CliLocalProvider, effectiveMode: PermissionMode): Promise<string[]> {
+  for await (const _ of provider.stream(
+    [{ role: 'user', content: 'apply the task' }], [], { systemPrompt: '', permissionMode: effectiveMode },
+  )) { /* drain */ }
+  return capturedArgs
+}
+
+interface ProviderSpec {
+  bin: InitCliBin
+  make(): CliLocalProvider
+  flags(mode: PermissionMode): string[]
+}
+
+const PROVIDERS: ProviderSpec[] = [
+  { bin: 'claude', make: () => new ClaudeLocalProvider({ fetchImpl }), flags: claudePermissionFlags },
+  { bin: 'codex', make: () => new CodexLocalProvider({ fetchImpl }), flags: codexPermissionFlags },
+  { bin: 'opencode', make: () => new OpencodeLocalProvider({ fetchImpl }), flags: opencodePermissionFlags },
+  { bin: 'copilot', make: () => new CopilotLocalProvider({ fetchImpl }), flags: copilotPermissionFlags },
+]
+const SELECTED_MODES: PermissionMode[] = ['default', 'plan', 'bypass']
+
+describe('provider permission workflow matrix (4 CLIs × 3 modes)', () => {
+  for (const p of PROVIDERS) {
+    for (const selected of SELECTED_MODES) {
+      it(`${p.bin}: selecting '${selected}' spawns the headless-normalized flags`, async () => {
+        // What the runner actually does: resolve → normalize for the CLI → spawn.
+        const effective = normalizeHeadlessMode(selected, p.bin)
+        const expected = p.flags(effective)
+        const args = await spawnArgsFor(p.make(), effective)
+        for (const flag of expected) expect(args).toContain(flag)
+        // Plan must never leave a bypass flag on a CLI that has native plan.
+        if (selected === 'plan' && (p.bin === 'claude' || p.bin === 'codex')) {
+          expect(args).not.toContain('--dangerously-skip-permissions')
+          expect(args).not.toContain('--dangerously-bypass-approvals-and-sandbox')
+        }
+      })
+    }
+  }
+})
+
+describe("headline 'Auto' (default) safety behavior per CLI", () => {
+  it('codex Auto stays sandboxed (--full-auto), NOT sandbox-off', async () => {
+    const args = await spawnArgsFor(new CodexLocalProvider({ fetchImpl }), normalizeHeadlessMode('default', 'codex'))
+    expect(args).toContain('--full-auto')
+    expect(args).not.toContain('--dangerously-bypass-approvals-and-sandbox')
+  })
+  it('copilot Auto stays minimal (--allow-all-tools), NOT --allow-all', async () => {
+    const args = await spawnArgsFor(new CopilotLocalProvider({ fetchImpl }), normalizeHeadlessMode('default', 'copilot'))
+    expect(args).toContain('--allow-all-tools')
+    expect(args).not.toContain('--allow-all')
+  })
+  it('claude Auto escalates to bypass (no headless ask-mode)', async () => {
+    const args = await spawnArgsFor(new ClaudeLocalProvider({ fetchImpl }), normalizeHeadlessMode('default', 'claude'))
+    expect(args).toContain('--dangerously-skip-permissions')
+  })
+  it('opencode Auto escalates to bypass (no headless ask-mode)', async () => {
+    const args = await spawnArgsFor(new OpencodeLocalProvider({ fetchImpl }), normalizeHeadlessMode('default', 'opencode'))
+    expect(args).toContain('--dangerously-skip-permissions')
+  })
+})
+
+describe('ANNOTASK_MAX_PERMISSION clamp gates the right providers (per-task path)', () => {
+  afterEach(() => { delete process.env.ANNOTASK_MAX_PERMISSION })
+
+  it("cap=default blocks an Auto run on claude/opencode but allows codex/copilot", async () => {
+    process.env.ANNOTASK_MAX_PERMISSION = 'default'
+    for (const p of PROVIDERS) {
+      const args = await spawnArgsFor(p.make(), normalizeHeadlessMode('default', p.bin))
+      const blocked = exceedsPermissionCap(args)
+      if (p.bin === 'claude' || p.bin === 'opencode') {
+        expect(blocked).toMatchObject({ level: 'bypass', cap: 'default' })
+      } else {
+        expect(blocked).toBeNull()
+      }
+    }
+  })
+
+  it('cap=plan blocks an Auto run on every CLI (all need writes)', async () => {
+    process.env.ANNOTASK_MAX_PERMISSION = 'plan'
+    for (const p of PROVIDERS) {
+      const args = await spawnArgsFor(p.make(), normalizeHeadlessMode('default', p.bin))
+      expect(exceedsPermissionCap(args)).not.toBeNull()
+    }
+  })
+
+  it('no cap → an Auto run is allowed on every CLI', async () => {
+    delete process.env.ANNOTASK_MAX_PERMISSION
+    for (const p of PROVIDERS) {
+      const args = await spawnArgsFor(p.make(), normalizeHeadlessMode('default', p.bin))
+      expect(exceedsPermissionCap(args)).toBeNull()
+    }
+  })
+})
diff --git a/src/embedded/__tests__/redaction.test.ts b/src/embedded/__tests__/redaction.test.ts
new file mode 100644
index 0000000..4ec52c2
--- /dev/null
+++ b/src/embedded/__tests__/redaction.test.ts
@@ -0,0 +1,167 @@
+import { describe, it, expect } from 'vitest'
+import {
+  redact,
+  redactString,
+  redactValue,
+  DEFAULT_REDACTION_PATTERNS,
+  type RedactionPattern,
+} from '../redaction.js'
+
+describe('redact', () => {
+  it('redacts Anthropic api keys', () => {
+    const input = 'use sk-ant-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 to call'
+    const { output, matches } = redact(input)
+    expect(output).toBe('use [REDACTED:anthropic_api_key] to call')
+    expect(matches).toHaveLength(1)
+    expect(matches[0].label).toBe('anthropic_api_key')
+  })
+
+  it('redacts OpenAI api keys including project-scoped form', () => {
+    const a = redactString('OPENAI_KEY=sk-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890')
+    expect(a).toContain('[REDACTED:openai_api_key]')
+
+    const b = redactString('key sk-proj-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 ok')
+    expect(b).toContain('[REDACTED:openai_api_key]')
+  })
+
+  it('redacts GitHub PATs and classic tokens', () => {
+    // Real github_pat_ format: 22 base62 + _ + 59 base62. The test fixture
+    // here matches that exactly so the parser sees a valid PAT.
+    const tail = 'AbCdEfGhIjKlMnOpQrStUv' // 22
+    const secret = 'WxYz0123456789AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGhI' // 59
+    const pat = redactString(`token=github_pat_${tail}_${secret}`)
+    expect(pat).toContain('[REDACTED:github_pat]')
+
+    const classic = redactString('ghp_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890ab here')
+    expect(classic).toContain('[REDACTED:github_token]')
+  })
+
+  it('redacts AWS access key ids and labelled secrets', () => {
+    const k = redactString('AKIAIOSFODNN7EXAMPLE was leaked')
+    expect(k).toContain('[REDACTED:aws_access_key_id]')
+
+    const s = redactString('aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY rest')
+    expect(s).toContain('[REDACTED:aws_secret_access_key]')
+  })
+
+  it('redacts JWT-shaped tokens', () => {
+    const jwt =
+      'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyIn0.dBjftJeZ4CVPMZ4Y8c0Knw5XfM5xqZx8rJk1lT0wZ7s'
+    const r = redactString(`Authorization: Bearer ${jwt}`)
+    // Either bearer_token or jwt label is acceptable as long as the secret
+    // is gone.
+    expect(r).not.toContain(jwt)
+    expect(r).toMatch(/\[REDACTED:(bearer_token|jwt)\]/)
+  })
+
+  it('redacts PEM private key blocks across lines and beats inner matches', () => {
+    const inner = 'sk-ant-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890'
+    const pem = `-----BEGIN RSA PRIVATE KEY-----\nMIIBOQIBAAJAa${inner}\nABCDEF\n-----END RSA PRIVATE KEY-----`
+    const r = redactString(pem)
+    expect(r).toBe('[REDACTED:private_key_pem]')
+    expect(r).not.toContain(inner)
+  })
+
+  it('redacts env-style assignments only by value', () => {
+    const input = 'GH_TOKEN=ghp_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890ab\nAPI_KEY=mySuperSecret123'
+    const r = redactString(input)
+    // The variable name MUST stay so a debugger can see context.
+    expect(r).toContain('GH_TOKEN=')
+    expect(r).toContain('API_KEY=')
+    // The value is gone.
+    expect(r).not.toContain('mySuperSecret123')
+    expect(r).not.toContain('ghp_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890ab')
+  })
+
+  it('leaves benign text untouched', () => {
+    const input = 'The quick brown fox jumps over the lazy dog.'
+    expect(redactString(input)).toBe(input)
+  })
+
+  it('is idempotent', () => {
+    const input = 'key=sk-ant-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890'
+    const once = redactString(input)
+    const twice = redactString(once)
+    expect(twice).toBe(once)
+  })
+
+  it('returns match offsets in the original string', () => {
+    const input = 'pre sk-ant-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890 post'
+    const { matches } = redact(input)
+    expect(matches).toHaveLength(1)
+    expect(input.slice(matches[0].start, matches[0].end)).toBe(
+      'sk-ant-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890',
+    )
+  })
+
+  it('handles empty input', () => {
+    expect(redactString('')).toBe('')
+    expect(redact('').matches).toEqual([])
+  })
+
+  it('respects custom pattern lists', () => {
+    const patterns: RedactionPattern[] = [
+      { label: 'customer_id', pattern: /\bCUST-\d{6}\b/g },
+    ]
+    const r = redactString('order for CUST-123456 ok', patterns)
+    expect(r).toBe('order for [REDACTED:customer_id] ok')
+  })
+
+  it('exports a default pattern set with the documented labels', () => {
+    const labels = new Set(DEFAULT_REDACTION_PATTERNS.map((p) => p.label))
+    for (const required of [
+      'anthropic_api_key',
+      'openai_api_key',
+      'github_token',
+      'aws_access_key_id',
+      'private_key_pem',
+      'jwt',
+      'bearer_token',
+    ]) {
+      expect(labels.has(required)).toBe(true)
+    }
+  })
+
+  it('does not match short alphanum runs in prose', () => {
+    // The previous "Bearer" rule was anchored on the literal word; bare
+    // tokens without the prefix should pass through.
+    const input = 'I love coding in TypeScript on weekdays at home in Brooklyn'
+    expect(redactString(input)).toBe(input)
+  })
+})
+
+describe('redactValue', () => {
+  it('walks plain objects and arrays', () => {
+    const input = {
+      provider: 'anthropic',
+      key: 'sk-ant-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890',
+      nested: {
+        tokens: ['ghp_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890ab', 'safe-value'],
+      },
+      count: 7,
+      ok: true,
+    }
+    const out = redactValue(input)
+    expect(out.provider).toBe('anthropic')
+    expect(out.key).toBe('[REDACTED:anthropic_api_key]')
+    expect(out.nested.tokens[0]).toBe('[REDACTED:github_token]')
+    expect(out.nested.tokens[1]).toBe('safe-value')
+    expect(out.count).toBe(7)
+    expect(out.ok).toBe(true)
+  })
+
+  it('returns non-plain-object values unchanged', () => {
+    const date = new Date()
+    expect(redactValue(date)).toBe(date)
+    const map = new Map([['k', 'v']])
+    expect(redactValue(map)).toBe(map)
+    expect(redactValue(null)).toBe(null)
+    expect(redactValue(undefined)).toBe(undefined)
+  })
+
+  it('does not mutate the input', () => {
+    const input = { key: 'sk-ant-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890' }
+    redactValue(input)
+    expect(input.key).toBe('sk-ant-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890')
+  })
+})
diff --git a/src/embedded/anthropic-provider.ts b/src/embedded/anthropic-provider.ts
index ca3709b..55aa7f3 100644
--- a/src/embedded/anthropic-provider.ts
+++ b/src/embedded/anthropic-provider.ts
@@ -22,6 +22,9 @@ export interface AnthropicCreateParams {
   messages: AnthropicMessage[]
   tools?: AnthropicTool[]
   metadata?: Record<string, unknown>
+  /** Extended-thinking budget. Mapped from StreamOptions.effort in
+   *  buildAnthropicRequest. */
+  thinking?: { type: 'enabled'; budget_tokens: number }
 }
 
 export type AnthropicSystem =
@@ -184,13 +187,33 @@ export function buildAnthropicRequest(
     anthropicTools[anthropicTools.length - 1].cache_control = { type: 'ephemeral' }
   }
 
-  return {
+  const params: AnthropicCreateParams = {
     model: options.model ?? defaults.defaultModel,
     max_tokens: options.maxTokens ?? defaults.defaultMaxTokens,
     system,
     messages: messages.map(toAnthropicMessage),
     tools: anthropicTools,
   }
+  // Map provider-agnostic effort to Anthropic extended-thinking budget.
+  // `auto` → don't request thinking at all; minimal/low → small budget for
+  // brief reasoning; medium/high → progressively larger budgets. Models
+  // that don't support extended thinking ignore the field.
+  const thinkingBudget = mapEffortToThinkingBudget(options.effort)
+  if (thinkingBudget > 0) {
+    params.thinking = { type: 'enabled', budget_tokens: thinkingBudget }
+  }
+  return params
+}
+
+function mapEffortToThinkingBudget(effort: StreamOptions['effort']): number {
+  switch (effort) {
+    case 'minimal': return 1024
+    case 'low':     return 2048
+    case 'medium':  return 5000
+    case 'high':    return 15000
+    case 'auto':
+    case undefined: return 0
+  }
 }
 
 function toAnthropicTool(tool: ProviderTool): AnthropicTool {
diff --git a/src/embedded/chat-completions.ts b/src/embedded/chat-completions.ts
index 26da0a3..e14dd06 100644
--- a/src/embedded/chat-completions.ts
+++ b/src/embedded/chat-completions.ts
@@ -169,7 +169,7 @@ export function buildChatCompletionsRequest(
   }
   for (const msg of messages) out.push(...toChatCompletionsMessages(msg))
 
-  return {
+  const req: ChatCompletionsRequest = {
     model: options.model ?? defaults.defaultModel,
     messages: out,
     tools: tools.length > 0 ? tools.map(toChatCompletionsTool) : undefined,
@@ -179,6 +179,13 @@ export function buildChatCompletionsRequest(
     // most compat servers but they tolerate the extra field.
     stream_options: { include_usage: true },
   }
+  // Reasoning-effort hint. Compat servers without reasoning ignore unknown
+  // body fields, so it's safe to send always. We only send for non-auto
+  // levels so the body for older endpoints stays byte-identical.
+  if (options.effort && options.effort !== 'auto') {
+    req.reasoning_effort = options.effort
+  }
+  return req
 }
 
 function toChatCompletionsTool(tool: ProviderTool): ChatCompletionsTool {
diff --git a/src/embedded/claude-local-provider.ts b/src/embedded/claude-local-provider.ts
new file mode 100644
index 0000000..0fe1613
--- /dev/null
+++ b/src/embedded/claude-local-provider.ts
@@ -0,0 +1,190 @@
+/**
+ * Claude Code CLI (local) provider.
+ *
+ * Spawns `claude --print --output-format=stream-json --verbose` and pipes
+ * the user prompt in on stdin. The CLI emits one JSON object per line on
+ * stdout — we parse the subset we need (text deltas, usage, result) and
+ * map to the shared `ProviderEvent` shape.
+ *
+ * Auth: the user must already be logged into the `claude` CLI
+ * (`~/.claude/auth.json`). Annotask never sees the token.
+ *
+ * Reference shape: Claude Code's `stream-json` output (compatible with the
+ * Anthropic SDK's event names: `message_start`, `content_block_delta`, …).
+ */
+
+import {
+  CliLocalProvider,
+  flattenMessagesAsPrompt,
+  type ParsedLineResult,
+  type SpawnRequest,
+} from './cli-local-provider.js'
+import { claudePermissionFlags, defaultPermissionModeFor } from './permission-mode-flags.js'
+import type {
+  ProviderEvent,
+  ProviderMessage,
+  ProviderTool,
+  StreamOptions,
+} from './provider.js'
+
+export interface ClaudeLocalProviderOptions {
+  /** Optional model id passed to `claude --model`. */
+  model?: string
+  /** Extra args appended after the canonical args. */
+  extraArgs?: string[]
+  spawnUrl?: string
+  fetchImpl?: typeof fetch
+}
+
+export class ClaudeLocalProvider extends CliLocalProvider {
+  private readonly model?: string
+  private readonly extraArgs: string[]
+
+  constructor(opts: ClaudeLocalProviderOptions = {}) {
+    super({
+      name: 'claude-local',
+      spawnUrl: opts.spawnUrl,
+      fetchImpl: opts.fetchImpl,
+    })
+    this.model = opts.model?.trim() || undefined
+    this.extraArgs = (opts.extraArgs ?? []).filter((s) => s.trim().length > 0)
+  }
+
+  protected buildSpawn(
+    messages: ProviderMessage[],
+    _tools: ProviderTool[],
+    options: StreamOptions,
+  ): SpawnRequest {
+    const args = ['--print', '--output-format', 'stream-json', '--verbose']
+    // Permission mode is resolved + headless-normalized per-call (task ??
+    // persona ?? global, then normalizeHeadlessMode). The fail-safe fallback is
+    // claude's safe default (bypass — claude has no headless ask-mode), not a
+    // blanket bypass for every CLI.
+    args.push(...claudePermissionFlags(options.permissionMode ?? defaultPermissionModeFor('claude')))
+    if (this.model) args.push('--model', this.model)
+    args.push(...this.extraArgs)
+    return {
+      cli: 'claude',
+      args,
+      stdin: flattenMessagesAsPrompt(messages, options.systemPrompt),
+    }
+  }
+
+  protected parseStdoutLine(line: string): ParsedLineResult {
+    const trimmed = line.trim()
+    if (!trimmed) return []
+    let event: ClaudeStreamEvent
+    try { event = JSON.parse(trimmed) as ClaudeStreamEvent }
+    catch { return [] }
+    return mapClaudeEvent(event)
+  }
+}
+
+/**
+ * Narrowed view of the `claude --output-format stream-json` event shapes
+ * we read. The CLI emits a superset; we ignore anything we don't recognise.
+ *
+ * Two top-level envelopes carry content blocks:
+ *   - `{type: 'assistant', message: {content: [...]}}` — model output. Blocks
+ *     are `text` and `tool_use` (claude's tool loop only emits `tool_use`
+ *     after the model finishes assembling JSON input, so we get them whole).
+ *   - `{type: 'user', message: {content: [...]}}` — synthetic user message
+ *     that wraps a tool's `tool_result` block. The CLI manufactures this
+ *     turn after running the tool and before re-prompting the model.
+ */
+export interface ClaudeStreamEvent {
+  type?: string
+  message?: {
+    role?: string
+    content?: Array<ClaudeContentBlock>
+    usage?: ClaudeUsage
+  }
+  usage?: ClaudeUsage
+  [extra: string]: unknown
+}
+
+interface ClaudeContentBlock {
+  type?: string
+  // text block
+  text?: string
+  // tool_use block
+  id?: string
+  name?: string
+  input?: unknown
+  // tool_result block
+  tool_use_id?: string
+  content?: unknown
+  is_error?: boolean
+}
+
+interface ClaudeUsage {
+  input_tokens?: number
+  output_tokens?: number
+  cache_creation_input_tokens?: number
+  cache_read_input_tokens?: number
+}
+
+export function mapClaudeEvent(ev: ClaudeStreamEvent): ProviderEvent[] {
+  if (ev.type === 'assistant' && ev.message) {
+    const out: ProviderEvent[] = []
+    for (const block of ev.message.content ?? []) {
+      if (!block || typeof block.type !== 'string') continue
+      if (block.type === 'text' && typeof block.text === 'string' && block.text.length > 0) {
+        out.push({ type: 'text', text: block.text })
+      } else if (block.type === 'tool_use' && typeof block.id === 'string' && typeof block.name === 'string') {
+        out.push({ type: 'tool_call', id: block.id, name: block.name, input: block.input ?? {} })
+      }
+    }
+    if (ev.message.usage) out.push(usageEvent(ev.message.usage))
+    return out
+  }
+  if (ev.type === 'user' && ev.message) {
+    // Tool results land as content blocks on a synthetic user turn.
+    const out: ProviderEvent[] = []
+    for (const block of ev.message.content ?? []) {
+      if (block?.type !== 'tool_result' || typeof block.tool_use_id !== 'string') continue
+      out.push({
+        type: 'tool_result',
+        toolUseId: block.tool_use_id,
+        content: flattenToolResultContent(block.content),
+        isError: block.is_error === true ? true : undefined,
+      })
+    }
+    return out
+  }
+  if (ev.type === 'result' && ev.usage) {
+    return [usageEvent(ev.usage)]
+  }
+  return []
+}
+
+/**
+ * Tool-result content can be a plain string OR an array of `{type:'text',text}`
+ * blocks (Claude SDK shape). Coerce to a single string for the work-stream.
+ */
+function flattenToolResultContent(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    const parts: string[] = []
+    for (const c of content) {
+      if (c && typeof c === 'object') {
+        const obj = c as { type?: string; text?: string }
+        if (obj.type === 'text' && typeof obj.text === 'string') parts.push(obj.text)
+      }
+    }
+    if (parts.length > 0) return parts.join('\n')
+  }
+  // Unknown shapes (image blocks, structured payloads) round-trip as JSON so
+  // the UI's expandable raw view still has something to show.
+  try { return JSON.stringify(content) } catch { return '' }
+}
+
+function usageEvent(u: ClaudeUsage): ProviderEvent {
+  return {
+    type: 'usage',
+    inputTokens: u.input_tokens ?? 0,
+    outputTokens: u.output_tokens ?? 0,
+    cacheReadTokens: u.cache_read_input_tokens,
+    cacheCreationTokens: u.cache_creation_input_tokens,
+  }
+}
diff --git a/src/embedded/cli-local-provider.ts b/src/embedded/cli-local-provider.ts
new file mode 100644
index 0000000..7ed0405
--- /dev/null
+++ b/src/embedded/cli-local-provider.ts
@@ -0,0 +1,437 @@
+/**
+ * Base class for "local CLI" providers — claude-local, codex-local,
+ * opencode-local, copilot-local. These don't speak HTTP wire formats;
+ * instead, the browser asks the Annotask dev server to spawn the user's
+ * locally-installed CLI in headless JSON mode and pipes the user's message
+ * in on stdin. The CLI
+ * streams JSON events back on stdout, which the server forwards as SSE,
+ * which this provider parses into the shared `ProviderEvent` shape.
+ *
+ * Why this lives in the browser at all (instead of the server):
+ *   - Provider config (active model, extra args) is browser state.
+ *   - The transcript UI subscribes to `provider.stream()` directly; only the
+ *     transport (subprocess) requires server help.
+ *   - This keeps the LLMProvider contract uniform across direct-API and
+ *     local-CLI providers — `useEmbeddedAgent` doesn't care which kind ran.
+ *
+ * Wire contract with /__annotask/api/agent/spawn:
+ *   POST { cli, args, stdin? } → text/event-stream
+ *     event: stdout   data: <one line of CLI stdout>
+ *     event: stderr   data: <one line of CLI stderr>
+ *     event: exit     data: { code: number, signal: string|null }
+ *     event: error    data: <string>
+ *
+ * Each subclass implements `buildSpawn()` (how to invoke the CLI for the
+ * given prompt) and `parseStdoutLine()` (how to map one JSON line to zero or
+ * more ProviderEvents).
+ */
+
+import type {
+  LLMProvider,
+  ProviderMessage,
+  ProviderTool,
+  ProviderEvent,
+  StreamOptions,
+} from './provider.js'
+
+/** Shape returned by the server when spawning a CLI. */
+export interface SpawnRequest {
+  /** Allow-listed CLI binary name. */
+  cli: 'claude' | 'codex' | 'opencode' | 'copilot'
+  /** Argv after the cli name. No shell quoting needed; passed straight to spawn. */
+  args: string[]
+  /** Optional stdin body; written to the child's stdin then EOF. */
+  stdin?: string
+  /** Optional extra environment variables, merged over the dev server's env. */
+  env?: Record<string, string>
+}
+
+export interface CliLocalProviderConfig {
+  /** Stable identifier for telemetry/UI labels. */
+  name: string
+  /**
+   * Endpoint the browser should hit to spawn the CLI. Defaults to
+   * `/__annotask/api/agent/spawn`; tests can inject a mock transport.
+   */
+  spawnUrl?: string
+  /** Test seam: inject a custom fetch implementation. */
+  fetchImpl?: typeof fetch
+}
+
+/**
+ * Conversion result for one stdout line. Subclasses return zero events for
+ * "no payload" (headers, blank lines), one or more for real chunks. The base
+ * class emits its own `usage` and `done` at end-of-stream, so subclasses
+ * SHOULD NOT emit `done` themselves — they may emit `usage` early if the
+ * CLI reports it inline.
+ */
+export type ParsedLineResult = ProviderEvent[]
+
+export abstract class CliLocalProvider implements LLMProvider {
+  readonly name: string
+  private readonly spawnUrl: string
+  private readonly fetchImpl: typeof fetch
+  private lastRunId: string | null = null
+
+  constructor(cfg: CliLocalProviderConfig) {
+    this.name = cfg.name
+    this.spawnUrl = cfg.spawnUrl ?? '/__annotask/api/agent/spawn'
+    this.fetchImpl = cfg.fetchImpl ?? globalThis.fetch.bind(globalThis)
+  }
+
+  /** Explicitly kill a running subprocess via the server's abort endpoint. */
+  async abortRun(): Promise<void> {
+    const runId = this.lastRunId
+    if (!runId) return
+    this.lastRunId = null
+    try {
+      await this.fetchImpl(`${this.spawnUrl}/${encodeURIComponent(runId)}`, { method: 'DELETE' })
+    } catch { /* best effort */ }
+  }
+
+  /** Build the CLI spawn request for this conversation turn. */
+  protected abstract buildSpawn(
+    messages: ProviderMessage[],
+    tools: ProviderTool[],
+    options: StreamOptions,
+  ): SpawnRequest
+
+  /** Parse one stdout line (one JSON event). Return zero or more ProviderEvents. */
+  protected abstract parseStdoutLine(line: string): ParsedLineResult
+
+  /** Subclass hook: called when the CLI exits non-zero. Default: emit an error. */
+  protected onCliError(stderr: string, exitCode: number | null): ProviderEvent {
+    const msg = stderr.trim() || `CLI exited with code ${exitCode ?? 'unknown'}`
+    return { type: 'error', error: `[${this.name}] ${msg}` }
+  }
+
+  async *stream(
+    messages: ProviderMessage[],
+    tools: ProviderTool[],
+    options: StreamOptions,
+  ): AsyncIterable<ProviderEvent> {
+    if (options.signal?.aborted) {
+      yield { type: 'done', stopReason: 'aborted' }
+      return
+    }
+
+    const spawn = this.buildSpawn(messages, tools, options)
+    // Forward the task id (when this run is applying one) so the server can key
+    // its run registry by task — dedup cross-tab runs + finalize orphans.
+    const spawnBody = options.taskId ? { ...spawn, taskId: options.taskId } : spawn
+
+    let response: Response
+    try {
+      response = await this.fetchImpl(this.spawnUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'text/event-stream' },
+        body: JSON.stringify(spawnBody),
+        signal: options.signal,
+      })
+    } catch (err) {
+      yield { type: 'error', error: `[${this.name}] spawn fetch failed: ${(err as Error).message}` }
+      yield { type: 'done', stopReason: 'error' }
+      return
+    }
+
+    if (!response.ok) {
+      const text = await safeReadText(response)
+      // Cross-tab dedup: the server already has a live run for this task in
+      // another tab/session (409 `task_already_running`). THIS run never
+      // started, so it must not be treated as an error — an error reverts the
+      // task to pending, which would yank the WINNING tab's live run out from
+      // under it. Signal a benign, distinct stop reason and let the caller
+      // leave the task status untouched.
+      if (response.status === 409 && text.includes('task_already_running')) {
+        yield { type: 'done', stopReason: 'already_running' }
+        return
+      }
+      yield {
+        type: 'error',
+        error: `[${this.name}] spawn HTTP ${response.status}: ${text || response.statusText}`,
+      }
+      yield { type: 'done', stopReason: 'error' }
+      return
+    }
+    if (!response.body) {
+      yield { type: 'error', error: `[${this.name}] spawn response has no body` }
+      yield { type: 'done', stopReason: 'error' }
+      return
+    }
+
+    let exitCode: number | null = null
+    let stderrBuffer = ''
+    let stopReason: string | undefined
+    let usageEmitted = false
+    this.lastRunId = null
+
+    try {
+      for await (const ev of iterateSse(response.body, options.signal)) {
+        if (ev.event === 'run') {
+          // Capture the server-assigned run ID so abortRun() can kill it.
+          try {
+            const parsed = JSON.parse(ev.data) as { runId?: string }
+            if (parsed.runId) this.lastRunId = parsed.runId
+          } catch { /* ignore */ }
+        } else if (ev.event === 'stdout') {
+          for (const out of this.parseStdoutLine(ev.data)) {
+            if (out.type === 'usage') usageEmitted = true
+            yield out
+          }
+        } else if (ev.event === 'stderr') {
+          // Buffer stderr — only surface if the process exits non-zero.
+          stderrBuffer += ev.data + '\n'
+        } else if (ev.event === 'exit') {
+          try {
+            const parsed = JSON.parse(ev.data) as { code?: number | null }
+            exitCode = typeof parsed.code === 'number' ? parsed.code : null
+          } catch { /* ignore */ }
+        } else if (ev.event === 'error') {
+          yield { type: 'error', error: `[${this.name}] ${ev.data}` }
+          stopReason = 'error'
+        }
+      }
+    } catch (err) {
+      yield { type: 'error', error: (err as Error).message ?? String(err) }
+      stopReason = 'error'
+    }
+    this.lastRunId = null
+
+    if (options.signal?.aborted) stopReason = 'aborted'
+    else if (exitCode !== null && exitCode !== 0) {
+      yield this.onCliError(stderrBuffer, exitCode)
+      stopReason = stopReason ?? 'error'
+    }
+
+    if (!usageEmitted) {
+      // Subclasses that don't surface usage still need a `usage` event so the
+      // cost meter doesn't show a phantom zero forever.
+      yield { type: 'usage', inputTokens: 0, outputTokens: 0 }
+    }
+    yield { type: 'done', stopReason }
+  }
+}
+
+/** Extract the text payload of one provider message. Tool blocks have no
+ *  positional-prompt representation here — by the time a thread message
+ *  reaches a provider its `content` already carries the flat text rollup
+ *  (including `[Tool] …` / `[Result] …` summary lines), so text blocks are
+ *  the only thing worth reading. */
+function messageText(msg: ProviderMessage): string {
+  if (typeof msg.content === 'string') return msg.content
+  const text: string[] = []
+  for (const block of msg.content) {
+    if (block.type === 'text') text.push(block.text)
+  }
+  return text.join('')
+}
+
+/** Flatten the provider-agnostic message history into a single prompt string. */
+export function flattenMessagesAsPrompt(
+  messages: ProviderMessage[],
+  systemPrompt: string,
+): string {
+  const parts: string[] = []
+  if (systemPrompt) parts.push(systemPrompt, '')
+  for (const msg of messages) {
+    const text = messageText(msg)
+    if (text.length > 0) {
+      parts.push(`${msg.role === 'user' ? 'User' : 'Assistant'}: ${text}`)
+    }
+  }
+  return parts.join('\n').trim()
+}
+
+/**
+ * Prepend a system prompt to a positional CLI prompt. Used by CLIs whose
+ * headless modes don't expose a separate system-prompt flag (`codex exec`,
+ * `opencode run`, `copilot -p`). The CLI receives one prompt that opens with
+ * the system instructions, a separator, then the user turn — the model still
+ * picks up the instructions even though everything is technically one user
+ * message.
+ *
+ * `claude --print` already supports a real system prompt via stdin's flatten
+ * helper above, so it doesn't go through this.
+ */
+export function withSystemPrompt(userText: string, systemPrompt: string): string {
+  const trimmed = systemPrompt.trim()
+  if (trimmed.length === 0) return userText
+  return `${trimmed}\n\n---\n\n${userText}`
+}
+
+/**
+ * Extract just the latest user turn as a single string. Used by CLIs whose
+ * headless mode runs one-shot ("answer this one prompt") rather than a true
+ * multi-turn protocol — `codex exec`, `opencode run`, `copilot -p`.
+ * Multi-turn context is expressed by prepending the rolled-up history — see
+ * `rollupHistoryAsPrompt` below.
+ */
+export function lastUserMessageText(messages: ProviderMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]
+    if (m.role !== 'user') continue
+    return messageText(m)
+  }
+  return ''
+}
+
+/**
+ * Character budget for prompts passed as a single argv element. Linux caps
+ * one argv string at MAX_ARG_STRLEN (128 KiB) and macOS shares a 1 MiB
+ * ARG_MAX across the whole argv + environment — 100 KB leaves comfortable
+ * headroom for the rest of the command line on both. claude isn't affected
+ * (its prompt rides on stdin), only the positional-prompt CLIs are.
+ */
+export const POSITIONAL_PROMPT_MAX_CHARS = 100_000
+
+/** Inserted at the top of the rolled-up transcript when old turns were
+ *  dropped, so the model knows the history is incomplete rather than
+ *  inventing the missing context. */
+export const HISTORY_TRUNCATED_MARKER = '[earlier turns truncated]'
+
+/**
+ * Roll up the full conversation into a single positional prompt for one-shot
+ * CLIs (`codex exec`, `opencode run`, `copilot -p`). Each chat turn spawns a
+ * fresh subprocess, so without this every follow-up message would lose ALL
+ * prior context — the rolled-up history is the only memory these CLIs get.
+ *
+ * Shape (system prompt first so it reads as instructions, then the prior
+ * turns as a clearly-delimited transcript, then the live request):
+ *
+ *   <system prompt>
+ *   ---
+ *   ## Conversation so far
+ *   User: …
+ *   Assistant: …
+ *   ## Current request
+ *   <latest user message>
+ *
+ * First turns (no prior history) keep the exact single-shot shape of
+ * `withSystemPrompt(lastUserMessageText(...), ...)` so seed-run prompts are
+ * byte-identical to what they were before multi-turn support.
+ *
+ * Budget: the whole prompt must fit in one argv element (see
+ * `POSITIONAL_PROMPT_MAX_CHARS`). The system prompt and the current request
+ * are never truncated — history turns are dropped OLDEST-first until the
+ * rest fits, with `HISTORY_TRUNCATED_MARKER` left where they were.
+ */
+export function rollupHistoryAsPrompt(
+  messages: ProviderMessage[],
+  systemPrompt: string,
+  maxChars: number = POSITIONAL_PROMPT_MAX_CHARS,
+): string {
+  // The current turn is the LAST user message; everything before it is
+  // prior conversation. (Messages after it shouldn't exist — the runner
+  // always appends the user turn last before streaming.)
+  let lastUserIdx = -1
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === 'user') { lastUserIdx = i; break }
+  }
+  const current = lastUserIdx >= 0 ? messageText(messages[lastUserIdx]) : ''
+  if (lastUserIdx <= 0) {
+    return withSystemPrompt(current, systemPrompt)
+  }
+
+  const turns: string[] = []
+  for (let i = 0; i < lastUserIdx; i++) {
+    const m = messages[i]
+    const text = messageText(m).trim()
+    if (text.length === 0) continue
+    turns.push(`${m.role === 'user' ? 'User' : 'Assistant'}: ${text}`)
+  }
+  if (turns.length === 0) {
+    return withSystemPrompt(current, systemPrompt)
+  }
+
+  const heading = '## Conversation so far'
+  const currentHeading = '## Current request'
+  // Fixed cost = everything that survives no matter what: system prompt,
+  // both headings, the current request, plus reserved room for the
+  // truncation marker (cheaper to always reserve its ~30 chars than to
+  // re-balance the budget when truncation kicks in).
+  const fixedCost = withSystemPrompt(
+    [heading, '', currentHeading, '', current].join('\n'),
+    systemPrompt,
+  ).length + HISTORY_TRUNCATED_MARKER.length + 2
+  let remaining = maxChars - fixedCost
+
+  // Walk history NEWEST-first so the budget keeps the most recent turns;
+  // the first turn that doesn't fit ends the walk (skipping it but keeping
+  // older turns would scramble the transcript's continuity).
+  const kept: string[] = []
+  let truncated = false
+  for (let i = turns.length - 1; i >= 0; i--) {
+    const cost = turns[i].length + 2 // +2 for the blank-line separator
+    if (cost > remaining) { truncated = true; break }
+    kept.unshift(turns[i])
+    remaining -= cost
+  }
+  if (truncated) kept.unshift(HISTORY_TRUNCATED_MARKER)
+
+  const body = [heading, '', kept.join('\n\n'), '', currentHeading, '', current].join('\n')
+  return withSystemPrompt(body, systemPrompt)
+}
+
+/** Parsed SSE event from the spawn endpoint. */
+interface SseEvent {
+  event: string
+  data: string
+}
+
+/**
+ * Parse a stream of SSE frames from the spawn endpoint. Each frame is a
+ * `event:` + `data:` pair, separated by blank lines. We ignore comment lines
+ * (`:` prefix) and id lines — the spawn endpoint never uses them.
+ */
+async function* iterateSse(
+  body: ReadableStream<Uint8Array>,
+  signal: AbortSignal | undefined,
+): AsyncIterable<SseEvent> {
+  const decoder = new TextDecoder()
+  const reader = body.getReader()
+  let buffer = ''
+  let currentEvent = 'message'
+  let currentData: string[] = []
+
+  try {
+    for (;;) {
+      if (signal?.aborted) break
+      const { value, done } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+
+      let nl
+      while ((nl = buffer.indexOf('\n')) >= 0) {
+        const rawLine = buffer.slice(0, nl).replace(/\r$/, '')
+        buffer = buffer.slice(nl + 1)
+
+        if (rawLine === '') {
+          if (currentData.length > 0) {
+            yield { event: currentEvent, data: currentData.join('\n') }
+          }
+          currentEvent = 'message'
+          currentData = []
+          continue
+        }
+        if (rawLine.startsWith(':')) continue // comment line
+        const colon = rawLine.indexOf(':')
+        if (colon < 0) continue
+        const field = rawLine.slice(0, colon)
+        const value = rawLine.slice(colon + 1).replace(/^ /, '')
+        if (field === 'event') currentEvent = value
+        else if (field === 'data') currentData.push(value)
+      }
+    }
+    // flush trailing event if the stream ended without a blank line
+    if (currentData.length > 0) {
+      yield { event: currentEvent, data: currentData.join('\n') }
+    }
+  } finally {
+    try { await reader.cancel() } catch { /* ignore */ }
+  }
+}
+
+async function safeReadText(response: Response): Promise<string> {
+  try { return (await response.text()).slice(0, 1024) }
+  catch { return '' }
+}
diff --git a/src/embedded/codex-local-provider.ts b/src/embedded/codex-local-provider.ts
new file mode 100644
index 0000000..8f8714d
--- /dev/null
+++ b/src/embedded/codex-local-provider.ts
@@ -0,0 +1,214 @@
+/**
+ * OpenAI Codex CLI (local) provider.
+ *
+ * Spawns `codex exec --json` and pipes the user prompt in on stdin. The
+ * CLI emits one JSON line per event on stdout. We read the events we need
+ * to drive the chat UI: `item.completed` for assistant text, `turn.completed`
+ * for usage and termination.
+ *
+ * Auth: the user must already be logged into the `codex` CLI. Annotask
+ * never sees their token.
+ */
+
+import {
+  CliLocalProvider,
+  rollupHistoryAsPrompt,
+  type ParsedLineResult,
+  type SpawnRequest,
+} from './cli-local-provider.js'
+import { codexPermissionFlags, defaultPermissionModeFor } from './permission-mode-flags.js'
+import type {
+  ProviderEvent,
+  ProviderMessage,
+  ProviderTool,
+  StreamOptions,
+} from './provider.js'
+
+export interface CodexLocalProviderOptions {
+  /** Optional model id passed to `codex exec --model`. */
+  model?: string
+  extraArgs?: string[]
+  spawnUrl?: string
+  fetchImpl?: typeof fetch
+}
+
+export class CodexLocalProvider extends CliLocalProvider {
+  private readonly model?: string
+  private readonly extraArgs: string[]
+
+  constructor(opts: CodexLocalProviderOptions = {}) {
+    super({
+      name: 'codex-local',
+      spawnUrl: opts.spawnUrl,
+      fetchImpl: opts.fetchImpl,
+    })
+    this.model = opts.model?.trim() || undefined
+    this.extraArgs = (opts.extraArgs ?? []).filter((s) => s.trim().length > 0)
+  }
+
+  protected buildSpawn(
+    messages: ProviderMessage[],
+    _tools: ProviderTool[],
+    options: StreamOptions,
+  ): SpawnRequest {
+    const args = ['exec', '--json']
+    // Permission mode → codex sandbox flags. `bypass` keeps the historical
+    // `--dangerously-bypass-approvals-and-sandbox`; `plan` clamps the sandbox
+    // to `read-only`; `default` uses `--full-auto` (workspace-write sandbox).
+    // Headless `exec` doesn't surface per-action approvals. The fail-safe
+    // fallback is codex's safe default (`default` = sandboxed), not bypass.
+    args.push(...codexPermissionFlags(options.permissionMode ?? defaultPermissionModeFor('codex')))
+    // Allow running in projects that aren't a git repo. Without this, codex
+    // refuses to start when the dev server's cwd isn't inside a repository.
+    args.push('--skip-git-repo-check')
+    if (this.model) args.push('--model', this.model)
+    // Map effort → `-c model_reasoning_effort=<level>` (Codex's only knob).
+    // `auto` and `minimal` map to nothing — Codex picks its own default.
+    if (options.effort && options.effort !== 'auto' && options.effort !== 'minimal') {
+      args.push('-c', `model_reasoning_effort=${options.effort}`)
+    }
+    args.push(...this.extraArgs)
+    // Codex consumes the prompt as the trailing positional arg. Prepend the
+    // annotask system prompt so the persona's instructions reach the model
+    // even though codex has no separate system-prompt flag, and roll up the
+    // prior turns as a transcript — each turn spawns a fresh `codex exec`,
+    // so the prompt is the only memory follow-up messages get. The `--`
+    // separator is required: skill bodies often start with `---` (YAML
+    // frontmatter), and without it clap parses the leading `--` as an
+    // unknown long flag.
+    args.push('--', rollupHistoryAsPrompt(messages, options.systemPrompt))
+    return { cli: 'codex', args }
+  }
+
+  protected parseStdoutLine(line: string): ParsedLineResult {
+    const trimmed = line.trim()
+    if (!trimmed) return []
+    let event: CodexEvent
+    try { event = JSON.parse(trimmed) as CodexEvent }
+    catch { return [] }
+    return mapCodexEvent(event)
+  }
+}
+
+export interface CodexEvent {
+  type?: string
+  item?: CodexItem
+  usage?: {
+    input_tokens?: number
+    cached_input_tokens?: number
+    output_tokens?: number
+  }
+  [extra: string]: unknown
+}
+
+/**
+ * Codex item shapes vary by version. We accept the common surface — `id`,
+ * `item_type`, plus optional fields per kind. Each branch in mapCodexEvent
+ * narrows to what it needs.
+ */
+interface CodexItem {
+  id?: string
+  /** Older codex builds used `item_type`; newer (0.111+) emit `type`. */
+  item_type?: string
+  type?: string
+  text?: string
+  // function_call / tool_call
+  name?: string
+  arguments?: unknown
+  call_id?: string
+  // function_call_output / tool_result
+  output?: unknown
+  // command_execution
+  command?: string | string[]
+  exit_code?: number
+  // file_change
+  path?: string
+  [extra: string]: unknown
+}
+
+export function mapCodexEvent(ev: CodexEvent): ProviderEvent[] {
+  if (ev.type === 'item.completed' && ev.item) {
+    return mapCodexItem(ev.item)
+  }
+  if (ev.type === 'turn.completed' && ev.usage) {
+    return [{
+      type: 'usage',
+      inputTokens: ev.usage.input_tokens ?? 0,
+      outputTokens: ev.usage.output_tokens ?? 0,
+      cacheReadTokens: ev.usage.cached_input_tokens,
+    }]
+  }
+  return []
+}
+
+function mapCodexItem(item: CodexItem): ProviderEvent[] {
+  // 0.111+ renamed the discriminator from `item_type` to `type` and the
+  // assistant-message value from `assistant_message` to `agent_message`.
+  // Accept both so the parser keeps working across CLI bumps.
+  const kind = item.item_type ?? item.type
+  if ((kind === 'assistant_message' || kind === 'agent_message') && typeof item.text === 'string') {
+    return [{ type: 'text', text: item.text }]
+  }
+  // Function / tool calls. Codex names these `function_call` (OpenAI-style)
+  // but `tool_call` shows up in some versions too. The id field is named
+  // `id` on the call and `call_id` on the result — pair on the latter.
+  if ((kind === 'function_call' || kind === 'tool_call') && typeof item.id === 'string' && typeof item.name === 'string') {
+    return [{
+      type: 'tool_call',
+      id: item.id,
+      name: item.name,
+      input: parseMaybeJson(item.arguments) ?? {},
+    }]
+  }
+  if ((kind === 'function_call_output' || kind === 'tool_result') && typeof item.call_id === 'string') {
+    return [{
+      type: 'tool_result',
+      toolUseId: item.call_id,
+      content: coerceToString(item.output),
+      isError: typeof item.exit_code === 'number' && item.exit_code !== 0 ? true : undefined,
+    }]
+  }
+  // Shell commands surface as a tool_call/result pair so the work-stream
+  // shows them inline. Use the item.id (or a stable synthesized id) so the
+  // UI can pair them if codex emits both phases.
+  if (kind === 'command_execution' && typeof item.command !== 'undefined') {
+    const cmd = Array.isArray(item.command) ? item.command.join(' ') : String(item.command)
+    const callId = typeof item.id === 'string' ? item.id : `cmd-${cmd.slice(0, 16)}`
+    const events: ProviderEvent[] = [{
+      type: 'tool_call',
+      id: callId,
+      name: 'Bash',
+      input: { command: cmd },
+    }]
+    if (typeof item.output !== 'undefined') {
+      events.push({
+        type: 'tool_result',
+        toolUseId: callId,
+        content: coerceToString(item.output),
+        isError: typeof item.exit_code === 'number' && item.exit_code !== 0 ? true : undefined,
+      })
+    }
+    return events
+  }
+  if (kind === 'file_change' && typeof item.path === 'string') {
+    const callId = typeof item.id === 'string' ? item.id : `fc-${item.path}`
+    return [{
+      type: 'tool_call',
+      id: callId,
+      name: 'Edit',
+      input: { file_path: item.path },
+    }]
+  }
+  return []
+}
+
+function parseMaybeJson(v: unknown): unknown {
+  if (typeof v !== 'string') return v
+  try { return JSON.parse(v) } catch { return v }
+}
+
+function coerceToString(v: unknown): string {
+  if (typeof v === 'string') return v
+  if (v == null) return ''
+  try { return JSON.stringify(v) } catch { return String(v) }
+}
diff --git a/src/embedded/copilot-local-provider.ts b/src/embedded/copilot-local-provider.ts
new file mode 100644
index 0000000..575eccb
--- /dev/null
+++ b/src/embedded/copilot-local-provider.ts
@@ -0,0 +1,183 @@
+/**
+ * GitHub Copilot CLI (local) provider.
+ *
+ * Spawns `copilot -p <prompt> --output-format json --allow-all-tools
+ * --no-ask-user` and parses the JSONL event stream on stdout. Auth lives in
+ * `~/.copilot/`; the user must have signed in via `copilot` before.
+ *
+ * NOT the same thing as `CopilotProvider` (in `copilot-provider.ts`), which
+ * talks to `api.githubcopilot.com` over HTTP using the `gh` CLI's OAuth
+ * token. This file wraps the first-party Copilot CLI as a local subprocess
+ * and is registered as provider id `'copilot-local'`.
+ *
+ * Reference event shapes (copilot 1.0.48):
+ *   {"type":"assistant.message_delta","data":{"deltaContent":"ok", ...}}
+ *   {"type":"assistant.message","data":{"content":"ok","outputTokens":21,...}}
+ *   {"type":"result","usage":{...}}
+ *
+ * Many other event types (session.*, user.message, assistant.turn_start,
+ * assistant.reasoning, …) are surfaced too but carry no user-visible payload;
+ * we ignore them silently rather than fail.
+ */
+
+import {
+  CliLocalProvider,
+  rollupHistoryAsPrompt,
+  type ParsedLineResult,
+  type SpawnRequest,
+} from './cli-local-provider.js'
+import { copilotPermissionFlags, defaultPermissionModeFor } from './permission-mode-flags.js'
+import type {
+  ProviderEvent,
+  ProviderMessage,
+  ProviderTool,
+  StreamOptions,
+} from './provider.js'
+
+export interface CopilotLocalProviderOptions {
+  /** Optional model id passed to `copilot --model`. */
+  model?: string
+  extraArgs?: string[]
+  spawnUrl?: string
+  fetchImpl?: typeof fetch
+}
+
+export class CopilotLocalProvider extends CliLocalProvider {
+  private readonly model?: string
+  private readonly extraArgs: string[]
+
+  constructor(opts: CopilotLocalProviderOptions = {}) {
+    super({
+      name: 'copilot-local',
+      spawnUrl: opts.spawnUrl,
+      fetchImpl: opts.fetchImpl,
+    })
+    this.model = opts.model?.trim() || undefined
+    this.extraArgs = (opts.extraArgs ?? []).filter((s) => s.trim().length > 0)
+  }
+
+  protected buildSpawn(
+    messages: ProviderMessage[],
+    _tools: ProviderTool[],
+    options: StreamOptions,
+  ): SpawnRequest {
+    // `--allow-all-tools` is required for `-p` (non-interactive) per the CLI's
+    // own help — so even non-bypass modes keep it. `bypass` additionally
+    // enables `--allow-all` (paths + URLs + tools); weaker modes stop at the
+    // minimum required for headless to run. Per-action approval is not
+    // possible in `copilot -p`; surface this limitation in the UI.
+    const args = ['--output-format', 'json']
+    args.push(...copilotPermissionFlags(options.permissionMode ?? defaultPermissionModeFor('copilot')))
+    if (this.model) args.push('--model', this.model)
+    // Map effort. Copilot exposes "low" | "medium" | "high" | "xhigh".
+    if (options.effort && options.effort !== 'auto' && options.effort !== 'minimal') {
+      args.push('--reasoning-effort', options.effort)
+    }
+    args.push(...this.extraArgs)
+    // Copilot consumes the prompt via `-p <text>`. Prepend the system prompt
+    // (there's no separate system-prompt flag) and roll up the prior turns
+    // as a transcript — each turn spawns a fresh `copilot -p` with no
+    // session memory of its own.
+    args.push('-p', rollupHistoryAsPrompt(messages, options.systemPrompt))
+    return { cli: 'copilot', args }
+  }
+
+  protected parseStdoutLine(line: string): ParsedLineResult {
+    const trimmed = line.trim()
+    if (!trimmed) return []
+    let event: CopilotCliEvent
+    try { event = JSON.parse(trimmed) as CopilotCliEvent }
+    catch { return [] }
+    return mapCopilotEvent(event)
+  }
+}
+
+export interface CopilotCliEvent {
+  type?: string
+  data?: CopilotEventData
+  usage?: CopilotResultUsage
+  [extra: string]: unknown
+}
+
+interface CopilotEventData {
+  /** Streaming chunk text. */
+  deltaContent?: string
+  /** Final cumulative message content. */
+  content?: string
+  /** Token counts reported on the final message. Copilot historically surfaces
+   *  only output tokens at this layer; we read input/cache too if a newer CLI
+   *  starts emitting them rather than hardcoding the input side to 0. */
+  outputTokens?: number
+  inputTokens?: number
+  cacheReadTokens?: number
+  /** Tool requests embedded on the final assistant message. Each one
+   *  describes a tool the model wants to invoke. */
+  toolRequests?: CopilotToolRequest[]
+  [extra: string]: unknown
+}
+
+interface CopilotToolRequest {
+  id?: string
+  name?: string
+  arguments?: unknown
+}
+
+interface CopilotResultUsage {
+  premiumRequests?: number
+  totalApiDurationMs?: number
+  sessionDurationMs?: number
+}
+
+export function mapCopilotEvent(ev: CopilotCliEvent): ProviderEvent[] {
+  const out: ProviderEvent[] = []
+  const data = ev.data ?? undefined
+
+  // Streaming text deltas. message_delta is the per-chunk surface; assistant
+  // .message at end-of-turn carries the full content but emitting it would
+  // duplicate the deltas, so we only read outputTokens off of it.
+  if (ev.type === 'assistant.message_delta' && data && typeof data.deltaContent === 'string' && data.deltaContent.length > 0) {
+    out.push({ type: 'text', text: data.deltaContent })
+  }
+  // Fallback: a stream that emitted only a final assistant.message with no
+  // deltas (some agent modes do this). Surface its content as one text event
+  // so the user still sees the reply.
+  if (ev.type === 'assistant.message' && data && typeof data.content === 'string' && data.content.length > 0) {
+    // Only emit if no prior delta carried text — we can't know here, so the
+    // safest behavior is to always emit. The base class concatenates text
+    // events into a single block in the UI; duplicate text would surface as
+    // doubled content. Copilot's contract today (1.0.48) is to emit deltas
+    // AND a final message, so we skip emitting text from `assistant.message`
+    // and rely on deltas. Tool requests on the final message still need to
+    // be surfaced — see below.
+  }
+  if (ev.type === 'assistant.message' && data && Array.isArray(data.toolRequests)) {
+    for (const tr of data.toolRequests) {
+      if (typeof tr.id !== 'string' || typeof tr.name !== 'string') continue
+      out.push({
+        type: 'tool_call',
+        id: tr.id,
+        name: tr.name,
+        input: parseMaybeJson(tr.arguments) ?? {},
+      })
+    }
+  }
+  // Per-message token counts. Older copilot CLIs surface only outputTokens
+  // (inputTokens stays 0 — the cost meter undercounts input on those); newer
+  // ones may add input/cache, which we pick up here instead of dropping.
+  if (ev.type === 'assistant.message' && data && (typeof data.outputTokens === 'number' || typeof data.inputTokens === 'number')) {
+    out.push({
+      type: 'usage',
+      inputTokens: typeof data.inputTokens === 'number' ? data.inputTokens : 0,
+      outputTokens: typeof data.outputTokens === 'number' ? data.outputTokens : 0,
+      ...(typeof data.cacheReadTokens === 'number' ? { cacheReadTokens: data.cacheReadTokens } : {}),
+    })
+  }
+  // No usage info beyond what's already surfaced on `assistant.message`. The
+  // `result` event carries timing + premiumRequests but no token totals.
+  return out
+}
+
+function parseMaybeJson(v: unknown): unknown {
+  if (typeof v !== 'string') return v
+  try { return JSON.parse(v) } catch { return v }
+}
diff --git a/src/embedded/copilot-provider.ts b/src/embedded/copilot-provider.ts
deleted file mode 100644
index f9d96d5..0000000
--- a/src/embedded/copilot-provider.ts
+++ /dev/null
@@ -1,235 +0,0 @@
-/**
- * GitHub Copilot Chat provider.
- *
- * Ports the auth flow used by `sst/opencode`:
- *   1. Read the user's GitHub OAuth token from `~/.config/github-copilot/`
- *      (`apps.json` on newer Copilot installs, `hosts.json` on older).
- *   2. Exchange that OAuth token for a short-lived Copilot session token via
- *      `GET https://api.github.com/copilot_internal/v2/token`.
- *   3. Use the session token against `https://api.githubcopilot.com/chat/completions`
- *      with the Chat Completions wire format and Copilot-specific editor
- *      headers.
- *
- * This is the well-known contract between Copilot's session-token exchange
- * and its chat endpoint; if GitHub re-shapes either side, the smoke test
- * (`__tests__/copilot-smoke.test.ts`, run on demand) is what catches it.
- */
-
-import * as fs from 'node:fs/promises'
-import * as os from 'node:os'
-import * as path from 'node:path'
-import {
-  ChatCompletionsProvider,
-  type ChatCompletionsTransport,
-  type ChatCompletionsRequest,
-} from './chat-completions.js'
-
-const SESSION_TOKEN_URL = 'https://api.github.com/copilot_internal/v2/token'
-const DEFAULT_CHAT_ENDPOINT = 'https://api.githubcopilot.com/chat/completions'
-const DEFAULT_MODEL = 'gpt-4o'
-const DEFAULT_MAX_TOKENS = 4096
-const EDITOR_VERSION = 'annotask/0.1'
-const EDITOR_PLUGIN_VERSION = 'annotask-embedded/0.1'
-const COPILOT_INTEGRATION_ID = 'vscode-chat'
-const USER_AGENT = 'GithubCopilot/annotask'
-const TOKEN_REFRESH_SLACK_MS = 60_000
-
-export interface CopilotSessionToken {
-  /** Bearer token to send to the Copilot chat endpoint. */
-  token: string
-  /** Unix seconds when the token expires. */
-  expiresAt: number
-  /** Optional override of the chat endpoint base URL. */
-  chatEndpoint?: string
-}
-
-export interface CopilotProviderOptions {
-  /** Override the OAuth token instead of reading the config file. Mostly for
-   *  tests; in production callers should let the provider auto-discover. */
-  oauthToken?: string
-  /** Override the Copilot config dir (defaults to `~/.config/github-copilot`).
-   *  Useful for tests and for Windows users on non-standard layouts. */
-  configDir?: string
-  /** Override the chat endpoint URL (handles users behind a proxy). */
-  chatEndpoint?: string
-  defaultModel?: string
-  defaultMaxTokens?: number
-  /** Editor stamp used in the request headers — Copilot rejects calls
-   *  without it. Override if you need to spoof a specific editor. */
-  editorVersion?: string
-  editorPluginVersion?: string
-  copilotIntegrationId?: string
-  /** Test seam: inject a transport. When set, no token exchange happens. */
-  transport?: ChatCompletionsTransport
-  /** Test seam: inject a pre-built session-token resolver, used to verify
-   *  refresh logic without making real HTTP calls. */
-  sessionTokenResolver?: () => Promise<CopilotSessionToken>
-}
-
-export class CopilotProvider extends ChatCompletionsProvider {
-  constructor(opts: CopilotProviderOptions = {}) {
-    const transport = opts.transport ?? buildCopilotTransport(opts)
-    super({
-      name: 'copilot',
-      transport,
-      defaultModel: opts.defaultModel ?? DEFAULT_MODEL,
-      defaultMaxTokens: opts.defaultMaxTokens ?? DEFAULT_MAX_TOKENS,
-      shapeRequest: stripUnsupportedFields,
-    })
-  }
-}
-
-/**
- * Copilot's chat endpoint rejects a few of the optional fields we send to
- * OpenAI proper (notably `stream_options.include_usage` in some rollouts).
- * Strip them so the request body is the conservative intersection.
- */
-function stripUnsupportedFields(body: ChatCompletionsRequest): ChatCompletionsRequest {
-  const { stream_options: _stream_options, ...rest } = body
-  return rest as ChatCompletionsRequest
-}
-
-function buildCopilotTransport(opts: CopilotProviderOptions): ChatCompletionsTransport {
-  const resolver = opts.sessionTokenResolver ?? createDefaultResolver(opts)
-  const cache = new TokenCache(resolver)
-  const editorVersion = opts.editorVersion ?? EDITOR_VERSION
-  const editorPluginVersion = opts.editorPluginVersion ?? EDITOR_PLUGIN_VERSION
-  const copilotIntegrationId = opts.copilotIntegrationId ?? COPILOT_INTEGRATION_ID
-
-  return async (body, signal) => {
-    const session = await cache.get()
-    const endpoint = opts.chatEndpoint ?? session.chatEndpoint ?? DEFAULT_CHAT_ENDPOINT
-    const headers: Record<string, string> = {
-      Authorization: `Bearer ${session.token}`,
-      'Content-Type': 'application/json',
-      Accept: 'text/event-stream',
-      'Editor-Version': editorVersion,
-      'Editor-Plugin-Version': editorPluginVersion,
-      'Copilot-Integration-Id': copilotIntegrationId,
-      'User-Agent': USER_AGENT,
-      'OpenAI-Intent': 'conversation-panel',
-    }
-    return fetch(endpoint, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify(body),
-      signal,
-    })
-  }
-}
-
-/** Caches the Copilot session token and refreshes when it nears expiry. */
-class TokenCache {
-  private current: CopilotSessionToken | null = null
-  private pending: Promise<CopilotSessionToken> | null = null
-
-  constructor(private readonly resolver: () => Promise<CopilotSessionToken>) {}
-
-  async get(): Promise<CopilotSessionToken> {
-    if (this.current && !this.isExpired(this.current)) return this.current
-    if (this.pending) return this.pending
-    this.pending = (async () => {
-      try {
-        const next = await this.resolver()
-        this.current = next
-        return next
-      } finally {
-        this.pending = null
-      }
-    })()
-    return this.pending
-  }
-
-  private isExpired(token: CopilotSessionToken): boolean {
-    const expMs = token.expiresAt * 1000
-    return Date.now() > expMs - TOKEN_REFRESH_SLACK_MS
-  }
-}
-
-function createDefaultResolver(
-  opts: CopilotProviderOptions,
-): () => Promise<CopilotSessionToken> {
-  return async () => {
-    const oauthToken = opts.oauthToken ?? (await readOAuthToken(opts.configDir))
-    return exchangeOAuthForSessionToken(oauthToken, {
-      editorVersion: opts.editorVersion ?? EDITOR_VERSION,
-      editorPluginVersion: opts.editorPluginVersion ?? EDITOR_PLUGIN_VERSION,
-    })
-  }
-}
-
-/**
- * Read the OAuth token from the Copilot config files. Tries `apps.json` first
- * (used by `gh auth login --web` and the newer Copilot CLI), falling back to
- * `hosts.json` (older clients).
- */
-export async function readOAuthToken(
-  configDir: string = path.join(os.homedir(), '.config', 'github-copilot'),
-): Promise<string> {
-  const candidates = ['apps.json', 'hosts.json']
-  const errors: string[] = []
-  for (const name of candidates) {
-    const file = path.join(configDir, name)
-    try {
-      const raw = await fs.readFile(file, 'utf8')
-      const parsed = JSON.parse(raw) as Record<string, { oauth_token?: string, token?: string }>
-      for (const entry of Object.values(parsed)) {
-        const token = entry?.oauth_token ?? entry?.token
-        if (typeof token === 'string' && token.length > 0) return token
-      }
-      errors.push(`${name} had no oauth_token`)
-    } catch (err: any) {
-      if (err?.code === 'ENOENT') continue
-      errors.push(`${name}: ${err?.message ?? String(err)}`)
-    }
-  }
-  throw new Error(
-    `[annotask] No GitHub Copilot OAuth token found under ${configDir}. ` +
-      `Sign in with the GitHub Copilot extension or \`gh auth login\` first.` +
-      (errors.length > 0 ? ` (${errors.join('; ')})` : ''),
-  )
-}
-
-/**
- * Exchange a GitHub OAuth token for a short-lived Copilot session token.
- * Exposed for the smoke test and for ops scripts that want to verify auth
- * out-of-band without sending a full chat call.
- */
-export async function exchangeOAuthForSessionToken(
-  oauthToken: string,
-  opts: { editorVersion?: string, editorPluginVersion?: string } = {},
-): Promise<CopilotSessionToken> {
-  const res = await fetch(SESSION_TOKEN_URL, {
-    method: 'GET',
-    headers: {
-      Authorization: `token ${oauthToken}`,
-      Accept: 'application/json',
-      'Editor-Version': opts.editorVersion ?? EDITOR_VERSION,
-      'Editor-Plugin-Version': opts.editorPluginVersion ?? EDITOR_PLUGIN_VERSION,
-      'User-Agent': USER_AGENT,
-    },
-  })
-  if (!res.ok) {
-    const text = await res.text().catch(() => '')
-    throw new Error(
-      `[annotask] Copilot session-token exchange failed: HTTP ${res.status} ${text.slice(0, 256)}`,
-    )
-  }
-  const body = (await res.json()) as {
-    token?: string
-    expires_at?: number
-    endpoints?: { api?: string }
-  }
-  if (!body.token || typeof body.expires_at !== 'number') {
-    throw new Error(
-      '[annotask] Copilot session-token response missing `token`/`expires_at` — ' +
-        'GitHub may have changed the contract; run the Copilot smoke test.',
-    )
-  }
-  const api = body.endpoints?.api
-  return {
-    token: body.token,
-    expiresAt: body.expires_at,
-    chatEndpoint: api ? `${api.replace(/\/+$/, '')}/chat/completions` : undefined,
-  }
-}
diff --git a/src/embedded/event-log.ts b/src/embedded/event-log.ts
new file mode 100644
index 0000000..9c10000
--- /dev/null
+++ b/src/embedded/event-log.ts
@@ -0,0 +1,274 @@
+/**
+ * Local-only provider event log.
+ *
+ * Captures one row per provider turn (and per tool call) for inspection in
+ * the AI settings panel and to support debugging. Strict requirements:
+ *
+ * 1. **No network egress.** This module is forbidden from making any
+ *    `fetch`/XHR/network call. It writes to an in-memory ring buffer that
+ *    can optionally persist into `localStorage` (caller-controlled).
+ * 2. **Bounded memory.** Old rows are evicted when the buffer cap is hit,
+ *    so a long session can't grow without bound.
+ * 3. **No secret leakage.** Rows store counts and labels, not message
+ *    bodies. Tool-call arguments are recorded as a JSON sketch (top-level
+ *    keys only) — never the full payload.
+ *
+ * The log is meant for the user — never for telemetry to a hosted server.
+ */
+
+export type ProviderEventKind = 'turn' | 'tool_call' | 'tool_result' | 'error'
+
+export interface BaseEventRow {
+  /** Monotonic id assigned on append. */
+  id: number
+  /** Wall-clock timestamp (ms since epoch) of the recorded event. */
+  ts: number
+  /** Conversation/task this event belongs to. */
+  conversationId: string
+  kind: ProviderEventKind
+}
+
+export interface TurnEventRow extends BaseEventRow {
+  kind: 'turn'
+  provider: string
+  model: string
+  /** Tokens billed at the standard input rate. */
+  inputTokens: number
+  /** Tokens billed at the output rate. */
+  outputTokens: number
+  /** Cache-read tokens, when the provider exposes them. */
+  cacheReadTokens?: number
+  /** Cache-write tokens, when the provider exposes them. */
+  cacheCreationTokens?: number
+  /** Wall-clock latency, in milliseconds, from request to terminal event. */
+  latencyMs: number
+  /** Optional reason emitted by the provider (`'end_turn'`, `'tool_use'`, …). */
+  stopReason?: string
+}
+
+export interface ToolCallEventRow extends BaseEventRow {
+  kind: 'tool_call'
+  provider: string
+  model: string
+  /** Tool name the model invoked. */
+  toolName: string
+  /** Provider tool-call id, so we can pair the eventual `tool_result`. */
+  toolUseId: string
+  /** Top-level keys of the tool input. Never the values. */
+  inputKeys: string[]
+}
+
+export interface ToolResultEventRow extends BaseEventRow {
+  kind: 'tool_result'
+  toolUseId: string
+  toolName: string
+  /** True iff the tool reported an error rather than a normal result. */
+  isError: boolean
+  /** Wall-clock latency from `tool_call` append to `tool_result` append. */
+  latencyMs: number
+}
+
+export interface ErrorEventRow extends BaseEventRow {
+  kind: 'error'
+  provider: string
+  model: string
+  /** Short label (`network`, `rate_limit`, `cap_exceeded`, …). */
+  reason: string
+  /** Optional human-readable detail. Already-redacted. */
+  detail?: string
+}
+
+export type EventRow = TurnEventRow | ToolCallEventRow | ToolResultEventRow | ErrorEventRow
+
+export type EventInput =
+  | (Omit<TurnEventRow, 'id' | 'ts'> & { ts?: number })
+  | (Omit<ToolCallEventRow, 'id' | 'ts'> & { ts?: number })
+  | (Omit<ToolResultEventRow, 'id' | 'ts'> & { ts?: number })
+  | (Omit<ErrorEventRow, 'id' | 'ts'> & { ts?: number })
+
+export interface EventLogOptions {
+  /** Max rows held in memory. Older rows are dropped. Defaults to 500. */
+  capacity?: number
+  /**
+   * Optional sink for persisted reads/writes. Pass `localStorage` in the
+   * shell; tests can pass an in-memory shim or omit entirely.
+   */
+  persistence?: PersistenceSink
+  /** Persistence storage key. Defaults to `annotask:ai:eventLog`. */
+  persistenceKey?: string
+  /** Clock injection seam for deterministic tests. Defaults to `Date.now`. */
+  now?: () => number
+}
+
+export interface PersistenceSink {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+}
+
+const DEFAULT_CAPACITY = 500
+const DEFAULT_PERSISTENCE_KEY = 'annotask:ai:eventLog'
+
+export class EventLog {
+  private rows: EventRow[] = []
+  private nextId = 1
+  private listeners = new Set<(rows: ReadonlyArray<EventRow>) => void>()
+  private readonly capacity: number
+  private readonly persistence?: PersistenceSink
+  private readonly persistenceKey: string
+  private readonly now: () => number
+
+  constructor(options: EventLogOptions = {}) {
+    this.capacity = options.capacity ?? DEFAULT_CAPACITY
+    if (!(this.capacity > 0)) {
+      throw new Error(`EventLog: capacity must be > 0, got ${this.capacity}`)
+    }
+    this.persistence = options.persistence
+    this.persistenceKey = options.persistenceKey ?? DEFAULT_PERSISTENCE_KEY
+    this.now = options.now ?? (() => Date.now())
+    this.hydrate()
+  }
+
+  append(event: EventInput): EventRow {
+    const row = {
+      ...(event as object),
+      id: this.nextId++,
+      ts: event.ts ?? this.now(),
+    } as EventRow
+    this.rows.push(row)
+    if (this.rows.length > this.capacity) {
+      // Drop the oldest rows. We drop from the front rather than mutating
+      // in-place so the listeners always see a stable list.
+      this.rows = this.rows.slice(this.rows.length - this.capacity)
+    }
+    this.persist()
+    this.notify()
+    return row
+  }
+
+  /**
+   * Idiomatic helper for the runner: builds a `tool_call` row with the
+   * top-level argument keys captured for inspection.
+   */
+  appendToolCall(args: {
+    conversationId: string
+    provider: string
+    model: string
+    toolName: string
+    toolUseId: string
+    input: unknown
+  }): ToolCallEventRow {
+    const inputKeys =
+      args.input && typeof args.input === 'object' && !Array.isArray(args.input)
+        ? Object.keys(args.input as Record<string, unknown>)
+        : []
+    return this.append({
+      kind: 'tool_call',
+      conversationId: args.conversationId,
+      provider: args.provider,
+      model: args.model,
+      toolName: args.toolName,
+      toolUseId: args.toolUseId,
+      inputKeys,
+    }) as ToolCallEventRow
+  }
+
+  list(): ReadonlyArray<EventRow> {
+    return this.rows
+  }
+
+  /**
+   * Filter helper used by the AI panel's "Activity" view.
+   */
+  filter(predicate: (row: EventRow) => boolean): ReadonlyArray<EventRow> {
+    return this.rows.filter(predicate)
+  }
+
+  clear(): void {
+    if (this.rows.length === 0) return
+    this.rows = []
+    this.persist()
+    this.notify()
+  }
+
+  /**
+   * Subscribe to log updates. Returns an unsubscribe function. The
+   * listener is called with the new row list after every append/clear.
+   */
+  subscribe(listener: (rows: ReadonlyArray<EventRow>) => void): () => void {
+    this.listeners.add(listener)
+    return () => {
+      this.listeners.delete(listener)
+    }
+  }
+
+  /**
+   * Aggregate totals across all `turn` rows. Useful for the per-task token
+   * meter in the composer (`ProviderEvent.usage`-style readout).
+   */
+  totalsByConversation(conversationId: string): {
+    inputTokens: number
+    outputTokens: number
+    cacheReadTokens: number
+    cacheCreationTokens: number
+    turns: number
+  } {
+    let inputTokens = 0
+    let outputTokens = 0
+    let cacheReadTokens = 0
+    let cacheCreationTokens = 0
+    let turns = 0
+    for (const row of this.rows) {
+      if (row.kind !== 'turn' || row.conversationId !== conversationId) continue
+      inputTokens += row.inputTokens
+      outputTokens += row.outputTokens
+      cacheReadTokens += row.cacheReadTokens ?? 0
+      cacheCreationTokens += row.cacheCreationTokens ?? 0
+      turns += 1
+    }
+    return { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens, turns }
+  }
+
+  private persist(): void {
+    if (!this.persistence) return
+    try {
+      this.persistence.setItem(this.persistenceKey, JSON.stringify({
+        nextId: this.nextId,
+        rows: this.rows,
+      }))
+    } catch {
+      // Persistence is best-effort — quota or serialization errors must not
+      // break the runner.
+    }
+  }
+
+  private hydrate(): void {
+    if (!this.persistence) return
+    try {
+      const raw = this.persistence.getItem(this.persistenceKey)
+      if (!raw) return
+      const parsed = JSON.parse(raw) as { nextId?: number; rows?: EventRow[] }
+      if (Array.isArray(parsed.rows)) {
+        this.rows = parsed.rows.slice(-this.capacity)
+      }
+      if (typeof parsed.nextId === 'number' && parsed.nextId > this.nextId) {
+        this.nextId = parsed.nextId
+      }
+    } catch {
+      // Corrupt persisted state — discard and start clean.
+      this.persistence.removeItem(this.persistenceKey)
+    }
+  }
+
+  private notify(): void {
+    if (this.listeners.size === 0) return
+    const snapshot = this.rows
+    for (const l of this.listeners) {
+      try {
+        l(snapshot)
+      } catch {
+        // Listener failure must not break appends.
+      }
+    }
+  }
+}
diff --git a/src/embedded/index.ts b/src/embedded/index.ts
index c2e71b9..c6b6b64 100644
--- a/src/embedded/index.ts
+++ b/src/embedded/index.ts
@@ -33,15 +33,34 @@ export {
 } from './chat-completions.js'
 
 export { OpenAIProvider, type OpenAIProviderOptions } from './openai-provider.js'
+export { OpenRouterProvider, type OpenRouterProviderOptions } from './openrouter-provider.js'
 export {
   OpenAICompatibleProvider,
   type OpenAICompatibleProviderOptions,
 } from './openai-compatible-provider.js'
-export {
-  CopilotProvider,
-  readOAuthToken,
-  exchangeOAuthForSessionToken,
-  type CopilotProviderOptions,
-  type CopilotSessionToken,
-} from './copilot-provider.js'
 export { PaperclipProvider, type PaperclipProviderOptions } from './paperclip-provider.js'
+export {
+  CliLocalProvider,
+  flattenMessagesAsPrompt,
+  lastUserMessageText,
+  type CliLocalProviderConfig,
+  type ParsedLineResult,
+  type SpawnRequest,
+} from './cli-local-provider.js'
+export {
+  ClaudeLocalProvider,
+  mapClaudeEvent,
+  type ClaudeLocalProviderOptions,
+} from './claude-local-provider.js'
+export {
+  CodexLocalProvider,
+  mapCodexEvent,
+  type CodexLocalProviderOptions,
+} from './codex-local-provider.js'
+export {
+  OpencodeLocalProvider,
+  mapOpencodeEvent,
+  type OpencodeLocalProviderOptions,
+} from './opencode-local-provider.js'
+
+export { makeProvider, type MakeProviderContext } from './provider-factory.js'
diff --git a/src/embedded/opencode-local-provider.ts b/src/embedded/opencode-local-provider.ts
new file mode 100644
index 0000000..4c1a239
--- /dev/null
+++ b/src/embedded/opencode-local-provider.ts
@@ -0,0 +1,201 @@
+/**
+ * opencode CLI (local) provider.
+ *
+ * Spawns `opencode run --print-logs --format=json <prompt>` (opencode v0.x
+ * uses positional prompt + JSON event stream). Each stdout line is one
+ * JSON event; we surface assistant text and rely on the base class for
+ * exit handling.
+ *
+ * opencode's JSON event surface is fluid across releases. We accept a
+ * handful of likely shapes (`type: 'text'`, `type: 'message'` with content
+ * blocks, plus a `text` top-level key as a fallback) so this keeps
+ * working when opencode bumps. Unknown shapes drop silently — better to
+ * lose a token than to crash the chat.
+ */
+
+import {
+  CliLocalProvider,
+  rollupHistoryAsPrompt,
+  type ParsedLineResult,
+  type SpawnRequest,
+} from './cli-local-provider.js'
+import { opencodePermissionFlags, defaultPermissionModeFor } from './permission-mode-flags.js'
+import type {
+  ProviderEvent,
+  ProviderMessage,
+  ProviderTool,
+  StreamOptions,
+} from './provider.js'
+
+export interface OpencodeLocalProviderOptions {
+  /** Optional model id passed to `opencode run --model`. */
+  model?: string
+  extraArgs?: string[]
+  spawnUrl?: string
+  fetchImpl?: typeof fetch
+}
+
+export class OpencodeLocalProvider extends CliLocalProvider {
+  private readonly model?: string
+  private readonly extraArgs: string[]
+
+  constructor(opts: OpencodeLocalProviderOptions = {}) {
+    super({
+      name: 'opencode-local',
+      spawnUrl: opts.spawnUrl,
+      fetchImpl: opts.fetchImpl,
+    })
+    this.model = opts.model?.trim() || undefined
+    this.extraArgs = (opts.extraArgs ?? []).filter((s) => s.trim().length > 0)
+  }
+
+  protected buildSpawn(
+    messages: ProviderMessage[],
+    _tools: ProviderTool[],
+    options: StreamOptions,
+  ): SpawnRequest {
+    const args = ['run', '--print-logs', '--format=json']
+    // Opencode only exposes a single `--dangerously-skip-permissions` toggle
+    // in headless `run`; non-bypass modes omit it. Plan and default collapse
+    // to the same behavior — the CLI doesn't surface finer granularity.
+    // See permission-mode-flags.ts for the rationale.
+    args.push(...opencodePermissionFlags(options.permissionMode ?? defaultPermissionModeFor('opencode')))
+    if (this.model) args.push('--model', this.model)
+    args.push(...this.extraArgs)
+    // Prepend the annotask system prompt to the positional — opencode has
+    // no separate system-prompt flag in headless mode — and roll up the
+    // prior turns as a transcript, since each turn spawns a fresh
+    // `opencode run` with no memory of its own. The `--` separator is
+    // required: skill bodies often start with `---` (YAML frontmatter),
+    // and without it the CLI parses the leading `--` as an unknown long flag.
+    args.push('--', rollupHistoryAsPrompt(messages, options.systemPrompt))
+    return { cli: 'opencode', args }
+  }
+
+  protected parseStdoutLine(line: string): ParsedLineResult {
+    const trimmed = line.trim()
+    if (!trimmed) return []
+    let event: OpencodeEvent
+    try { event = JSON.parse(trimmed) as OpencodeEvent }
+    catch { return [] }
+    return mapOpencodeEvent(event)
+  }
+}
+
+interface OpencodeEvent {
+  type?: string
+  text?: string
+  content?: string | Array<OpencodeContentBlock>
+  // opencode v1.14+ wraps payloads inside a `part` envelope alongside the
+  // top-level `type`. Text events look like:
+  //   { type: 'text', part: { type: 'text', text: '...' } }
+  // step_finish carries the run's usage totals:
+  //   { type: 'step_finish', part: { type: 'step-finish',
+  //       tokens: { input, output, cache: { read, write } }, reason, ... } }
+  part?: OpencodePart
+  // Tool envelopes that some versions emit at the top level.
+  id?: string
+  name?: string
+  input?: unknown
+  call_id?: string
+  output?: unknown
+  is_error?: boolean
+  usage?: { input_tokens?: number; output_tokens?: number }
+  [extra: string]: unknown
+}
+
+interface OpencodePart {
+  type?: string
+  text?: string
+  tokens?: {
+    input?: number
+    output?: number
+    cache?: { read?: number; write?: number }
+  }
+  [extra: string]: unknown
+}
+
+interface OpencodeContentBlock {
+  type?: string
+  text?: string
+  id?: string
+  name?: string
+  input?: unknown
+  tool_use_id?: string
+  content?: unknown
+  is_error?: boolean
+}
+
+export function mapOpencodeEvent(ev: OpencodeEvent): ProviderEvent[] {
+  const out: ProviderEvent[] = []
+  // Text-bearing shapes:
+  //   1. v1.14+: { type: 'text', part: { type: 'text', text } }
+  //   2. v1.14+: step_finish event carries usage totals on part.tokens
+  //   3. legacy: { type: 'text',    text }
+  //   4. legacy: { type: 'assistant', text }
+  //   5. legacy: { type: 'message', content: 'string' | block[] }
+  if (ev.type === 'text' && ev.part && typeof ev.part.text === 'string') {
+    out.push({ type: 'text', text: ev.part.text })
+  } else if (ev.type === 'text' && typeof ev.text === 'string') {
+    out.push({ type: 'text', text: ev.text })
+  } else if (ev.type === 'assistant' && typeof ev.text === 'string') {
+    out.push({ type: 'text', text: ev.text })
+  } else if (typeof ev.content === 'string' && ev.content.length > 0) {
+    out.push({ type: 'text', text: ev.content })
+  } else if (Array.isArray(ev.content)) {
+    for (const block of ev.content) {
+      if (!block || typeof block.type !== 'string') continue
+      if (block.type === 'text' && typeof block.text === 'string') {
+        out.push({ type: 'text', text: block.text })
+      } else if (block.type === 'tool_use' && typeof block.id === 'string' && typeof block.name === 'string') {
+        out.push({ type: 'tool_call', id: block.id, name: block.name, input: block.input ?? {} })
+      } else if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') {
+        out.push({
+          type: 'tool_result',
+          toolUseId: block.tool_use_id,
+          content: coerceToString(block.content),
+          isError: block.is_error === true ? true : undefined,
+        })
+      }
+    }
+  }
+  // Tool envelopes at the top level (newer opencode shapes).
+  if (ev.type === 'tool_call' && typeof ev.id === 'string' && typeof ev.name === 'string') {
+    out.push({ type: 'tool_call', id: ev.id, name: ev.name, input: ev.input ?? {} })
+  }
+  if (ev.type === 'tool_result' && typeof ev.call_id === 'string') {
+    out.push({
+      type: 'tool_result',
+      toolUseId: ev.call_id,
+      content: coerceToString(ev.output),
+      isError: ev.is_error === true ? true : undefined,
+    })
+  }
+  if (ev.usage && (ev.usage.input_tokens || ev.usage.output_tokens)) {
+    out.push({
+      type: 'usage',
+      inputTokens: ev.usage.input_tokens ?? 0,
+      outputTokens: ev.usage.output_tokens ?? 0,
+    })
+  }
+  // v1.14+: step_finish carries the turn's token totals on part.tokens.
+  if (ev.type === 'step_finish' && ev.part?.tokens) {
+    const t = ev.part.tokens
+    if (typeof t.input === 'number' || typeof t.output === 'number') {
+      out.push({
+        type: 'usage',
+        inputTokens: t.input ?? 0,
+        outputTokens: t.output ?? 0,
+        cacheReadTokens: t.cache?.read,
+        cacheCreationTokens: t.cache?.write,
+      })
+    }
+  }
+  return out
+}
+
+function coerceToString(v: unknown): string {
+  if (typeof v === 'string') return v
+  if (v == null) return ''
+  try { return JSON.stringify(v) } catch { return String(v) }
+}
diff --git a/src/embedded/openrouter-provider.ts b/src/embedded/openrouter-provider.ts
new file mode 100644
index 0000000..e29d54d
--- /dev/null
+++ b/src/embedded/openrouter-provider.ts
@@ -0,0 +1,66 @@
+/**
+ * OpenRouter provider.
+ *
+ * OpenRouter speaks the OpenAI Chat Completions wire format, so this is a
+ * thin specialisation: fixed default base URL, OpenRouter-recommended
+ * attribution headers (`HTTP-Referer`, `X-Title`), and a default model
+ * that's available on the free tier so first-run users see *something*
+ * even before they pick a model.
+ *
+ * See https://openrouter.ai/docs#headers — the attribution headers are
+ * optional, but recommended for app-level analytics on the OpenRouter side.
+ */
+
+import {
+  ChatCompletionsProvider,
+  type ChatCompletionsTransport,
+  createFetchTransport,
+} from './chat-completions.js'
+
+const DEFAULT_BASE_URL = 'https://openrouter.ai/api/v1'
+const DEFAULT_MODEL = 'openai/gpt-4o-mini'
+const DEFAULT_MAX_TOKENS = 4096
+
+export interface OpenRouterProviderOptions {
+  /** Required: the user's OpenRouter API key. */
+  apiKey?: string
+  /** Override the base URL (defaults to https://openrouter.ai/api/v1). */
+  baseURL?: string
+  /** Optional referer for OpenRouter analytics. Falls back to `http://localhost`. */
+  referer?: string
+  /** Optional app title for OpenRouter analytics. Falls back to `Annotask`. */
+  appTitle?: string
+  defaultModel?: string
+  defaultMaxTokens?: number
+  /** Test seam: inject a transport that returns a synthetic SSE Response. */
+  transport?: ChatCompletionsTransport
+}
+
+export class OpenRouterProvider extends ChatCompletionsProvider {
+  constructor(opts: OpenRouterProviderOptions = {}) {
+    const transport = opts.transport ?? buildOpenRouterTransport(opts)
+    super({
+      name: 'openrouter',
+      transport,
+      defaultModel: opts.defaultModel ?? DEFAULT_MODEL,
+      defaultMaxTokens: opts.defaultMaxTokens ?? DEFAULT_MAX_TOKENS,
+    })
+  }
+}
+
+function buildOpenRouterTransport(opts: OpenRouterProviderOptions): ChatCompletionsTransport {
+  const baseURL = (opts.baseURL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, '')
+  const endpoint = `${baseURL}/chat/completions`
+  return createFetchTransport(endpoint, () => {
+    if (!opts.apiKey) {
+      throw new Error(
+        '[annotask] OpenRouterProvider requires `apiKey`. Get one at https://openrouter.ai/keys.',
+      )
+    }
+    return {
+      Authorization: `Bearer ${opts.apiKey}`,
+      'HTTP-Referer': opts.referer || 'http://localhost',
+      'X-Title': opts.appTitle || 'Annotask',
+    }
+  })
+}
diff --git a/src/embedded/permission-mode-flags.ts b/src/embedded/permission-mode-flags.ts
new file mode 100644
index 0000000..f43002a
--- /dev/null
+++ b/src/embedded/permission-mode-flags.ts
@@ -0,0 +1,199 @@
+/**
+ * Translate a normalized `PermissionMode` into each CLI's own permission flags,
+ * plus a system-prompt prefix that enforces `plan` mode at the model level on
+ * CLIs that don't have a native read-only flag.
+ *
+ * Why two surfaces (flags + prompt prefix):
+ *   - claude-local has a real `--permission-mode plan` flag (CLI-enforced).
+ *   - codex-local has `--sandbox read-only` (OS-enforced — writes fail at the
+ *     sandbox boundary even if the model tries).
+ *   - opencode-local headless `run` has only `--dangerously-skip-permissions`
+ *     (no native plan equivalent).
+ *   - copilot-local headless `-p` REQUIRES `--allow-all-tools` to run at all
+ *     and has no native plan mode.
+ *
+ * To deliver plan mode uniformly across all four, we layer a strong
+ * system-prompt directive when mode === 'plan'. The native flag still does the
+ * heavy lifting on claude/codex (refusal can't be jailbroken); the prompt
+ * directive is the only lever on opencode/copilot and is enforced at the
+ * model layer (the model refuses write tools because the prompt told it to).
+ *
+ * Per-CLI flag surfaces observed at implementation time:
+ *
+ *   claude   --permission-mode <default|plan>
+ *            --dangerously-skip-permissions               (bypass shorthand)
+ *   codex    -s/--sandbox <read-only|workspace-write|danger-full-access>
+ *            --full-auto                                  (workspace-write)
+ *            --dangerously-bypass-approvals-and-sandbox
+ *   opencode --dangerously-skip-permissions               (single boolean)
+ *   copilot  --allow-all-tools                            (REQUIRED for `-p`)
+ *            --no-ask-user
+ *            --allow-all
+ */
+
+import type { PermissionMode } from '../schema.js'
+
+/**
+ * Claude Code CLI. 1:1 mapping — claude exposes plan/default/bypass natively.
+ *
+ * Bypass uses `--dangerously-skip-permissions` rather than the equivalent
+ * `--permission-mode bypassPermissions` form because the dangerously-prefixed
+ * flag is the one Claude surfaces in its own error messages (e.g. when it
+ * refuses to run as root), matches the bypass-flag naming on codex / opencode,
+ * and is what users will recognize when reading docs or stderr.
+ */
+export function claudePermissionFlags(mode: PermissionMode): string[] {
+  switch (mode) {
+    case 'default': return ['--permission-mode', 'default']
+    case 'plan':    return ['--permission-mode', 'plan']
+    case 'bypass':  return ['--dangerously-skip-permissions']
+  }
+}
+
+/**
+ * Codex CLI: sandbox-driven. `plan` clamps to `read-only` (OS-enforced);
+ * `default` uses `--full-auto` (workspace-write, on-request approvals — but
+ * approvals don't surface in non-interactive `exec`, so effectively
+ * workspace-write); `bypass` removes the sandbox entirely.
+ */
+export function codexPermissionFlags(mode: PermissionMode): string[] {
+  switch (mode) {
+    case 'default': return ['--full-auto']
+    case 'plan':    return ['--sandbox', 'read-only']
+    case 'bypass':  return ['--dangerously-bypass-approvals-and-sandbox']
+  }
+}
+
+/**
+ * Opencode CLI: only `--dangerously-skip-permissions` is exposed in headless
+ * `run`. Default and plan both omit it; plan additionally relies on the
+ * system-prompt directive from `permissionModeSystemPromptPrefix` to enforce
+ * read-only at the model layer.
+ */
+export function opencodePermissionFlags(mode: PermissionMode): string[] {
+  if (mode === 'bypass') return ['--dangerously-skip-permissions']
+  return []
+}
+
+/**
+ * Copilot CLI: headless `-p` mode requires `--allow-all-tools` to run at all,
+ * so even `plan` keeps it. The model-layer plan directive does the actual
+ * read-only enforcement on this CLI. `bypass` additionally enables
+ * `--allow-all` (paths + URLs + tools).
+ */
+export function copilotPermissionFlags(mode: PermissionMode): string[] {
+  switch (mode) {
+    case 'bypass':  return ['--allow-all', '--allow-all-tools', '--no-ask-user']
+    case 'default':
+    case 'plan':    return ['--allow-all-tools', '--no-ask-user']
+  }
+}
+
+/**
+ * Local-CLI bin names recognized by the init pipeline. Kept in this file
+ * (rather than init.ts) so `initPermissionModeFor` and the AgentQuickSetup
+ * warning copy can share the same surface.
+ */
+export type InitCliBin = 'claude' | 'codex' | 'opencode' | 'copilot'
+
+/**
+ * CLIs that have NO headless "ask / workspace-write" mode — for them `default`
+ * cannot run autonomously (the call either blocks on a permission prompt with
+ * no human to answer, or refuses tools outright), so `default` has to escalate
+ * to `bypass` to do anything at all.
+ *
+ *   claude   — headless `default` blocks Bash/grep tool calls; no native
+ *              workspace-write mode exists.
+ *   opencode — headless `run` exposes only `--dangerously-skip-permissions`;
+ *              `default` emits no flag and stalls on the first write prompt.
+ *
+ * codex (`--full-auto`, an OS-enforced workspace-write sandbox) and copilot
+ * (`--allow-all-tools --no-ask-user`, the minimum `-p` requires) DO honor
+ * `default` headlessly, and those modes are strictly safer than `bypass`, so
+ * they are left untouched.
+ */
+const NO_HEADLESS_DEFAULT: ReadonlySet<InitCliBin> = new Set(['claude', 'opencode'])
+
+/**
+ * Map a *requested* permission mode to the mode that actually runs headlessly
+ * on the given CLI. The only adjustment is `default` → `bypass` on the CLIs in
+ * `NO_HEADLESS_DEFAULT`; every other (cli, mode) pair passes through unchanged.
+ *
+ * This is what makes `'default'` a safe, working out-of-box default: codex and
+ * copilot keep their sandboxed/minimal modes, while claude and opencode — which
+ * have no headless ask-mode — fall back to the only thing that works for them.
+ * Plan and bypass are never rewritten (plan is read-only everywhere; bypass is
+ * already maximal).
+ */
+export function normalizeHeadlessMode(mode: PermissionMode, bin: InitCliBin): PermissionMode {
+  if (mode === 'default' && NO_HEADLESS_DEFAULT.has(bin)) return 'bypass'
+  return mode
+}
+
+/**
+ * The out-of-box default permission mode for a given CLI: the least-permissive
+ * mode that still lets the agent apply tasks headlessly. Equivalent to
+ * `normalizeHeadlessMode('default', bin)` — codex/copilot → `default`
+ * (sandboxed/minimal), claude/opencode → `bypass` (no headless ask-mode).
+ *
+ * Used as the fail-safe fallback in each provider's `buildSpawn` so a missing
+ * resolved mode lands on the CLI's safe default rather than blanket `bypass`.
+ */
+export function defaultPermissionModeFor(bin: InitCliBin): PermissionMode {
+  return normalizeHeadlessMode('default', bin)
+}
+
+/**
+ * Least-permissive `PermissionMode` that still lets the headless init agent
+ * write into `.annotask/` for each CLI. Init runs `--print` / `exec` / `run`
+ * / `-p` with stdin closed, so it can never answer an interactive permission
+ * prompt — the choice is "permissive enough to write, or the run hangs/refuses."
+ * Identical to `defaultPermissionModeFor`: init wants the same safe-but-working
+ * mode the per-task runner now defaults to.
+ */
+export function initPermissionModeFor(bin: InitCliBin): PermissionMode {
+  return defaultPermissionModeFor(bin)
+}
+
+/** Resolved init-mode flags per CLI — what spawnCliWithSkill actually passes. */
+export function initPermissionFlagsFor(bin: InitCliBin): string[] {
+  const mode = initPermissionModeFor(bin)
+  switch (bin) {
+    case 'claude':   return claudePermissionFlags(mode)
+    case 'codex':    return codexPermissionFlags(mode)
+    case 'opencode': return opencodePermissionFlags(mode)
+    case 'copilot':  return copilotPermissionFlags(mode)
+  }
+}
+
+/**
+ * Optional system-prompt directive prepended to the persona/skill system
+ * prompt. Plan mode is the only one that needs this — claude and codex enforce
+ * read-only at the CLI/OS layer regardless, and the directive reinforces them;
+ * opencode and copilot have no native plan mode, so the directive is the only
+ * line of defense and must be strong enough to make the model refuse on its
+ * own.
+ *
+ * Returns an empty string for `default` and `bypass` so the system prompt
+ * stays unchanged in the common case.
+ */
+export function permissionModeSystemPromptPrefix(mode: PermissionMode): string {
+  if (mode !== 'plan') return ''
+  return [
+    '## PLAN MODE — READ-ONLY',
+    '',
+    'You are running in plan mode for this turn. Do NOT call any tool that',
+    'writes, edits, deletes, or executes commands. Allowed: reading files,',
+    'searching code, inspecting state, viewing structure. Forbidden: file',
+    'edits, shell commands, network mutations, package installs, git writes,',
+    'or any side effect that changes the project or system.',
+    '',
+    'Your job is to produce a written plan describing what you WOULD do, with',
+    'concrete file paths, line ranges, and code snippets. Do not apply any',
+    'changes — even partial ones.',
+    '',
+    "If the user's request requires a write to satisfy, say so explicitly and",
+    'stop. The user will re-run the task in a different permission mode if',
+    'they want the change applied.',
+  ].join('\n')
+}
diff --git a/src/embedded/permission-mode.ts b/src/embedded/permission-mode.ts
new file mode 100644
index 0000000..26c1b9f
--- /dev/null
+++ b/src/embedded/permission-mode.ts
@@ -0,0 +1,64 @@
+/**
+ * Permission-mode helpers shared between the shell UI and the provider stream
+ * options. The canonical type + enum live in `src/schema.ts` (alongside
+ * TASK_TYPES) since they cross the wire to the server and to MCP boundaries.
+ *
+ * Three tiers:
+ *   - global   — `ProviderSettings.permissionMode`, set in the General tab.
+ *                Floor for all providers and the default for new ones.
+ *   - provider — `ProviderConfig.permissionMode` on each local-CLI provider.
+ *                Optional per-provider override (set in Provider settings).
+ *   - task     — `AnnotaskTask.permissionMode`, flipped via the chip menu in
+ *                the Conversation tab or the dropdown in Task details.
+ *
+ * Resolution: `task ?? provider ?? global ?? 'bypass'`. Global always has a
+ * value (the schema defaults it to `'bypass'` for back-compat with installs
+ * predating the feature).
+ */
+
+import { z } from 'zod'
+import { PERMISSION_MODES, type PermissionMode } from '../schema.js'
+
+export { PERMISSION_MODES, type PermissionMode } from '../schema.js'
+
+export const PermissionModeSchema = z.enum(PERMISSION_MODES)
+
+/**
+ * Resolve the effective permission mode for an agent run. First defined tier
+ * wins (task > provider > global). `'bypass'` is the historical fallback so
+ * installs that haven't opted in still run with their old flags.
+ */
+export function resolveEffectivePermissionMode(
+  taskMode: PermissionMode | undefined | null,
+  providerMode: PermissionMode | undefined | null,
+  globalMode: PermissionMode | undefined | null,
+): PermissionMode {
+  if (taskMode) return taskMode
+  if (providerMode) return providerMode
+  if (globalMode) return globalMode
+  return 'bypass'
+}
+
+/**
+ * Providers whose `plan` (read-only) mode is enforced at the CLI/OS boundary —
+ * claude (`--permission-mode plan`) and codex (`--sandbox read-only`). opencode
+ * and copilot are deliberately absent: their headless modes have no native
+ * read-only flag, so plan there is best-effort (model-directive only, via
+ * `permissionModeSystemPromptPrefix`). Single source of truth for the UI hints
+ * that distinguish hard vs. soft plan enforcement.
+ */
+export const NATIVE_PLAN_PROVIDERS: ReadonlySet<string> = new Set(['claude-local', 'codex-local'])
+
+/** Human labels for the picker UI. */
+export const PERMISSION_MODE_LABELS: Record<PermissionMode, string> = {
+  default: 'Default — CLI asks for non-trivial actions',
+  plan: 'Plan — read-only, no writes',
+  bypass: 'Bypass — auto-approve everything',
+}
+
+/** Short labels for compact dropdowns. */
+export const PERMISSION_MODE_SHORT_LABELS: Record<PermissionMode, string> = {
+  default: 'Default',
+  plan: 'Plan',
+  bypass: 'Bypass',
+}
diff --git a/src/embedded/persona.ts b/src/embedded/persona.ts
new file mode 100644
index 0000000..c47e8af
--- /dev/null
+++ b/src/embedded/persona.ts
@@ -0,0 +1,210 @@
+/**
+ * Agent personas — named bundles of provider + model + effort + target task
+ * types. Each task picks a persona (or falls back to the global active
+ * provider) and the embedded runner resolves the persona's settings before
+ * spawning the provider. The system prompt is composed from the
+ * `annotask-apply` skill + the task-type companion playbook via the shared
+ * skills loader (see src/skills/loader.ts).
+ *
+ * Personas are additive: tasks without a `personaOverride` mapping keep
+ * today's "global activeProvider" behavior. Built-ins are read-only;
+ * customs (`custom:<uuid>`) are user-cloned and editable.
+ */
+
+import { z } from 'zod'
+// Type-only imports so we keep the strong static type without creating a
+// runtime cycle with provider-config.ts (which imports
+// `PersonaConfigSchema` from here at module load).
+import type { ProviderId, EffortLevel } from './provider-config.js'
+import { TASK_TYPES, type TaskType } from '../schema.js'
+
+const TaskTypeSchema = z.enum(TASK_TYPES)
+
+// Runtime enums duplicated here so PersonaConfigSchema doesn't have to pull
+// the schemas from provider-config. The corresponding TypeScript types
+// `ProviderId` / `EffortLevel` remain the single source of truth via the
+// type-only import above.
+const PROVIDER_ID_VALUES = [
+  'claude-local',
+  'codex-local',
+  'opencode-local',
+  'copilot-local',
+  'anthropic',
+  'openai',
+  'openrouter',
+  'openai-compatible',
+  'paperclip',
+] as const satisfies readonly ProviderId[]
+
+const EFFORT_VALUES = ['auto', 'minimal', 'low', 'medium', 'high'] as const satisfies readonly EffortLevel[]
+
+export const PersonaConfigSchema = z.object({
+  /** Stable id. Built-ins use a bare slug (`general`, `designer`, …); user
+   *  customs are prefixed `custom:` so the UI can flag them as editable. */
+  id: z.string().min(1),
+  /** Display name shown in the persona row + task picker. */
+  name: z.string().min(1),
+  /** Short one-line description of when the persona fires. */
+  description: z.string().default(''),
+  /** Task types this persona targets. Empty means "fallback for everything
+   *  not claimed by another persona." */
+  taskTypes: z.array(TaskTypeSchema).default([]),
+  /** Which provider this persona uses when it fires. */
+  providerId: z.enum(PROVIDER_ID_VALUES),
+  /** Override model id — empty means use the provider's default. */
+  model: z.string().default(''),
+  /** Reasoning-effort hint passed to the provider. `auto` lets the provider
+   *  pick its default. */
+  effort: z.enum(EFFORT_VALUES).default('auto'),
+  /** Built-in role identity for this persona ("You are a senior front-end
+   *  developer …"). Read-only for built-ins; also used as the seed value
+   *  for a user's editable `projectDirections` in `.annotask/agents.json`
+   *  so the panel starts with copy the user can tweak. */
+  roleDirections: z.string().default(''),
+  /** Extra system-prompt fragment appended after the skill+companion bundle.
+   *  Use for project-specific instructions like "always run lint after". */
+  systemPromptExtras: z.string().default(''),
+  /** True for user-cloned personas. The UI gates delete/rename on this. */
+  isCustom: z.boolean().default(false),
+})
+
+export type PersonaConfig = z.infer<typeof PersonaConfigSchema>
+
+/**
+ * Four built-in personas covering all task types. Keep this list
+ * stable — the ids are referenced from persisted `personaOverrides` maps,
+ * so renaming an id orphans existing overrides.
+ *
+ * Defaults to `claude-local` because (a) it's the most polished local CLI
+ * surface and (b) it can actually apply changes via its native file-edit
+ * tools (per Phase 3). Users on codex-local / opencode-local can clone any
+ * persona and swap the provider.
+ */
+export const BUILT_IN_PERSONAS: readonly PersonaConfig[] = [
+  {
+    id: 'general',
+    name: 'Frontend Developer',
+    description: 'Default for annotations and freeform requests.',
+    taskTypes: ['annotation', 'section_request', 'wireframe_apply'],
+    providerId: 'claude-local',
+    model: '',
+    effort: 'auto',
+    roleDirections:
+      'You are a senior front-end developer. You write idiomatic, modular code that follows the project\'s framework conventions (Vue, React, Svelte, SolidJS, Astro, or plain HTML), match existing patterns, and keep changes small and reviewable. You prefer editing existing files over creating new ones and avoid speculative abstractions.',
+    systemPromptExtras: '',
+    isCustom: false,
+  },
+  {
+    id: 'designer',
+    name: 'Designer',
+    description: 'CSS, design tokens, and visual styling work.',
+    taskTypes: ['style_update', 'theme_update'],
+    providerId: 'claude-local',
+    model: '',
+    effort: 'medium',
+    roleDirections:
+      'You are a UI/UX designer who codes. You translate visual edits into clean CSS and design-token changes, respect the project\'s existing tokens and theme variables, avoid hard-coded colors when a token exists, and keep typography, spacing, and color usage consistent across the app.',
+    systemPromptExtras: '',
+    isCustom: false,
+  },
+  {
+    id: 'a11y',
+    name: 'Accessibility',
+    description: 'WCAG fixes from the a11y scanner.',
+    taskTypes: ['a11y_fix'],
+    providerId: 'claude-local',
+    model: '',
+    effort: 'high',
+    roleDirections:
+      'You are a web accessibility expert fluent in WCAG 2.2, WAI-ARIA, and assistive-tech behavior. You produce minimal, semantically correct fixes — prefer native HTML semantics over ARIA, preserve keyboard navigation and focus order, and verify color-contrast and label associations rather than guessing.',
+    systemPromptExtras: '',
+    isCustom: false,
+  },
+  {
+    id: 'bug-hunter',
+    name: 'Bug Hunter',
+    description: 'Console errors and performance findings.',
+    taskTypes: ['error_fix', 'perf_fix'],
+    providerId: 'claude-local',
+    model: '',
+    effort: 'high',
+    roleDirections:
+      'You are an expert at diagnosing runtime errors and performance regressions. You read stack traces and Web Vitals carefully, fix root causes rather than symptoms, avoid swallowing errors, and only add error handling at real boundaries. You measure before optimizing and prefer targeted fixes over broad refactors.',
+    systemPromptExtras: '',
+    isCustom: false,
+  },
+]
+
+/**
+ * Resolve a task type to a persona. Priority:
+ *   1. Explicit `personaOverrides[taskType]` mapping (user-pinned).
+ *   2. Any persona whose `taskTypes` includes the type.
+ *   3. The `general` built-in (catch-all fallback).
+ *   4. `null` when even `general` is missing — caller falls back to global
+ *      activeProvider/model/effort.
+ */
+export function resolvePersonaForTaskType(
+  personas: readonly PersonaConfig[],
+  taskType: TaskType | string | undefined,
+  overrides: Record<string, string> = {},
+): PersonaConfig | null {
+  if (!taskType) {
+    return personas.find(p => p.id === 'general') ?? personas[0] ?? null
+  }
+  const overrideId = overrides[taskType]
+  if (overrideId) {
+    const pinned = personas.find(p => p.id === overrideId)
+    if (pinned) return pinned
+  }
+  const match = personas.find(p => (p.taskTypes as readonly string[]).includes(taskType))
+  if (match) return match
+  return personas.find(p => p.id === 'general') ?? null
+}
+
+/** Per-agent overrides keyed by persona id. Sourced from
+ *  `.annotask/agents.json` at the shell layer. Only the fields the user has
+ *  set are present; missing ones inherit from the built-in persona. */
+export interface PersonaRuntimeOverride {
+  providerId?: ProviderId
+  model?: string
+  effort?: EffortLevel
+}
+
+/**
+ * Merge built-ins with user customs, deduping by id. User customs win — this
+ * lets a user clone a built-in and reassign its task types without removing
+ * the original (the original keeps existing as a fallback). v1 simpler
+ * behavior: customs sit alongside built-ins and the resolver picks the
+ * first match in array order.
+ *
+ * `overrides` applies on top of built-ins (never customs) so the per-project
+ * `agents.json` can swap provider/model/effort for the read-only built-ins
+ * without forcing the user to clone them.
+ */
+export function combinePersonas(
+  custom: readonly PersonaConfig[],
+  overrides: Record<string, PersonaRuntimeOverride> = {},
+): PersonaConfig[] {
+  const out: PersonaConfig[] = []
+  const seen = new Set<string>()
+  for (const p of BUILT_IN_PERSONAS) {
+    if (seen.has(p.id)) continue
+    seen.add(p.id)
+    const o = overrides[p.id]
+    if (!o) { out.push(p); continue }
+    out.push({
+      ...p,
+      providerId: o.providerId ?? p.providerId,
+      model: typeof o.model === 'string' ? o.model : p.model,
+      effort: o.effort ?? p.effort,
+    })
+  }
+  for (const p of custom) {
+    if (seen.has(p.id)) continue
+    seen.add(p.id)
+    out.push(p)
+  }
+  return out
+}
+
+export type { TaskType }
diff --git a/src/embedded/provider-config.ts b/src/embedded/provider-config.ts
new file mode 100644
index 0000000..8b245cf
--- /dev/null
+++ b/src/embedded/provider-config.ts
@@ -0,0 +1,687 @@
+/**
+ * Provider configuration for the embedded chat surface.
+ *
+ * Storage posture:
+ * - Lives entirely in the user's browser (localStorage or whatever sink the
+ *   shell injects). Never transmitted to any Annotask service.
+ * - Secrets (API keys, OAuth tokens) sit alongside non-secrets so the user
+ *   has one place to configure the embedded chat.
+ *
+ * Branches:
+ * - Direct-API providers (anthropic, openai, openai-compatible, openrouter,
+ *   paperclip) carry their own credentials in this blob.
+ * - Local-CLI providers (claude-local, codex-local, opencode-local,
+ *   copilot-local) carry NO credentials — they reuse the locally-installed
+ *   CLI's own login state (~/.claude, ~/.codex, ~/.copilot, …). The shell's
+ *   `agent-detect` endpoint reports whether the CLI is installed and logged in.
+ *
+ * Per-provider knobs:
+ * - `model` — empty string means "auto" (the provider picks). Otherwise the
+ *   exact identifier (e.g. `claude-sonnet-4-5`, `openai/gpt-4o-mini`).
+ * - `effort` — reasoning effort knob. `auto` means "don't send a hint at
+ *   all"; `minimal | low | medium | high` map to provider-specific fields
+ *   (`reasoning_effort` for OpenAI-compat, `thinking` budget for Anthropic,
+ *   `-c model_reasoning_effort` for codex CLI). Providers that don't grok
+ *   the hint just ignore it.
+ *
+ * The schema is intentionally narrow. New auth modes get a new discriminated
+ * union branch rather than free-form fields.
+ */
+
+import { z } from 'zod'
+
+export const PROVIDER_IDS = [
+  // Local-CLI providers (reuse the CLI's own login state — no API keys here).
+  'claude-local',
+  'codex-local',
+  'opencode-local',
+  'copilot-local',
+  // Direct-API providers
+  'anthropic',
+  'openai',
+  'openrouter',
+  'openai-compatible',
+  'paperclip',
+] as const
+
+export type ProviderId = (typeof PROVIDER_IDS)[number]
+
+export const ProviderIdSchema = z.enum(PROVIDER_IDS)
+
+export const EFFORT_LEVELS = ['auto', 'minimal', 'low', 'medium', 'high'] as const
+export type EffortLevel = (typeof EFFORT_LEVELS)[number]
+export const EffortSchema = z.enum(EFFORT_LEVELS).default('auto')
+
+/**
+ * Subset of EFFORT_LEVELS each provider actually honors. Providers not listed
+ * inherit the full list. The picker filters to this slice so users can't
+ * select an effort the provider would silently drop.
+ */
+export const EFFORTS_BY_PROVIDER: Partial<Record<ProviderId, readonly EffortLevel[]>> = {
+  // Local CLIs that wrap their own model_reasoning_effort flag — full slate.
+  'claude-local': ['auto', 'minimal', 'low', 'medium', 'high'],
+  'codex-local':  ['auto', 'minimal', 'low', 'medium', 'high'],
+  // OpenCode dispatches to subproviders; effort hint is best-effort only.
+  'opencode-local': ['auto', 'low', 'medium', 'high'],
+  // Copilot CLI exposes `--reasoning-effort low|medium|high|xhigh`. We only
+  // forward the levels common across providers; xhigh is opt-in via extraArgs.
+  'copilot-local': ['auto', 'low', 'medium', 'high'],
+  anthropic: ['auto', 'minimal', 'low', 'medium', 'high'],
+  openai:    ['auto', 'minimal', 'low', 'medium', 'high'],
+  openrouter:['auto', 'low', 'medium', 'high'],
+}
+
+/**
+ * Agent mode — how aggressive the in-shell chat should be:
+ *   - `auto`: every newly-created task auto-opens its Conversation tab and
+ *     fires the first turn with the task description. Hands-free.
+ *   - `manual` (default): the Conversation tab is available but only fires
+ *     when the user clicks the Run-with-agent button on a task (or the
+ *     batch Run-pending button on the tasks list). Manual control.
+ *   - `off`: no in-shell chat surface at all. Users drive agents via the
+ *     terminal — `/annotask-apply`, MCP, the `annotask` CLI.
+ */
+export const AGENT_MODES = ['auto', 'manual', 'off'] as const
+export type AgentMode = (typeof AGENT_MODES)[number]
+export const AgentModeSchema = z.enum(AGENT_MODES).default('auto')
+
+// Re-export PermissionMode for callers that already import from this module.
+export { PERMISSION_MODES, type PermissionMode } from '../schema.js'
+import { PermissionModeSchema } from './permission-mode.js'
+export { PermissionModeSchema } from './permission-mode.js'
+
+const TrimmedString = z.string().trim()
+const NonEmptyTrimmed = TrimmedString.min(1, 'value cannot be empty')
+
+/**
+ * URL validator that accepts http(s) URLs only and rejects auth credentials
+ * in the URL itself. We deliberately allow custom hosts (localhost, LAN
+ * IPs, hostnames) because opencode and LM Studio commonly run on
+ * `http://localhost:4096` and similar.
+ */
+const EndpointUrl = NonEmptyTrimmed.superRefine((value, ctx) => {
+  let url: URL
+  try {
+    url = new URL(value)
+  } catch {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Must be a valid URL.',
+    })
+    return
+  }
+  if (!/^https?:$/.test(url.protocol)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Only http(s) URLs are supported.',
+    })
+  }
+  if (url.username || url.password) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Embed credentials via the API key field, not the URL.',
+    })
+  }
+})
+
+/** Local-CLI provider config — the same shape for claude/codex/opencode/copilot. */
+function localCliSchema<T extends 'claude-local' | 'codex-local' | 'opencode-local' | 'copilot-local'>(id: T) {
+  return z.object({
+    id: z.literal(id),
+    /** Empty string means "auto" (let the CLI pick its default model). */
+    model: TrimmedString.default(''),
+    effort: EffortSchema,
+    /** Extra args appended after the canonical args. Trim+filter empty. */
+    extraArgs: z.array(TrimmedString).default([]),
+    /** Per-provider permission-mode override. When unset, the runner falls
+     *  back to the global `ProviderSettings.permissionMode`. Task overrides
+     *  win over both. Only local-CLI providers carry this — HTTP providers
+     *  have no tool-write loop yet, so the mode is moot for them. */
+    permissionMode: PermissionModeSchema.optional(),
+  })
+}
+
+export const ClaudeLocalProviderConfigSchema = localCliSchema('claude-local')
+export type ClaudeLocalProviderConfig = z.infer<typeof ClaudeLocalProviderConfigSchema>
+
+export const CodexLocalProviderConfigSchema = localCliSchema('codex-local')
+export type CodexLocalProviderConfig = z.infer<typeof CodexLocalProviderConfigSchema>
+
+export const OpencodeLocalProviderConfigSchema = localCliSchema('opencode-local')
+export type OpencodeLocalProviderConfig = z.infer<typeof OpencodeLocalProviderConfigSchema>
+
+/**
+ * GitHub Copilot CLI (`copilot`) — subprocess provider. Same shape as the
+ * other local-CLI configs: no credentials stored here, the CLI manages its
+ * own auth (OS keyring or `~/.copilot/`). Lets users with a working
+ * `copilot login` skip the HTTP `/copilot_internal/v2/token` flow, which
+ * rejects tokens issued by anything other than the Copilot IDE OAuth app.
+ */
+export const CopilotLocalProviderConfigSchema = localCliSchema('copilot-local')
+export type CopilotLocalProviderConfig = z.infer<typeof CopilotLocalProviderConfigSchema>
+
+/**
+ * Anthropic provider — BYOK only. Keys start with `sk-ant-`; we accept any
+ * non-empty trimmed string and rely on the live `validate()` call to verify
+ * against the real API.
+ */
+export const AnthropicProviderConfigSchema = z.object({
+  id: z.literal('anthropic'),
+  apiKey: TrimmedString.default(''),
+  model: TrimmedString.default(''),
+  effort: EffortSchema,
+})
+export type AnthropicProviderConfig = z.infer<typeof AnthropicProviderConfigSchema>
+
+/**
+ * OpenAI / Codex provider — BYOK with optional org id.
+ */
+export const OpenAIProviderConfigSchema = z.object({
+  id: z.literal('openai'),
+  apiKey: TrimmedString.default(''),
+  /** Optional organization id (`org-…`). */
+  organization: TrimmedString.default(''),
+  model: TrimmedString.default(''),
+  effort: EffortSchema,
+})
+export type OpenAIProviderConfig = z.infer<typeof OpenAIProviderConfigSchema>
+
+/**
+ * OpenRouter — OpenAI-compatible router with a single API key and a fixed
+ * default base URL. Behaves like `openai-compatible` but is tagged so the
+ * UI can show OpenRouter-specific affordances (model picker, free-credit
+ * hint) and the provider can inject the recommended attribution headers.
+ */
+export const OpenRouterProviderConfigSchema = z.object({
+  id: z.literal('openrouter'),
+  apiKey: TrimmedString.default(''),
+  /** Allow override for self-hosted gateways; defaults to api.openrouter.ai. */
+  baseUrl: TrimmedString.default(''),
+  model: TrimmedString.default(''),
+  effort: EffortSchema,
+})
+export type OpenRouterProviderConfig = z.infer<typeof OpenRouterProviderConfigSchema>
+
+/**
+ * OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, …).
+ * `endpointUrl` is mandatory for this branch.
+ */
+export const OpenAICompatibleProviderConfigSchema = z.object({
+  id: z.literal('openai-compatible'),
+  endpointUrl: EndpointUrl,
+  apiKey: TrimmedString.default(''),
+  model: NonEmptyTrimmed,
+  effort: EffortSchema,
+  /** Friendly label for the UI, e.g. "Ollama local". */
+  label: TrimmedString.default(''),
+})
+export type OpenAICompatibleProviderConfig = z.infer<
+  typeof OpenAICompatibleProviderConfigSchema
+>
+
+/**
+ * Paperclip-managed inference. The user pastes a Paperclip company API key
+ * (or runs `pnpm paperclipai connect`). The shell never stores Paperclip
+ * credentials past this field.
+ */
+export const PaperclipProviderConfigSchema = z.object({
+  id: z.literal('paperclip'),
+  companyId: TrimmedString.default(''),
+  apiKey: TrimmedString.default(''),
+  /** Override the Paperclip API base URL (e.g. self-hosted instance). */
+  apiBaseUrl: TrimmedString.default(''),
+  model: TrimmedString.default(''),
+  effort: EffortSchema,
+})
+export type PaperclipProviderConfig = z.infer<typeof PaperclipProviderConfigSchema>
+
+export const ProviderConfigSchema = z.discriminatedUnion('id', [
+  ClaudeLocalProviderConfigSchema,
+  CodexLocalProviderConfigSchema,
+  OpencodeLocalProviderConfigSchema,
+  CopilotLocalProviderConfigSchema,
+  AnthropicProviderConfigSchema,
+  OpenAIProviderConfigSchema,
+  OpenRouterProviderConfigSchema,
+  OpenAICompatibleProviderConfigSchema,
+  PaperclipProviderConfigSchema,
+])
+export type ProviderConfig = z.infer<typeof ProviderConfigSchema>
+
+const DEFAULT_CLAUDE_LOCAL: ClaudeLocalProviderConfig = {
+  id: 'claude-local',
+  model: '',
+  effort: 'auto',
+  extraArgs: [],
+}
+const DEFAULT_CODEX_LOCAL: CodexLocalProviderConfig = {
+  id: 'codex-local',
+  model: '',
+  effort: 'auto',
+  extraArgs: [],
+}
+const DEFAULT_OPENCODE_LOCAL: OpencodeLocalProviderConfig = {
+  id: 'opencode-local',
+  model: '',
+  effort: 'auto',
+  extraArgs: [],
+}
+const DEFAULT_COPILOT_LOCAL: CopilotLocalProviderConfig = {
+  id: 'copilot-local',
+  model: '',
+  effort: 'auto',
+  extraArgs: [],
+}
+const DEFAULT_ANTHROPIC: AnthropicProviderConfig = {
+  id: 'anthropic',
+  apiKey: '',
+  model: '',
+  effort: 'auto',
+}
+const DEFAULT_OPENAI: OpenAIProviderConfig = {
+  id: 'openai',
+  apiKey: '',
+  organization: '',
+  model: '',
+  effort: 'auto',
+}
+const DEFAULT_OPENROUTER: OpenRouterProviderConfig = {
+  id: 'openrouter',
+  apiKey: '',
+  baseUrl: '',
+  model: '',
+  effort: 'auto',
+}
+const DEFAULT_OPENAI_COMPATIBLE = {
+  id: 'openai-compatible' as const,
+  endpointUrl: '',
+  apiKey: '',
+  model: '',
+  label: '',
+  effort: 'auto' as EffortLevel,
+}
+const DEFAULT_PAPERCLIP: PaperclipProviderConfig = {
+  id: 'paperclip',
+  companyId: '',
+  apiKey: '',
+  apiBaseUrl: '',
+  model: '',
+  effort: 'auto',
+}
+
+/**
+ * Shape of the persisted settings blob. The active provider id selects
+ * which entry in `providers` is currently in use; the other branches stay
+ * populated so the user can flip between providers without re-entering
+ * credentials.
+ */
+// Personas are defined in persona.ts to keep the heavy task-type list out of
+// the provider-config surface. We import the schema and re-export the type
+// from this module so persisted settings carry a strongly-typed personas[].
+import { PersonaConfigSchema } from './persona.js'
+
+export const ProviderSettingsSchema = z.object({
+  /** Provider currently selected for new conversations. */
+  activeProvider: ProviderIdSchema.default('claude-local'),
+  /**
+   * Agent mode (auto | manual | off). See `AgentModeSchema` for semantics.
+   * Defaults to `auto` — tasks run autonomously on creation when a provider
+   * is ready. Users can switch to `manual` for click-to-run or `off` to
+   * disable the in-shell chat surface entirely.
+   */
+  agentMode: AgentModeSchema,
+  /**
+   * Top-level toggle: is the in-shell embedded agent feature enabled at all?
+   * - `null`  — user has not yet chosen (first run). The init wizard's Page 0
+   *             forces an explicit choice between skill/MCP mode and embedded.
+   * - `true`  — embedded UI on; Conversation tab, auto-run driver, and provider
+   *             setup wizard are all available.
+   * - `false` — skill/MCP mode. All embedded surfaces hidden; wizard never
+   *             auto-opens. MCP server still runs (that's how the user's
+   *             editor agent drives `/annotask-apply`).
+   *
+   * Migration of pre-existing installs (no value in localStorage) is handled
+   * in `useProviderSettings` based on the historical `agentMode`.
+   */
+  embeddedAgentEnabled: z.boolean().nullable().default(null),
+  /** True once the user has dismissed the first-run setup modal. */
+  onboardingDismissed: z.boolean().default(false),
+  /** Toggle to disable redaction in *the user's own* config (testing only). */
+  redactionEnabled: z.boolean().default(true),
+  /** Local event log toggle. Defaults on. Logged data never leaves the box. */
+  eventLogEnabled: z.boolean().default(true),
+  /**
+   * Global permission mode for agent actions. Default `'default'` ("Auto"):
+   * each CLI runs the least-permissive mode that still applies tasks headlessly
+   * — codex stays in its `--full-auto` OS sandbox and copilot at the minimal
+   * `--allow-all-tools`, while claude/opencode (which have no headless ask-mode)
+   * escalate to `bypass` via `normalizeHeadlessMode` at spawn time. `bypass`
+   * (all sandboxes off) is now an explicit opt-in, not the default. Pre-feature
+   * installs that already stored `'bypass'` keep it (treated as a deliberate
+   * choice); only fresh installs get the safer `'default'`.
+   */
+  permissionMode: PermissionModeSchema.default('default'),
+  /** Stored config per provider. Branches the user hasn't touched stay at defaults. */
+  providers: z
+    .object({
+      'claude-local': ClaudeLocalProviderConfigSchema.default(DEFAULT_CLAUDE_LOCAL),
+      'codex-local': CodexLocalProviderConfigSchema.default(DEFAULT_CODEX_LOCAL),
+      'opencode-local': OpencodeLocalProviderConfigSchema.default(DEFAULT_OPENCODE_LOCAL),
+      'copilot-local': CopilotLocalProviderConfigSchema.default(DEFAULT_COPILOT_LOCAL),
+      anthropic: AnthropicProviderConfigSchema.default(DEFAULT_ANTHROPIC),
+      openai: OpenAIProviderConfigSchema.default(DEFAULT_OPENAI),
+      openrouter: OpenRouterProviderConfigSchema.default(DEFAULT_OPENROUTER),
+      'openai-compatible': z
+        .object({
+          id: z.literal('openai-compatible'),
+          endpointUrl: TrimmedString.default(''),
+          apiKey: TrimmedString.default(''),
+          model: TrimmedString.default(''),
+          label: TrimmedString.default(''),
+          effort: EffortSchema,
+        })
+        .default(DEFAULT_OPENAI_COMPATIBLE),
+      paperclip: PaperclipProviderConfigSchema.default(DEFAULT_PAPERCLIP),
+    })
+    .default(() => ({
+      'claude-local': DEFAULT_CLAUDE_LOCAL,
+      'codex-local': DEFAULT_CODEX_LOCAL,
+      'opencode-local': DEFAULT_OPENCODE_LOCAL,
+      'copilot-local': DEFAULT_COPILOT_LOCAL,
+      anthropic: DEFAULT_ANTHROPIC,
+      openai: DEFAULT_OPENAI,
+      openrouter: DEFAULT_OPENROUTER,
+      'openai-compatible': DEFAULT_OPENAI_COMPATIBLE,
+      paperclip: DEFAULT_PAPERCLIP,
+    })),
+  /**
+   * User-defined personas. Built-ins live in src/embedded/persona.ts and
+   * are merged at read time. This array only holds the user's customs +
+   * any built-ins the user explicitly edited. Empty means "use built-ins
+   * as-is."
+   */
+  customPersonas: z.array(PersonaConfigSchema).default([]),
+  /**
+   * Task-type → persona-id pins. Override the natural `taskTypes[]`-based
+   * routing for the named type. Used by the Agents settings UI to let
+   * users reassign (e.g. force `a11y_fix` to the Designer persona).
+   */
+  personaOverrides: z.record(z.string(), z.string()).default({}),
+  /**
+   * Run-safety watchdog. `idleTimeoutMs` aborts a run that produces no output
+   * for that long (default 2 min); `maxRunDurationMs` is an absolute per-run
+   * ceiling (default 10 min). `0` disables that timer. Prevents a stuck agent
+   * from blocking the auto-run FIFO queue forever.
+   */
+  idleTimeoutMs: z.number().int().min(0).default(120_000),
+  maxRunDurationMs: z.number().int().min(0).default(600_000),
+})
+export type ProviderSettings = z.infer<typeof ProviderSettingsSchema>
+
+export const DEFAULT_PROVIDER_SETTINGS: ProviderSettings = {
+  // Default to claude-local — paperclip rule: prefer the user's logged-in CLI.
+  // If `claude` isn't installed/logged in, the detect banner steers the user
+  // to whichever local CLI *is* available; the chat composer also surfaces
+  // the "pick a provider" empty state.
+  activeProvider: 'claude-local',
+  agentMode: 'auto',
+  embeddedAgentEnabled: null,
+  onboardingDismissed: false,
+  redactionEnabled: true,
+  eventLogEnabled: true,
+  // "Auto" — least-permissive headless-capable mode per CLI (see the schema
+  // comment above and normalizeHeadlessMode). Bypass is an explicit opt-in.
+  permissionMode: 'default',
+  providers: {
+    'claude-local': DEFAULT_CLAUDE_LOCAL,
+    'codex-local': DEFAULT_CODEX_LOCAL,
+    'opencode-local': DEFAULT_OPENCODE_LOCAL,
+    'copilot-local': DEFAULT_COPILOT_LOCAL,
+    anthropic: DEFAULT_ANTHROPIC,
+    openai: DEFAULT_OPENAI,
+    openrouter: DEFAULT_OPENROUTER,
+    'openai-compatible': DEFAULT_OPENAI_COMPATIBLE,
+    paperclip: DEFAULT_PAPERCLIP,
+  },
+  customPersonas: [],
+  personaOverrides: {},
+  idleTimeoutMs: 120_000,
+  maxRunDurationMs: 600_000,
+}
+
+/**
+ * Validate a single provider config branch and return either a parsed
+ * config or a list of human-readable issues. The `openai-compatible`
+ * branch's endpoint URL is validated strictly here even though it accepts
+ * empty defaults in storage — callers who *use* the provider must pass a
+ * filled-in endpoint URL.
+ */
+export function validateProviderConfig(
+  config: ProviderConfig,
+): { ok: true; config: ProviderConfig } | { ok: false; errors: string[] } {
+  let schema: z.ZodTypeAny
+  switch (config.id) {
+    case 'claude-local':
+      schema = ClaudeLocalProviderConfigSchema
+      break
+    case 'codex-local':
+      schema = CodexLocalProviderConfigSchema
+      break
+    case 'opencode-local':
+      schema = OpencodeLocalProviderConfigSchema
+      break
+    case 'copilot-local':
+      schema = CopilotLocalProviderConfigSchema
+      break
+    case 'anthropic':
+      schema = AnthropicProviderConfigSchema
+      break
+    case 'openai':
+      schema = OpenAIProviderConfigSchema
+      break
+    case 'openrouter':
+      schema = OpenRouterProviderConfigSchema
+      break
+    case 'openai-compatible':
+      schema = OpenAICompatibleProviderConfigSchema
+      break
+    case 'paperclip':
+      schema = PaperclipProviderConfigSchema
+      break
+  }
+  const parsed = schema.safeParse(config)
+  if (parsed.success) return { ok: true, config: parsed.data as ProviderConfig }
+  return {
+    ok: false,
+    errors: parsed.error.issues.map((i) => {
+      const path = i.path.length > 0 ? `${i.path.join('.')}: ` : ''
+      return `${path}${i.message}`
+    }),
+  }
+}
+
+/**
+ * Parse a stored settings blob (e.g. from localStorage). Falls back to
+ * `DEFAULT_PROVIDER_SETTINGS` on any error so the shell never gets stuck
+ * with a corrupt config.
+ */
+export function parseProviderSettings(raw: unknown): ProviderSettings {
+  if (raw == null) return DEFAULT_PROVIDER_SETTINGS
+  let input: unknown = raw
+  if (typeof raw === 'string') {
+    try {
+      input = JSON.parse(raw)
+    } catch {
+      return DEFAULT_PROVIDER_SETTINGS
+    }
+  }
+  // Migrate the removed `copilot` (HTTP/OAuth) provider id to `copilot-local`
+  // so users who previously selected it land on the CLI subprocess instead of
+  // losing their entire settings blob on the enum-rejection fallback.
+  if (input && typeof input === 'object') {
+    const obj = input as Record<string, unknown>
+    if (obj.activeProvider === 'copilot') obj.activeProvider = 'copilot-local'
+    if (obj.providers && typeof obj.providers === 'object') {
+      delete (obj.providers as Record<string, unknown>).copilot
+    }
+    // NOTE: the pre-`embeddedAgentEnabled` migration is intentionally
+    // deferred — it now runs inside `useInitFlow`'s watcher once we know
+    // whether the project is initialized. That way an uninitialized project
+    // always lands on Page 0, even if stale `agentMode` settings from a
+    // prior install would otherwise have implied a workflow choice.
+
+    // NOTE: a former migration here rewrote `permissionMode: 'default'` to
+    // `'bypass'` because headless `default` stalls on claude/opencode. That
+    // escalation now happens safely per-CLI at spawn time via
+    // `normalizeHeadlessMode` (codex/copilot keep their sandboxed/minimal
+    // `default`; only claude/opencode escalate). Rewriting the stored value
+    // would wrongly force codex/copilot off their sandbox, so it is gone —
+    // `'default'` is the intended out-of-box default and is preserved as-is.
+  }
+  const parsed = ProviderSettingsSchema.safeParse(input)
+  if (!parsed.success) return DEFAULT_PROVIDER_SETTINGS
+  // Merge the parsed result over the hand-built defaults so any provider
+  // branch the user has never touched still has a usable default. zod 4's
+  // nested .default() only fires when the parent key is missing, not when
+  // it is present but partially-populated.
+  return {
+    activeProvider: parsed.data.activeProvider,
+    agentMode: parsed.data.agentMode,
+    embeddedAgentEnabled: parsed.data.embeddedAgentEnabled,
+    onboardingDismissed: parsed.data.onboardingDismissed,
+    redactionEnabled: parsed.data.redactionEnabled,
+    eventLogEnabled: parsed.data.eventLogEnabled,
+    permissionMode: parsed.data.permissionMode,
+    providers: {
+      ...DEFAULT_PROVIDER_SETTINGS.providers,
+      ...parsed.data.providers,
+    },
+    customPersonas: parsed.data.customPersonas ?? [],
+    personaOverrides: parsed.data.personaOverrides ?? {},
+    idleTimeoutMs: parsed.data.idleTimeoutMs,
+    maxRunDurationMs: parsed.data.maxRunDurationMs,
+  }
+}
+
+/**
+ * Probe for local-CLI providers. Each entry is true iff `agent-detect`
+ * reports the CLI installed AND logged in. Callers (the composer's "ready"
+ * check, the runtime factory) inject a fresh probe; pass an empty object
+ * when probing isn't available (treats local providers as not-ready).
+ */
+export interface LocalCliReadiness {
+  'claude-local'?: boolean
+  'codex-local'?: boolean
+  'opencode-local'?: boolean
+  'copilot-local'?: boolean
+}
+
+/**
+ * Return true when the given settings blob has enough credentials for the
+ * active provider to actually run. Useful for the "Run" button gating in
+ * the composer. Local-CLI providers need an extra `probe` from agent-detect
+ * since their "credentials" live in the user's home directory, not here.
+ */
+export function isActiveProviderReady(
+  settings: ProviderSettings,
+  probe: LocalCliReadiness = {},
+): boolean {
+  const active = settings.providers[settings.activeProvider]
+  switch (active.id) {
+    case 'claude-local':
+    case 'codex-local':
+    case 'opencode-local':
+    case 'copilot-local':
+      return probe[active.id] === true
+    case 'anthropic':
+      return active.apiKey.trim().length > 0
+    case 'openai':
+      return active.apiKey.trim().length > 0
+    case 'openrouter':
+      return active.apiKey.trim().length > 0
+    case 'openai-compatible': {
+      const result = OpenAICompatibleProviderConfigSchema.safeParse(active)
+      return result.success
+    }
+    case 'paperclip':
+      return active.apiKey.trim().length > 0
+  }
+}
+
+/**
+ * Redact secret fields for safe logging. Returns a shallow copy with
+ * sensitive fields replaced by `'<set>'` / `'<unset>'` markers.
+ */
+export function redactForLogging(settings: ProviderSettings): unknown {
+  const mask = (v: string) => (v.length > 0 ? '<set>' : '<unset>')
+  return {
+    activeProvider: settings.activeProvider,
+    agentMode: settings.agentMode,
+    onboardingDismissed: settings.onboardingDismissed,
+    redactionEnabled: settings.redactionEnabled,
+    eventLogEnabled: settings.eventLogEnabled,
+    permissionMode: settings.permissionMode,
+    providers: {
+      'claude-local': {
+        id: 'claude-local',
+        model: settings.providers['claude-local'].model,
+        effort: settings.providers['claude-local'].effort,
+        extraArgs: settings.providers['claude-local'].extraArgs,
+      },
+      'codex-local': {
+        id: 'codex-local',
+        model: settings.providers['codex-local'].model,
+        effort: settings.providers['codex-local'].effort,
+        extraArgs: settings.providers['codex-local'].extraArgs,
+      },
+      'opencode-local': {
+        id: 'opencode-local',
+        model: settings.providers['opencode-local'].model,
+        effort: settings.providers['opencode-local'].effort,
+        extraArgs: settings.providers['opencode-local'].extraArgs,
+      },
+      'copilot-local': {
+        id: 'copilot-local',
+        model: settings.providers['copilot-local'].model,
+        effort: settings.providers['copilot-local'].effort,
+        extraArgs: settings.providers['copilot-local'].extraArgs,
+      },
+      anthropic: {
+        id: 'anthropic',
+        apiKey: mask(settings.providers.anthropic.apiKey),
+        model: settings.providers.anthropic.model,
+        effort: settings.providers.anthropic.effort,
+      },
+      openai: {
+        id: 'openai',
+        apiKey: mask(settings.providers.openai.apiKey),
+        organization: settings.providers.openai.organization,
+        model: settings.providers.openai.model,
+        effort: settings.providers.openai.effort,
+      },
+      openrouter: {
+        id: 'openrouter',
+        apiKey: mask(settings.providers.openrouter.apiKey),
+        baseUrl: settings.providers.openrouter.baseUrl,
+        model: settings.providers.openrouter.model,
+        effort: settings.providers.openrouter.effort,
+      },
+      'openai-compatible': {
+        id: 'openai-compatible',
+        endpointUrl: settings.providers['openai-compatible'].endpointUrl,
+        apiKey: mask(settings.providers['openai-compatible'].apiKey),
+        model: settings.providers['openai-compatible'].model,
+        effort: settings.providers['openai-compatible'].effort,
+        label: settings.providers['openai-compatible'].label,
+      },
+      paperclip: {
+        id: 'paperclip',
+        companyId: settings.providers.paperclip.companyId,
+        apiKey: mask(settings.providers.paperclip.apiKey),
+        apiBaseUrl: settings.providers.paperclip.apiBaseUrl,
+        model: settings.providers.paperclip.model,
+        effort: settings.providers.paperclip.effort,
+      },
+    },
+  }
+}
diff --git a/src/embedded/provider-factory.ts b/src/embedded/provider-factory.ts
new file mode 100644
index 0000000..a51f12d
--- /dev/null
+++ b/src/embedded/provider-factory.ts
@@ -0,0 +1,130 @@
+/**
+ * Provider factory — given a parsed `ProviderSettings` blob, return the
+ * concrete `LLMProvider` instance for the active provider.
+ *
+ * This is the single seam where "the user picked X" turns into "instantiate
+ * class Y with credentials Z." Callers (`useEmbeddedAgent`, server-side
+ * orchestrators, tests) get a uniform `LLMProvider` and never need to
+ * branch on provider id themselves.
+ *
+ * The factory takes a small optional context object so the browser can pass
+ * runtime details (referer, fetch override) without baking them into the
+ * persisted settings blob.
+ */
+
+import type { LLMProvider } from './provider.js'
+import type { ProviderSettings } from './provider-config.js'
+import { AnthropicProvider } from './anthropic-provider.js'
+import { OpenAIProvider } from './openai-provider.js'
+import { OpenRouterProvider } from './openrouter-provider.js'
+import { OpenAICompatibleProvider } from './openai-compatible-provider.js'
+import { PaperclipProvider } from './paperclip-provider.js'
+import { ClaudeLocalProvider } from './claude-local-provider.js'
+import { CodexLocalProvider } from './codex-local-provider.js'
+import { OpencodeLocalProvider } from './opencode-local-provider.js'
+import { CopilotLocalProvider } from './copilot-local-provider.js'
+
+export interface MakeProviderContext {
+  /** OpenRouter attribution referer; defaults to window.location.origin. */
+  referer?: string
+  /** OpenRouter attribution app title; defaults to 'Annotask'. */
+  appTitle?: string
+  /** Spawn endpoint for CLI-local providers. Defaults to /__annotask/api/agent/spawn. */
+  spawnUrl?: string
+  /** Test seam: inject a custom fetch (also used by CLI-local providers). */
+  fetchImpl?: typeof fetch
+}
+
+export function makeProvider(
+  settings: ProviderSettings,
+  ctx: MakeProviderContext = {},
+): LLMProvider {
+  const id = settings.activeProvider
+  switch (id) {
+    case 'claude-local': {
+      const cfg = settings.providers['claude-local']
+      return new ClaudeLocalProvider({
+        model: cfg.model || undefined,
+        extraArgs: cfg.extraArgs,
+        spawnUrl: ctx.spawnUrl,
+        fetchImpl: ctx.fetchImpl,
+      })
+    }
+    case 'codex-local': {
+      const cfg = settings.providers['codex-local']
+      return new CodexLocalProvider({
+        model: cfg.model || undefined,
+        extraArgs: cfg.extraArgs,
+        spawnUrl: ctx.spawnUrl,
+        fetchImpl: ctx.fetchImpl,
+      })
+    }
+    case 'opencode-local': {
+      const cfg = settings.providers['opencode-local']
+      return new OpencodeLocalProvider({
+        model: cfg.model || undefined,
+        extraArgs: cfg.extraArgs,
+        spawnUrl: ctx.spawnUrl,
+        fetchImpl: ctx.fetchImpl,
+      })
+    }
+    case 'copilot-local': {
+      const cfg = settings.providers['copilot-local']
+      return new CopilotLocalProvider({
+        model: cfg.model || undefined,
+        extraArgs: cfg.extraArgs,
+        spawnUrl: ctx.spawnUrl,
+        fetchImpl: ctx.fetchImpl,
+      })
+    }
+    case 'anthropic': {
+      const cfg = settings.providers.anthropic
+      return new AnthropicProvider({
+        apiKey: cfg.apiKey,
+        defaultModel: cfg.model || undefined,
+      })
+    }
+    case 'openai': {
+      const cfg = settings.providers.openai
+      return new OpenAIProvider({
+        apiKey: cfg.apiKey,
+        organization: cfg.organization || undefined,
+        defaultModel: cfg.model || undefined,
+      })
+    }
+    case 'openrouter': {
+      const cfg = settings.providers.openrouter
+      return new OpenRouterProvider({
+        apiKey: cfg.apiKey,
+        baseURL: cfg.baseUrl || undefined,
+        defaultModel: cfg.model || undefined,
+        referer: ctx.referer,
+        appTitle: ctx.appTitle,
+      })
+    }
+    case 'openai-compatible': {
+      const cfg = settings.providers['openai-compatible']
+      return new OpenAICompatibleProvider({
+        baseURL: cfg.endpointUrl,
+        apiKey: cfg.apiKey || undefined,
+        defaultModel: cfg.model,
+        name: cfg.label.trim() || undefined,
+      })
+    }
+    case 'paperclip': {
+      const cfg = settings.providers.paperclip
+      // Build the Paperclip chat endpoint from the configured base URL.
+      // The companyId is sent as a header so the same base URL can serve
+      // multiple companies without per-company routing baked into the path.
+      const base = (cfg.apiBaseUrl?.trim() || 'https://paperclip.ai/api').replace(/\/+$/, '')
+      const headers: Record<string, string> = {}
+      if (cfg.companyId) headers['X-Paperclip-Company-Id'] = cfg.companyId
+      return new PaperclipProvider({
+        endpoint: `${base}/chat/completions`,
+        apiKey: cfg.apiKey,
+        defaultModel: cfg.model || undefined,
+        headers,
+      })
+    }
+  }
+}
diff --git a/src/embedded/provider.ts b/src/embedded/provider.ts
index 2d4628c..a826395 100644
--- a/src/embedded/provider.ts
+++ b/src/embedded/provider.ts
@@ -43,6 +43,32 @@ export interface StreamOptions {
   model?: string
   /** Max tokens to generate. */
   maxTokens?: number
+  /**
+   * Reasoning-effort hint. `'auto'` (or omitted) means "don't bias the
+   * provider"; the named levels map to provider-specific knobs:
+   *   - Chat-Completions endpoints (OpenAI, OpenRouter, Copilot, Paperclip,
+   *     OpenAI-compatible): `reasoning_effort` in the body.
+   *   - Anthropic: extended-thinking budget.
+   *   - Codex CLI: `-c model_reasoning_effort=<level>`.
+   * Providers that don't grok the hint MUST ignore it silently rather than
+   * fail — the same `'high'` hint is sent to every provider that's active.
+   */
+  effort?: 'auto' | 'minimal' | 'low' | 'medium' | 'high'
+  /**
+   * Permission mode for this turn. Local-CLI providers translate it to the
+   * CLI's own permission flag (Claude `--permission-mode`, Codex `--ask-for-
+   * approval` + `--sandbox`, Copilot `--allow-all-tools` toggles). HTTP API
+   * providers currently ignore this (no tool-write loop yet). Resolved by
+   * `resolveEffectivePermissionMode(task, persona, global)` in the runner.
+   */
+  permissionMode?: 'default' | 'plan' | 'bypass'
+  /**
+   * Task this run is applying, if any. Local-CLI providers forward it in the
+   * spawn request so the server can key its run registry by task (one live run
+   * per task → no cross-tab double-spawn) and finalize orphaned tasks. HTTP
+   * providers ignore it.
+   */
+  taskId?: string
   /** Caller's abort signal. Providers must terminate the stream when it fires. */
   signal?: AbortSignal
 }
@@ -53,6 +79,12 @@ export type ProviderEvent =
   /** A complete tool call ready to dispatch. Emitted once the model has
    *  finished assembling the tool's JSON input. */
   | { type: 'tool_call', id: string, name: string, input: unknown }
+  /** Output from a tool the agent invoked. Paired with a prior `tool_call`
+   *  by `toolUseId`. Local CLIs that run their own tool loop (claude/codex/
+   *  opencode --print) surface these so the work-stream view can render the
+   *  full call → response timeline. API providers that only call tools
+   *  client-side never emit this. */
+  | { type: 'tool_result', toolUseId: string, content: string, isError?: boolean }
   /** End-of-message usage counters. Cache-token fields are populated when the
    *  provider exposes them (Anthropic does). */
   | {
@@ -86,4 +118,11 @@ export interface LLMProvider {
     tools: ProviderTool[],
     options: StreamOptions,
   ): AsyncIterable<ProviderEvent>
+
+  /**
+   * Explicitly abort a running subprocess. Local-CLI providers issue
+   * `DELETE /agent/spawn/:runId` to kill the child process server-side.
+   * HTTP API providers typically don't need this (AbortSignal handles it).
+   */
+  abortRun?(): Promise<void>
 }
diff --git a/src/embedded/redaction.ts b/src/embedded/redaction.ts
new file mode 100644
index 0000000..9ec99e8
--- /dev/null
+++ b/src/embedded/redaction.ts
@@ -0,0 +1,235 @@
+/**
+ * Secret redaction for prompts and tool results before they leave the
+ * machine. Applied to every string that goes to a provider — system prompt,
+ * conversation messages, and tool results.
+ *
+ * Three rules:
+ * 1. Catch common provider-key and credential shapes by structure (prefix +
+ *    high-entropy tail), not by exhaustive enumeration. New providers fall
+ *    into one of these shapes naturally.
+ * 2. Never alter byte ranges that are not a secret. Redacted output is the
+ *    same string with literal `[REDACTED:<label>]` markers swapped in.
+ * 3. Idempotent. Running redact twice on a payload produces the same output
+ *    as running it once.
+ *
+ * Conservative on false positives in the bodies of natural-language prompts
+ * (avoid eating short alphanum runs); aggressive on identifiable provider
+ * prefixes (`sk-ant-`, `ghp_`, `xoxb-`, `AKIA…`, `-----BEGIN…PRIVATE KEY-----`).
+ */
+
+export interface RedactionPattern {
+  /** Label included in the redaction marker, e.g. `anthropic_api_key`. */
+  label: string
+  /** Pattern to match. Should be anchored on prefix where possible. */
+  pattern: RegExp
+}
+
+export interface RedactionMatch {
+  label: string
+  /** Index of the first character of the match in the input. */
+  start: number
+  /** Index past the last character of the match. */
+  end: number
+}
+
+export interface RedactionResult {
+  output: string
+  matches: ReadonlyArray<RedactionMatch>
+}
+
+/**
+ * Default redaction patterns. Ordered so that more specific patterns run
+ * first; the redactor short-circuits per-byte so order matters when two
+ * patterns could overlap.
+ */
+export const DEFAULT_REDACTION_PATTERNS: ReadonlyArray<RedactionPattern> = [
+  // PEM blocks — multi-line, must run before per-line scans.
+  {
+    label: 'private_key_pem',
+    pattern: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/g,
+  },
+  // Anthropic — `sk-ant-` followed by base64url-ish characters.
+  {
+    label: 'anthropic_api_key',
+    pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g,
+  },
+  // OpenAI — both legacy `sk-…` and project-scoped `sk-proj-…`.
+  {
+    label: 'openai_api_key',
+    pattern: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/g,
+  },
+  // GitHub personal-access tokens and OAuth tokens.
+  {
+    label: 'github_token',
+    pattern: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/g,
+  },
+  // GitHub fine-grained PATs — `github_pat_` + 22 base62 + `_` + 59 base62.
+  {
+    label: 'github_pat',
+    pattern: /\bgithub_pat_[A-Za-z0-9]{22}_[A-Za-z0-9]{59}\b/g,
+  },
+  // Slack bot/user/app tokens.
+  {
+    label: 'slack_token',
+    pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g,
+  },
+  // AWS access key ids.
+  {
+    label: 'aws_access_key_id',
+    pattern: /\b(?:AKIA|ASIA|AGPA|AIDA|AROA|ANPA|ANVA|ASCA)[A-Z0-9]{16}\b/g,
+  },
+  // AWS secret access keys when explicitly labeled. Bare 40-char b64 strings
+  // are too noisy to match safely without a key cue.
+  {
+    label: 'aws_secret_access_key',
+    pattern: /(?<=aws_?secret(?:_access)?_?key["'\s:=]+)["']?[A-Za-z0-9/+]{40}["']?/gi,
+  },
+  // Generic bearer tokens in Authorization headers.
+  {
+    label: 'bearer_token',
+    pattern: /\bBearer\s+[A-Za-z0-9._~+/=-]{20,}\b/g,
+  },
+  // JWT tokens — three base64url segments separated by dots.
+  {
+    label: 'jwt',
+    pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+  },
+  // Google API keys — `AIza` + 35 url-safe chars.
+  {
+    label: 'google_api_key',
+    pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g,
+  },
+  // Stripe secret/restricted keys (live and test).
+  {
+    label: 'stripe_secret_key',
+    pattern: /\b(?:sk|rk)_(?:live|test)_[0-9A-Za-z]{16,}\b/g,
+  },
+  // Credentials embedded in a connection string (`proto://user:PASSWORD@host`).
+  // Redact just the password via the `value` sub-group; the scheme/user stay.
+  {
+    label: 'connection_string_password',
+    pattern: /(?<=[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:)(?<value>[^@\s/]+)(?=@)/gi,
+  },
+  // .env-style assignments where the variable name screams secret. Match the
+  // value only, so the variable name stays in context for debugging.
+  {
+    label: 'env_secret',
+    pattern: /(?<=^|\n)(?<keyword>(?:[A-Z][A-Z0-9_]*_)?(?:API_KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE_KEY))\s*=\s*["']?(?<value>[^\s"'\n]{8,})["']?/g,
+  },
+]
+
+/**
+ * Apply the given patterns to `input` and return the redacted output plus
+ * the list of match locations (against the *original* input, not the output
+ * — useful for telemetry without leaking the redacted bytes).
+ */
+export function redact(
+  input: string,
+  patterns: ReadonlyArray<RedactionPattern> = DEFAULT_REDACTION_PATTERNS,
+): RedactionResult {
+  if (!input) return { output: input, matches: [] }
+
+  // Collect every match across all patterns first. We compare offsets in the
+  // original string and then drop matches that fully overlap an earlier one.
+  type Hit = { label: string; start: number; end: number; replacement: string }
+  const hits: Hit[] = []
+
+  for (const { label, pattern } of patterns) {
+    // Patterns are stateful (`g` flag); reset lastIndex before reusing.
+    pattern.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = pattern.exec(input)) != null) {
+      // env_secret keeps the keyword=...  prefix outside the match via a
+      // lookbehind; if a sub-group `value` exists, redact just that.
+      const groupValue = m.groups?.value
+      let start: number
+      let end: number
+      if (groupValue != null) {
+        // Re-anchor the match to the `value` sub-group's byte range.
+        const idx = input.indexOf(groupValue, m.index)
+        if (idx < 0) continue
+        start = idx
+        end = idx + groupValue.length
+      } else {
+        start = m.index
+        end = m.index + m[0].length
+      }
+      if (end === start) {
+        // Defensive: zero-width match — advance to avoid infinite loop.
+        pattern.lastIndex = start + 1
+        continue
+      }
+      hits.push({
+        label,
+        start,
+        end,
+        replacement: `[REDACTED:${label}]`,
+      })
+    }
+  }
+
+  if (hits.length === 0) return { output: input, matches: [] }
+
+  // Sort by start; resolve overlaps by keeping the earliest start and the
+  // widest span (so a private-key PEM block beats any anthropic-key match
+  // inside it).
+  hits.sort((a, b) => (a.start - b.start) || (b.end - b.start) - (a.end - a.start))
+  const accepted: Hit[] = []
+  let cursor = -1
+  for (const hit of hits) {
+    if (hit.start < cursor) continue
+    accepted.push(hit)
+    cursor = hit.end
+  }
+
+  let out = ''
+  let last = 0
+  for (const hit of accepted) {
+    out += input.slice(last, hit.start)
+    out += hit.replacement
+    last = hit.end
+  }
+  out += input.slice(last)
+
+  return {
+    output: out,
+    matches: accepted.map(({ label, start, end }) => ({ label, start, end })),
+  }
+}
+
+/**
+ * Convenience wrapper that returns just the redacted string. Use this when
+ * the caller doesn't need the match-location metadata.
+ */
+export function redactString(
+  input: string,
+  patterns?: ReadonlyArray<RedactionPattern>,
+): string {
+  return redact(input, patterns).output
+}
+
+/**
+ * Walk a structured value (e.g. a tool-call argument or tool result) and
+ * redact every string in place. Non-string values are returned unchanged.
+ * Arrays and plain objects are descended into; class instances and other
+ * exotica are passed through untouched to avoid corrupting them.
+ */
+export function redactValue<T>(
+  value: T,
+  patterns?: ReadonlyArray<RedactionPattern>,
+): T {
+  if (typeof value === 'string') {
+    return redactString(value, patterns) as unknown as T
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => redactValue(v, patterns)) as unknown as T
+  }
+  if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = redactValue(v, patterns)
+    }
+    return out as unknown as T
+  }
+  return value
+}
diff --git a/src/mcp/__tests__/server.test.ts b/src/mcp/__tests__/server.test.ts
index eaab430..8461dde 100644
--- a/src/mcp/__tests__/server.test.ts
+++ b/src/mcp/__tests__/server.test.ts
@@ -1,10 +1,13 @@
 import { describe, it, expect } from 'vitest'
 import http from 'node:http'
+import os from 'node:os'
+import fsp from 'node:fs/promises'
+import nodePath from 'node:path'
 import { AddressInfo } from 'node:net'
 import { createMcpMiddleware, type McpDeps } from '../server'
 import { getSystemPrompt } from '../../skills/index.js'
 
-function makeDeps(): McpDeps {
+function makeDeps(overrides: Partial<McpDeps> = {}): McpDeps {
   return {
     projectRoot: process.cwd(),
     getDesignSpec: () => null,
@@ -14,6 +17,7 @@ function makeDeps(): McpDeps {
     deleteTask: async () => ({ ok: true }),
     readInteractionHistory: async () => null,
     readRenderedHtml: async () => null,
+    ...overrides,
   }
 }
 
@@ -30,6 +34,31 @@ async function rpc(url: string, body: object): Promise<any> {
   return res.json()
 }
 
+/** Spin the real HTTP middleware on an ephemeral port for the duration of `fn`. */
+async function withServer(deps: McpDeps, fn: (url: string) => Promise<void>): Promise<void> {
+  const middleware = createMcpMiddleware(deps)
+  const server = http.createServer((req, res) => {
+    middleware(req, res, () => { res.statusCode = 404; res.end() })
+  })
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+  const { port } = server.address() as AddressInfo
+  try {
+    await fn(`http://127.0.0.1:${port}/__annotask/mcp`)
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()))
+  }
+}
+
+/** Real tools/call through the JSON-RPC transport. Returns the envelope plus parsed text payload. */
+async function toolCall(url: string, name: string, args: Record<string, unknown>): Promise<{ isError: boolean; text: string; json: any }> {
+  const response = await rpc(url, { jsonrpc: '2.0', method: 'tools/call', id: 1, params: { name, arguments: args } })
+  expect(response.result).toBeTruthy()
+  const text: string = response.result.content?.[0]?.text ?? ''
+  let json: any = null
+  try { json = JSON.parse(text) } catch { /* non-JSON payloads (error strings) stay null */ }
+  return { isError: response.result.isError === true, text, json }
+}
+
 describe('MCP server — initialize.instructions', () => {
   it('returns the annotask-apply skill body as initialize.instructions', async () => {
     const middleware = createMcpMiddleware(makeDeps())
@@ -78,4 +107,198 @@ describe('MCP server — initialize.instructions', () => {
       await new Promise<void>((resolve) => server.close(() => resolve()))
     }
   })
+
+  it('lists the agent-grounding tools (source excerpt, playbook, agent directions)', async () => {
+    await withServer(makeDeps(), async (url) => {
+      const response = await rpc(url, { jsonrpc: '2.0', method: 'tools/list', id: 3 })
+      const names = response.result.tools.map((t: any) => t.name)
+      expect(names).toContain('annotask_get_source_excerpt')
+      expect(names).toContain('annotask_get_playbook')
+      expect(names).toContain('annotask_get_agent_directions')
+    })
+  })
+})
+
+describe('MCP tools/call — annotask_get_source_excerpt', () => {
+  it('grounds an arbitrary file/line to a source excerpt', async () => {
+    await withServer(makeDeps(), async (url) => {
+      const { isError, json } = await toolCall(url, 'annotask_get_source_excerpt', {
+        file: 'src/schema.ts',
+        line: 10,
+        context_lines: 5,
+      })
+      expect(isError).toBe(false)
+      expect(json.file).toBe('src/schema.ts')
+      expect(json.error).toBeUndefined()
+      expect(json.excerpt).toBeTruthy()
+      expect(json.excerpt_hash).toMatch(/^[0-9a-f]{16}$/)
+      // ±5 lines around line 10 — at most 11 lines.
+      expect(json.excerpt.split('\n').length).toBeLessThanOrEqual(11)
+      expect(json.excerpt_start_line).toBe(5)
+    })
+  })
+
+  it('rejects escaping paths via resolveProjectFile containment', async () => {
+    await withServer(makeDeps(), async (url) => {
+      const { json } = await toolCall(url, 'annotask_get_source_excerpt', {
+        file: '../'.repeat(12) + 'etc/passwd',
+        line: 1,
+      })
+      // Same contract as GET /api/source-excerpt: a 200-shaped payload whose
+      // `error` field flags the rejection, with no file contents leaked.
+      expect(json.error).toBe('Invalid or escaping file path')
+      expect(json.excerpt ?? '').toBe('')
+    })
+  })
+
+  it('rejects missing/invalid arguments at the schema boundary', async () => {
+    await withServer(makeDeps(), async (url) => {
+      const { isError } = await toolCall(url, 'annotask_get_source_excerpt', { file: 'src/schema.ts' })
+      expect(isError).toBe(true)
+    })
+  })
+})
+
+describe('MCP tools/call — annotask_get_playbook', () => {
+  it('returns the WIREFRAME_APPLY companion for wireframe_apply', async () => {
+    await withServer(makeDeps(), async (url) => {
+      const { isError, json } = await toolCall(url, 'annotask_get_playbook', { task_type: 'wireframe_apply' })
+      expect(isError).toBe(false)
+      expect(json.task_type).toBe('wireframe_apply')
+      expect(json.file).toBe('WIREFRAME_APPLY.md')
+      expect(json.content).toContain('# Wireframe Apply')
+      // Must be the real playbook, not a stub — anchors/instances are its core vocabulary.
+      expect(json.content).toContain('anchor')
+    })
+  })
+
+  it('returns a message (no content) for task types without a companion', async () => {
+    await withServer(makeDeps(), async (url) => {
+      const { isError, json } = await toolCall(url, 'annotask_get_playbook', { task_type: 'annotation' })
+      expect(isError).toBe(false)
+      expect(json.task_type).toBe('annotation')
+      expect(json.content).toBeUndefined()
+      expect(json.message).toMatch(/No companion playbook/)
+    })
+  })
+
+  it('rejects unknown task types', async () => {
+    await withServer(makeDeps(), async (url) => {
+      const { isError, text } = await toolCall(url, 'annotask_get_playbook', { task_type: 'nonsense' })
+      expect(isError).toBe(true)
+      expect(text).toMatch(/Invalid task type/)
+    })
+  })
+})
+
+describe('MCP tools/call — annotask_get_agent_directions', () => {
+  async function withAgentsJson(agents: Record<string, unknown>, fn: (deps: McpDeps) => Promise<void>): Promise<void> {
+    const dir = await fsp.mkdtemp(nodePath.join(os.tmpdir(), 'annotask-mcp-test-'))
+    try {
+      await fsp.mkdir(nodePath.join(dir, '.annotask'), { recursive: true })
+      await fsp.writeFile(nodePath.join(dir, '.annotask', 'agents.json'), JSON.stringify({ version: 1, agents }), 'utf-8')
+      await fn(makeDeps({ projectRoot: dir }))
+    } finally {
+      await fsp.rm(dir, { recursive: true, force: true })
+    }
+  }
+
+  it('returns all personas without persona_id', async () => {
+    await withAgentsJson({ general: { projectDirections: 'Use Vue 3 SFC patterns' }, designer: { projectDirections: 'Tokens only' } }, async (deps) => {
+      await withServer(deps, async (url) => {
+        const { isError, json } = await toolCall(url, 'annotask_get_agent_directions', {})
+        expect(isError).toBe(false)
+        expect(json.version).toBe(1)
+        expect(json.agents.general.projectDirections).toBe('Use Vue 3 SFC patterns')
+        expect(json.agents.designer.projectDirections).toBe('Tokens only')
+      })
+    })
+  })
+
+  it('returns a single persona entry, and not_configured for unknown ids', async () => {
+    await withAgentsJson({ general: { projectDirections: 'Use Vue 3 SFC patterns' } }, async (deps) => {
+      await withServer(deps, async (url) => {
+        const one = await toolCall(url, 'annotask_get_agent_directions', { persona_id: 'general' })
+        expect(one.json.persona_id).toBe('general')
+        expect(one.json.projectDirections).toBe('Use Vue 3 SFC patterns')
+
+        const missing = await toolCall(url, 'annotask_get_agent_directions', { persona_id: 'bug-hunter' })
+        expect(missing.isError).toBe(false)
+        expect(missing.json.not_configured).toBe(true)
+        expect(missing.json.projectDirections).toBe('')
+      })
+    })
+  })
+})
+
+describe('MCP tools/call — task hygiene and guards', () => {
+  const renderedTask = {
+    id: 't1',
+    type: 'annotation',
+    status: 'pending',
+    description: 'Make the header sticky',
+    file: 'src/App.vue',
+    line: 12,
+    visual: { x: 1, y: 2 },
+    interaction_history: { route_path: ['/'], actions: [{ kind: 'click' }] },
+    context: { rendered: '<div class="header">big blob</div>', element_tag: 'div' },
+  }
+
+  it('get_tasks(detail=true) always strips context.rendered and interaction_history', async () => {
+    const deps = makeDeps({ getTasks: () => ({ version: '1.0', tasks: [{ ...renderedTask }] }) })
+    await withServer(deps, async (url) => {
+      const { json } = await toolCall(url, 'annotask_get_tasks', { detail: true })
+      expect(json.count).toBe(1)
+      const task = json.tasks[0]
+      expect(task.visual).toBeUndefined()
+      expect(task.interaction_history).toBeUndefined()
+      expect(task.context.rendered).toBeUndefined()
+      // The rest of context survives — only the bulky snapshot comes off.
+      expect(task.context.element_tag).toBe('div')
+    })
+  })
+
+  it('get_task (single) still returns interaction_history and context.rendered', async () => {
+    const deps = makeDeps({ getTasks: () => ({ version: '1.0', tasks: [{ ...renderedTask }] }) })
+    await withServer(deps, async (url) => {
+      const { json } = await toolCall(url, 'annotask_get_task', { task_id: 't1' })
+      expect(json.interaction_history).toBeTruthy()
+      expect(json.context.rendered).toContain('big blob')
+    })
+  })
+
+  it('get_tasks paginates with limit/offset and reports total', async () => {
+    const tasks = ['a', 'b', 'c'].map(id => ({ id, type: 'annotation', status: 'pending', description: id }))
+    const deps = makeDeps({ getTasks: () => ({ version: '1.0', tasks }) })
+    await withServer(deps, async (url) => {
+      const paged = await toolCall(url, 'annotask_get_tasks', { limit: 1, offset: 1 })
+      expect(paged.json.total).toBe(3)
+      expect(paged.json.count).toBe(1)
+      expect(paged.json.tasks[0].id).toBe('b')
+
+      // No limit/offset → existing return-everything behavior.
+      const all = await toolCall(url, 'annotask_get_tasks', {})
+      expect(all.json.total).toBe(3)
+      expect(all.json.count).toBe(3)
+    })
+  })
+
+  it('update_task rejects invalid status transitions with the error envelope', async () => {
+    const deps = makeDeps({
+      getTasks: () => ({ version: '1.0', tasks: [{ id: 't1', type: 'annotation', status: 'pending', description: 'x' }] }),
+    })
+    await withServer(deps, async (url) => {
+      const { isError, text } = await toolCall(url, 'annotask_update_task', { task_id: 't1', status: 'accepted' })
+      expect(isError).toBe(true)
+      expect(text).toMatch(/Invalid state transition: pending → accepted/)
+    })
+  })
+
+  it('create_task rejects bogus task types', async () => {
+    await withServer(makeDeps(), async (url) => {
+      const { isError, text } = await toolCall(url, 'annotask_create_task', { type: 'totally_fake', description: 'x' })
+      expect(isError).toBe(true)
+      expect(text).toMatch(/Invalid task type/)
+    })
+  })
 })
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index beda5a6..4097cc1 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -1,59 +1,9 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
-import fsp from 'node:fs/promises'
-import nodePath from 'node:path'
 import { isLocalOrigin } from '../server/origin.js'
-import { scanComponentLibraries } from '../server/component-scanner.js'
-import { buildTaskSummary, filterTasksByMfe, stripTaskVisual, trimAgentFeedback, compactJson } from '../shared/task-summary.js'
-import { isSafeScreenshot } from '../server/validation.js'
-import { getCodeContext } from '../server/code-context.js'
-import { getComponentExamples } from '../server/component-examples.js'
-import { resolveDataContext } from '../server/data-context.js'
-import { scanDataSources } from '../server/data-source-scanner.js'
-import { mergeRuntimeOrphansIntoEntries, findMatchingStaticEntries } from '../server/runtime-endpoints.js'
-import { getDataSourceExamples } from '../server/data-source-examples.js'
-import { resolveDataSourceDetails } from '../server/data-source-details.js'
-import { scanApiSchemas } from '../server/api-schema-scanner.js'
-import { resolveEndpoint } from '../server/api-schema-resolver.js'
-import { resolveWorkspace } from '../server/workspace.js'
-import { TASK_TYPES, type DataSource, type RuntimeEndpoint, type RuntimeEndpointCatalog } from '../schema.js'
 import { getSystemPrompt } from '../skills/index.js'
+import { callTool, MCP_TOOLS, type McpDeps } from './tools.js'
 
-/** Monorepo root for containment checks, or `undefined` when the project is
- *  not inside a workspace. Cached via `resolveWorkspace`. */
-async function getWorkspaceRoot(projectRoot: string): Promise<string | undefined> {
-  try {
-    const info = await resolveWorkspace(projectRoot)
-    return info.isWorkspace ? info.root : undefined
-  } catch {
-    return undefined
-  }
-}
-import {
-  McpGetTasksArgs,
-  McpGetTaskArgs,
-  McpUpdateTaskArgs,
-  McpCreateTaskArgs,
-  McpDeleteTaskArgs,
-  McpGetDesignSpecArgs,
-  McpGetComponentsArgs,
-  McpGetComponentArgs,
-  McpGetScreenshotArgs,
-  McpGetCodeContextArgs,
-  McpGetComponentExamplesArgs,
-  McpGetDataContextArgs,
-  McpGetInteractionHistoryArgs,
-  McpGetRenderedHtmlArgs,
-  McpGetDataSourcesArgs,
-  McpGetDataSourceExamplesArgs,
-  McpGetDataSourceDetailsArgs,
-  McpGetApiSchemasArgs,
-  McpGetApiOperationArgs,
-  McpResolveEndpointArgs,
-  McpGetRuntimeEndpointsArgs,
-  parseWith,
-  assertTransition,
-  AgentFeedbackSchema,
-} from '../server/schemas.js'
+export type { McpDeps } from './tools.js'
 
 // ── Types ────────────────────────────────────────────
 
@@ -71,75 +21,13 @@ interface JsonRpcResponse {
   id: string | number | null
 }
 
-interface ToolDef {
-  name: string
-  description: string
-  inputSchema: Record<string, unknown>
-}
-
-export interface McpDeps {
-  projectRoot: string
-  getDesignSpec: () => unknown
-  getTasks: () => { version: string; tasks: Array<Record<string, unknown>> }
-  addTask: (task: Record<string, unknown>) => unknown | Promise<unknown>
-  updateTask: (id: string, updates: Record<string, unknown>) => unknown | Promise<unknown>
-  deleteTask: (id: string) => unknown | Promise<unknown>
-  readInteractionHistory: (taskId: string) => Promise<unknown | null>
-  readRenderedHtml: (taskId: string) => Promise<string | null>
-  /** Aggregated runtime-observed endpoint catalog. Optional — when missing, the MCP tool returns an empty catalog. */
-  getRuntimeEndpointCatalog?: () => RuntimeEndpointCatalog
-}
-
-// ── Constants ────────────────────────────────────────
-
-// Compact JSON + stripVisual + agent-feedback trimming are shared with the CLI
-// so agents get identical output whether they hit the MCP endpoint directly or
-// fall back to `npx annotask ... --mcp`.
-const compact = compactJson
-const stripVisual = stripTaskVisual
-
-// Minimal shapes so we don't drag the full scanner types through the MCP layer.
-interface ScannedComponentLike {
-  name: string
-  module: string
-  description?: string | null
-  category?: string | null
-  tags?: string[]
-  deprecated?: boolean
-  props?: Array<{ name: string }>
-  slots?: Array<{ name: string }>
-  events?: Array<{ name: string }>
-}
-interface ScannedLibraryLike {
-  name: string
-  version?: string
-  components?: ScannedComponentLike[]
-}
-
-/** Compact summary for an agent-facing component list — no props/slots/events bodies. */
-function componentSummary(c: ScannedComponentLike) {
-  return {
-    name: c.name,
-    module: c.module,
-    category: c.category ?? null,
-    description: c.description ?? null,
-    propCount: c.props?.length ?? 0,
-    slotCount: c.slots?.length ?? 0,
-    eventCount: c.events?.length ?? 0,
-    deprecated: c.deprecated ? true : undefined,
-  }
-}
-
 const PROTOCOL_VERSION = '2025-03-26'
-// Version is baked at build time from package.json so the MCP initialize response doesn't drift.
 declare const __ANNOTASK_VERSION__: string | undefined
 const SERVER_INFO = { name: 'annotask', version: typeof __ANNOTASK_VERSION__ === 'string' ? __ANNOTASK_VERSION__ : '0.0.0' }
 
 /** Cached `initialize.instructions` payload. The MCP server returns the
  *  `annotask-apply` skill as instructions so external agents (Claude Code,
- *  editors) get the same system prompt the embedded runner uses. Loaded
- *  lazily and tolerant of missing bundled skills (we still return a usable
- *  initialize response in that case). */
+ *  editors) get the same system prompt the embedded runner uses. */
 let cachedInstructions: string | null = null
 function getMcpInstructions(): string {
   if (cachedInstructions !== null) return cachedInstructions
@@ -151,803 +39,9 @@ function getMcpInstructions(): string {
   return cachedInstructions
 }
 
-// ── Tool definitions ─────────────────────────────────
-
-const TOOLS: ToolDef[] = [
-  {
-    name: 'annotask_get_tasks',
-    description:
-      'Get design tasks from Annotask. Returns task summaries by default (id, type, status, description, file, line, action, screenshot). ' +
-      'Use detail=true for full objects including context, viewport, and interaction_history. ' +
-      'Use annotask_get_task to fetch full detail for a single task. ' +
-      'Focus on "pending" and "denied" (with feedback) tasks for work to do.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        status: {
-          type: 'string',
-          description: 'Filter tasks by status',
-          enum: ['pending', 'in_progress', 'applied', 'review', 'denied', 'needs_info', 'blocked'],
-        },
-        mfe: {
-          type: 'string',
-          description: 'Filter by micro-frontend identity (e.g. "@myorg/my-mfe")',
-        },
-        detail: {
-          type: 'boolean',
-          description: 'If true, return full task objects. Default false returns summaries.',
-        },
-      },
-    },
-  },
-  {
-    name: 'annotask_get_task',
-    description:
-      'Get full details for a single task by ID. Returns all fields including context, interaction_history, and agent_feedback. ' +
-      'Use this after reviewing the task summary list to get full context for a specific task.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task_id: { type: 'string', description: 'The task ID to fetch' },
-      },
-      required: ['task_id'],
-    },
-  },
-  {
-    name: 'annotask_update_task',
-    description:
-      'Update a task status or fields. Common workflows:\n' +
-      '- Lock before working: status→"in_progress"\n' +
-      '- Mark applied: status→"review" + resolution note\n' +
-      '- Ask user questions: provide questions array (auto-sets status→"needs_info")\n' +
-      '- Mark blocked: provide blocked_reason (auto-sets status→"blocked")\n' +
-      'Valid transitions: pending→in_progress|denied, in_progress→review|needs_info|blocked|denied, review→accepted|denied|in_progress, needs_info→in_progress|denied, blocked→in_progress|denied, denied→pending|in_progress.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task_id: { type: 'string', description: 'The task ID to update' },
-        status: {
-          type: 'string',
-          description: 'New status for the task',
-          enum: ['pending', 'in_progress', 'applied', 'review', 'accepted', 'denied', 'needs_info', 'blocked'],
-        },
-        resolution: { type: 'string', description: 'Brief note on what was changed (use when marking review)' },
-        feedback: { type: 'string', description: 'Denial notes from reviewer' },
-        blocked_reason: { type: 'string', description: 'Why the task cannot be applied (markdown). Auto-sets status to "blocked" if no status given.' },
-        questions: {
-          type: 'array',
-          description: 'Ask the user clarifying questions. Auto-sets status to "needs_info" if no status given.',
-          items: {
-            type: 'object',
-            properties: {
-              id: { type: 'string', description: 'Unique question ID (e.g. "q1")' },
-              text: { type: 'string', description: 'The question text' },
-              type: { type: 'string', enum: ['text', 'choice'], description: '"text" for free-text, "choice" for multiple choice' },
-              options: { type: 'array', items: { type: 'string' }, description: 'Choices (required when type is "choice")' },
-            },
-            required: ['id', 'text', 'type'],
-          },
-        },
-        question_context: { type: 'string', description: 'Optional markdown context to accompany questions' },
-      },
-      required: ['task_id'],
-    },
-  },
-  {
-    name: 'annotask_create_task',
-    description: `Create a new design task with "pending" status. Types: ${TASK_TYPES.join(', ')}.`,
-    inputSchema: {
-      type: 'object',
-      properties: {
-        type: { type: 'string', description: 'Task type' },
-        description: { type: 'string', description: 'What needs to be done (markdown)' },
-        file: { type: 'string', description: 'Source file path' },
-        line: { type: 'number', description: 'Line number in file' },
-        component: { type: 'string', description: 'Component name' },
-        mfe: { type: 'string', description: 'MFE identity (e.g. "@myorg/my-mfe") for multi-project setups' },
-        context: { type: 'object', description: 'Arbitrary context data' },
-      },
-      required: ['type', 'description'],
-    },
-  },
-  {
-    name: 'annotask_delete_task',
-    description: 'Permanently delete a task and its associated screenshot.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task_id: { type: 'string', description: 'The task ID to delete' },
-      },
-      required: ['task_id'],
-    },
-  },
-  {
-    name: 'annotask_get_design_spec',
-    description:
-      'Get the project design specification. Without a category, returns a summary (framework info, token counts). ' +
-      'With a category, returns full tokens for that category. Generated by /annotask-init.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        category: {
-          type: 'string',
-          description: 'Return only this category. Omit for a summary overview.',
-          enum: ['colors', 'typography', 'spacing', 'borders', 'breakpoints', 'icons', 'components', 'framework'],
-        },
-      },
-    },
-  },
-  {
-    name: 'annotask_get_components',
-    description:
-      'Search component libraries detected in node_modules. By default returns compact summaries (name, module, category) — set detail=true for full props/slots/events/description. ' +
-      'Filters: `search` (name substring), `library` (exact library name), `category` (e.g. "button", "form"), `used_only` (restrict to components actually imported in this codebase — highest-signal filter). ' +
-      'Paginate with `limit` (default 50, max 500) and `offset`. For a single component use annotask_get_component.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        search: { type: 'string', description: 'Filter components by name (case-insensitive substring match)' },
-        library: { type: 'string', description: 'Exact library name (e.g. "primevue")' },
-        category: { type: 'string', description: 'Category filter (e.g. "button", "form", "overlay", "data", "layout")' },
-        used_only: { type: 'boolean', description: 'Return only components that are actually imported in the codebase (from design-spec.components.used)' },
-        detail: { type: 'boolean', description: 'Include full props, slots, events, and description. Default false returns compact summaries.' },
-        limit: { type: 'number', description: 'Max results per library. Default 50, max 500.' },
-        offset: { type: 'number', description: 'Skip the first N results (pagination). Default 0.' },
-      },
-    },
-  },
-  {
-    name: 'annotask_get_component',
-    description:
-      'Get full detail for a single component by name: props, slots, events, description, category, import module. ' +
-      'Use after annotask_get_components identifies candidates. Provide `library` to disambiguate when the same name exists in multiple libraries.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', description: 'Component name (e.g. "Button", "DataTable")' },
-        library: { type: 'string', description: 'Library name to disambiguate (e.g. "primevue")' },
-      },
-      required: ['name'],
-    },
-  },
-  {
-    name: 'annotask_get_screenshot',
-    description: 'Get a task screenshot as a base64-encoded PNG image. Screenshots show what the user sees in the browser, providing visual context for what change is needed.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task_id: { type: 'string', description: 'The task ID whose screenshot to fetch' },
-      },
-      required: ['task_id'],
-    },
-  },
-  {
-    name: 'annotask_get_code_context',
-    description:
-      'Resolve a task to grounded source context: a ±15 line excerpt around `task.line`, the nearest enclosing symbol/component, the file\'s import block, and a short `excerpt_hash` for drift detection. ' +
-      'Prefer this over trusting `task.line` when a task has been retried, is older than your current triage pass, or when a prior Edit touched the same file. ' +
-      'Use `context_lines` to widen/narrow the window (default 15, max 200).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task_id: { type: 'string', description: 'The task ID to resolve source context for' },
-        context_lines: { type: 'number', description: 'Lines of context on each side of task.line. Default 15, max 200.' },
-      },
-      required: ['task_id'],
-    },
-  },
-  {
-    name: 'annotask_get_component_examples',
-    description:
-      'Find real in-repo usages of a component by name. Returns up to `limit` call sites (default 3) with a short surrounding source snippet, the line number, and the most common import path for the component. ' +
-      'Use this when you are about to reuse or place a component and want to match the repo\'s own conventions (prop combinations, wrapper patterns, slot usage) rather than invent new ones. ' +
-      'Pass `library` (e.g. `@mantine/core`, `radix-vue`) to keep same-name components from different libraries out of the result.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', description: 'Component name to search for (case-sensitive)' },
-        limit: { type: 'number', description: 'Max examples to return. Default 3, max 10.' },
-        library: { type: 'string', description: 'Optional library/package name (e.g. @mantine/core). Only examples whose import specifier belongs to this library are returned.' },
-      },
-      required: ['name'],
-    },
-  },
-  {
-    name: 'annotask_get_interaction_history',
-    description:
-      'Retrieve the user\'s pre-task interaction trace: navigation path plus the last ~20 recorded actions (clicks, form submits, route changes) as of task creation. ' +
-      'Always captured server-side — the per-task "Embed interaction history" toggle only decides whether this data rides in the task payload, so use this tool whenever an annotation references a flow or sequence ("after I click submit…", "on the orders page…") and the payload itself lacks `interaction_history`. ' +
-      'Returns the stored snapshot (or the embedded copy when the user opted in). If nothing was captured (e.g. task came from an external API caller), the response has `not_captured: true`.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task_id: { type: 'string', description: 'The task ID whose interaction history to fetch' },
-      },
-      required: ['task_id'],
-    },
-  },
-  {
-    name: 'annotask_get_rendered_html',
-    description:
-      'Fetch the `outerHTML` of the element the task was attached to, captured post-render at task creation (React/Vue bindings resolved, annotask attrs stripped). ' +
-      'Always captured when a selection existed — the "Embed rendered HTML" toggle only gates embedding in the task payload. Use this when the task description references visual structure that is hard to reconstruct from source alone ("the three spans in the header", "this button\'s icon wrapper") or when you need to match existing inline markup for a style fix. ' +
-      'Response shape: `{ task_id, rendered, source }` where `source` is `"embedded"` (read from the task payload) or `"sidecar"` (loaded from the per-task store). `{ rendered: null, not_captured: true }` when no snapshot exists. Hard-capped at 200 KB per task.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task_id: { type: 'string', description: 'The task ID whose rendered HTML to fetch' },
-      },
-      required: ['task_id'],
-    },
-  },
-  {
-    name: 'annotask_get_data_context',
-    description:
-      'Resolve (or return stored) data_context for a task — what hooks/stores/fetch calls power the selected element. ' +
-      'Returns `sources[]` — every data reference in the enclosing file, sorted with the primary (nearest to `task.line`, tie-broken hook>store>fetch>graphql>loader>rpc) at index 0 — plus `rendered_identifiers` (template/JSX names, CSV) and `route_bindings` (route params/query keys, CSV). ' +
-      'Use this before editing or inserting any data-driven UI so you reuse the repo\'s own queries/stores instead of writing fake data. Pass `refresh: true` to force a fresh scan even if the task already stores a data_context.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task_id: { type: 'string', description: 'The task ID to resolve data context for' },
-        refresh: { type: 'boolean', description: 'Ignore stored data_context on the task and re-scan the source file.' },
-      },
-      required: ['task_id'],
-    },
-  },
-  {
-    name: 'annotask_get_data_sources',
-    description:
-      'List the project-wide data source catalog: detected data-fetching libraries from package.json (React Query, SWR, Pinia, Zustand, Apollo, tRPC, …) and project-specific entries found in `src/` (user hooks, stores, fetch wrappers, GraphQL operations). ' +
-      '`project_entries` come sorted by `used_count` descending — the most load-bearing entries first. Use this when deciding which existing data source to reuse before writing new code. ' +
-      'By default, orphan endpoints observed at runtime (fetch/XHR traffic the regex scanner missed) are promoted into `project_entries` with `discovered_by: "runtime"` and `file: ""` — these represent real APIs the frontend hits but that the static pass couldn\'t pin to a source location. Pass `merge_runtime: false` for a pure static-scan view; use `annotask_get_runtime_endpoints` for the full runtime catalog.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        kind: { type: 'string', enum: ['composable', 'signal', 'store', 'fetch', 'graphql', 'loader', 'rpc'], description: 'Only return project entries of this kind. "composable" covers React hooks, Vue composables, Svelte helpers, Solid primitive wrappers. "signal" is fine-grained reactive (Solid createSignal, Svelte store reads).' },
-        library: { type: 'string', description: 'Only return this library from the libraries list.' },
-        search: { type: 'string', description: 'Substring match on project entry name (case-insensitive).' },
-        used_only: { type: 'boolean', description: 'Restrict project entries to `used_count > 0` — analogous to `annotask_get_components` used_only filter.' },
-        merge_runtime: { type: 'boolean', description: 'Include orphan runtime-observed endpoints as synthetic `project_entries` (default true). These carry `discovered_by: "runtime"` and have `file: ""` because they were found by live network capture, not source scan. Set false for static-only.' },
-      },
-    },
-  },
-  {
-    name: 'annotask_get_api_schemas',
-    description:
-      'List discovered API schemas. Sources: OpenAPI/Swagger JSON/YAML files, GraphQL SDL files, tRPC routers (with zod input/output), and live dev-server probes at common paths (/openapi.json, /graphql with introspection, etc.). ' +
-      'Default returns compact entries (kind, location, title, operation_count). Set detail=true to include every `operations[]` with full request/response schemas. ' +
-      'Use alongside `annotask_get_data_context` — when a source has `response_schema_ref`, this tool lets you pull the full shape.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        kind: { type: 'string', enum: ['openapi', 'graphql', 'trpc', 'jsonschema'], description: 'Filter by schema kind.' },
-        detail: { type: 'boolean', description: 'Include full operations[] array. Default false — agents usually fetch by operation via annotask_get_api_operation.' },
-      },
-    },
-  },
-  {
-    name: 'annotask_get_api_operation',
-    description:
-      'Fetch a single operation by path (+ optional method). Returns the operation with `request_schema`, `response_schema`, `schema_refs` (named types to chase via further calls), and a `schema_location` pointer. ' +
-      'Use this after `annotask_get_data_context` surfaces a `response_schema_ref`, or after `annotask_resolve_endpoint` returns a match.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: 'Operation path pattern (OpenAPI: "/users/{id}"; GraphQL: field name like "users"; tRPC: procedure name "users.list").' },
-        method: { type: 'string', description: 'HTTP method for OpenAPI (GET/POST/...), or "query"/"mutation"/"subscription" for GraphQL, or "query"/"mutation" for tRPC.' },
-        schema_location: { type: 'string', description: 'Disambiguate when the same path exists in multiple discovered schemas — use the `location` from annotask_get_api_schemas.' },
-      },
-      required: ['path'],
-    },
-  },
-  {
-    name: 'annotask_resolve_endpoint',
-    description:
-      'Resolve a concrete URL (e.g. `/api/users/42`) against the discovered OpenAPI / GraphQL / tRPC schemas — returns the best-match operation with a confidence score. ' +
-      'Call this when `data_context` surfaces an endpoint and you want to know its declared response shape. Complementary to `annotask_get_api_operation`: use this when you have a URL, use `annotask_get_api_operation` when you have a path pattern.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        url: { type: 'string', description: 'Concrete URL or path. Query strings / fragments are stripped.' },
-        method: { type: 'string', description: 'HTTP method — improves match score when provided.' },
-      },
-      required: ['url'],
-    },
-  },
-  {
-    name: 'annotask_get_data_source_examples',
-    description:
-      'Find in-repo usages of a data source by name — symmetric with `annotask_get_component_examples`. Returns up to `limit` call sites (default 3) with ±5 lines of surrounding code and the dominant import path. ' +
-      'Use this after identifying a candidate hook/store/query from `annotask_get_data_sources` or from a task\'s `data_context`, to see how the project actually uses it (destructuring, parameters, common wrappers). ' +
-      'Pass `kind` for more accurate matching: `store` looks for property reads too (`userStore.x`), hook/fetch/rpc look for call sites only.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', description: 'Data source name to search for (case-sensitive identifier).' },
-        kind: { type: 'string', enum: ['composable', 'signal', 'store', 'fetch', 'graphql', 'loader', 'rpc'], description: 'DataSource kind — tightens the match regex (store matches property access too; signal matches bare reads and calls).' },
-        limit: { type: 'number', description: 'Max examples to return. Default 3, max 10.' },
-      },
-      required: ['name'],
-    },
-  },
-  {
-    name: 'annotask_get_runtime_endpoints',
-    description:
-      'List endpoints the frontend has *actually hit at runtime* — captured by the iframe-side network monitor (fetch + XHR + sendBeacon) and aggregated per (origin, method, path pattern). ' +
-      'This is the runtime counterpart to `annotask_get_data_sources`, whose regex-driven static scan can miss endpoints built from computed strings, generated clients, or dynamic libraries. ' +
-      'Each row carries `count`, `routes[]` (per iframe route with per-route counts), `statuses[]`, and a rotating `sampleUrls[]` for debugging. ' +
-      'When `enrich` is true (default), rows also include `matchedSources` (static `ProjectDataEntry` names whose endpoint aligns with this call) and `matchedSchemaLocation` / `matchedOperationId` for the best OpenAPI / GraphQL / tRPC operation match. ' +
-      'Use `orphans_only: true` to surface endpoints the static scanner missed — those are the highest-value gaps to look at.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        route: { type: 'string', description: 'Filter to endpoints hit on this iframe route (e.g. "/dashboard"). Matches against the per-call route recorded at capture time.' },
-        method: { type: 'string', description: 'Filter by HTTP method (GET/POST/PUT/PATCH/DELETE). Case-insensitive.' },
-        search: { type: 'string', description: 'Substring match (case-insensitive) on the endpoint path or one of its sample URLs.' },
-        orphans_only: { type: 'boolean', description: 'Only return endpoints with no matching static data source — gaps the regex scanner missed.' },
-        enrich: { type: 'boolean', description: 'Cross-reference each endpoint against the static data-source catalog and discovered API schemas. Default true.' },
-      },
-    },
-  },
-  {
-    name: 'annotask_get_data_source_details',
-    description:
-      'Pull the *definition* of a project-specific data source (hook, store, fetch wrapper, GraphQL operation, tRPC router) by name. ' +
-      'Complements `annotask_get_data_source_examples` (which shows call sites): this returns signature, return-type annotation, ±15 lines of surrounding body, the file\'s import block, co-located sibling exports, and referenced named types. ' +
-      'Regex-driven in V1 — results carry `resolved_by: "regex"` and a `confidence` field (high | medium | low). When multiple definitions share the name, returns `{ error: "ambiguous", candidates }`; narrow with `file` and/or `kind` and call again. ' +
-      'Not found → `{ error: "not_found", name }`.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', description: 'Data source name (case-sensitive identifier).' },
-        kind: { type: 'string', enum: ['composable', 'signal', 'store', 'fetch', 'graphql', 'loader', 'rpc'], description: 'Optional disambiguation when multiple kinds share a name.' },
-        file: { type: 'string', description: 'Optional disambiguation — project-relative file path to resolve the definition against.' },
-        context_lines: { type: 'number', description: 'Lines of body excerpt around the definition (default 15, max 40).' },
-      },
-      required: ['name'],
-    },
-  },
-]
-
-// ── Tool handlers ────────────────────────────────────
-
-function toolError(text: string): { content: unknown[]; isError: true } {
-  return { content: [{ type: 'text', text }], isError: true }
-}
-
-async function callTool(name: string, rawArgs: Record<string, unknown>, deps: McpDeps): Promise<{ content: unknown[]; isError?: boolean }> {
-  switch (name) {
-    case 'annotask_get_tasks': {
-      const parsed = parseWith(McpGetTasksArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const args = parsed.data
-      const taskData = deps.getTasks()
-      let tasks = taskData.tasks
-      if (args.status) tasks = tasks.filter(t => t.status === args.status)
-      if (args.mfe) tasks = filterTasksByMfe(tasks, args.mfe)
-
-      const output = args.detail === true
-        ? tasks.map(stripVisual)
-        : tasks.map(buildTaskSummary)
-
-      return { content: [{ type: 'text', text: compact({ version: taskData.version, count: output.length, tasks: output }) }] }
-    }
-
-    case 'annotask_get_task': {
-      const parsed = parseWith(McpGetTaskArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { task_id: taskId } = parsed.data
-      const taskData = deps.getTasks()
-      const task = taskData.tasks.find(t => t.id === taskId)
-      if (!task) return toolError(`Task not found: ${taskId}`)
-      const detail = trimAgentFeedback(stripVisual(task))
-      return { content: [{ type: 'text', text: compact(detail) }] }
-    }
-
-    case 'annotask_update_task': {
-      const parsed = parseWith(McpUpdateTaskArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const args = parsed.data
-      const taskId = args.task_id
-
-      const updates: Record<string, unknown> = {}
-
-      // Handle questions → agent_feedback thread
-      if (args.questions) {
-        const taskData = deps.getTasks()
-        const task = taskData.tasks.find(t => t.id === taskId)
-        if (!task) return toolError(`Task not found: ${taskId}`)
-
-        const entry: Record<string, unknown> = {
-          asked_at: Date.now(),
-          questions: args.questions,
-        }
-        if (args.question_context) entry.message = args.question_context
-        const existingFeedback = Array.isArray(task.agent_feedback) ? task.agent_feedback : []
-        const nextFeedback = [...existingFeedback, entry]
-        const check = AgentFeedbackSchema.safeParse(nextFeedback)
-        if (!check.success) return toolError(check.error.issues[0]?.message ?? 'Invalid agent_feedback')
-        updates.agent_feedback = nextFeedback
-        updates.status = args.status || 'needs_info'
-      } else if (args.status) {
-        updates.status = args.status
-      }
-
-      if (args.blocked_reason) {
-        updates.blocked_reason = args.blocked_reason
-        if (!updates.status) updates.status = 'blocked'
-      }
-      if (args.resolution) updates.resolution = args.resolution
-      if (args.feedback) updates.feedback = args.feedback
-
-      // Validate state transition
-      if (updates.status) {
-        const taskData = deps.getTasks()
-        const task = taskData.tasks.find(t => t.id === taskId)
-        if (!task) return toolError(`Task not found: ${taskId}`)
-        const reason = assertTransition(task.status, updates.status)
-        if (reason) return toolError(reason)
-      }
-
-      const result = await deps.updateTask(taskId, updates)
-      return { content: [{ type: 'text', text: compact(stripVisual(result)) }] }
-    }
-
-    case 'annotask_create_task': {
-      const parsed = parseWith(McpCreateTaskArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const args = parsed.data
-      const task: Record<string, unknown> = { type: args.type, description: args.description }
-      if (args.file) task.file = args.file
-      if (args.line != null) task.line = args.line
-      if (args.component) task.component = args.component
-      if (args.mfe) task.mfe = args.mfe
-      if (args.context) task.context = args.context
-      const result = await deps.addTask(task)
-      return { content: [{ type: 'text', text: compact(stripVisual(result)) }] }
-    }
-
-    case 'annotask_delete_task': {
-      const parsed = parseWith(McpDeleteTaskArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const result = await deps.deleteTask(parsed.data.task_id)
-      return { content: [{ type: 'text', text: compact(result) }] }
-    }
-
-    case 'annotask_get_design_spec': {
-      const parsed = parseWith(McpGetDesignSpecArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const spec = deps.getDesignSpec() as Record<string, any> | null
-      if (!spec) return { content: [{ type: 'text', text: compact({ initialized: false }) }] }
-
-      const category = parsed.data.category
-      if (category) {
-        const slice: Record<string, unknown> = { version: spec.version, framework: spec.framework }
-        if (category !== 'framework') {
-          if (!(category in spec)) return toolError(`Unknown category: ${category}`)
-          slice[category] = spec[category]
-        }
-        return { content: [{ type: 'text', text: compact(slice) }] }
-      }
-
-      // Summary mode: token counts instead of full data
-      const summary = {
-        version: spec.version,
-        framework: spec.framework,
-        counts: {
-          colors: spec.colors?.length ?? 0,
-          typographyFamilies: spec.typography?.families?.length ?? 0,
-          typographyScale: spec.typography?.scale?.length ?? 0,
-          spacing: spec.spacing?.length ?? 0,
-          borderRadius: spec.borders?.radius?.length ?? 0,
-        },
-        hasBreakpoints: !!spec.breakpoints && Object.keys(spec.breakpoints).length > 0,
-        icons: spec.icons ? { library: spec.icons.library } : null,
-        components: spec.components ? { library: spec.components.library, used: spec.components.used?.length ?? 0 } : null,
-      }
-      return { content: [{ type: 'text', text: compact(summary) }] }
-    }
-
-    case 'annotask_get_components': {
-      const parsed = parseWith(McpGetComponentsArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { search = '', library, category, used_only, detail = false, limit = 50, offset = 0 } = parsed.data
-      const catalog = await scanComponentLibraries(deps.projectRoot) as { libraries?: ScannedLibraryLike[] }
-
-      // Resolve the "used" set once, from design-spec, when used_only is requested.
-      let usedSet: Set<string> | null = null
-      if (used_only) {
-        const spec = deps.getDesignSpec() as { components?: { used?: unknown } } | null
-        const used = Array.isArray(spec?.components?.used) ? spec!.components!.used as unknown[] : []
-        usedSet = new Set(used.filter((u): u is string => typeof u === 'string'))
-      }
-
-      const searchLc = search.toLowerCase()
-      const libraries = (catalog.libraries || [])
-        .filter(lib => !library || lib.name === library)
-        .map((lib) => {
-          let components = (lib.components || []).filter(c => {
-            if (searchLc && !c.name.toLowerCase().includes(searchLc)) return false
-            if (category && c.category !== category) return false
-            if (usedSet && !usedSet.has(c.name)) return false
-            return true
-          })
-          const total = components.length
-          const paged = components.slice(offset, offset + limit)
-          return {
-            name: lib.name,
-            version: lib.version,
-            total,
-            components: paged.map(c => detail ? c : componentSummary(c)),
-          }
-        }).filter(lib => lib.components.length > 0)
-
-      return { content: [{ type: 'text', text: compact({ libraries }) }] }
-    }
-
-    case 'annotask_get_component': {
-      const parsed = parseWith(McpGetComponentArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { name, library } = parsed.data
-      const catalog = await scanComponentLibraries(deps.projectRoot) as { libraries?: ScannedLibraryLike[] }
-      const matches: Array<{ library: string; version: string | undefined; component: ScannedComponentLike }> = []
-      for (const lib of catalog.libraries || []) {
-        if (library && lib.name !== library) continue
-        for (const c of lib.components || []) {
-          if (c.name === name) matches.push({ library: lib.name, version: lib.version, component: c })
-        }
-      }
-      if (matches.length === 0) return toolError(`Component not found: ${name}${library ? ` (library: ${library})` : ''}`)
-      if (matches.length > 1 && !library) {
-        return {
-          content: [{ type: 'text', text: compact({
-            ambiguous: true,
-            message: `Found ${matches.length} components named ${name}. Pass \`library\` to disambiguate.`,
-            candidates: matches.map(m => ({ library: m.library, module: m.component.module })),
-          }) }],
-        }
-      }
-      const { library: libName, version, component } = matches[0]
-      return { content: [{ type: 'text', text: compact({ library: libName, version, ...component }) }] }
-    }
-
-    case 'annotask_get_code_context': {
-      const parsed = parseWith(McpGetCodeContextArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { task_id: taskId, context_lines: contextLines } = parsed.data
-      const taskData = deps.getTasks()
-      const task = taskData.tasks.find(t => t.id === taskId)
-      if (!task) return toolError(`Task not found: ${taskId}`)
-      const file = typeof task.file === 'string' ? task.file : ''
-      const line = typeof task.line === 'number' ? task.line : 0
-      if (!file) return toolError('Task has no file reference — cannot resolve code context')
-      const workspaceRoot = await getWorkspaceRoot(deps.projectRoot)
-      const result = await getCodeContext(deps.projectRoot, file, line, contextLines ?? 15, workspaceRoot)
-      return { content: [{ type: 'text', text: compact(result) }] }
-    }
-
-    case 'annotask_get_component_examples': {
-      const parsed = parseWith(McpGetComponentExamplesArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { name, limit, library } = parsed.data
-      const result = await getComponentExamples(deps.projectRoot, name, limit ?? 3, library)
-      return { content: [{ type: 'text', text: compact(result) }] }
-    }
-
-    case 'annotask_get_data_context': {
-      const parsed = parseWith(McpGetDataContextArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { task_id: taskId, refresh } = parsed.data
-      const taskData = deps.getTasks()
-      const task = taskData.tasks.find(t => t.id === taskId)
-      if (!task) return toolError(`Task not found: ${taskId}`)
-      const stored = task.data_context
-      if (!refresh && stored && typeof stored === 'object') {
-        return { content: [{ type: 'text', text: compact(stored) }] }
-      }
-      const file = typeof task.file === 'string' ? task.file : ''
-      const line = typeof task.line === 'number' ? task.line : 0
-      if (!file) return toolError('Task has no file reference — cannot resolve data context')
-      const workspaceRoot = await getWorkspaceRoot(deps.projectRoot)
-      const result = await resolveDataContext(deps.projectRoot, file, line, {}, workspaceRoot)
-      return { content: [{ type: 'text', text: compact(result) }] }
-    }
-
-    case 'annotask_get_interaction_history': {
-      const parsed = parseWith(McpGetInteractionHistoryArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { task_id: taskId } = parsed.data
-      const taskData = deps.getTasks()
-      const task = taskData.tasks.find(t => t.id === taskId)
-      if (!task) return toolError(`Task not found: ${taskId}`)
-      // Prefer embedded — the user opted in, so it's guaranteed fresh relative
-      // to the task. Fall back to the sidecar (always written at creation).
-      if (task.interaction_history) {
-        return { content: [{ type: 'text', text: compact(task.interaction_history) }] }
-      }
-      const stored = await deps.readInteractionHistory(taskId)
-      if (stored == null) {
-        return { content: [{ type: 'text', text: compact({ task_id: taskId, not_captured: true }) }] }
-      }
-      return { content: [{ type: 'text', text: compact(stored) }] }
-    }
-
-    case 'annotask_get_rendered_html': {
-      const parsed = parseWith(McpGetRenderedHtmlArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { task_id: taskId } = parsed.data
-      const taskData = deps.getTasks()
-      const task = taskData.tasks.find(t => t.id === taskId)
-      if (!task) return toolError(`Task not found: ${taskId}`)
-      const ctx = task.context as Record<string, unknown> | undefined
-      const embedded = ctx && typeof ctx.rendered === 'string' ? ctx.rendered : null
-      if (embedded) {
-        return { content: [{ type: 'text', text: compact({ task_id: taskId, rendered: embedded, source: 'embedded' }) }] }
-      }
-      const stored = await deps.readRenderedHtml(taskId)
-      if (stored == null) {
-        return { content: [{ type: 'text', text: compact({ task_id: taskId, rendered: null, not_captured: true }) }] }
-      }
-      return { content: [{ type: 'text', text: compact({ task_id: taskId, rendered: stored, source: 'sidecar' }) }] }
-    }
-
-    case 'annotask_get_data_sources': {
-      const parsed = parseWith(McpGetDataSourcesArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const args = parsed.data
-      const catalog = await scanDataSources(deps.projectRoot)
-      const libraries = args.library ? catalog.libraries.filter(l => l.name === args.library) : catalog.libraries
-      let entries = catalog.project_entries
-      // Promote orphan runtime endpoints into project_entries by default — the
-      // regex scanner is lossy and runtime capture is the backstop. Each
-      // promoted row carries `discovered_by: 'runtime'` so agents can tell
-      // them apart from regex-scanned ones.
-      const mergeRuntime = args.merge_runtime !== false
-      if (mergeRuntime && deps.getRuntimeEndpointCatalog) {
-        const runtimeCat = deps.getRuntimeEndpointCatalog()
-        entries = mergeRuntimeOrphansIntoEntries(entries, runtimeCat.endpoints)
-      }
-      if (args.kind) entries = entries.filter(e => e.kind === args.kind)
-      if (args.search) {
-        const q = args.search.toLowerCase()
-        entries = entries.filter(e => e.name.toLowerCase().includes(q))
-      }
-      if (args.used_only) entries = entries.filter(e => e.used_count > 0)
-      return { content: [{ type: 'text', text: compact({ libraries, project_entries: entries, scannedAt: catalog.scannedAt }) }] }
-    }
-
-    case 'annotask_get_api_schemas': {
-      const parsed = parseWith(McpGetApiSchemasArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { kind, detail } = parsed.data
-      const catalog = await scanApiSchemas(deps.projectRoot)
-      let schemas = catalog.schemas
-      if (kind) schemas = schemas.filter(s => s.kind === kind)
-      const emitted = detail ? schemas : schemas.map(s => ({ ...s, operations: [] }))
-      return { content: [{ type: 'text', text: compact({ schemas: emitted, scannedAt: catalog.scannedAt }) }] }
-    }
-
-    case 'annotask_get_api_operation': {
-      const parsed = parseWith(McpGetApiOperationArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { path, method, schema_location } = parsed.data
-      const catalog = await scanApiSchemas(deps.projectRoot)
-      const normMethod = method ? method.toUpperCase() : undefined
-      const matches: Array<Record<string, unknown>> = []
-      for (const schema of catalog.schemas) {
-        if (schema_location && schema.location !== schema_location) continue
-        for (const op of schema.operations) {
-          if (op.path !== path) continue
-          if (normMethod && op.method.toUpperCase() !== normMethod) continue
-          matches.push({ schema_location: schema.location, schema_kind: schema.kind, operation: op })
-        }
-      }
-      if (matches.length === 0) return toolError(`Operation not found: ${path}${method ? ` (${method})` : ''}`)
-      if (matches.length === 1) return { content: [{ type: 'text', text: compact(matches[0]) }] }
-      return { content: [{ type: 'text', text: compact({ ambiguous: true, candidates: matches }) }] }
-    }
-
-    case 'annotask_resolve_endpoint': {
-      const parsed = parseWith(McpResolveEndpointArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { url, method } = parsed.data
-      const catalog = await scanApiSchemas(deps.projectRoot)
-      const match = resolveEndpoint(catalog, url, method)
-      return { content: [{ type: 'text', text: compact({ match }) }] }
-    }
-
-    case 'annotask_get_runtime_endpoints': {
-      const parsed = parseWith(McpGetRuntimeEndpointsArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const args = parsed.data
-      const enrich = args.enrich !== false
-      const catalog = deps.getRuntimeEndpointCatalog
-        ? deps.getRuntimeEndpointCatalog()
-        : { version: '1.0' as const, updatedAt: 0, endpoints: [] as RuntimeEndpoint[] }
-      let endpoints = catalog.endpoints
-      if (args.route) endpoints = endpoints.filter(ep => ep.routes.some(r => r.route === args.route))
-      if (args.method) {
-        const m = args.method.toUpperCase()
-        endpoints = endpoints.filter(ep => ep.method === m)
-      }
-      if (args.search) {
-        const q = args.search.toLowerCase()
-        endpoints = endpoints.filter(ep =>
-          ep.path.toLowerCase().includes(q)
-          || ep.pattern.toLowerCase().includes(q)
-          || ep.sampleUrls.some(u => u.toLowerCase().includes(q)),
-        )
-      }
-      if (enrich) {
-        const [staticCat, schemaCat] = await Promise.all([
-          scanDataSources(deps.projectRoot),
-          scanApiSchemas(deps.projectRoot),
-        ])
-        endpoints = endpoints.map(ep => enrichRuntimeEndpoint(ep, staticCat.project_entries, schemaCat))
-      }
-      if (args.orphans_only) {
-        endpoints = endpoints.filter(ep => !ep.matchedSources || ep.matchedSources.length === 0)
-      }
-      return { content: [{ type: 'text', text: compact({ version: catalog.version, updatedAt: catalog.updatedAt, endpoints }) }] }
-    }
-
-    case 'annotask_get_data_source_examples': {
-      const parsed = parseWith(McpGetDataSourceExamplesArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { name, kind, limit } = parsed.data
-      const result = await getDataSourceExamples(deps.projectRoot, name, limit ?? 3, kind as DataSource['kind'] | undefined)
-      return { content: [{ type: 'text', text: compact(result) }] }
-    }
-
-    case 'annotask_get_data_source_details': {
-      const parsed = parseWith(McpGetDataSourceDetailsArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { name, kind, file, context_lines } = parsed.data
-      const workspaceRoot = await getWorkspaceRoot(deps.projectRoot)
-      const result = await resolveDataSourceDetails({
-        projectRoot: deps.projectRoot,
-        name,
-        kind: kind as DataSource['kind'] | undefined,
-        file,
-        contextLines: context_lines,
-        workspaceRoot,
-      })
-      return { content: [{ type: 'text', text: compact(result) }] }
-    }
-
-    case 'annotask_get_screenshot': {
-      const parsed = parseWith(McpGetScreenshotArgs, rawArgs)
-      if (!parsed.ok) return toolError(parsed.error)
-      const { task_id: taskId } = parsed.data
-      const taskData = deps.getTasks()
-      const task = taskData.tasks.find(t => t.id === taskId)
-      if (!task) return toolError(`Task not found: ${taskId}`)
-      if (!isSafeScreenshot(task.screenshot)) return toolError('Task has no screenshot')
-
-      const screenshotPath = nodePath.join(deps.projectRoot, '.annotask', 'screenshots', task.screenshot)
-      try {
-        const data = await fsp.readFile(screenshotPath)
-        return {
-          content: [
-            { type: 'image', data: data.toString('base64'), mimeType: 'image/png' },
-            { type: 'text', text: `Screenshot for task ${taskId}: ${task.description}` },
-          ],
-        }
-      } catch {
-        return { content: [{ type: 'text', text: `Screenshot file not found: ${task.screenshot}` }], isError: true }
-      }
-    }
-
-    default:
-      return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true }
-  }
-}
-
 // ── JSON-RPC dispatcher ──────────────────────────────
 
 async function handleJsonRpc(req: JsonRpcRequest, deps: McpDeps): Promise<JsonRpcResponse | null> {
-  // Notifications have no id — return null (no response)
   if (req.id === undefined) return null
 
   switch (req.method) {
@@ -966,7 +60,7 @@ async function handleJsonRpc(req: JsonRpcRequest, deps: McpDeps): Promise<JsonRp
       return { jsonrpc: '2.0', result: {}, id: req.id }
 
     case 'tools/list':
-      return { jsonrpc: '2.0', result: { tools: TOOLS }, id: req.id }
+      return { jsonrpc: '2.0', result: { tools: MCP_TOOLS }, id: req.id }
 
     case 'tools/call': {
       const params = req.params as { name: string; arguments?: Record<string, unknown> } | undefined
@@ -994,33 +88,6 @@ async function handleJsonRpc(req: JsonRpcRequest, deps: McpDeps): Promise<JsonRp
   }
 }
 
-/**
- * Annotate a runtime endpoint with the matching static sources and OpenAPI
- * operation. Mirrors the HTTP-side helper in `server/api.ts` — kept local so
- * the MCP layer doesn't have to import back into api.ts.
- */
-function enrichRuntimeEndpoint(
-  ep: RuntimeEndpoint,
-  staticEntries: Array<{ name: string; method?: string; endpoint?: string; resolved_endpoint?: string }>,
-  schemaCatalog: Awaited<ReturnType<typeof scanApiSchemas>>,
-): RuntimeEndpoint {
-  const out: RuntimeEndpoint = { ...ep }
-  // Origin-aware static matching — see api.ts:enrichEndpoint and
-  // runtime-endpoints.ts:findMatchingStaticEntries for the rationale.
-  const matched: string[] = []
-  for (const entry of findMatchingStaticEntries(ep, staticEntries)) {
-    if (!matched.includes(entry.name)) matched.push(entry.name)
-  }
-  if (matched.length > 0) out.matchedSources = matched
-  const sampleUrl = ep.sampleUrls[0] || ep.path
-  const match = resolveEndpoint(schemaCatalog, sampleUrl, ep.method)
-  if (match) {
-    out.matchedSchemaLocation = match.schema_location
-    if (match.operation.id) out.matchedOperationId = match.operation.id
-  }
-  return out
-}
-
 // ── HTTP middleware (Streamable HTTP transport) ───────
 
 function readBody(req: IncomingMessage): Promise<string> {
@@ -1041,7 +108,6 @@ export function createMcpMiddleware(deps: McpDeps) {
   return async (req: IncomingMessage, res: ServerResponse, next: () => void) => {
     if (!req.url?.startsWith('/__annotask/mcp')) return next()
 
-    // Localhost only
     if (!isLocalOrigin(req.headers.origin as string | undefined)) {
       res.statusCode = 403
       res.end('Forbidden')
@@ -1061,7 +127,6 @@ export function createMcpMiddleware(deps: McpDeps) {
       return
     }
 
-    // Prevent caching of MCP responses
     res.setHeader('Cache-Control', 'no-store')
 
     let raw: string
@@ -1102,10 +167,8 @@ export function createMcpMiddleware(deps: McpDeps) {
       return
     }
 
-    // Single request
     const request = parsed as JsonRpcRequest
     if (request.id === undefined) {
-      // Notification — process but don't respond
       await handleJsonRpc(request, deps)
       res.statusCode = 202
       res.end()
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
new file mode 100644
index 0000000..a62fab2
--- /dev/null
+++ b/src/mcp/tools.ts
@@ -0,0 +1,1224 @@
+// MCP tool catalog + in-process dispatcher.
+//
+// Both the MCP HTTP server (src/mcp/server.ts) and the embedded agent
+// (src/embedded/tool-bridge.ts) dispatch through `callTool` so external
+// editors and the in-shell runner see identical tool semantics.
+
+import fsp from 'node:fs/promises'
+import nodePath from 'node:path'
+import { z } from 'zod'
+import { scanComponentLibraries } from '../server/component-scanner.js'
+import { buildTaskSummary, filterTasksByMfe, stripTaskVisual, stripTaskForList, trimAgentFeedback, compactJson } from '../shared/task-summary.js'
+import { isSafeScreenshot } from '../server/validation.js'
+import { getCodeContext } from '../server/code-context.js'
+import { classifyBindings } from '../server/binding-classify.js'
+import { createAgentConfigStore } from '../server/agent-configs.js'
+import { loadSkill, TASK_TYPE_COMPANIONS } from '../skills/loader.js'
+import { getComponentExamples } from '../server/component-examples.js'
+import { resolveDataContext } from '../server/data-context.js'
+import { scanDataSources } from '../server/data-source-scanner.js'
+import { mergeRuntimeOrphansIntoEntries, findMatchingStaticEntries } from '../server/runtime-endpoints.js'
+import { getDataSourceExamples } from '../server/data-source-examples.js'
+import { resolveDataSourceDetails } from '../server/data-source-details.js'
+import { scanApiSchemas } from '../server/api-schema-scanner.js'
+import { resolveEndpoint } from '../server/api-schema-resolver.js'
+import { resolveWorkspace } from '../server/workspace.js'
+import { TASK_TYPES, type DataSource, type RuntimeEndpoint, type RuntimeEndpointCatalog } from '../schema.js'
+import type { TaskThreadStore, ThreadMessage } from '../server/task-thread.js'
+import {
+  McpGetTasksArgs,
+  McpGetTaskArgs,
+  McpUpdateTaskArgs,
+  McpCreateTaskArgs,
+  McpDeleteTaskArgs,
+  McpGetDesignSpecArgs,
+  McpGetComponentsArgs,
+  McpGetComponentArgs,
+  McpGetScreenshotArgs,
+  McpGetCodeContextArgs,
+  McpGetComponentExamplesArgs,
+  McpGetDataContextArgs,
+  McpGetInteractionHistoryArgs,
+  McpGetRenderedHtmlArgs,
+  McpGetDataSourcesArgs,
+  McpGetDataSourceExamplesArgs,
+  McpGetDataSourceDetailsArgs,
+  McpGetApiSchemasArgs,
+  McpGetApiOperationArgs,
+  McpResolveEndpointArgs,
+  McpGetRuntimeEndpointsArgs,
+  SafeSourceFile,
+  parseWith,
+  assertTransition,
+  AgentFeedbackSchema,
+} from '../server/schemas.js'
+
+// ── MCP-only argument schemas ────────────────────────────
+// These tools have no HTTP body counterpart in server/schemas.ts (the
+// source-excerpt route parses query params by hand), so their schemas live
+// next to the dispatcher that consumes them.
+
+/** `annotask_get_tasks` with optional pagination. Extends the shared schema
+ *  rather than replacing it so status/mfe/detail validation stays single-
+ *  sourced. No default limit — omitting both params preserves the historical
+ *  "return everything" behavior. */
+const McpGetTasksPagedArgs = McpGetTasksArgs.extend({
+  limit: z.number().int().min(1).max(500).optional(),
+  offset: z.number().int().min(0).optional(),
+})
+
+const McpGetSourceExcerptArgs = z.object({
+  file: SafeSourceFile,
+  line: z.number().int().min(1, 'line must be >= 1'),
+  context_lines: z.number().int().min(0).max(200).optional(),
+})
+
+const McpGetBindingClassificationArgs = z.object({
+  file: SafeSourceFile,
+  line: z.number().int().min(1, 'line must be >= 1'),
+  tag: z.string().max(200).optional(),
+})
+
+const taskTypeValues = [...TASK_TYPES] as [typeof TASK_TYPES[number], ...typeof TASK_TYPES[number][]]
+const McpGetPlaybookArgs = z.object({
+  task_type: z.enum(taskTypeValues, { message: `Invalid task type. Must be one of: ${TASK_TYPES.join(', ')}` }),
+})
+
+const McpGetAgentDirectionsArgs = z.object({
+  // Same id shape the HTTP PATCH /agent-configs/:id route enforces.
+  persona_id: z.string().regex(/^[a-z0-9-]+$/, 'Invalid persona id').optional(),
+})
+
+export interface ToolDef {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+
+export interface McpDeps {
+  projectRoot: string
+  getDesignSpec: () => unknown
+  getTasks: () => { version: string; tasks: Array<Record<string, unknown>> }
+  addTask: (task: Record<string, unknown>) => unknown | Promise<unknown>
+  updateTask: (id: string, updates: Record<string, unknown>) => unknown | Promise<unknown>
+  deleteTask: (id: string) => unknown | Promise<unknown>
+  readInteractionHistory: (taskId: string) => Promise<unknown | null>
+  readRenderedHtml: (taskId: string) => Promise<string | null>
+  /** Aggregated runtime-observed endpoint catalog. Optional — when missing, the MCP tool returns an empty catalog. */
+  getRuntimeEndpointCatalog?: () => RuntimeEndpointCatalog
+  /** Per-task conversation thread store. When omitted, the conversation tools return errors. */
+  taskThread?: TaskThreadStore
+}
+
+export interface ToolResult {
+  content: unknown[]
+  isError?: boolean
+}
+
+/** Monorepo root for containment checks, or `undefined` when the project is
+ *  not inside a workspace. Cached via `resolveWorkspace`. */
+async function getWorkspaceRoot(projectRoot: string): Promise<string | undefined> {
+  try {
+    const info = await resolveWorkspace(projectRoot)
+    return info.isWorkspace ? info.root : undefined
+  } catch {
+    return undefined
+  }
+}
+
+// Compact JSON + stripVisual + agent-feedback trimming are shared with the CLI
+// so agents get identical output whether they hit the MCP endpoint directly or
+// fall back to `npx annotask ... --mcp`.
+const compact = compactJson
+const stripVisual = stripTaskVisual
+
+// Minimal shapes so we don't drag the full scanner types through the MCP layer.
+interface ScannedComponentLike {
+  name: string
+  module: string
+  description?: string | null
+  category?: string | null
+  tags?: string[]
+  deprecated?: boolean
+  props?: Array<{ name: string }>
+  slots?: Array<{ name: string }>
+  events?: Array<{ name: string }>
+}
+interface ScannedLibraryLike {
+  name: string
+  version?: string
+  components?: ScannedComponentLike[]
+}
+
+/** Compact summary for an agent-facing component list — no props/slots/events bodies. */
+function componentSummary(c: ScannedComponentLike) {
+  return {
+    name: c.name,
+    module: c.module,
+    category: c.category ?? null,
+    description: c.description ?? null,
+    propCount: c.props?.length ?? 0,
+    slotCount: c.slots?.length ?? 0,
+    eventCount: c.events?.length ?? 0,
+    deprecated: c.deprecated ? true : undefined,
+  }
+}
+
+export const MCP_TOOLS: ToolDef[] = [
+  {
+    name: 'annotask_get_tasks',
+    description:
+      'Get design tasks from Annotask. Returns task summaries by default (id, type, status, description, file, line, action, screenshot). ' +
+      'Use detail=true for full objects including context and viewport. Even in detail mode, two bulky per-task payloads are always stripped from list output: ' +
+      '`interaction_history` (fetch via annotask_get_interaction_history) and `context.rendered` (fetch via annotask_get_rendered_html). ' +
+      'Use annotask_get_task to fetch full detail for a single task. ' +
+      'Paginate with `limit`/`offset` — omitting both returns every matching task. ' +
+      'Focus on "pending" and "denied" (with feedback) tasks for work to do.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'string',
+          description: 'Filter tasks by status',
+          enum: ['pending', 'in_progress', 'applied', 'review', 'denied', 'needs_info', 'blocked'],
+        },
+        mfe: {
+          type: 'string',
+          description: 'Filter by micro-frontend identity (e.g. "@myorg/my-mfe")',
+        },
+        detail: {
+          type: 'boolean',
+          description: 'If true, return full task objects. Default false returns summaries.',
+        },
+        limit: { type: 'number', description: 'Max tasks to return. No default — omit to return all matches.' },
+        offset: { type: 'number', description: 'Skip the first N matching tasks (pagination). Default 0.' },
+      },
+    },
+  },
+  {
+    name: 'annotask_get_task',
+    description:
+      'Get full details for a single task by ID. Returns all fields including context, interaction_history, and agent_feedback. ' +
+      'Use this after reviewing the task summary list to get full context for a specific task.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID to fetch' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_update_task',
+    description:
+      'Update a task status or fields. Common workflows:\n' +
+      '- Lock before working: status→"in_progress"\n' +
+      '- Mark applied: status→"review" + resolution note\n' +
+      '- Ask user questions: provide questions array (auto-sets status→"needs_info")\n' +
+      '- Mark blocked: provide blocked_reason (auto-sets status→"blocked")\n' +
+      'Valid transitions: pending→in_progress|denied, in_progress→review|needs_info|blocked|denied, review→accepted|denied|in_progress, needs_info→in_progress|denied, blocked→in_progress|denied, denied→pending|in_progress.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID to update' },
+        status: {
+          type: 'string',
+          description: 'New status for the task',
+          enum: ['pending', 'in_progress', 'applied', 'review', 'accepted', 'denied', 'needs_info', 'blocked'],
+        },
+        resolution: { type: 'string', description: 'Brief note on what was changed (use when marking review)' },
+        feedback: { type: 'string', description: 'Denial notes from reviewer' },
+        blocked_reason: { type: 'string', description: 'Why the task cannot be applied (markdown). Auto-sets status to "blocked" if no status given.' },
+        questions: {
+          type: 'array',
+          description: 'Ask the user clarifying questions. Auto-sets status to "needs_info" if no status given.',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'Unique question ID (e.g. "q1")' },
+              text: { type: 'string', description: 'The question text' },
+              type: { type: 'string', enum: ['text', 'choice'], description: '"text" for free-text, "choice" for multiple choice' },
+              options: { type: 'array', items: { type: 'string' }, description: 'Choices (required when type is "choice")' },
+            },
+            required: ['id', 'text', 'type'],
+          },
+        },
+        question_context: { type: 'string', description: 'Optional markdown context to accompany questions' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_create_task',
+    description: `Create a new design task with "pending" status. Types: ${TASK_TYPES.join(', ')}.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: { type: 'string', description: 'Task type' },
+        description: { type: 'string', description: 'What needs to be done (markdown)' },
+        file: { type: 'string', description: 'Source file path' },
+        line: { type: 'number', description: 'Line number in file' },
+        component: { type: 'string', description: 'Component name' },
+        mfe: { type: 'string', description: 'MFE identity (e.g. "@myorg/my-mfe") for multi-project setups' },
+        context: { type: 'object', description: 'Arbitrary context data' },
+      },
+      required: ['type', 'description'],
+    },
+  },
+  {
+    name: 'annotask_delete_task',
+    description: 'Permanently delete a task and its associated screenshot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID to delete' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_get_design_spec',
+    description:
+      'Get the project design specification. Without a category, returns a summary (framework info, token counts). ' +
+      'With a category, returns full tokens for that category. Generated by /annotask-init.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        category: {
+          type: 'string',
+          description: 'Return only this category. Omit for a summary overview.',
+          enum: ['colors', 'typography', 'spacing', 'borders', 'breakpoints', 'icons', 'components', 'framework'],
+        },
+      },
+    },
+  },
+  {
+    name: 'annotask_get_components',
+    description:
+      'Search component libraries detected in node_modules. By default returns compact summaries (name, module, category) — set detail=true for full props/slots/events/description. ' +
+      'Filters: `search` (name substring), `library` (exact library name), `category` (e.g. "button", "form"), `used_only` (restrict to components actually imported in this codebase — highest-signal filter). ' +
+      'Paginate with `limit` (default 50, max 500) and `offset`. For a single component use annotask_get_component.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        search: { type: 'string', description: 'Filter components by name (case-insensitive substring match)' },
+        library: { type: 'string', description: 'Exact library name (e.g. "primevue")' },
+        category: { type: 'string', description: 'Category filter (e.g. "button", "form", "overlay", "data", "layout")' },
+        used_only: { type: 'boolean', description: 'Return only components that are actually imported in the codebase (from design-spec.components.used)' },
+        detail: { type: 'boolean', description: 'Include full props, slots, events, and description. Default false returns compact summaries.' },
+        limit: { type: 'number', description: 'Max results per library. Default 50, max 500.' },
+        offset: { type: 'number', description: 'Skip the first N results (pagination). Default 0.' },
+      },
+    },
+  },
+  {
+    name: 'annotask_get_component',
+    description:
+      'Get full detail for a single component by name: props, slots, events, description, category, import module. ' +
+      'Use after annotask_get_components identifies candidates. Provide `library` to disambiguate when the same name exists in multiple libraries.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Component name (e.g. "Button", "DataTable")' },
+        library: { type: 'string', description: 'Library name to disambiguate (e.g. "primevue")' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'annotask_get_screenshot',
+    description: 'Get a task screenshot as a base64-encoded PNG image. Screenshots show what the user sees in the browser, providing visual context for what change is needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID whose screenshot to fetch' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_get_code_context',
+    description:
+      'Resolve a task to grounded source context: a ±15 line excerpt around `task.line`, the nearest enclosing symbol/component, the file\'s import block, and a short `excerpt_hash` for drift detection. ' +
+      'Prefer this over trusting `task.line` when a task has been retried, is older than your current triage pass, or when a prior Edit touched the same file. ' +
+      'Use `context_lines` to widen/narrow the window (default 15, max 200).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID to resolve source context for' },
+        context_lines: { type: 'number', description: 'Lines of context on each side of task.line. Default 15, max 200.' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_get_source_excerpt',
+    description:
+      'Ground an *arbitrary* file/line to current source: same payload as annotask_get_code_context (±N line excerpt, nearest enclosing symbol, import block, `excerpt_hash`) but keyed by file path instead of task id. ' +
+      'Use this when a task references locations beyond its own `file`/`line` — e.g. each `anchor.file`/`anchor.line` of a wireframe_apply instance, an arrow task\'s `to_element`, or any file you are about to edit and want to re-anchor first. ' +
+      'Paths are project-relative and containment-checked server-side; escaping paths return an `error` field. Use `context_lines` to widen/narrow the window (default 15, max 200).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Project-relative source file path (e.g. "src/pages/Home.vue")' },
+        line: { type: 'number', description: '1-based line number to center the excerpt on' },
+        context_lines: { type: 'number', description: 'Lines of context on each side. Default 15, max 200.' },
+      },
+      required: ['file', 'line'],
+    },
+  },
+  {
+    name: 'annotask_get_binding_classification',
+    description:
+      'Round-trip-honesty classification of one element against CURRENT source: every attribute/prop at the usage site classified literal | bound | unknown (with the expression text), the text content classified literal | bound | mixed, and any enclosing loop (v-for / .map() / {#each}). ' +
+      'Use this before rewriting a prop or text from a design-session edit when the anchor may have drifted, or to confirm a value is a plain literal (safe to rewrite) vs a bound expression (never rewrite). ' +
+      '`tag` narrows the match when several elements share a line. Parse failures and ambiguous lines return an `error` field with everything read-only — treat that as "do not edit here without re-anchoring".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Project-relative source file path (e.g. "src/pages/Home.vue")' },
+        line: { type: 'number', description: '1-based line of the element\'s opening tag' },
+        tag: { type: 'string', description: 'Tag/component name to disambiguate (e.g. "PlanetCard", "h1")' },
+      },
+      required: ['file', 'line'],
+    },
+  },
+  {
+    name: 'annotask_get_component_examples',
+    description:
+      'Find real in-repo usages of a component by name. Returns up to `limit` call sites (default 3) with a short surrounding source snippet, the line number, and the most common import path for the component. ' +
+      'Use this when you are about to reuse or place a component and want to match the repo\'s own conventions (prop combinations, wrapper patterns, slot usage) rather than invent new ones. ' +
+      'Pass `library` (e.g. `@mantine/core`, `radix-vue`) to keep same-name components from different libraries out of the result.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Component name to search for (case-sensitive)' },
+        limit: { type: 'number', description: 'Max examples to return. Default 3, max 10.' },
+        library: { type: 'string', description: 'Optional library/package name (e.g. @mantine/core). Only examples whose import specifier belongs to this library are returned.' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'annotask_get_interaction_history',
+    description:
+      'Retrieve the user\'s pre-task interaction trace: navigation path plus the last ~20 recorded actions (clicks, form submits, route changes) as of task creation. ' +
+      'Always captured server-side — the per-task "Embed interaction history" toggle only decides whether this data rides in the task payload, so use this tool whenever an annotation references a flow or sequence ("after I click submit…", "on the orders page…") and the payload itself lacks `interaction_history`. ' +
+      'Returns the stored snapshot (or the embedded copy when the user opted in). If nothing was captured (e.g. task came from an external API caller), the response has `not_captured: true`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID whose interaction history to fetch' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_get_rendered_html',
+    description:
+      'Fetch the `outerHTML` of the element the task was attached to, captured post-render at task creation (React/Vue bindings resolved, annotask attrs stripped). ' +
+      'Always captured when a selection existed — the "Embed rendered HTML" toggle only gates embedding in the task payload. Use this when the task description references visual structure that is hard to reconstruct from source alone ("the three spans in the header", "this button\'s icon wrapper") or when you need to match existing inline markup for a style fix. ' +
+      'Response shape: `{ task_id, rendered, source }` where `source` is `"embedded"` (read from the task payload) or `"sidecar"` (loaded from the per-task store). `{ rendered: null, not_captured: true }` when no snapshot exists. Hard-capped at 200 KB per task.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID whose rendered HTML to fetch' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_get_data_context',
+    description:
+      'Resolve (or return stored) data_context for a task — what hooks/stores/fetch calls power the selected element. ' +
+      'Returns `sources[]` — every data reference in the enclosing file, sorted with the primary (nearest to `task.line`, tie-broken hook>store>fetch>graphql>loader>rpc) at index 0 — plus `rendered_identifiers` (template/JSX names, CSV) and `route_bindings` (route params/query keys, CSV). ' +
+      'Use this before editing or inserting any data-driven UI so you reuse the repo\'s own queries/stores instead of writing fake data. Pass `refresh: true` to force a fresh scan even if the task already stores a data_context.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'The task ID to resolve data context for' },
+        refresh: { type: 'boolean', description: 'Ignore stored data_context on the task and re-scan the source file.' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_get_data_sources',
+    description:
+      'List the project-wide data source catalog: detected data-fetching libraries from package.json (React Query, SWR, Pinia, Zustand, Apollo, tRPC, …) and project-specific entries found in `src/` (user hooks, stores, fetch wrappers, GraphQL operations). ' +
+      '`project_entries` come sorted by `used_count` descending — the most load-bearing entries first. Use this when deciding which existing data source to reuse before writing new code. ' +
+      'By default, orphan endpoints observed at runtime (fetch/XHR traffic the regex scanner missed) are promoted into `project_entries` with `discovered_by: "runtime"` and `file: ""` — these represent real APIs the frontend hits but that the static pass couldn\'t pin to a source location. Pass `merge_runtime: false` for a pure static-scan view; use `annotask_get_runtime_endpoints` for the full runtime catalog.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['composable', 'signal', 'store', 'fetch', 'graphql', 'loader', 'rpc'], description: 'Only return project entries of this kind. "composable" covers React hooks, Vue composables, Svelte helpers, Solid primitive wrappers. "signal" is fine-grained reactive (Solid createSignal, Svelte store reads).' },
+        library: { type: 'string', description: 'Only return this library from the libraries list.' },
+        search: { type: 'string', description: 'Substring match on project entry name (case-insensitive).' },
+        used_only: { type: 'boolean', description: 'Restrict project entries to `used_count > 0` — analogous to `annotask_get_components` used_only filter.' },
+        merge_runtime: { type: 'boolean', description: 'Include orphan runtime-observed endpoints as synthetic `project_entries` (default true). These carry `discovered_by: "runtime"` and have `file: ""` because they were found by live network capture, not source scan. Set false for static-only.' },
+      },
+    },
+  },
+  {
+    name: 'annotask_get_api_schemas',
+    description:
+      'List discovered API schemas. Sources: OpenAPI/Swagger JSON/YAML files, GraphQL SDL files, tRPC routers (with zod input/output), and live dev-server probes at common paths (/openapi.json, /graphql with introspection, etc.). ' +
+      'Default returns compact entries (kind, location, title, operation_count). Set detail=true to include every `operations[]` with full request/response schemas. ' +
+      'Use alongside `annotask_get_data_context` — when a source has `response_schema_ref`, this tool lets you pull the full shape.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['openapi', 'graphql', 'trpc', 'jsonschema'], description: 'Filter by schema kind.' },
+        detail: { type: 'boolean', description: 'Include full operations[] array. Default false — agents usually fetch by operation via annotask_get_api_operation.' },
+      },
+    },
+  },
+  {
+    name: 'annotask_get_api_operation',
+    description:
+      'Fetch a single operation by path (+ optional method). Returns the operation with `request_schema`, `response_schema`, `schema_refs` (named types to chase via further calls), and a `schema_location` pointer. ' +
+      'Use this after `annotask_get_data_context` surfaces a `response_schema_ref`, or after `annotask_resolve_endpoint` returns a match.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Operation path pattern (OpenAPI: "/users/{id}"; GraphQL: field name like "users"; tRPC: procedure name "users.list").' },
+        method: { type: 'string', description: 'HTTP method for OpenAPI (GET/POST/...), or "query"/"mutation"/"subscription" for GraphQL, or "query"/"mutation" for tRPC.' },
+        schema_location: { type: 'string', description: 'Disambiguate when the same path exists in multiple discovered schemas — use the `location` from annotask_get_api_schemas.' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'annotask_resolve_endpoint',
+    description:
+      'Resolve a concrete URL (e.g. `/api/users/42`) against the discovered OpenAPI / GraphQL / tRPC schemas — returns the best-match operation with a confidence score. ' +
+      'Call this when `data_context` surfaces an endpoint and you want to know its declared response shape. Complementary to `annotask_get_api_operation`: use this when you have a URL, use `annotask_get_api_operation` when you have a path pattern.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'Concrete URL or path. Query strings / fragments are stripped.' },
+        method: { type: 'string', description: 'HTTP method — improves match score when provided.' },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'annotask_get_data_source_examples',
+    description:
+      'Find in-repo usages of a data source by name — symmetric with `annotask_get_component_examples`. Returns up to `limit` call sites (default 3) with ±5 lines of surrounding code and the dominant import path. ' +
+      'Use this after identifying a candidate hook/store/query from `annotask_get_data_sources` or from a task\'s `data_context`, to see how the project actually uses it (destructuring, parameters, common wrappers). ' +
+      'Pass `kind` for more accurate matching: `store` looks for property reads too (`userStore.x`), hook/fetch/rpc look for call sites only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Data source name to search for (case-sensitive identifier).' },
+        kind: { type: 'string', enum: ['composable', 'signal', 'store', 'fetch', 'graphql', 'loader', 'rpc'], description: 'DataSource kind — tightens the match regex (store matches property access too; signal matches bare reads and calls).' },
+        limit: { type: 'number', description: 'Max examples to return. Default 3, max 10.' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'annotask_get_runtime_endpoints',
+    description:
+      'List endpoints the frontend has *actually hit at runtime* — captured by the iframe-side network monitor (fetch + XHR + sendBeacon) and aggregated per (origin, method, path pattern). ' +
+      'This is the runtime counterpart to `annotask_get_data_sources`, whose regex-driven static scan can miss endpoints built from computed strings, generated clients, or dynamic libraries. ' +
+      'Each row carries `count`, `routes[]` (per iframe route with per-route counts), `statuses[]`, and a rotating `sampleUrls[]` for debugging. ' +
+      'When `enrich` is true (default), rows also include `matchedSources` (static `ProjectDataEntry` names whose endpoint aligns with this call) and `matchedSchemaLocation` / `matchedOperationId` for the best OpenAPI / GraphQL / tRPC operation match. ' +
+      'Use `orphans_only: true` to surface endpoints the static scanner missed — those are the highest-value gaps to look at.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        route: { type: 'string', description: 'Filter to endpoints hit on this iframe route (e.g. "/dashboard"). Matches against the per-call route recorded at capture time.' },
+        method: { type: 'string', description: 'Filter by HTTP method (GET/POST/PUT/PATCH/DELETE). Case-insensitive.' },
+        search: { type: 'string', description: 'Substring match (case-insensitive) on the endpoint path or one of its sample URLs.' },
+        orphans_only: { type: 'boolean', description: 'Only return endpoints with no matching static data source — gaps the regex scanner missed.' },
+        enrich: { type: 'boolean', description: 'Cross-reference each endpoint against the static data-source catalog and discovered API schemas. Default true.' },
+      },
+    },
+  },
+  {
+    name: 'annotask_conversation_read',
+    description:
+      'Read the per-task conversation thread for the embedded chat. Returns messages in append order. ' +
+      'Use `after_id` to fetch only messages newer than a known id (cheap polling).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task whose conversation to read.' },
+        after_id: { type: 'string', description: 'Return only messages with an id greater than this.' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_conversation_post',
+    description:
+      'Append a message to a task\'s conversation thread. Used by external CLI agents (claude/codex/opencode) so the in-shell Conversation tab and the terminal stay in sync. ' +
+      '`role` is one of user|assistant|system|tool. The returned record carries the server-minted `id` and `ts`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string', description: 'Task whose conversation to post to.' },
+        role: { type: 'string', enum: ['user', 'assistant', 'system', 'tool'] },
+        content: { type: 'string', description: 'Message content (markdown allowed).' },
+        provider_id: { type: 'string', description: 'Provider that generated the turn (for assistant messages).' },
+        model: { type: 'string', description: 'Model id reported by the provider.' },
+      },
+      required: ['task_id', 'role', 'content'],
+    },
+  },
+  {
+    name: 'annotask_conversation_subscribe',
+    description:
+      'Long-poll for new conversation messages. Returns immediately if there are messages after `after_id`; otherwise waits up to `timeout_ms` (default 25000, max 55000) for one. ' +
+      'External agents loop on this tool to mirror an SSE subscription without persistent connections.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: { type: 'string' },
+        after_id: { type: 'string', description: 'Latest id the caller has already seen.' },
+        timeout_ms: { type: 'number', description: 'Max wait in milliseconds (default 25000, max 55000).' },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'annotask_get_data_source_details',
+    description:
+      'Pull the *definition* of a project-specific data source (hook, store, fetch wrapper, GraphQL operation, tRPC router) by name. ' +
+      'Complements `annotask_get_data_source_examples` (which shows call sites): this returns signature, return-type annotation, ±15 lines of surrounding body, the file\'s import block, co-located sibling exports, and referenced named types. ' +
+      'Regex-driven in V1 — results carry `resolved_by: "regex"` and a `confidence` field (high | medium | low). When multiple definitions share the name, returns `{ error: "ambiguous", candidates }`; narrow with `file` and/or `kind` and call again. ' +
+      'Not found → `{ error: "not_found", name }`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Data source name (case-sensitive identifier).' },
+        kind: { type: 'string', enum: ['composable', 'signal', 'store', 'fetch', 'graphql', 'loader', 'rpc'], description: 'Optional disambiguation when multiple kinds share a name.' },
+        file: { type: 'string', description: 'Optional disambiguation — project-relative file path to resolve the definition against.' },
+        context_lines: { type: 'number', description: 'Lines of body excerpt around the definition (default 15, max 40).' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'annotask_get_playbook',
+    description:
+      'Fetch the task-type companion playbook — detailed apply instructions that supplement the base annotask-apply skill. ' +
+      'Companions exist for: a11y_fix, theme_update, error_fix, perf_fix, wireframe_apply. Call this before applying your first task of one of those types ' +
+      '(once per batch, not once per task). Other task types return no `content`, just a `message` — the base instructions (served as MCP initialize.instructions) already cover them. ' +
+      'Response shape: `{ task_type, file, content }` where `content` is the playbook markdown.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_type: { type: 'string', description: 'Task type to fetch the playbook for', enum: [...TASK_TYPES] },
+      },
+      required: ['task_type'],
+    },
+  },
+  {
+    name: 'annotask_get_agent_directions',
+    description:
+      'Fetch per-persona project directions — project-specific guidance written by the init agent and editable in Settings (conventions, file layout, gotchas the user wants every agent to honor). ' +
+      'Built-in persona ids: general (annotations/sections/wireframes), designer (style/theme), a11y, bug-hunter (errors/perf). ' +
+      'Without `persona_id`, returns the full `{ version, agents }` map. With one, returns that persona\'s entry — `not_configured: true` (with empty directions) when nothing was written for it. ' +
+      'Read the directions for the persona matching your task type before applying changes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        persona_id: { type: 'string', description: 'Persona id (e.g. "general", "designer", "a11y", "bug-hunter"). Omit for all personas.' },
+      },
+    },
+  },
+]
+
+function toolError(text: string): ToolResult {
+  return { content: [{ type: 'text', text }], isError: true }
+}
+
+function stringArg(args: Record<string, unknown>, key: string): string | undefined {
+  const v = args[key]
+  return typeof v === 'string' && v.length > 0 ? v : undefined
+}
+
+function optionalStringArg(args: Record<string, unknown>, key: string): string | undefined {
+  const v = args[key]
+  return typeof v === 'string' && v.length > 0 ? v : undefined
+}
+
+/**
+ * In-process tool dispatcher. Both the MCP HTTP transport and the embedded
+ * agent route through here. Returns a `{ content, isError? }` envelope shaped
+ * for MCP `tools/call` responses.
+ */
+export async function callTool(name: string, rawArgs: Record<string, unknown>, deps: McpDeps): Promise<ToolResult> {
+  switch (name) {
+    case 'annotask_get_tasks': {
+      const parsed = parseWith(McpGetTasksPagedArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const args = parsed.data
+      const taskData = deps.getTasks()
+      let tasks = taskData.tasks
+      if (args.status) tasks = tasks.filter(t => t.status === args.status)
+      if (args.mfe) tasks = filterTasksByMfe(tasks, args.mfe)
+
+      // `total` is the post-filter, pre-pagination count (mirrors the
+      // per-library `total` in annotask_get_components). No default limit —
+      // both params omitted returns everything, as before pagination existed.
+      const total = tasks.length
+      if (args.limit != null || args.offset != null) {
+        const offset = args.offset ?? 0
+        tasks = tasks.slice(offset, args.limit != null ? offset + args.limit : undefined)
+      }
+
+      // Detail mode uses the *list* strip: interaction_history and
+      // context.rendered always come off here — they each have a dedicated
+      // retrieval tool and would otherwise dominate the payload.
+      const output = args.detail === true
+        ? tasks.map(stripTaskForList)
+        : tasks.map(buildTaskSummary)
+
+      return { content: [{ type: 'text', text: compact({ version: taskData.version, total, count: output.length, tasks: output }) }] }
+    }
+
+    case 'annotask_get_task': {
+      const parsed = parseWith(McpGetTaskArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { task_id: taskId } = parsed.data
+      const taskData = deps.getTasks()
+      const task = taskData.tasks.find(t => t.id === taskId)
+      if (!task) return toolError(`Task not found: ${taskId}`)
+      const detail = trimAgentFeedback(stripVisual(task))
+      return { content: [{ type: 'text', text: compact(detail) }] }
+    }
+
+    case 'annotask_update_task': {
+      const parsed = parseWith(McpUpdateTaskArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const args = parsed.data
+      const taskId = args.task_id
+
+      const updates: Record<string, unknown> = {}
+
+      if (args.questions) {
+        const taskData = deps.getTasks()
+        const task = taskData.tasks.find(t => t.id === taskId)
+        if (!task) return toolError(`Task not found: ${taskId}`)
+
+        const entry: Record<string, unknown> = {
+          asked_at: Date.now(),
+          questions: args.questions,
+        }
+        if (args.question_context) entry.message = args.question_context
+        const existingFeedback = Array.isArray(task.agent_feedback) ? task.agent_feedback : []
+        const nextFeedback = [...existingFeedback, entry]
+        const check = AgentFeedbackSchema.safeParse(nextFeedback)
+        if (!check.success) return toolError(check.error.issues[0]?.message ?? 'Invalid agent_feedback')
+        updates.agent_feedback = nextFeedback
+        updates.status = args.status || 'needs_info'
+      } else if (args.status) {
+        updates.status = args.status
+      }
+
+      if (args.blocked_reason) {
+        updates.blocked_reason = args.blocked_reason
+        if (!updates.status) updates.status = 'blocked'
+      }
+      if (args.resolution) updates.resolution = args.resolution
+      if (args.feedback) updates.feedback = args.feedback
+
+      if (updates.status) {
+        const taskData = deps.getTasks()
+        const task = taskData.tasks.find(t => t.id === taskId)
+        if (!task) return toolError(`Task not found: ${taskId}`)
+        const reason = assertTransition(task.status, updates.status)
+        if (reason) return toolError(reason)
+      }
+
+      const result = await deps.updateTask(taskId, updates)
+      return { content: [{ type: 'text', text: compact(stripVisual(result)) }] }
+    }
+
+    case 'annotask_create_task': {
+      const parsed = parseWith(McpCreateTaskArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const args = parsed.data
+      const task: Record<string, unknown> = { type: args.type, description: args.description }
+      if (args.file) task.file = args.file
+      if (args.line != null) task.line = args.line
+      if (args.component) task.component = args.component
+      if (args.mfe) task.mfe = args.mfe
+      if (args.context) task.context = args.context
+      const result = await deps.addTask(task)
+      return { content: [{ type: 'text', text: compact(stripVisual(result)) }] }
+    }
+
+    case 'annotask_delete_task': {
+      const parsed = parseWith(McpDeleteTaskArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const result = await deps.deleteTask(parsed.data.task_id)
+      return { content: [{ type: 'text', text: compact(result) }] }
+    }
+
+    case 'annotask_get_design_spec': {
+      const parsed = parseWith(McpGetDesignSpecArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const spec = deps.getDesignSpec() as Record<string, any> | null
+      if (!spec) return { content: [{ type: 'text', text: compact({ initialized: false }) }] }
+
+      const category = parsed.data.category
+      if (category) {
+        const slice: Record<string, unknown> = { version: spec.version, framework: spec.framework }
+        if (category !== 'framework') {
+          if (!(category in spec)) return toolError(`Unknown category: ${category}`)
+          slice[category] = spec[category]
+        }
+        return { content: [{ type: 'text', text: compact(slice) }] }
+      }
+
+      const summary = {
+        version: spec.version,
+        framework: spec.framework,
+        counts: {
+          colors: spec.colors?.length ?? 0,
+          typographyFamilies: spec.typography?.families?.length ?? 0,
+          typographyScale: spec.typography?.scale?.length ?? 0,
+          spacing: spec.spacing?.length ?? 0,
+          borderRadius: spec.borders?.radius?.length ?? 0,
+        },
+        hasBreakpoints: !!spec.breakpoints && Object.keys(spec.breakpoints).length > 0,
+        icons: spec.icons ? { library: spec.icons.library } : null,
+        components: spec.components ? { library: spec.components.library, used: spec.components.used?.length ?? 0 } : null,
+      }
+      return { content: [{ type: 'text', text: compact(summary) }] }
+    }
+
+    case 'annotask_get_components': {
+      const parsed = parseWith(McpGetComponentsArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { search = '', library, category, used_only, detail = false, limit = 50, offset = 0 } = parsed.data
+      const catalog = await scanComponentLibraries(deps.projectRoot) as { libraries?: ScannedLibraryLike[] }
+
+      let usedSet: Set<string> | null = null
+      if (used_only) {
+        const spec = deps.getDesignSpec() as { components?: { used?: unknown } } | null
+        const used = Array.isArray(spec?.components?.used) ? spec!.components!.used as unknown[] : []
+        usedSet = new Set(used.filter((u): u is string => typeof u === 'string'))
+      }
+
+      const searchLc = search.toLowerCase()
+      const libraries = (catalog.libraries || [])
+        .filter(lib => !library || lib.name === library)
+        .map((lib) => {
+          let components = (lib.components || []).filter(c => {
+            if (searchLc && !c.name.toLowerCase().includes(searchLc)) return false
+            if (category && c.category !== category) return false
+            if (usedSet && !usedSet.has(c.name)) return false
+            return true
+          })
+          const total = components.length
+          const paged = components.slice(offset, offset + limit)
+          return {
+            name: lib.name,
+            version: lib.version,
+            total,
+            components: paged.map(c => detail ? c : componentSummary(c)),
+          }
+        }).filter(lib => lib.components.length > 0)
+
+      return { content: [{ type: 'text', text: compact({ libraries }) }] }
+    }
+
+    case 'annotask_get_component': {
+      const parsed = parseWith(McpGetComponentArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { name, library } = parsed.data
+      const catalog = await scanComponentLibraries(deps.projectRoot) as { libraries?: ScannedLibraryLike[] }
+      const matches: Array<{ library: string; version: string | undefined; component: ScannedComponentLike }> = []
+      for (const lib of catalog.libraries || []) {
+        if (library && lib.name !== library) continue
+        for (const c of lib.components || []) {
+          if (c.name === name) matches.push({ library: lib.name, version: lib.version, component: c })
+        }
+      }
+      if (matches.length === 0) return toolError(`Component not found: ${name}${library ? ` (library: ${library})` : ''}`)
+      if (matches.length > 1 && !library) {
+        return {
+          content: [{ type: 'text', text: compact({
+            ambiguous: true,
+            message: `Found ${matches.length} components named ${name}. Pass \`library\` to disambiguate.`,
+            candidates: matches.map(m => ({ library: m.library, module: m.component.module })),
+          }) }],
+        }
+      }
+      const { library: libName, version, component } = matches[0]
+      return { content: [{ type: 'text', text: compact({ library: libName, version, ...component }) }] }
+    }
+
+    case 'annotask_get_code_context': {
+      const parsed = parseWith(McpGetCodeContextArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { task_id: taskId, context_lines: contextLines } = parsed.data
+      const taskData = deps.getTasks()
+      const task = taskData.tasks.find(t => t.id === taskId)
+      if (!task) return toolError(`Task not found: ${taskId}`)
+      const file = typeof task.file === 'string' ? task.file : ''
+      const line = typeof task.line === 'number' ? task.line : 0
+      if (!file) return toolError('Task has no file reference — cannot resolve code context')
+      const workspaceRoot = await getWorkspaceRoot(deps.projectRoot)
+      const result = await getCodeContext(deps.projectRoot, file, line, contextLines ?? 15, workspaceRoot)
+      return { content: [{ type: 'text', text: compact(result) }] }
+    }
+
+    case 'annotask_get_source_excerpt': {
+      const parsed = parseWith(McpGetSourceExcerptArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { file, line, context_lines: contextLines } = parsed.data
+      // Same resolution as GET /__annotask/api/source-excerpt: getCodeContext
+      // runs the path through resolveProjectFile, so escaping/absolute paths
+      // come back as `{ error: 'Invalid or escaping file path' }` rather than
+      // reading outside the workspace.
+      const workspaceRoot = await getWorkspaceRoot(deps.projectRoot)
+      const result = await getCodeContext(deps.projectRoot, file, line, contextLines ?? 15, workspaceRoot)
+      return { content: [{ type: 'text', text: compact(result) }] }
+    }
+
+    case 'annotask_get_binding_classification': {
+      const parsed = parseWith(McpGetBindingClassificationArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { file, line, tag } = parsed.data
+      const workspaceRoot = await getWorkspaceRoot(deps.projectRoot)
+      const result = await classifyBindings(deps.projectRoot, file, line, { tag, workspaceRoot })
+      return { content: [{ type: 'text', text: compact(result) }] }
+    }
+
+    case 'annotask_get_component_examples': {
+      const parsed = parseWith(McpGetComponentExamplesArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { name, limit, library } = parsed.data
+      const result = await getComponentExamples(deps.projectRoot, name, limit ?? 3, library)
+      return { content: [{ type: 'text', text: compact(result) }] }
+    }
+
+    case 'annotask_get_data_context': {
+      const parsed = parseWith(McpGetDataContextArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { task_id: taskId, refresh } = parsed.data
+      const taskData = deps.getTasks()
+      const task = taskData.tasks.find(t => t.id === taskId)
+      if (!task) return toolError(`Task not found: ${taskId}`)
+      const stored = task.data_context
+      if (!refresh && stored && typeof stored === 'object') {
+        return { content: [{ type: 'text', text: compact(stored) }] }
+      }
+      const file = typeof task.file === 'string' ? task.file : ''
+      const line = typeof task.line === 'number' ? task.line : 0
+      if (!file) return toolError('Task has no file reference — cannot resolve data context')
+      const workspaceRoot = await getWorkspaceRoot(deps.projectRoot)
+      const result = await resolveDataContext(deps.projectRoot, file, line, {}, workspaceRoot)
+      return { content: [{ type: 'text', text: compact(result) }] }
+    }
+
+    case 'annotask_get_interaction_history': {
+      const parsed = parseWith(McpGetInteractionHistoryArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { task_id: taskId } = parsed.data
+      const taskData = deps.getTasks()
+      const task = taskData.tasks.find(t => t.id === taskId)
+      if (!task) return toolError(`Task not found: ${taskId}`)
+      if (task.interaction_history) {
+        return { content: [{ type: 'text', text: compact(task.interaction_history) }] }
+      }
+      const stored = await deps.readInteractionHistory(taskId)
+      if (stored == null) {
+        return { content: [{ type: 'text', text: compact({ task_id: taskId, not_captured: true }) }] }
+      }
+      return { content: [{ type: 'text', text: compact(stored) }] }
+    }
+
+    case 'annotask_get_rendered_html': {
+      const parsed = parseWith(McpGetRenderedHtmlArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { task_id: taskId } = parsed.data
+      const taskData = deps.getTasks()
+      const task = taskData.tasks.find(t => t.id === taskId)
+      if (!task) return toolError(`Task not found: ${taskId}`)
+      const ctx = task.context as Record<string, unknown> | undefined
+      const embedded = ctx && typeof ctx.rendered === 'string' ? ctx.rendered : null
+      if (embedded) {
+        return { content: [{ type: 'text', text: compact({ task_id: taskId, rendered: embedded, source: 'embedded' }) }] }
+      }
+      const stored = await deps.readRenderedHtml(taskId)
+      if (stored == null) {
+        return { content: [{ type: 'text', text: compact({ task_id: taskId, rendered: null, not_captured: true }) }] }
+      }
+      return { content: [{ type: 'text', text: compact({ task_id: taskId, rendered: stored, source: 'sidecar' }) }] }
+    }
+
+    case 'annotask_get_data_sources': {
+      const parsed = parseWith(McpGetDataSourcesArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const args = parsed.data
+      const catalog = await scanDataSources(deps.projectRoot)
+      const libraries = args.library ? catalog.libraries.filter(l => l.name === args.library) : catalog.libraries
+      let entries = catalog.project_entries
+      const mergeRuntime = args.merge_runtime !== false
+      if (mergeRuntime && deps.getRuntimeEndpointCatalog) {
+        const runtimeCat = deps.getRuntimeEndpointCatalog()
+        entries = mergeRuntimeOrphansIntoEntries(entries, runtimeCat.endpoints)
+      }
+      if (args.kind) entries = entries.filter(e => e.kind === args.kind)
+      if (args.search) {
+        const q = args.search.toLowerCase()
+        entries = entries.filter(e => e.name.toLowerCase().includes(q))
+      }
+      if (args.used_only) entries = entries.filter(e => e.used_count > 0)
+      return { content: [{ type: 'text', text: compact({ libraries, project_entries: entries, scannedAt: catalog.scannedAt }) }] }
+    }
+
+    case 'annotask_get_api_schemas': {
+      const parsed = parseWith(McpGetApiSchemasArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { kind, detail } = parsed.data
+      const catalog = await scanApiSchemas(deps.projectRoot)
+      let schemas = catalog.schemas
+      if (kind) schemas = schemas.filter(s => s.kind === kind)
+      const emitted = detail ? schemas : schemas.map(s => ({ ...s, operations: [] }))
+      return { content: [{ type: 'text', text: compact({ schemas: emitted, scannedAt: catalog.scannedAt }) }] }
+    }
+
+    case 'annotask_get_api_operation': {
+      const parsed = parseWith(McpGetApiOperationArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { path, method, schema_location } = parsed.data
+      const catalog = await scanApiSchemas(deps.projectRoot)
+      const normMethod = method ? method.toUpperCase() : undefined
+      const matches: Array<Record<string, unknown>> = []
+      for (const schema of catalog.schemas) {
+        if (schema_location && schema.location !== schema_location) continue
+        for (const op of schema.operations) {
+          if (op.path !== path) continue
+          if (normMethod && op.method.toUpperCase() !== normMethod) continue
+          matches.push({ schema_location: schema.location, schema_kind: schema.kind, operation: op })
+        }
+      }
+      if (matches.length === 0) return toolError(`Operation not found: ${path}${method ? ` (${method})` : ''}`)
+      if (matches.length === 1) return { content: [{ type: 'text', text: compact(matches[0]) }] }
+      return { content: [{ type: 'text', text: compact({ ambiguous: true, candidates: matches }) }] }
+    }
+
+    case 'annotask_resolve_endpoint': {
+      const parsed = parseWith(McpResolveEndpointArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { url, method } = parsed.data
+      const catalog = await scanApiSchemas(deps.projectRoot)
+      const match = resolveEndpoint(catalog, url, method)
+      return { content: [{ type: 'text', text: compact({ match }) }] }
+    }
+
+    case 'annotask_get_runtime_endpoints': {
+      const parsed = parseWith(McpGetRuntimeEndpointsArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const args = parsed.data
+      const enrich = args.enrich !== false
+      const catalog = deps.getRuntimeEndpointCatalog
+        ? deps.getRuntimeEndpointCatalog()
+        : { version: '1.0' as const, updatedAt: 0, endpoints: [] as RuntimeEndpoint[] }
+      let endpoints = catalog.endpoints
+      if (args.route) endpoints = endpoints.filter(ep => ep.routes.some(r => r.route === args.route))
+      if (args.method) {
+        const m = args.method.toUpperCase()
+        endpoints = endpoints.filter(ep => ep.method === m)
+      }
+      if (args.search) {
+        const q = args.search.toLowerCase()
+        endpoints = endpoints.filter(ep =>
+          ep.path.toLowerCase().includes(q)
+          || ep.pattern.toLowerCase().includes(q)
+          || ep.sampleUrls.some(u => u.toLowerCase().includes(q)),
+        )
+      }
+      if (enrich) {
+        const [staticCat, schemaCat] = await Promise.all([
+          scanDataSources(deps.projectRoot),
+          scanApiSchemas(deps.projectRoot),
+        ])
+        endpoints = endpoints.map(ep => enrichRuntimeEndpoint(ep, staticCat.project_entries, schemaCat))
+      }
+      if (args.orphans_only) {
+        endpoints = endpoints.filter(ep => !ep.matchedSources || ep.matchedSources.length === 0)
+      }
+      return { content: [{ type: 'text', text: compact({ version: catalog.version, updatedAt: catalog.updatedAt, endpoints }) }] }
+    }
+
+    case 'annotask_get_data_source_examples': {
+      const parsed = parseWith(McpGetDataSourceExamplesArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { name, kind, limit } = parsed.data
+      const result = await getDataSourceExamples(deps.projectRoot, name, limit ?? 3, kind as DataSource['kind'] | undefined)
+      return { content: [{ type: 'text', text: compact(result) }] }
+    }
+
+    case 'annotask_get_data_source_details': {
+      const parsed = parseWith(McpGetDataSourceDetailsArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { name, kind, file, context_lines } = parsed.data
+      const workspaceRoot = await getWorkspaceRoot(deps.projectRoot)
+      const result = await resolveDataSourceDetails({
+        projectRoot: deps.projectRoot,
+        name,
+        kind: kind as DataSource['kind'] | undefined,
+        file,
+        contextLines: context_lines,
+        workspaceRoot,
+      })
+      return { content: [{ type: 'text', text: compact(result) }] }
+    }
+
+    case 'annotask_conversation_read': {
+      const taskId = stringArg(rawArgs, 'task_id')
+      if (!taskId) return toolError('`task_id` is required')
+      const afterId = optionalStringArg(rawArgs, 'after_id')
+      if (!deps.taskThread) return toolError('Conversation store is not available')
+      const msgs = await deps.taskThread.read(taskId, { afterId: afterId })
+      return { content: [{ type: 'text', text: compact({ task_id: taskId, count: msgs.length, messages: msgs }) }] }
+    }
+
+    case 'annotask_conversation_post': {
+      const taskId = stringArg(rawArgs, 'task_id')
+      const role = stringArg(rawArgs, 'role')
+      const content = stringArg(rawArgs, 'content')
+      if (!taskId || !role || !content) return toolError('`task_id`, `role`, and `content` are required')
+      if (role !== 'user' && role !== 'assistant' && role !== 'system' && role !== 'tool') {
+        return toolError('`role` must be user|assistant|system|tool')
+      }
+      if (!deps.taskThread) return toolError('Conversation store is not available')
+      const msg = await deps.taskThread.append(taskId, {
+        role,
+        content,
+        providerId: optionalStringArg(rawArgs, 'provider_id'),
+        model: optionalStringArg(rawArgs, 'model'),
+      })
+      return { content: [{ type: 'text', text: compact(msg) }] }
+    }
+
+    case 'annotask_conversation_subscribe': {
+      const taskId = stringArg(rawArgs, 'task_id')
+      if (!taskId) return toolError('`task_id` is required')
+      if (!deps.taskThread) return toolError('Conversation store is not available')
+      const afterId = optionalStringArg(rawArgs, 'after_id')
+      const requestedTimeout = typeof rawArgs.timeout_ms === 'number' ? rawArgs.timeout_ms : 25_000
+      const timeoutMs = Math.max(0, Math.min(55_000, requestedTimeout))
+      const initial = await deps.taskThread.read(taskId, { afterId })
+      if (initial.length > 0) {
+        return { content: [{ type: 'text', text: compact({ task_id: taskId, count: initial.length, messages: initial }) }] }
+      }
+      const store = deps.taskThread
+      const received = await new Promise<ThreadMessage | null>((resolve) => {
+        const unsubscribe = store.subscribe(taskId, (m) => {
+          unsubscribe()
+          clearTimeout(t)
+          resolve(m)
+        })
+        const t = setTimeout(() => { unsubscribe(); resolve(null) }, timeoutMs)
+      })
+      const msgs = received ? [received] : []
+      return { content: [{ type: 'text', text: compact({ task_id: taskId, count: msgs.length, messages: msgs }) }] }
+    }
+
+    case 'annotask_get_playbook': {
+      const parsed = parseWith(McpGetPlaybookArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { task_type: taskType } = parsed.data
+      const companion = TASK_TYPE_COMPANIONS[taskType]
+      if (!companion) {
+        // No `content` key on purpose — compactJson would strip a null anyway.
+        return { content: [{ type: 'text', text: compact({
+          task_type: taskType,
+          message: `No companion playbook for "${taskType}" — the base annotask-apply instructions (served as MCP initialize.instructions) cover this type.`,
+        }) }] }
+      }
+      // Served from the bundled skill files so pure-MCP clients get the exact
+      // content an installed SKILL.md would tell a filesystem agent to read.
+      let content: string | undefined
+      try {
+        content = loadSkill('annotask-apply').files[companion]
+      } catch (err: any) {
+        return toolError(`Could not load skill files: ${err?.message ?? String(err)}`)
+      }
+      if (!content) return toolError(`Playbook file missing from the installed package: ${companion}`)
+      return { content: [{ type: 'text', text: compact({ task_type: taskType, file: companion, content }) }] }
+    }
+
+    case 'annotask_get_agent_directions': {
+      const parsed = parseWith(McpGetAgentDirectionsArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const personaId = parsed.data.persona_id
+      // Same store the HTTP /agent-configs route reads. It is deliberately
+      // uncached (the init pipeline writes agents.json directly), so building
+      // it per call always serves the current file contents.
+      const configs = await createAgentConfigStore(deps.projectRoot).get()
+      if (personaId) {
+        const entry = configs.agents[personaId]
+        if (!entry) {
+          // Unconfigured isn't an error — it just means the init agent (or
+          // user) hasn't written directions for this persona yet.
+          return { content: [{ type: 'text', text: compact({ persona_id: personaId, projectDirections: '', not_configured: true }) }] }
+        }
+        return { content: [{ type: 'text', text: compact({ persona_id: personaId, ...entry }) }] }
+      }
+      return { content: [{ type: 'text', text: compact(configs) }] }
+    }
+
+    case 'annotask_get_screenshot': {
+      const parsed = parseWith(McpGetScreenshotArgs, rawArgs)
+      if (!parsed.ok) return toolError(parsed.error)
+      const { task_id: taskId } = parsed.data
+      const taskData = deps.getTasks()
+      const task = taskData.tasks.find(t => t.id === taskId)
+      if (!task) return toolError(`Task not found: ${taskId}`)
+      if (!isSafeScreenshot(task.screenshot)) return toolError('Task has no screenshot')
+
+      const screenshotPath = nodePath.join(deps.projectRoot, '.annotask', 'screenshots', task.screenshot)
+      try {
+        const data = await fsp.readFile(screenshotPath)
+        return {
+          content: [
+            { type: 'image', data: data.toString('base64'), mimeType: 'image/png' },
+            { type: 'text', text: `Screenshot for task ${taskId}: ${task.description}` },
+          ],
+        }
+      } catch {
+        return { content: [{ type: 'text', text: `Screenshot file not found: ${task.screenshot}` }], isError: true }
+      }
+    }
+
+    default:
+      return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true }
+  }
+}
+
+/**
+ * Annotate a runtime endpoint with the matching static sources and OpenAPI
+ * operation. Mirrors the HTTP-side helper in `server/api.ts` — kept local so
+ * the MCP layer doesn't have to import back into api.ts.
+ */
+function enrichRuntimeEndpoint(
+  ep: RuntimeEndpoint,
+  staticEntries: Array<{ name: string; method?: string; endpoint?: string; resolved_endpoint?: string }>,
+  schemaCatalog: Awaited<ReturnType<typeof scanApiSchemas>>,
+): RuntimeEndpoint {
+  const out: RuntimeEndpoint = { ...ep }
+  const matched: string[] = []
+  for (const entry of findMatchingStaticEntries(ep, staticEntries)) {
+    if (!matched.includes(entry.name)) matched.push(entry.name)
+  }
+  if (matched.length > 0) out.matchedSources = matched
+  const sampleUrl = ep.sampleUrls[0] || ep.path
+  const match = resolveEndpoint(schemaCatalog, sampleUrl, ep.method)
+  if (match) {
+    out.matchedSchemaLocation = match.schema_location
+    if (match.operation.id) out.matchedOperationId = match.operation.id
+  }
+  return out
+}
diff --git a/src/plugin/__tests__/api.test.ts b/src/plugin/__tests__/api.test.ts
index c1f6dde..57a5149 100644
--- a/src/plugin/__tests__/api.test.ts
+++ b/src/plugin/__tests__/api.test.ts
@@ -1,6 +1,15 @@
-import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest'
 import http from 'http'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
 import { createAPIMiddleware } from '../../server/api'
+import { createWireframeStore } from '../../server/wireframe-store'
+import { createSessionStore } from '../../server/session-store'
+import { createSnapshotStore } from '../../server/file-snapshots'
+import type { WireframeDocument, WireframeInstance } from '../../shared/wireframe-types'
+import { emptyDesignSessionDocument, type DesignSessionDocument, type SessionEntry } from '../../shared/design-session-types'
 
 function createTestServer(options: Parameters<typeof createAPIMiddleware>[0]) {
   const middleware = createAPIMiddleware(options)
@@ -18,7 +27,7 @@ function createTestServer(options: Parameters<typeof createAPIMiddleware>[0]) {
 function request(server: http.Server, method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<{ status: number; data: any; raw: string }> {
   return new Promise((resolve, reject) => {
     const url = new URL(path, `http://localhost:${(server.address() as any).port}`)
-    const options: http.RequestOptions = { method, hostname: url.hostname, port: url.port, path: url.pathname, headers: { ...extraHeaders } }
+    const options: http.RequestOptions = { method, hostname: url.hostname, port: url.port, path: url.pathname + url.search, headers: { ...extraHeaders } }
     if (body !== undefined) {
       options.headers = { ...options.headers, 'Content-Type': 'application/json' }
     }
@@ -42,6 +51,12 @@ describe('API endpoints', () => {
   const tasks: any[] = []
 
   let perfSnapshot: unknown = null
+  // Real wireframe store on a temp dir — the rev CAS and the accept/delete
+  // lifecycle hooks are exactly what these tests exercise, so stubbing the
+  // store would test nothing.
+  let wireframeRoot: string
+  let wireframeStore: ReturnType<typeof createWireframeStore>
+  let sessionStore: ReturnType<typeof createSessionStore>
   const options = {
     projectRoot: '/tmp/annotask-test',
     getReport: () => ({ version: '1.0', changes: [] }),
@@ -53,9 +68,15 @@ describe('API endpoints', () => {
       tasks.push(newTask)
       return newTask
     },
-    updateTask: (id: string, updates: Record<string, unknown>) => {
+    updateTask: (id: string, updates: Record<string, unknown>, opts?: { guard?: (task: Record<string, unknown>) => string | null }) => {
       const task = tasks.find(t => t.id === id)
       if (!task) return { error: 'Task not found' }
+      // Mirror the real store: the transition guard runs against the task as
+      // it exists at update time (state.ts runs it inside the task lock).
+      if (opts?.guard) {
+        const reason = opts.guard(task)
+        if (reason) return { error: 'Invalid transition', reason }
+      }
       Object.assign(task, updates)
       return task
     },
@@ -74,15 +95,89 @@ describe('API endpoints', () => {
     ingestNetworkCalls: (_calls: unknown[]) => { /* no-op for tests */ },
     getRuntimeEndpointCatalog: () => ({ version: '1.0' as const, updatedAt: 0, endpoints: [] }),
     clearRuntimeEndpoints: () => { /* no-op for tests */ },
+    // Embedded-chat stubs — these tests don't exercise the chat endpoints,
+    // but APIOptions requires them. Each stub returns a sensible empty value.
+    taskThread: {
+      read: async (_id: string) => [],
+      append: async (_id: string, input: { role: 'user' | 'assistant' | 'system' | 'tool'; content: string }) => ({
+        id: 'msg-test', ts: 0, role: input.role, content: input.content,
+      }),
+      update: async (_id: string, msgId: string, patch: { content?: string }) => ({
+        id: msgId, ts: 0, role: 'assistant' as const, content: patch.content ?? '',
+      }),
+      subscribe: () => () => { /* no-op */ },
+      clear: async () => { /* no-op */ },
+    },
+    agentSpawn: {
+      registry: { abort: () => false, size: () => 0, taskRunning: () => false, killAll: () => { /* no-op */ } },
+      handleSpawn: async (_req: unknown, res: { statusCode: number; end: (s?: string) => void }) => {
+        res.statusCode = 501; res.end('not supported in this test')
+      },
+    },
+    agentDetect: {
+      detect: async () => ({
+        'claude-local': { found: false },
+        'codex-local': { found: false },
+        'opencode-local': { found: false },
+        'copilot-local': { found: false },
+        copilot: { found: false },
+        openrouter: { hasEnv: false },
+        ts: 0,
+      }),
+      invalidate: () => { /* no-op */ },
+    },
+    initRunner: {
+      start: () => ({ running: false, steps: [] }),
+      cancel: () => { /* no-op */ },
+      commit: async () => ({ running: false, steps: [], result: 'success' as const }),
+      skip: async () => ({ running: false, steps: [], result: 'success' as const }),
+      reset: () => ({ running: false, steps: [] }),
+      getState: () => ({ running: false, steps: [] }),
+    },
+    getAgentConfigs: async () => ({ version: 1 as const, agents: {} }),
+    setAgentConfig: async () => ({ version: 1 as const, agents: {} }),
+    getWireframe: async () => wireframeStore.get(),
+    setWireframe: async (doc: WireframeDocument) => wireframeStore.set(doc),
+    getDesignSession: async () => sessionStore.get(),
+    setDesignSession: async (doc: DesignSessionDocument) => sessionStore.set(doc),
+    clearDesignSession: async () => {
+      const fresh = emptyDesignSessionDocument(`ds-${Date.now()}`)
+      fresh.startedAt = Date.now()
+      fresh.updatedAt = Date.now()
+      return sessionStore.replace(fresh)
+    },
+    snapshots: undefined as never, // assigned a real store on the temp dir in beforeAll
+    usageLedger: {
+      append: async (e: { scope: 'task' | 'init' | 'apply' | 'chat' }) => ({ ts: 0, scope: e.scope, inputTokens: 0, outputTokens: 0 }),
+      readAll: async () => [],
+      summary: async () => ({
+        totals: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+        byScope: {
+          task: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+          init: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+          apply: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+          chat: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+        },
+        byProvider: {},
+        firstAt: null,
+        lastAt: null,
+      }),
+      recent: async () => [],
+    },
   }
 
   beforeAll(async () => {
+    wireframeRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-api-wf-'))
+    wireframeStore = createWireframeStore(wireframeRoot)
+    sessionStore = createSessionStore(wireframeRoot)
+    ;(options as { snapshots: unknown }).snapshots = createSnapshotStore(wireframeRoot)
     server = createTestServer(options)
     await new Promise<void>((resolve) => server.listen(0, resolve))
   })
 
   afterAll(async () => {
     await new Promise<void>((resolve) => server.close(() => resolve()))
+    await fsp.rm(wireframeRoot, { recursive: true, force: true })
   })
 
   it('GET /api/report returns report', async () => {
@@ -110,6 +205,14 @@ describe('API endpoints', () => {
     expect(data.tasks).toEqual(tasks)
   })
 
+  it('GET /api/project-components returns the Project library envelope', async () => {
+    const { status, data } = await request(server, 'GET', '/__annotask/api/project-components')
+    expect(status).toBe(200)
+    expect(data.library.name).toBe('Project')
+    expect(Array.isArray(data.library.components)).toBe(true)
+    expect(typeof data.scannedAt).toBe('number')
+  })
+
   it('GET /api/status returns ok', async () => {
     const { status, data } = await request(server, 'GET', '/__annotask/api/status')
     expect(status).toBe(200)
@@ -190,7 +293,7 @@ describe('API endpoints', () => {
     it('accepts every canonical task type', async () => {
       const canonical = [
         'annotation', 'section_request', 'style_update', 'theme_update',
-        'a11y_fix', 'error_fix', 'perf_fix', 'api_update',
+        'a11y_fix', 'error_fix', 'perf_fix', 'wireframe_apply',
       ]
       for (const type of canonical) {
         const { status, data } = await request(server, 'POST', '/__annotask/api/tasks', {
@@ -436,6 +539,78 @@ describe('API endpoints', () => {
       })
       expect(status).toBe(200)
     })
+
+    it('concurrent pending → in_progress PATCHes: exactly one wins (guard runs at update time)', async () => {
+      const created = await request(server, 'POST', '/__annotask/api/tasks', {
+        type: 'annotation',
+        description: 'Race test task',
+      })
+      expect(created.status).toBe(200)
+      const id = created.data.id
+      const [a, b] = await Promise.all([
+        request(server, 'PATCH', `/__annotask/api/tasks/${id}`, { status: 'in_progress' }),
+        request(server, 'PATCH', `/__annotask/api/tasks/${id}`, { status: 'in_progress' }),
+      ])
+      const ok = [a, b].filter(r => r.status === 200)
+      const rejected = [a, b].filter(r => r.status === 400)
+      expect(ok).toHaveLength(1)
+      expect(rejected).toHaveLength(1)
+      expect(rejected[0].data.error.code).toBe('invalid_transition')
+      expect(rejected[0].data.error.message).toContain('Invalid state transition')
+    })
+  })
+
+  describe('host validation (DNS-rebinding gate)', () => {
+    afterEach(() => {
+      delete process.env.ANNOTASK_ALLOWED_HOSTS
+    })
+
+    it('blocks GET /api/tasks with a non-local Host header', async () => {
+      const { status, data } = await request(server, 'GET', '/__annotask/api/tasks', undefined, { Host: 'evil.example' })
+      expect(status).toBe(403)
+      expect(data.error.code).toBe('forbidden_host')
+    })
+
+    it('blocks the screenshot route with a non-local Host header', async () => {
+      const { status, data } = await request(server, 'GET', '/__annotask/screenshots/screenshot-1-a.png', undefined, { Host: 'evil.example:5173' })
+      expect(status).toBe(403)
+      expect(data.error.code).toBe('forbidden_host')
+    })
+
+    it('blocks mutations with a non-local Host header even when Origin is local', async () => {
+      const { status, data } = await request(server, 'POST', '/__annotask/api/tasks', {
+        type: 'annotation', description: 'rebound',
+      }, { Host: 'evil.example', Origin: 'http://localhost:5173' })
+      expect(status).toBe(403)
+      expect(data.error.code).toBe('forbidden_host')
+    })
+
+    it('allows explicit localhost and IP-literal Host headers', async () => {
+      const local = await request(server, 'GET', '/__annotask/api/tasks', undefined, { Host: 'localhost:9999' })
+      expect(local.status).toBe(200)
+      const lan = await request(server, 'GET', '/__annotask/api/tasks', undefined, { Host: '192.168.1.20:5173' })
+      expect(lan.status).toBe(200)
+    })
+
+    it('allows a host listed in ANNOTASK_ALLOWED_HOSTS', async () => {
+      process.env.ANNOTASK_ALLOWED_HOSTS = 'evil.example'
+      const { status } = await request(server, 'GET', '/__annotask/api/tasks', undefined, { Host: 'evil.example' })
+      expect(status).toBe(200)
+    })
+
+    it('allows hosts threaded via the allowedHosts option (announced bind host)', async () => {
+      const gated = createTestServer({ ...options, allowedHosts: () => ['dev.example.com'] })
+      await new Promise<void>((resolve) => gated.listen(0, resolve))
+      try {
+        const ok = await request(gated, 'GET', '/__annotask/api/tasks', undefined, { Host: 'dev.example.com:5173' })
+        expect(ok.status).toBe(200)
+        const blocked = await request(gated, 'GET', '/__annotask/api/tasks', undefined, { Host: 'other.example.com' })
+        expect(blocked.status).toBe(403)
+        expect(blocked.data.error.code).toBe('forbidden_host')
+      } finally {
+        await new Promise<void>((resolve) => gated.close(() => resolve()))
+      }
+    })
   })
 
   describe('origin validation', () => {
@@ -465,4 +640,338 @@ describe('API endpoints', () => {
       expect(status).toBe(200)
     })
   })
+
+  describe('wireframe GET/PUT', () => {
+    it('GET returns an empty document on a fresh project', async () => {
+      const { status, data } = await request(server, 'GET', '/__annotask/api/wireframe')
+      expect(status).toBe(200)
+      expect(data.version).toBe('1.0')
+      expect(Array.isArray(data.routes)).toBe(true)
+    })
+
+    it('PUT persists a document and GET returns it (with route filtering)', async () => {
+      const doc: WireframeDocument = {
+        version: '1.0',
+        updatedAt: 1,
+        routes: [
+          { route: '/planets', instances: [
+            { id: 'wfi-1', kind: 'component', anchor: { file: 'PlanetsPage.vue', line: 12, position: 'append' }, inserted: { tag: 'planetcard', componentName: 'PlanetCard' }, fidelity: 'live', mounted: true, createdAt: 1 },
+          ] },
+          { route: '/', instances: [] },
+        ],
+      }
+      const put = await request(server, 'PUT', '/__annotask/api/wireframe', doc as unknown as Record<string, unknown>)
+      expect(put.status).toBe(200)
+      expect(put.data.routes).toHaveLength(2)
+      // First write against a rev-less doc stamps the rev.
+      expect(put.data.rev).toBe(1)
+
+      const all = await request(server, 'GET', '/__annotask/api/wireframe')
+      expect(all.data.routes).toHaveLength(2)
+      expect(all.data.rev).toBe(1)
+
+      const filtered = await request(server, 'GET', '/__annotask/api/wireframe?route=/planets')
+      expect(filtered.data.routes).toHaveLength(1)
+      expect(filtered.data.routes[0].instances[0].id).toBe('wfi-1')
+    })
+
+    it('PUT rejects a non-wireframe body', async () => {
+      const { status, data } = await request(server, 'PUT', '/__annotask/api/wireframe', { nope: true })
+      expect(status).toBe(400)
+      expect(data.error.code).toBe('validation_failed')
+    })
+
+    it('PUT rejects a document with one malformed instance', async () => {
+      const current = await request(server, 'GET', '/__annotask/api/wireframe')
+      const { status, data } = await request(server, 'PUT', '/__annotask/api/wireframe', {
+        version: '1.0', updatedAt: 2, rev: current.data.rev,
+        routes: [{ route: '/planets', instances: [{ id: 'wfi-bad' /* no kind/anchor/inserted */ }] }],
+      })
+      expect(status).toBe(400)
+      expect(data.error.code).toBe('validation_failed')
+    })
+
+    it('PUT with the current rev succeeds and increments; stale/missing rev → 409 conflict', async () => {
+      const current = await request(server, 'GET', '/__annotask/api/wireframe')
+      const rev = current.data.rev as number
+
+      const ok = await request(server, 'PUT', '/__annotask/api/wireframe', {
+        ...current.data, updatedAt: Date.now(), rev,
+      })
+      expect(ok.status).toBe(200)
+      expect(ok.data.rev).toBe(rev + 1)
+
+      // Replaying the same (now stale) rev — the other-tab scenario.
+      const stale = await request(server, 'PUT', '/__annotask/api/wireframe', {
+        ...current.data, updatedAt: Date.now(), rev,
+      })
+      expect(stale.status).toBe(409)
+      expect(stale.data.error.code).toBe('conflict')
+
+      // Missing rev once the doc carries one is just as stale.
+      const { rev: _omitted, ...revless } = current.data
+      const missing = await request(server, 'PUT', '/__annotask/api/wireframe', {
+        ...revless, updatedAt: Date.now(),
+      })
+      expect(missing.status).toBe(409)
+      expect(missing.data.error.code).toBe('conflict')
+
+      // The losing writes must not have advanced the doc.
+      const after = await request(server, 'GET', '/__annotask/api/wireframe')
+      expect(after.data.rev).toBe(rev + 1)
+    })
+  })
+
+  describe('design-session GET/PUT/DELETE', () => {
+    function sessionEntry(id: string, extra: Partial<SessionEntry> = {}): SessionEntry {
+      return {
+        id,
+        ordinal: 1,
+        ts: 1,
+        route: '/planets',
+        change: {
+          id: `c-${id}`, type: 'style_update', description: 'x', file: 'PlanetsPage.vue',
+          section: 'style', line: 9, element: 'h1', property: 'color', before: 'red', after: 'blue',
+        } as SessionEntry['change'],
+        anchor: { file: 'PlanetsPage.vue', line: 9 },
+        live: { status: 'pending' },
+        ...extra,
+      }
+    }
+
+    it('GET returns an empty document on a fresh project', async () => {
+      const { status, data } = await request(server, 'GET', '/__annotask/api/design-session')
+      expect(status).toBe(200)
+      expect(data.version).toBe('1.0')
+      expect(data.entries).toEqual([])
+      expect(typeof data.sessionId).toBe('string')
+    })
+
+    it('PUT persists the journal (stamping the first rev) and CAS-rejects a stale rev', async () => {
+      const doc: DesignSessionDocument = {
+        version: '1.0', sessionId: 'ds-test-1', startedAt: 1, updatedAt: 1,
+        entries: [sessionEntry('se-1')],
+      }
+      const put = await request(server, 'PUT', '/__annotask/api/design-session', doc as unknown as Record<string, unknown>)
+      expect(put.status).toBe(200)
+      expect(put.data.rev).toBe(1)
+      expect(put.data.entries).toHaveLength(1)
+
+      const got = await request(server, 'GET', '/__annotask/api/design-session')
+      expect(got.data.entries[0].id).toBe('se-1')
+
+      // Round-tripping the current rev wins; replaying it is the other-tab loss.
+      const ok = await request(server, 'PUT', '/__annotask/api/design-session', {
+        ...got.data, updatedAt: Date.now(), entries: [sessionEntry('se-1'), sessionEntry('se-2', { ordinal: 2 })],
+      })
+      expect(ok.status).toBe(200)
+      expect(ok.data.rev).toBe(2)
+
+      const stale = await request(server, 'PUT', '/__annotask/api/design-session', {
+        ...got.data, updatedAt: Date.now(),
+      })
+      expect(stale.status).toBe(409)
+      expect(stale.data.error.code).toBe('conflict')
+    })
+
+    it('PUT rejects a non-session body and a document with one malformed entry', async () => {
+      const bad = await request(server, 'PUT', '/__annotask/api/design-session', { nope: true })
+      expect(bad.status).toBe(400)
+      expect(bad.data.error.code).toBe('validation_failed')
+
+      const current = await request(server, 'GET', '/__annotask/api/design-session')
+      const oneBad = await request(server, 'PUT', '/__annotask/api/design-session', {
+        ...current.data, entries: [sessionEntry('se-good'), { id: 'se-bad' }],
+      })
+      expect(oneBad.status).toBe(400)
+      expect(oneBad.data.error.code).toBe('validation_failed')
+    })
+
+    it('DELETE discards the session: clears the journal and removes session-created placements', async () => {
+      // Seed the wireframe doc with one session-owned instance and one foreign one.
+      const wf = await request(server, 'GET', '/__annotask/api/wireframe')
+      const seeded = await request(server, 'PUT', '/__annotask/api/wireframe', {
+        version: '1.0', updatedAt: Date.now(), rev: wf.data.rev,
+        routes: [{
+          route: '/planets',
+          instances: [
+            { id: 'wfi-session', kind: 'component', anchor: { file: 'PlanetsPage.vue', line: 12, position: 'append' }, inserted: { tag: 'planetcard', componentName: 'PlanetCard' }, fidelity: 'live', mounted: true, createdAt: 1 },
+            { id: 'wfi-keep', kind: 'component', anchor: { file: 'PlanetsPage.vue', line: 20, position: 'append' }, inserted: { tag: 'tag' }, fidelity: 'live', mounted: true, createdAt: 1 },
+          ],
+        }],
+      })
+      expect(seeded.status).toBe(200)
+
+      // Seed the session journal with a placement cross-ref + an element edit.
+      const current = await request(server, 'GET', '/__annotask/api/design-session')
+      const put = await request(server, 'PUT', '/__annotask/api/design-session', {
+        ...current.data, updatedAt: Date.now(),
+        entries: [
+          sessionEntry('se-place', { instanceId: 'wfi-session', change: { id: 'c-place', type: 'component_insert', description: 'place', file: 'PlanetsPage.vue', section: 'template', line: 12, insert_position: 'append', inserted: { tag: 'planetcard' } } as never }),
+          sessionEntry('se-style', { ordinal: 2 }),
+        ],
+      })
+      expect(put.status).toBe(200)
+
+      const del = await request(server, 'DELETE', '/__annotask/api/design-session')
+      expect(del.status).toBe(200)
+      expect(del.data.removedInstances).toBe(1)
+      expect(del.data.revertedFiles).toEqual([])
+
+      const after = await request(server, 'GET', '/__annotask/api/design-session')
+      expect(after.data.entries).toEqual([])
+      expect(after.data.sessionId).not.toBe(put.data.sessionId)
+
+      const wfAfter = await request(server, 'GET', '/__annotask/api/wireframe')
+      const ids = wfAfter.data.routes.flatMap((r: { instances: Array<{ id: string }> }) => r.instances.map((i) => i.id))
+      expect(ids).toContain('wfi-keep')
+      expect(ids).not.toContain('wfi-session')
+    })
+  })
+
+  describe('wireframe lifecycle closure (task accept / delete hooks)', () => {
+    function instance(id: string, extra: Partial<WireframeInstance> = {}): WireframeInstance {
+      return {
+        id,
+        kind: 'component',
+        anchor: { file: 'PlanetsPage.vue', line: 9, position: 'append' },
+        inserted: { tag: 'planetcard', componentName: 'PlanetCard' },
+        fidelity: 'live',
+        mounted: true,
+        createdAt: 1,
+        ...extra,
+      }
+    }
+
+    /** PUT the routes payload with the current rev (CAS round-trip). */
+    async function putRoutes(routes: WireframeDocument['routes']): Promise<void> {
+      const current = await request(server, 'GET', '/__annotask/api/wireframe')
+      const put = await request(server, 'PUT', '/__annotask/api/wireframe', {
+        version: '1.0', updatedAt: Date.now(), rev: current.data.rev, routes,
+      })
+      expect(put.status).toBe(200)
+    }
+
+    it('accepting a wireframe_apply task removes its instances (and only its instances)', async () => {
+      const created = await request(server, 'POST', '/__annotask/api/tasks', {
+        type: 'wireframe_apply', description: 'Build /planets',
+      })
+      expect(created.status).toBe(200)
+      const taskId = created.data.id as string
+
+      await putRoutes([
+        { route: '/planets', instances: [
+          instance('wfi-owned-1', { status: 'building', taskId }),
+          instance('wfi-owned-2', { status: 'building', taskId }),
+          instance('wfi-other', { status: 'placed' }),
+        ] },
+      ])
+
+      // Walk the full lifecycle the agent would: lock → review → accept.
+      await request(server, 'PATCH', `/__annotask/api/tasks/${taskId}`, { status: 'in_progress' })
+      await request(server, 'PATCH', `/__annotask/api/tasks/${taskId}`, { status: 'review' })
+      const accepted = await request(server, 'PATCH', `/__annotask/api/tasks/${taskId}`, { status: 'accepted' })
+      expect(accepted.status).toBe(200)
+
+      const after = await request(server, 'GET', '/__annotask/api/wireframe')
+      const planets = after.data.routes.find((r: { route: string }) => r.route === '/planets')
+      expect(planets.instances.map((i: { id: string }) => i.id)).toEqual(['wfi-other'])
+    })
+
+    it('deleting a wireframe_apply task reverts its instances to placed and clears taskId', async () => {
+      const created = await request(server, 'POST', '/__annotask/api/tasks', {
+        type: 'wireframe_apply', description: 'Build /moons',
+      })
+      expect(created.status).toBe(200)
+      const taskId = created.data.id as string
+
+      await putRoutes([
+        { route: '/moons', instances: [
+          instance('wfi-reverted', { status: 'building', taskId }),
+        ] },
+      ])
+
+      const deleted = await request(server, 'DELETE', `/__annotask/api/tasks/${taskId}`)
+      expect(deleted.status).toBe(200)
+
+      const after = await request(server, 'GET', '/__annotask/api/wireframe')
+      const moons = after.data.routes.find((r: { route: string }) => r.route === '/moons')
+      expect(moons.instances).toHaveLength(1)
+      expect(moons.instances[0].status).toBe('placed')
+      expect(moons.instances[0].taskId).toBeUndefined()
+    })
+
+    it('accepting a non-wireframe task leaves the wireframe document untouched', async () => {
+      const before = await request(server, 'GET', '/__annotask/api/wireframe')
+      const created = await request(server, 'POST', '/__annotask/api/tasks', {
+        type: 'annotation', description: 'unrelated',
+      })
+      const taskId = created.data.id as string
+      await request(server, 'PATCH', `/__annotask/api/tasks/${taskId}`, { status: 'in_progress' })
+      await request(server, 'PATCH', `/__annotask/api/tasks/${taskId}`, { status: 'review' })
+      await request(server, 'PATCH', `/__annotask/api/tasks/${taskId}`, { status: 'accepted' })
+      const after = await request(server, 'GET', '/__annotask/api/wireframe')
+      expect(after.data.rev).toBe(before.data.rev)
+    })
+  })
+
+  describe('wireframe-snapshots upload/serve/delete', () => {
+    // 1x1 transparent PNG
+    const PNG_B64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=='
+    const dataUrl = `data:image/png;base64,${PNG_B64}`
+
+    afterAll(async () => {
+      await fsp.rm(path.join(options.projectRoot, '.annotask', 'wireframe-snapshots'), { recursive: true, force: true })
+    })
+
+    it('uploads under the shell-minted id, serves it back as PNG, deletes it', async () => {
+      const up = await request(server, 'POST', '/__annotask/api/wireframe-snapshots', { id: 'wfb-test-1', data: dataUrl })
+      expect(up.status).toBe(200)
+      expect(up.data.filename).toBe('wfb-test-1.png')
+
+      const served = await request(server, 'GET', '/__annotask/wireframe-snapshots/wfb-test-1.png')
+      expect(served.status).toBe(200)
+      expect(served.raw.length).toBeGreaterThan(0)
+
+      const del = await request(server, 'DELETE', '/__annotask/api/wireframe-snapshots/wfb-test-1.png')
+      expect(del.status).toBe(200)
+      expect(del.data.deleted).toBe('wfb-test-1.png')
+
+      const gone = await request(server, 'GET', '/__annotask/wireframe-snapshots/wfb-test-1.png')
+      expect(gone.status).toBe(404)
+    })
+
+    it('re-upload under the same id overwrites (recapture semantics)', async () => {
+      await request(server, 'POST', '/__annotask/api/wireframe-snapshots', { id: 'wfb-test-2', data: dataUrl })
+      const again = await request(server, 'POST', '/__annotask/api/wireframe-snapshots', { id: 'wfb-test-2', data: dataUrl })
+      expect(again.status).toBe(200)
+      expect(again.data.filename).toBe('wfb-test-2.png')
+    })
+
+    it('rejects ids that are not shell-mintable (traversal/case/format)', async () => {
+      for (const id of ['../escape', 'a/b', 'UPPER', 'wfb_underscore', '', '-leading']) {
+        const res = await request(server, 'POST', '/__annotask/api/wireframe-snapshots', { id, data: dataUrl })
+        expect(res.status, `id ${JSON.stringify(id)} must be rejected`).toBe(400)
+      }
+    })
+
+    it('rejects non-PNG payloads and oversized bodies', async () => {
+      const badType = await request(server, 'POST', '/__annotask/api/wireframe-snapshots', { id: 'wfb-test-3', data: 'data:image/svg+xml;base64,PHN2Zz48L3N2Zz4=' })
+      expect(badType.status).toBe(400)
+      // The global 4MB body cap fires while the client is still streaming —
+      // readBody destroys the socket (ECONNRESET) or answers 413 by timing.
+      const big = `data:image/png;base64,${Buffer.alloc(4 * 1024 * 1024 + 16).toString('base64')}`
+      const result = await request(server, 'POST', '/__annotask/api/wireframe-snapshots', { id: 'wfb-test-4', data: big })
+        .then((r) => r.status as number | string)
+        .catch(() => 'connection-destroyed')
+      expect([413, 'connection-destroyed']).toContain(result)
+      expect(fs.existsSync(path.join(options.projectRoot, '.annotask', 'wireframe-snapshots', 'wfb-test-4.png'))).toBe(false)
+    })
+
+    it('serve and delete refuse filenames outside the minted-id shape', async () => {
+      expect((await request(server, 'GET', '/__annotask/wireframe-snapshots/..%2Fescape.png')).status).toBe(400)
+      expect((await request(server, 'GET', '/__annotask/wireframe-snapshots/NOPE.PNG')).status).toBe(400)
+      expect((await request(server, 'DELETE', '/__annotask/api/wireframe-snapshots/..%2Fescape.png')).status).toBe(400)
+    })
+  })
 })
diff --git a/src/plugin/__tests__/bridge-origin.test.ts b/src/plugin/__tests__/bridge-origin.test.ts
new file mode 100644
index 0000000..d699555
--- /dev/null
+++ b/src/plugin/__tests__/bridge-origin.test.ts
@@ -0,0 +1,193 @@
+import { describe, it, expect, afterEach } from 'vitest'
+import { JSDOM } from 'jsdom'
+import { bridgeClientScript } from '../bridge-client'
+
+/**
+ * Origin hardening for the in-iframe bridge (src/plugin/bridge/).
+ *
+ * The bridge runs inside the user's app page and talks to the shell via
+ * postMessage. These tests pin the security contract:
+ * - incoming commands are only accepted from LOCAL origins (localhost /
+ *   127.0.0.1 / [::1]), mirroring the server's isLocalHostname — port-agnostic
+ *   because the webpack standalone shell runs on a different port than the app
+ * - the first validated sender locks shellOrigin; later messages from any
+ *   other origin (even local ones) are ignored
+ * - no app data is ever posted to '*': only the data-free bridge:ready
+ *   handshake may broadcast; everything else queues (bounded) until lock.
+ *
+ * The bridge is a vanilla-JS IIFE string evaluated in the app page, so the
+ * tests eval it inside a fresh JSDOM window per test (node environment —
+ * the shared vitest jsdom global would leak listeners between tests because
+ * the bridge guards itself with window.__ANNOTASK_BRIDGE__).
+ */
+
+interface Post {
+  data: { type: string | null; payload: Record<string, unknown>; source: string; id?: string }
+  origin: string
+}
+
+interface BridgeHarness {
+  dom: JSDOM
+  win: any
+  posts: Post[]
+}
+
+const openWindows: JSDOM[] = []
+
+function createBridgeWindow(): BridgeHarness {
+  const dom = new JSDOM('<!doctype html><html><body><div id="app"></div></body></html>', {
+    url: 'http://localhost:5173/',
+    runScripts: 'outside-only',
+    pretendToBeVisual: true,
+  })
+  openWindows.push(dom)
+  const win = dom.window as any
+  const posts: Post[] = []
+  // Outside an iframe window.parent === window, so the bridge's
+  // window.parent.postMessage(...) resolves to this interceptor — it records
+  // exactly what the bridge sends "to the shell" and with which targetOrigin.
+  win.postMessage = (data: Post['data'], origin: string) => {
+    posts.push({ data, origin })
+  }
+  win.eval(bridgeClientScript())
+  return { dom, win, posts }
+}
+
+/** Dispatch a message event as if a (possibly hostile) parent posted it. */
+function shellMessage(win: any, origin: string, type: string, extra: Record<string, unknown> = {}) {
+  win.dispatchEvent(
+    new win.MessageEvent('message', {
+      data: { source: 'annotask-shell', type, payload: {}, ...extra },
+      origin,
+    })
+  )
+}
+
+afterEach(() => {
+  // Close windows so the bridge's setInterval route poller doesn't keep the
+  // worker alive across tests.
+  while (openWindows.length > 0) openWindows.pop()!.window.close()
+})
+
+describe('bridge postMessage origin validation', () => {
+  it('posts bridge:ready to * on boot, and nothing else to *', () => {
+    const { posts } = createBridgeWindow()
+    const wildcard = posts.filter((p) => p.origin === '*')
+    expect(wildcard.length).toBe(1)
+    expect(wildcard[0].data.type).toBe('bridge:ready')
+  })
+
+  it('ignores commands from a non-local origin (no response, no execution, no lock)', () => {
+    const { win, posts } = createBridgeWindow()
+
+    shellMessage(win, 'https://evil.example', 'bridge:ping', { id: 'evil-ping' })
+    // State-changing command must not execute either.
+    shellMessage(win, 'https://evil.example', 'theme:inject-css', {
+      id: 'evil-css',
+      payload: { styleId: 'evil-style', css: 'body { display: none }' },
+    })
+    // Opaque origins (sandboxed iframes, file://) arrive as the string 'null'.
+    shellMessage(win, 'null', 'bridge:ping', { id: 'opaque-ping' })
+
+    expect(posts.some((p) => p.data.id === 'evil-ping')).toBe(false)
+    expect(posts.some((p) => p.data.id === 'evil-css')).toBe(false)
+    expect(posts.some((p) => p.data.id === 'opaque-ping')).toBe(false)
+    expect(win.document.getElementById('evil-style')).toBeNull()
+
+    // The rejected sender must not have locked the session: pushes still
+    // queue rather than posting (shellOrigin would be the evil origin otherwise).
+    win.console.error('post-evil boom')
+    expect(posts.some((p) => p.data.type === 'error:console')).toBe(false)
+  })
+
+  it('processes a local-origin message and locks shellOrigin to it', () => {
+    const { win, posts } = createBridgeWindow()
+
+    shellMessage(win, 'http://localhost:5173', 'bridge:ping', { id: 'p1' })
+
+    const reply = posts.find((p) => p.data.id === 'p1')
+    expect(reply).toBeDefined()
+    expect(reply!.origin).toBe('http://localhost:5173')
+    expect(reply!.data.payload).toEqual({ ok: true })
+
+    // Locked: pushes now go straight to the validated origin, never '*'.
+    win.console.error('post-lock boom')
+    const err = posts.find((p) => p.data.type === 'error:console')
+    expect(err).toBeDefined()
+    expect(err!.origin).toBe('http://localhost:5173')
+  })
+
+  it('accepts a different localhost port (webpack standalone topology)', () => {
+    const { win, posts } = createBridgeWindow()
+    shellMessage(win, 'http://127.0.0.1:24678', 'bridge:ping', { id: 'wp1' })
+    const reply = posts.find((p) => p.data.id === 'wp1')
+    expect(reply).toBeDefined()
+    expect(reply!.origin).toBe('http://127.0.0.1:24678')
+  })
+
+  it('rejects messages from a different origin after lock, even local ones', () => {
+    const { win, posts } = createBridgeWindow()
+    shellMessage(win, 'http://localhost:5173', 'bridge:ping', { id: 'p1' })
+    expect(posts.some((p) => p.data.id === 'p1')).toBe(true)
+
+    // A second local-but-different context must not hijack the session.
+    shellMessage(win, 'http://127.0.0.1:9999', 'bridge:ping', { id: 'hijack' })
+    shellMessage(win, 'http://127.0.0.1:9999', 'theme:inject-css', {
+      id: 'hijack-css',
+      payload: { styleId: 'hijack-style', css: 'body { display: none }' },
+    })
+
+    expect(posts.some((p) => p.data.id === 'hijack')).toBe(false)
+    expect(posts.some((p) => p.data.id === 'hijack-css')).toBe(false)
+    expect(win.document.getElementById('hijack-style')).toBeNull()
+
+    // Same origin keeps working.
+    shellMessage(win, 'http://localhost:5173', 'bridge:ping', { id: 'p2' })
+    const reply2 = posts.find((p) => p.data.id === 'p2')
+    expect(reply2).toBeDefined()
+    expect(reply2!.origin).toBe('http://localhost:5173')
+  })
+
+  it('queues pre-lock pushes instead of posting to *, then flushes to the locked origin', () => {
+    const { win, posts } = createBridgeWindow()
+
+    // The bridge patches console.error → sendToShell('error:console', ...).
+    win.console.error('pre-lock boom')
+
+    // Not posted anywhere yet — and in particular never to '*'.
+    expect(posts.some((p) => p.data.type === 'error:console')).toBe(false)
+    expect(posts.filter((p) => p.origin === '*').every((p) => p.data.type === 'bridge:ready')).toBe(true)
+
+    shellMessage(win, 'http://localhost:5173', 'bridge:ping', { id: 'p1' })
+
+    const err = posts.find((p) => p.data.type === 'error:console')
+    expect(err).toBeDefined()
+    expect(err!.origin).toBe('http://localhost:5173')
+    expect(err!.data.payload.message).toContain('pre-lock boom')
+  })
+
+  it('bounds the pre-lock queue at 50 entries', () => {
+    const { win, posts } = createBridgeWindow()
+    for (let i = 0; i < 60; i++) win.console.error('flood ' + i)
+    shellMessage(win, 'http://localhost:5173', 'bridge:ping', { id: 'p1' })
+
+    const errs = posts.filter((p) => p.data.type === 'error:console')
+    expect(errs.length).toBe(50)
+    expect(errs.every((p) => p.origin === 'http://localhost:5173')).toBe(true)
+  })
+
+  it('never posts app data to * across the whole lifecycle', () => {
+    const { win, posts } = createBridgeWindow()
+    win.console.error('boom')
+    shellMessage(win, 'https://evil.example', 'bridge:ping', { id: 'e1' })
+    shellMessage(win, 'http://localhost:5173', 'bridge:ping', { id: 'p1' })
+    win.console.warn('warn after lock')
+    shellMessage(win, 'http://localhost:4000', 'bridge:ping', { id: 'p3' })
+
+    for (const p of posts) {
+      if (p.origin === '*') expect(p.data.type).toBe('bridge:ready')
+    }
+    // Sanity: lifecycle actually produced locked-origin traffic.
+    expect(posts.some((p) => p.origin === 'http://localhost:5173')).toBe(true)
+  })
+})
diff --git a/src/plugin/__tests__/transform-astro.test.ts b/src/plugin/__tests__/transform-astro.test.ts
index 4a9f758..c8851fb 100644
--- a/src/plugin/__tests__/transform-astro.test.ts
+++ b/src/plugin/__tests__/transform-astro.test.ts
@@ -119,6 +119,38 @@ describe('transformAstro', () => {
     expect(result).toContain('data-annotask-file="src/pages/index.astro"')
   })
 
+  it('does not treat a --- inside markup as frontmatter when none opens the file', () => {
+    const code = [
+      '<div>start</div>',
+      '---',
+      '<p>middle</p>',
+      '---',
+      '<div>end</div>',
+    ].join('\n')
+    const result = transform(code)!
+    // A bare indexOf('---') used to swallow everything between the two
+    // dashes as "frontmatter", leaving <p> uninstrumented.
+    expect(result).toMatch(/<p[^>]*data-annotask/)
+    const matches = result.match(/data-annotask-file/g)
+    expect(matches).toHaveLength(3)
+  })
+
+  it('anchors the frontmatter close to its own line', () => {
+    const code = [
+      '---',
+      'const divider = "a --- b"',
+      '---',
+      '<div>content</div>',
+      '---',
+      '<p>after</p>',
+    ].join('\n')
+    const result = transform(code)!
+    expect(result).toMatch(/<div[^>]*data-annotask/)
+    expect(result).toMatch(/<p[^>]*data-annotask/)
+    // The inline --- inside the frontmatter string must not close the block.
+    expect(result).toContain('const divider = "a --- b"')
+  })
+
   it('handles multiple markup regions between blocks', () => {
     const code = [
       '<header>top</header>',
diff --git a/src/plugin/__tests__/transform-react.test.ts b/src/plugin/__tests__/transform-react.test.ts
index c14f4a4..b9b9000 100644
--- a/src/plugin/__tests__/transform-react.test.ts
+++ b/src/plugin/__tests__/transform-react.test.ts
@@ -1,4 +1,8 @@
 import { describe, it, expect } from 'vitest'
+import { globSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
 import { transformJSX } from '../transform'
 
 const ROOT = '/project'
@@ -234,4 +238,137 @@ describe('transformJSX', () => {
     const matches = result.match(/data-annotask-file/g)
     expect(matches!.length).toBeGreaterThanOrEqual(5)
   })
+
+  // Regression: the top-level scanner must be string/comment-aware at
+  // statement scope — `const html = "<div>x</div>"` previously got
+  // attributes injected INSIDE the string literal (a hard syntax error for
+  // double-quoted strings, since the injection itself uses double quotes).
+  describe('statement-scope string/comment awareness', () => {
+    it('does not inject inside double-quoted string literals', () => {
+      const code = [
+        'const html = "<div>hello</div>"',
+        'export function App() { return <p>hi</p> }',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain('const html = "<div>hello</div>"')
+      expect(result.match(/data-annotask-file/g)).toHaveLength(1) // only <p>
+    })
+
+    it('does not inject inside single-quoted strings in a ternary', () => {
+      const code = [
+        "const label = ready ? '<b>y</b>' : '<i>n</i>'",
+        'export function App() { return <main>{label}</main> }',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain("ready ? '<b>y</b>' : '<i>n</i>'")
+      expect(result.match(/data-annotask-file/g)).toHaveLength(1) // only <main>
+    })
+
+    it('does not mutate template-literal text', () => {
+      const code = [
+        'const t = `<section>hi</section>`',
+        'export const App = () => <p>hi</p>',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain('const t = `<section>hi</section>`')
+      expect(result.match(/data-annotask-file/g)).toHaveLength(1) // only <p>
+    })
+
+    it('still transforms JSX inside template-literal ${} interpolations', () => {
+      // A tag inside an interpolation IS legal JSX — only the raw template
+      // text around it is opaque.
+      const code = 'const out = `<li>raw</li> ${cond ? <span>real</span> : null}`'
+      const result = transform(code)!
+      expect(result).toContain('`<li>raw</li> ')
+      expect(result).toMatch(/<span data-annotask-file/)
+      expect(result.match(/data-annotask-file/g)).toHaveLength(1) // span only, not li
+    })
+
+    it('handles nested template literals inside interpolations', () => {
+      const code = 'const out = `a ${wrap(`<em>inner</em>`)} ${flag ? <b>tag</b> : null} z`'
+      const result = transform(code)!
+      expect(result).toContain('`<em>inner</em>`')
+      expect(result).toMatch(/<b data-annotask-file/)
+      expect(result.match(/data-annotask-file/g)).toHaveLength(1)
+    })
+
+    it('does not inject inside // and /* */ comments', () => {
+      const code = [
+        '// <div>line comment</div>',
+        '/* <section>block',
+        '   comment</section> */',
+        'export function App() { return <main>hi</main> }',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain('// <div>line comment</div>')
+      expect(result).toContain('<section>block')
+      expect(result.match(/data-annotask-file/g)).toHaveLength(1) // only <main>
+    })
+
+    it('does not inject inside JSX expression comments', () => {
+      const code = 'function App() { return <div>{/* <b>no</b> */}<span>x</span></div> }'
+      const result = transform(code)!
+      expect(result).toContain('{/* <b>no</b> */}')
+      expect(result.match(/data-annotask-file/g)).toHaveLength(2) // div, span
+    })
+
+    it('treats quotes and slashes inside JSX children as plain text', () => {
+      // String skipping must only apply at statement scope — apostrophes in
+      // JSX text are NOT string delimiters.
+      const code = 'function App() { return <div>it\'s "quoted" 1/2 <em>fine</em></div> }'
+      const result = transform(code)!
+      expect(result).toContain('it\'s "quoted" 1/2')
+      expect(result.match(/data-annotask-file/g)).toHaveLength(2) // div, em
+    })
+
+    it('does not inject inside regex literals', () => {
+      const code = [
+        'const re = /<div>/',
+        'const ratio = total / 2 / count',
+        'export function App() { return <p>ok</p> }',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain('const re = /<div>/')
+      expect(result).toContain('total / 2 / count')
+      expect(result.match(/data-annotask-file/g)).toHaveLength(1) // only <p>
+    })
+
+    it('still transforms JSX after a string-bearing statement', () => {
+      const code = [
+        'const greeting = "hello <name>"',
+        'function App() {',
+        '  const cls = `theme-${mode}`',
+        '  return <div className={cls}>{greeting}</div>',
+        '}',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain('const greeting = "hello <name>"')
+      expect(result).toContain('`theme-${mode}`')
+      expect(result.match(/data-annotask-file/g)).toHaveLength(1) // the div
+    })
+
+    it('keeps every playground react-vite source syntactically valid after transform', () => {
+      // End-to-end net: real-world TSX (template literals, comments, string
+      // constants, generics) must survive the transform without syntax errors.
+      const playgroundRoot = path.resolve(
+        path.dirname(fileURLToPath(import.meta.url)),
+        '../../../playgrounds/simple/react-vite'
+      )
+      const files = globSync('src/**/*.{tsx,jsx}', { cwd: playgroundRoot })
+      expect(files.length).toBeGreaterThan(0)
+      for (const rel of files) {
+        const file = path.join(playgroundRoot, rel)
+        const code = readFileSync(file, 'utf8')
+        const result = transformJSX(code, file, playgroundRoot)
+        if (result === null) continue // nothing instrumentable
+        const sourceFile = ts.createSourceFile(rel, result, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+        // parseDiagnostics is internal but stable — the documented alternative
+        // (full ts.createProgram) is far heavier for a pure syntax check.
+        const diags = (sourceFile as unknown as { parseDiagnostics: ts.Diagnostic[] }).parseDiagnostics
+        expect(
+          diags.map(d => `${rel}: ${ts.flattenDiagnosticMessageText(d.messageText, ' ')}`),
+        ).toEqual([])
+      }
+    })
+  })
 })
diff --git a/src/plugin/__tests__/transform-svelte.test.ts b/src/plugin/__tests__/transform-svelte.test.ts
index d8e15a9..0e12d4c 100644
--- a/src/plugin/__tests__/transform-svelte.test.ts
+++ b/src/plugin/__tests__/transform-svelte.test.ts
@@ -1,5 +1,9 @@
 import { describe, it, expect } from 'vitest'
-import { transformSvelte } from '../transform'
+import { globSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { compile } from 'svelte/compiler'
+import { transformFile, transformSvelte } from '../transform'
 
 const ROOT = '/project'
 
@@ -7,6 +11,11 @@ function transform(code: string, file = '/project/src/Counter.svelte') {
   return transformSvelte(code, file, ROOT)
 }
 
+/** Assert the transformed source still compiles under the real Svelte compiler. */
+function expectCompiles(source: string) {
+  expect(() => compile(source, { generate: 'client', filename: 'Test.svelte' })).not.toThrow()
+}
+
 describe('transformSvelte', () => {
   it('injects attributes on markup elements', () => {
     const code = '<div>hello</div>'
@@ -178,4 +187,118 @@ describe('transformSvelte', () => {
     )!
     expect(result).toContain('data-annotask-component="MyComponent"')
   })
+
+  // Regression: findTagEnd must track {} brace depth in Svelte markup —
+  // attribute expressions like `onclick={() => ...}` contain bare `>` that
+  // would otherwise terminate the tag early and inject attributes INSIDE
+  // the expression (svelte/compiler js_parse_error).
+  describe('attribute expressions (brace tracking)', () => {
+    it('handles on:click={() => fn(null)} (Svelte 4 events)', () => {
+      const code = [
+        '<script>',
+        '  function fn(v) { console.log(v) }',
+        '</script>',
+        '<button on:click={() => fn(null)}>go</button>',
+      ].join('\n')
+      const result = transform(code)!
+      // Expression intact, injection landed on the tag — never inside braces
+      expect(result).toContain('on:click={() => fn(null)}')
+      expect(result).not.toMatch(/\{[^}]*data-annotask/)
+      expect(result).toMatch(/<button on:click=\{\(\) => fn\(null\)\} data-annotask-file/)
+      expectCompiles(result)
+    })
+
+    it('handles onclick={() => fn(1)} (Svelte 5 events)', () => {
+      const code = [
+        '<script>',
+        '  function fn(v) { console.log(v) }',
+        '</script>',
+        '<button onclick={() => fn(1)}>go</button>',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain('onclick={() => fn(1)}')
+      expect(result).not.toMatch(/\{[^}]*data-annotask/)
+      expectCompiles(result)
+    })
+
+    it('handles bare > comparison in class={a > b}', () => {
+      const code = [
+        '<script>',
+        '  let a = 1',
+        '  let b = 2',
+        '</script>',
+        '<div class={a > b}>x</div>',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain('class={a > b}')
+      expect(result).not.toMatch(/\{[^}]*data-annotask/)
+      expectCompiles(result)
+    })
+
+    it('handles arrow-function attribute value attr={x => y}', () => {
+      const code = [
+        '<script>',
+        '  let y = 1',
+        '</script>',
+        '<div data-handler={x => y}>hi</div>',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain('data-handler={x => y}')
+      expect(result).not.toMatch(/\{[^}]*data-annotask/)
+      expectCompiles(result)
+    })
+
+    it('handles multiline tags with expression attributes and trailing >', () => {
+      const code = [
+        '<button',
+        '  type="button"',
+        '  class:active={value === null}',
+        '  onclick={() => onselect(null)}',
+        '>',
+        '  All',
+        '</button>',
+      ].join('\n')
+      const result = transform(code)!
+      expect(result).toContain('class:active={value === null}')
+      expect(result).toContain('onclick={() => onselect(null)}')
+      expect(result).not.toMatch(/\{[^}]*data-annotask/)
+    })
+
+    it('transforms the real playground FilterChips.svelte without corruption', () => {
+      const playgroundRoot = path.resolve(
+        path.dirname(fileURLToPath(import.meta.url)),
+        '../../../playgrounds/simple/svelte-vite'
+      )
+      const file = path.join(playgroundRoot, 'src/components/FilterChips.svelte')
+      const code = readFileSync(file, 'utf8')
+      const result = transformFile(code, file, playgroundRoot)!
+      expect(result).toContain('onclick={() => onselect(null)}')
+      expect(result).toContain('onclick={() => onselect(option)}')
+      expect(result).not.toMatch(/\{[^}]*data-annotask/)
+      // Both <button>s and the wrapping <div> get instrumented
+      expect(result.match(/data-annotask-file/g)!.length).toBe(3)
+      expectCompiles(result)
+    })
+
+    it('keeps every playground svelte-vite component compilable after transform', () => {
+      // End-to-end net: real-world Svelte 5 sources (snippets, $props,
+      // expression attributes, each blocks) must survive the transform.
+      const playgroundRoot = path.resolve(
+        path.dirname(fileURLToPath(import.meta.url)),
+        '../../../playgrounds/simple/svelte-vite'
+      )
+      const files = globSync('src/**/*.svelte', { cwd: playgroundRoot })
+      expect(files.length).toBeGreaterThan(0)
+      for (const rel of files) {
+        const file = path.join(playgroundRoot, rel)
+        const code = readFileSync(file, 'utf8')
+        const result = transformFile(code, file, playgroundRoot)
+        if (result === null) continue // nothing instrumentable
+        expect(
+          () => compile(result, { generate: 'client', filename: rel }),
+          `${rel} no longer compiles after transform`
+        ).not.toThrow()
+      }
+    })
+  })
 })
diff --git a/src/plugin/bridge/events.ts b/src/plugin/bridge/events.ts
index 11b016b..af142e4 100644
--- a/src/plugin/bridge/events.ts
+++ b/src/plugin/bridge/events.ts
@@ -165,6 +165,29 @@ export function bridgeEvents(): string {
     var el = e.target;
     if (!el) return;
 
+    // Clicks inside an annotask-mounted placement select the PLACEMENT — the
+    // mounted component's own data-annotask-* attrs point at its internals
+    // (e.g. PlanetCard.vue), which is the wrong identity for editing.
+    var instEl = el.closest ? el.closest('[data-annotask-instance]') : null;
+    if (instEl) {
+      sendToShell('click:element', {
+        eid: getEid(instEl),
+        sourceEid: getEid(instEl),
+        instance_id: instEl.getAttribute('data-annotask-instance'),
+        file: '',
+        line: '',
+        component: instEl.getAttribute('data-annotask-component-name') || '',
+        tag: instEl.tagName.toLowerCase(),
+        classes: typeof instEl.className === 'string' ? instEl.className : '',
+        rect: getRect(instEl),
+        shiftKey: e.shiftKey,
+        clientX: e.clientX,
+        clientY: e.clientY,
+        text: getVisibleText(instEl, 200)
+      });
+      return;
+    }
+
     var source = findSourceElement(el);
     var data = getSourceData(source.sourceEl);
     var targetEl = source.targetEl;
diff --git a/src/plugin/bridge/helpers.ts b/src/plugin/bridge/helpers.ts
index 3aaf591..6cd8822 100644
--- a/src/plugin/bridge/helpers.ts
+++ b/src/plugin/bridge/helpers.ts
@@ -74,18 +74,12 @@ export function bridgeHelpers(): string {
       }
     } else if (isComponent) {
       var vcMounted = tryMountComponent(el, payload.tag, payload.defaultProps);
-      if (!vcMounted) {
-        el.style.cssText = 'min-height:80px;padding:16px;border:1px solid rgba(168,85,247,0.2);border-radius:8px;background:rgba(168,85,247,0.03);display:flex;flex-direction:column;gap:8px;overflow:hidden;';
-        var hdr = document.createElement('div');
-        hdr.style.cssText = 'display:flex;align-items:center;gap:6px;margin-bottom:4px;';
-        var dot = document.createElement('span');
-        dot.style.cssText = 'width:6px;height:6px;border-radius:50%;background:#a855f7;';
-        hdr.appendChild(dot);
-        var tagLabel = document.createElement('span');
-        tagLabel.style.cssText = 'font-size:11px;font-weight:600;color:#a855f7;';
-        tagLabel.textContent = payload.tag;
-        hdr.appendChild(tagLabel);
-        el.appendChild(hdr);
+      el.setAttribute('data-annotask-fidelity', vcMounted.fidelity);
+      if (vcMounted.reason) el.setAttribute('data-annotask-mount-reason', vcMounted.reason);
+      if (!vcMounted.mounted) {
+        renderUnmountedBadge(el, payload.tag, vcMounted.reason);
+      } else if (vcMounted.fidelity !== 'live') {
+        renderFidelityPill(el, vcMounted.fidelity);
       }
     } else {
       el.textContent = payload.textContent || '';
@@ -93,75 +87,332 @@ export function bridgeHelpers(): string {
     return el;
   }
 
-  function tryMountComponent(container, componentName, props) {
-    if (window.__ANNOTASK_VUE__) {
-      var mounted = tryMountVueComponent(container, componentName, props);
-      if (mounted) return true;
-    }
-    if (window.__ANNOTASK_REACT__) {
-      var mounted = tryMountReactComponent(container, componentName, props);
-      if (mounted) return true;
+  // ── Mount results (honest fidelity) ──────────────────
+  // Every tryMount* returns a structured result instead of a bare boolean so the
+  // canvas can render a VISIBLY different, honest state per outcome — never a
+  // silent empty box. reason: 'not-registered'|'threw'|'rendered-empty'|
+  // 'no-runtime'|'async-pending'. fidelity: 'live' (Vue in-context) |
+  // 'isolated-preview' (detached React/Svelte/Solid, no provider tree) |
+  // 'placeholder' (could not render).
+  function mountResult(mounted, reason, fidelity, detail) {
+    return { mounted: mounted, reason: reason || null, fidelity: fidelity || (mounted ? 'live' : 'placeholder'), detail: detail || null };
+  }
+
+  function errMsg(e) {
+    try { return String((e && (e.message || e.toString())) || e).slice(0, 300); } catch (x) { return 'error'; }
+  }
+
+  // A mount is empty only when it produced neither element children nor text —
+  // a text-only render (e.g. {{ msg }}) is still a real render, not 'empty'.
+  function isEmptyMount(mp) {
+    return mp.childElementCount === 0 && !(mp.textContent && mp.textContent.replace(/\\s+/g, ''));
+  }
+
+  function reasonText(reason) {
+    if (reason === 'not-registered') return 'not in registry';
+    if (reason === 'threw') return 'render error';
+    if (reason === 'rendered-empty') return 'rendered empty';
+    if (reason === 'no-runtime') return 'no runtime';
+    if (reason === 'async-pending') return 'pending';
+    if (reason === 'needs-children') return 'needs child content';
+    return reason || '';
+  }
+
+  // Labeled "couldn't render" box (purple dashed) so a failed mount is never an
+  // invisible empty div. Shared by createPlaceholder + the insert:component handler.
+  function renderUnmountedBadge(el, label, reason) {
+    el.style.cssText = 'position:relative;min-height:80px;padding:16px;border:1px solid rgba(168,85,247,0.2);border-radius:8px;background:rgba(168,85,247,0.03);display:flex;flex-direction:column;gap:8px;overflow:hidden;';
+    var hdr = document.createElement('div');
+    hdr.style.cssText = 'display:flex;align-items:center;gap:6px;margin-bottom:4px;';
+    var dot = document.createElement('span');
+    dot.style.cssText = 'width:6px;height:6px;border-radius:50%;background:#a855f7;';
+    hdr.appendChild(dot);
+    var tagLabel = document.createElement('span');
+    tagLabel.style.cssText = 'font-size:11px;font-weight:600;color:#a855f7;';
+    tagLabel.textContent = label;
+    hdr.appendChild(tagLabel);
+    if (reason) {
+      var reasonLabel = document.createElement('span');
+      reasonLabel.style.cssText = 'font-size:10px;font-weight:500;color:#a855f7;opacity:0.7;margin-left:auto;';
+      reasonLabel.textContent = reasonText(reason);
+      hdr.appendChild(reasonLabel);
     }
-    if (window.__ANNOTASK_SVELTE__) {
-      var mounted = tryMountSvelteComponent(container, componentName, props);
-      if (mounted) return true;
+    el.appendChild(hdr);
+  }
+
+  // A small corner pill marking a non-live fidelity (isolated preview) so the
+  // user knows the render is detached from the app's real provider tree. A
+  // slot-sample mount gets its own amber pill even at 'live' fidelity — the
+  // child content is OURS, and that must never be a silent fake.
+  function renderFidelityPill(el, fidelity) {
+    var slotSample = el.hasAttribute && el.hasAttribute('data-annotask-slot-sample');
+    if (fidelity === 'live' && !slotSample) return;
+    try {
+      var cs = window.getComputedStyle(el);
+      if (cs.position === 'static') el.style.position = 'relative';
+    } catch(e) {}
+    var pill = document.createElement('span');
+    pill.setAttribute('data-annotask-fidelity-pill', 'true');
+    var color, text;
+    if (slotSample) { color = '#f59e0b'; text = 'sample slot'; }
+    else if (fidelity === 'isolated-preview') { color = '#f59e0b'; text = 'preview'; }
+    else { color = '#9ca3af'; text = 'placeholder'; }
+    pill.textContent = text;
+    pill.style.cssText = 'position:absolute;top:2px;right:2px;z-index:2;font-size:9px;font-weight:600;line-height:1;padding:2px 5px;border-radius:6px;color:#fff;background:' + color + ';pointer-events:none;opacity:0.85;';
+    el.appendChild(pill);
+  }
+
+  // React/Svelte/Solid mount asynchronously, so a synchronous emptiness check is
+  // a false negative. Defer two frames, then flip the container to an honest
+  // placeholder ONLY if nothing rendered.
+  function scheduleEmptyCheck(container, mountPoint, label) {
+    requestAnimationFrame(function() {
+      requestAnimationFrame(function() {
+        if (!isEmptyMount(mountPoint)) return;
+        try { mountPoint.remove(); } catch(e) {}
+        var pill = container.querySelector('[data-annotask-fidelity-pill]');
+        if (pill) { try { pill.remove(); } catch(e) {} }
+        container.removeAttribute('data-annotask-mounted');
+        container.setAttribute('data-annotask-fidelity', 'placeholder');
+        container.setAttribute('data-annotask-mount-reason', 'rendered-empty');
+        renderUnmountedBadge(container, label, 'rendered-empty');
+      });
+    });
+  }
+
+  // On-demand component load: when a component isn't registered on the current
+  // route, ask the dev server for its raw module URL, dynamically import it, and
+  // register it — so the palette can preview/drop ANY catalog component. Raw
+  // (not optimized-dep) import avoids a Vite re-optimization page reload.
+  function ensureComponentLoaded(name, module) {
+    if (window.__ANNOTASK_COMPONENTS__ && window.__ANNOTASK_COMPONENTS__[name]) return Promise.resolve(true);
+    if (!module) return Promise.resolve(false);
+    return fetch('/__annotask/preview-module?spec=' + encodeURIComponent(module))
+      .then(function(r) { return r.ok ? r.json() : null; })
+      .then(function(j) {
+        if (!j || !j.url) return false;
+        return import(/* @vite-ignore */ j.url).then(function(mod) {
+          var comp = mod && (mod.default || mod[name] || mod);
+          if (comp && (typeof comp === 'object' || typeof comp === 'function')) {
+            window.__ANNOTASK_COMPONENTS__ = window.__ANNOTASK_COMPONENTS__ || {};
+            window.__ANNOTASK_COMPONENTS__[name] = comp;
+            return true;
+          }
+          return false;
+        });
+      })
+      .catch(function() { return false; });
+  }
+
+  // ── Per-framework live-mount registry ──────────────────
+  // Each framework has a mount strategy with a documented fidelity ceiling. We
+  // lift frameworks one at a time toward 'live' (renders inside the app's REAL
+  // provider tree) so dropped/previewed components look like the running app:
+  //
+  //   Framework | Strategy                                    | Fidelity ceiling
+  //   ----------|---------------------------------------------|------------------
+  //   Vue       | mini-app sharing the parent app's _context  | live  (reference)
+  //   React     | detached root re-wrapped in the app's       | live  (best-effort
+  //             |   discovered Context.Providers (fiber walk);|   fiber walk; falls
+  //             |   bare detached root otherwise              |   back to isolated)
+  //   Svelte    | detached mount()                            | isolated-preview
+  //   Solid     | detached render()                           | isolated-preview
+  //
+  // To improve a framework: give it a provider-discovery step like React's and
+  // raise its returned fidelity to 'live' when the app context is reachable.
+  // tryMountComponent tries each present runtime in order, returning the first
+  // success (or the most informative failure).
+  function tryMountComponent(container, componentName, props) {
+    var runtimes = [
+      ['__ANNOTASK_VUE__', tryMountVueComponent],
+      ['__ANNOTASK_REACT__', tryMountReactComponent],
+      ['__ANNOTASK_SOLID__', tryMountSolidComponent],
+      ['__ANNOTASK_SVELTE__', tryMountSvelteComponent]
+    ];
+    var best = null;
+    for (var i = 0; i < runtimes.length; i++) {
+      if (!window[runtimes[i][0]]) continue;
+      var r = runtimes[i][1](container, componentName, props);
+      if (r.mounted) return r;
+      // Keep the most informative failure: a definitive reason (threw/empty)
+      // beats 'not-registered'/'no-runtime' from a framework that didn't own it.
+      if (!best || best.reason === 'not-registered' || best.reason === 'no-runtime') best = r;
     }
-    return false;
+    return best || mountResult(false, 'no-runtime', 'placeholder');
   }
 
   function tryMountVueComponent(container, componentName, props) {
     try {
       var appEl = document.querySelector('#app');
       var vueApp = appEl && appEl.__vue_app__;
-      if (!vueApp) return false;
+      if (!vueApp) return mountResult(false, 'no-runtime', 'placeholder');
       var annotaskVue = window.__ANNOTASK_VUE__;
-      if (!annotaskVue || !annotaskVue.createApp || !annotaskVue.h) return false;
+      if (!annotaskVue || !annotaskVue.createApp || !annotaskVue.h) return mountResult(false, 'no-runtime', 'placeholder');
       var component = vueApp._context.components[componentName] || (window.__ANNOTASK_COMPONENTS__ && window.__ANNOTASK_COMPONENTS__[componentName]);
-      if (!component) return false;
-      var mountPoint = document.createElement('div');
-      container.appendChild(mountPoint);
-      var miniApp = annotaskVue.createApp({
-        render: function() { return annotaskVue.h(component, props || {}); }
-      });
-      // Share the parent app's provides, components, directives, and config
-      // but keep the mini app's own app reference intact
-      var parentCtx = vueApp._context;
-      miniApp._context.components = parentCtx.components;
-      miniApp._context.directives = parentCtx.directives;
-      miniApp._context.provides = parentCtx.provides;
-      miniApp._context.config.globalProperties = parentCtx.config.globalProperties;
-      // Suppress render errors so partial renders still display
-      miniApp.config.errorHandler = function() {};
-      miniApp.config.warnHandler = function() {};
-      miniApp.mount(mountPoint);
-      container.setAttribute('data-annotask-mounted', 'true');
-      container.__annotask_unmount = function() { try { miniApp.unmount(); } catch(e) {} };
-      return true;
-    } catch(e) { return false; }
+      if (!component) return mountResult(false, 'not-registered', 'placeholder');
+      // One mount attempt; withSlot fills the default slot with an honestly
+      // labeled sample so compound components (Accordion, TabView) can render
+      // their real chrome instead of throwing / rendering empty.
+      var attempt = function(withSlot) {
+        var mountPoint = document.createElement('div');
+        container.appendChild(mountPoint);
+        var caught = null;
+        var miniApp = annotaskVue.createApp({
+          render: function() {
+            var p = props || {};
+            if (withSlot) {
+              return annotaskVue.h(component, p, {
+                default: function() { return annotaskVue.h('div', { style: 'padding:8px;font-size:12px;opacity:.7;' }, 'Sample content'); }
+              });
+            }
+            return annotaskVue.h(component, p);
+          }
+        });
+        // Share the parent app's provides, components, directives, and config
+        // (by reference) so the dropped component renders in real app context.
+        var parentCtx = vueApp._context;
+        miniApp._context.components = parentCtx.components;
+        miniApp._context.directives = parentCtx.directives;
+        miniApp._context.provides = parentCtx.provides;
+        miniApp._context.config.globalProperties = parentCtx.config.globalProperties;
+        // Capture render errors (instead of the old no-op handlers) so we can
+        // report an honest 'threw' reason. warnHandler stays silent.
+        miniApp.config.errorHandler = function(err) { caught = err; };
+        miniApp.config.warnHandler = function() {};
+        miniApp.mount(mountPoint);
+        if (caught || isEmptyMount(mountPoint)) {
+          try { miniApp.unmount(); } catch(e) {}
+          try { mountPoint.remove(); } catch(e) {}
+          return { ok: false, caught: caught };
+        }
+        return { ok: true, miniApp: miniApp };
+      };
+
+      var finish = function(r) {
+        container.setAttribute('data-annotask-mounted', 'true');
+        container.__annotask_unmount = function() { try { r.miniApp.unmount(); } catch(e) {} };
+        return mountResult(true, null, 'live');
+      };
+
+      var first = attempt(false);
+      if (first.ok) return finish(first);
+      // Slot-retry, ONCE: a slot error or an empty render is the compound-
+      // component signature. The sample child is ours — the slot-sample
+      // attribute drives an amber "sample slot" pill, and the retry never
+      // writes into the persisted instance (codegen never fabricates children).
+      if (!first.caught || /slot/i.test(errMsg(first.caught))) {
+        var second = attempt(true);
+        if (second.ok) {
+          container.setAttribute('data-annotask-slot-sample', 'true');
+          return finish(second);
+        }
+      }
+      return mountResult(false, first.caught ? 'threw' : 'rendered-empty', 'placeholder', first.caught ? errMsg(first.caught) : null);
+    } catch(e) { return mountResult(false, 'threw', 'placeholder', errMsg(e)); }
+  }
+
+  // Collect the value of every Context.Provider currently mounted above the app
+  // content, so a detached React mount can be re-wrapped in the same providers
+  // (theme, router, query, …) and render in real app context instead of an
+  // isolated root. Best-effort: it reads React fiber internals (version-
+  // sensitive), so any failure returns null and the caller mounts bare.
+  function collectReactProviders() {
+    try {
+      var rootEl = document.querySelector('#root') || document.querySelector('#app') || document.body.firstElementChild;
+      if (!rootEl) return null;
+      var fiber = null, rk = Object.keys(rootEl);
+      for (var ri = 0; ri < rk.length; ri++) {
+        if (rk[ri].indexOf('__reactContainer$') === 0 || rk[ri].indexOf('__reactFiber$') === 0) { fiber = rootEl[rk[ri]]; break; }
+      }
+      if (!fiber) return null;
+      var providerSym = (typeof Symbol === 'function' && Symbol.for) ? Symbol.for('react.provider') : null;
+      var ctxSym = (typeof Symbol === 'function' && Symbol.for) ? Symbol.for('react.context') : null;
+      var found = [], seen = 0, node = fiber.child || fiber;
+      // Depth-first down the spine; providers live near the top, so cap the walk.
+      while (node && seen < 2000) {
+        seen++;
+        var t = node.type;
+        if (t && t.$$typeof) {
+          var ctx = null;
+          if (providerSym && t.$$typeof === providerSym && t._context) ctx = t._context;       // React 18: <Ctx.Provider>
+          else if (ctxSym && t.$$typeof === ctxSym && t.Provider) ctx = t;                       // React 19: <Ctx> is the provider
+          if (ctx && node.memoizedProps && Object.prototype.hasOwnProperty.call(node.memoizedProps, 'value')) {
+            found.push({ context: ctx, value: node.memoizedProps.value });
+          }
+        }
+        if (node.child) { node = node.child; continue; }
+        while (node && !node.sibling && node !== fiber) node = node.return;
+        if (!node || node === fiber) break;
+        node = node.sibling;
+      }
+      return found.length ? found : null;
+    } catch(e) { return null; }
   }
 
   function tryMountReactComponent(container, componentName, props) {
     try {
       var annotaskReact = window.__ANNOTASK_REACT__;
-      if (!annotaskReact || !annotaskReact.createElement || !annotaskReact.createRoot) return false;
+      if (!annotaskReact || !annotaskReact.createElement || !annotaskReact.createRoot) return mountResult(false, 'no-runtime', 'placeholder');
       var component = window.__ANNOTASK_COMPONENTS__ && window.__ANNOTASK_COMPONENTS__[componentName];
-      if (!component) return false;
+      if (!component) return mountResult(false, 'not-registered', 'placeholder');
       var mountPoint = document.createElement('div');
       container.appendChild(mountPoint);
+      // Re-wrap the component in the app's discovered providers when reachable so
+      // it renders 'live'; fall back to a bare detached root ('isolated-preview').
+      var fidelity = 'isolated-preview';
+      var providers = collectReactProviders();
+      var buildElement = function(p) {
+        var el = annotaskReact.createElement(component, p || {});
+        if (providers && providers.length) {
+          try {
+            for (var pi = providers.length - 1; pi >= 0; pi--) {
+              var Provider = providers[pi].context.Provider || providers[pi].context;
+              el = annotaskReact.createElement(Provider, { value: providers[pi].value }, el);
+            }
+          } catch(e) { return annotaskReact.createElement(component, p || {}); }
+        }
+        return el;
+      };
+      var element;
+      if (providers && providers.length) {
+        try { element = buildElement(props); fidelity = 'live'; }
+        catch(e) { element = annotaskReact.createElement(component, props || {}); fidelity = 'isolated-preview'; }
+      } else {
+        element = buildElement(props);
+      }
       var root = annotaskReact.createRoot(mountPoint);
-      root.render(annotaskReact.createElement(component, props || {}));
+      root.render(element);
       container.setAttribute('data-annotask-mounted', 'true');
       container.__annotask_unmount = function() { try { root.unmount(); } catch(e) {} };
-      return true;
-    } catch(e) { return false; }
+      // Confirm it actually rendered (async) — but first try ONE slot-retry
+      // with a labeled sample child, the compound-component signature. If the
+      // retry renders, the slot-sample attribute marks the children as ours;
+      // if it stays empty, the final check flips to the honest placeholder.
+      requestAnimationFrame(function() {
+        requestAnimationFrame(function() {
+          if (!isEmptyMount(mountPoint)) return;
+          try {
+            container.setAttribute('data-annotask-slot-sample', 'true');
+            var sampleChild = annotaskReact.createElement('div', { style: { padding: '8px', fontSize: '12px', opacity: 0.7 } }, 'Sample content');
+            var withChildren = annotaskReact.createElement(component, Object.assign({}, props || {}), sampleChild);
+            root.render(withChildren);
+            scheduleEmptyCheck(container, mountPoint, componentName);
+          } catch(e) {
+            container.removeAttribute('data-annotask-slot-sample');
+            scheduleEmptyCheck(container, mountPoint, componentName);
+          }
+        });
+      });
+      return mountResult(true, null, fidelity);
+    } catch(e) { return mountResult(false, 'threw', 'placeholder', errMsg(e)); }
   }
 
   function tryMountSvelteComponent(container, componentName, props) {
     try {
       var annotaskSvelte = window.__ANNOTASK_SVELTE__;
-      if (!annotaskSvelte || !annotaskSvelte.mount) return false;
+      if (!annotaskSvelte || !annotaskSvelte.mount) return mountResult(false, 'no-runtime', 'placeholder');
       var component = window.__ANNOTASK_COMPONENTS__ && window.__ANNOTASK_COMPONENTS__[componentName];
-      if (!component) return false;
+      if (!component) return mountResult(false, 'not-registered', 'placeholder');
       var mountPoint = document.createElement('div');
       container.appendChild(mountPoint);
       var instance = annotaskSvelte.mount(component, { target: mountPoint, props: props || {} });
@@ -171,8 +422,26 @@ export function bridgeHelpers(): string {
           if (annotaskSvelte.unmount) annotaskSvelte.unmount(instance);
         } catch(e) {}
       };
-      return true;
-    } catch(e) { return false; }
+      scheduleEmptyCheck(container, mountPoint, componentName);
+      return mountResult(true, null, 'isolated-preview');
+    } catch(e) { return mountResult(false, 'threw', 'placeholder'); }
+  }
+
+  function tryMountSolidComponent(container, componentName, props) {
+    try {
+      var annotaskSolid = window.__ANNOTASK_SOLID__;
+      if (!annotaskSolid || !annotaskSolid.render) return mountResult(false, 'no-runtime', 'placeholder');
+      var component = window.__ANNOTASK_COMPONENTS__ && window.__ANNOTASK_COMPONENTS__[componentName];
+      if (!component) return mountResult(false, 'not-registered', 'placeholder');
+      var mountPoint = document.createElement('div');
+      container.appendChild(mountPoint);
+      // solid-js/web render(code, element) returns a dispose function.
+      var dispose = annotaskSolid.render(function() { return component(props || {}); }, mountPoint);
+      container.setAttribute('data-annotask-mounted', 'true');
+      container.__annotask_unmount = function() { try { dispose(); } catch(e) {} };
+      scheduleEmptyCheck(container, mountPoint, componentName);
+      return mountResult(true, null, 'isolated-preview');
+    } catch(e) { return mountResult(false, 'threw', 'placeholder'); }
   }
 `
 }
diff --git a/src/plugin/bridge/messages.ts b/src/plugin/bridge/messages.ts
index 8bccec5..fc6013d 100644
--- a/src/plugin/bridge/messages.ts
+++ b/src/plugin/bridge/messages.ts
@@ -12,6 +12,35 @@ export function bridgeMessages(): string {
   //   3. Sniff explicit DOM markers (class / data-attr). A recognized marker
   //      overrides luminance when unambiguous ('dark'/'light'), since explicit
   //      dev intent should win over a heuristic.
+  function readBg(el) {
+    if (!el) return null;
+    var bg = '';
+    try { bg = window.getComputedStyle(el).backgroundColor || ''; } catch(e) { return null; }
+    if (!bg || bg === 'transparent' || bg === 'rgba(0, 0, 0, 0)') return null;
+    var parts = bg.match(/[0-9.]+/g);
+    if (!parts || parts.length < 3) return null;
+    var alpha = parts.length >= 4 ? parseFloat(parts[3]) : 1;
+    if (!alpha) return null;
+    return { r: parseFloat(parts[0]), g: parseFloat(parts[1]), b: parseFloat(parts[2]) };
+  }
+
+  // App-true preview surface: the background the app actually paints (body
+  // first — content sits on it — then html; deliberately the opposite order
+  // of detectColorScheme's viewport probe), plus a contrast-safe text color
+  // from its luminance. Scheme-derived fallback when both are transparent.
+  function resolveAppSurface() {
+    var bg = readBg(document.body) || readBg(document.documentElement);
+    if (bg) {
+      var lum = (0.2126 * bg.r + 0.7152 * bg.g + 0.0722 * bg.b) / 255;
+      return {
+        background: 'rgb(' + Math.round(bg.r) + ', ' + Math.round(bg.g) + ', ' + Math.round(bg.b) + ')',
+        color: lum < 0.5 ? '#f5f5f5' : '#111111'
+      };
+    }
+    var dark = detectColorScheme().scheme === 'dark';
+    return { background: dark ? '#111827' : '#ffffff', color: dark ? '#f5f5f5' : '#111111' };
+  }
+
   function detectColorScheme() {
     var scheme = 'light';
     var source = 'fallback';
@@ -21,18 +50,6 @@ export function bridgeMessages(): string {
       var html = document.documentElement;
       var body = document.body;
 
-      function readBg(el) {
-        if (!el) return null;
-        var bg = '';
-        try { bg = window.getComputedStyle(el).backgroundColor || ''; } catch(e) { return null; }
-        if (!bg || bg === 'transparent' || bg === 'rgba(0, 0, 0, 0)') return null;
-        var parts = bg.match(/[0-9.]+/g);
-        if (!parts || parts.length < 3) return null;
-        var alpha = parts.length >= 4 ? parseFloat(parts[3]) : 1;
-        if (!alpha) return null;
-        return { r: parseFloat(parts[0]), g: parseFloat(parts[1]), b: parseFloat(parts[2]) };
-      }
-
       var bg = readBg(html) || readBg(body);
       if (bg) {
         var lum = (0.2126 * bg.r + 0.7152 * bg.g + 0.0722 * bg.b) / 255;
@@ -119,7 +136,17 @@ export function bridgeMessages(): string {
   window.addEventListener('message', function(event) {
     var msg = event.data;
     if (!msg || msg.source !== 'annotask-shell') return;
-    if (shellOrigin === '*' && event.origin) shellOrigin = event.origin;
+    // Origin gate: only local origins may drive the bridge, and the first
+    // validated sender locks shellOrigin for the session. msg.source alone
+    // is spoofable by any page that iframes the dev app — without this
+    // check such a page could read outerHTML, set styles, and mount
+    // components cross-origin. Post-lock, even local-but-different origins
+    // are rejected so a second hostile localhost context can't hijack an
+    // established session. Locking happens BEFORE dispatch so responses
+    // (and the flushed pre-lock queue) post to the validated origin only.
+    if (!isLocalBridgeOrigin(event.origin)) return;
+    if (shellOrigin === null) lockShellOrigin(event.origin);
+    else if (event.origin !== shellOrigin) return;
 
     var type = msg.type;
     var payload = msg.payload || {};
@@ -172,6 +199,25 @@ export function bridgeMessages(): string {
         respond(id, null);
         return;
       }
+      // A point inside an annotask-mounted placement resolves to the PLACEMENT,
+      // never to the mounted component's internals — their data-annotask-*
+      // attrs describe the component's own source (e.g. PlanetCard.vue), which
+      // is the wrong identity for selection and a wrong anchor for drops.
+      var rapInst = el.closest ? el.closest('[data-annotask-instance]') : null;
+      if (rapInst) {
+        respond(id, {
+          eid: getEid(rapInst),
+          instance_id: rapInst.getAttribute('data-annotask-instance'),
+          file: '',
+          line: '',
+          component: rapInst.getAttribute('data-annotask-component-name') || '',
+          tag: rapInst.tagName.toLowerCase(),
+          rect: getRect(rapInst),
+          classes: typeof rapInst.className === 'string' ? rapInst.className : '',
+          text: getVisibleText(rapInst, 200)
+        });
+        return;
+      }
       var src = findSourceElement(el);
       var srcData = getSourceData(src.sourceEl);
       respond(id, {
@@ -239,6 +285,87 @@ export function bridgeMessages(): string {
       return;
     }
 
+    if (type === 'resolve:text-rects') {
+      // Re-measure a text selection's per-line rects by locating the selected
+      // substring inside the anchor element's text nodes and building a Range.
+      // Lets the shell refresh highlight overlays after text reflow (window
+      // resize, container size change) — translation alone misaligns when the
+      // line breaks shift.
+      var teEl = getEl(payload.eid);
+      if (!teEl || !teEl.isConnected) { respond(id, null); return; }
+      var needle = String(payload.text || '');
+      if (!needle) { respond(id, null); return; }
+      var nodes = [];
+      var concat = '';
+      try {
+        var walker = document.createTreeWalker(teEl, NodeFilter.SHOW_TEXT, null);
+        var tn;
+        while ((tn = walker.nextNode())) {
+          var tv = tn.nodeValue || '';
+          if (!tv) continue;
+          nodes.push({ node: tn, start: concat.length, end: concat.length + tv.length });
+          concat += tv;
+        }
+      } catch (_e) { respond(id, null); return; }
+      if (nodes.length === 0) { respond(id, null); return; }
+      var startIdx = concat.indexOf(needle);
+      if (startIdx < 0) {
+        // Whitespace-normalized fallback: collapsing runs of whitespace lets
+        // us match selections whose newlines/tabs the iframe normalized away.
+        var normNeedle = needle.replace(/\\s+/g, ' ').trim();
+        if (normNeedle) {
+          // Build a parallel index map: position in collapsed -> position in original.
+          var mapToOrig = [];
+          var collapsed = '';
+          var inWs = false;
+          for (var pi = 0; pi < concat.length; pi++) {
+            var ch = concat.charCodeAt(pi);
+            var isWs = ch === 32 || ch === 9 || ch === 10 || ch === 13;
+            if (isWs) {
+              if (!inWs) { mapToOrig.push(pi); collapsed += ' '; inWs = true; }
+            } else { mapToOrig.push(pi); collapsed += concat.charAt(pi); inWs = false; }
+          }
+          mapToOrig.push(concat.length);
+          var collIdx = collapsed.indexOf(normNeedle);
+          if (collIdx >= 0) {
+            startIdx = mapToOrig[collIdx] != null ? mapToOrig[collIdx] : -1;
+            if (startIdx >= 0) {
+              var collEnd = collIdx + normNeedle.length;
+              var origEnd = mapToOrig[collEnd] != null ? mapToOrig[collEnd] : concat.length;
+              needle = concat.substring(startIdx, origEnd);
+            }
+          }
+        }
+      }
+      if (startIdx < 0) { respond(id, null); return; }
+      var endIdx = startIdx + needle.length;
+      function pickNode(idx) {
+        for (var ni = 0; ni < nodes.length; ni++) {
+          if (idx >= nodes[ni].start && idx <= nodes[ni].end) {
+            return { node: nodes[ni].node, offset: idx - nodes[ni].start };
+          }
+        }
+        return null;
+      }
+      var startPos = pickNode(startIdx);
+      var endPos = pickNode(endIdx);
+      if (!startPos || !endPos) { respond(id, null); return; }
+      var range;
+      try {
+        range = document.createRange();
+        range.setStart(startPos.node, startPos.offset);
+        range.setEnd(endPos.node, endPos.offset);
+      } catch (_e) { respond(id, null); return; }
+      var crs = range.getClientRects();
+      var out = [];
+      for (var ki = 0; ki < crs.length; ki++) {
+        var cr = crs[ki];
+        if (cr.width > 0 && cr.height > 0) out.push({ x: cr.x, y: cr.y, width: cr.width, height: cr.height });
+      }
+      respond(id, { rects: out });
+      return;
+    }
+
     if (type === 'list:rendered-files') {
       // Distinct (file, mfe) pairs from the live iframe DOM. We used to emit
       // just file strings, but host-aggregated catalogs hold workspace-
@@ -926,6 +1053,369 @@ export function bridgeMessages(): string {
       return;
     }
 
+    if (type === 'wireframe:capture') {
+      // Rasterize the current route into per-block images for the snapshot
+      // wireframe canvas. Sequential captures (html2canvas costs 100-500ms per
+      // block) with progress pushes; one full-document pass at the end is the
+      // honest "before" the apply composite needs. Rects are document CSS px:
+      // we capture at scroll (0,0) so viewport rects equal document rects and
+      // fixed/sticky elements can't mis-crop.
+      var wfScale = Math.min(window.devicePixelRatio || 1, 2);
+      if (payload && typeof payload.scale === 'number' && payload.scale > 0) wfScale = Math.min(payload.scale, 3);
+      var wfSavedX = window.scrollX || 0;
+      var wfSavedY = window.scrollY || 0;
+
+      function wfQualifies(el) {
+        if (!el || el.nodeType !== 1) return false;
+        var t = el.tagName;
+        if (t === 'SCRIPT' || t === 'STYLE' || t === 'LINK' || t === 'TEMPLATE' || t === 'NOSCRIPT') return false;
+        if (el.hasAttribute('data-annotask-instance') || el.hasAttribute('data-annotask-preview')) return false;
+        var cs = window.getComputedStyle(el);
+        if (cs.display === 'none' || cs.visibility === 'hidden') return false;
+        var r = el.getBoundingClientRect();
+        return r.width > 0 && r.height > 0;
+      }
+
+      function wfChildren(el) {
+        var out = [];
+        for (var i = 0; i < el.children.length; i++) {
+          if (wfQualifies(el.children[i])) out.push(el.children[i]);
+        }
+        return out;
+      }
+
+      function wfHeight(el) { return el.getBoundingClientRect().height; }
+
+      // Content root: start at the semantic main when present, then unwrap
+      // single-child wrappers while the lone child covers most of its parent's
+      // HEIGHT. Height, not area: a centered max-width page column at a wide
+      // viewport is exactly the wrapper that must unwrap, and its horizontal
+      // margins would fail an area test. The unwrap applies to main too — a
+      // router outlet usually renders ONE page wrapper inside it, and the
+      // page's sections are what the user wants as blocks.
+      function wfContentRoot(root) {
+        var main = root.querySelector('main, [role="main"]');
+        var cur = (main && wfQualifies(main)) ? main : root;
+        for (var depth = 0; depth < 6; depth++) {
+          var kids = wfChildren(cur);
+          if (kids.length === 1 && wfHeight(cur) > 0 && wfHeight(kids[0]) >= wfHeight(cur) * 0.8) { cur = kids[0]; continue; }
+          break;
+        }
+        return cur;
+      }
+
+      function wfFinishError(message) {
+        window.scrollTo(wfSavedX, wfSavedY);
+        respond(id, { error: message });
+      }
+
+      window.scrollTo(0, 0);
+
+      var wfRoot = payload && payload.rootEid ? getEl(payload.rootEid) : document.body;
+      if (!wfRoot) { wfFinishError('root element not found'); return; }
+      var wfContent = wfContentRoot(wfRoot);
+
+      // Chrome pass: page furniture outside the content root, outermost only.
+      var wfChrome = [];
+      var wfChromeCandidates = wfRoot.querySelectorAll('header, nav, footer, aside');
+      for (var wci = 0; wci < wfChromeCandidates.length; wci++) {
+        var wcEl = wfChromeCandidates[wci];
+        if (!wfQualifies(wcEl)) continue;
+        if (wfContent !== wfRoot && wfContent.contains(wcEl) && wfContent !== wcEl) continue;
+        var wcContained = false;
+        for (var wcj = 0; wcj < wfChrome.length; wcj++) {
+          if (wfChrome[wcj].contains(wcEl)) { wcContained = true; break; }
+        }
+        if (!wcContained) wfChrome.push(wcEl);
+      }
+
+      // Content pass: direct qualifying children of the content root with a
+      // minimum footprint; when a level has only one (undersized) child,
+      // descend and retry so thin wrappers don't yield a single page block.
+      var wfContentKids = [];
+      var wfCursor = wfContent;
+      for (var wfDepth = 0; wfDepth < 5; wfDepth++) {
+        var wfRaw = wfChildren(wfCursor);
+        wfContentKids = [];
+        for (var wki = 0; wki < wfRaw.length; wki++) {
+          var wkr = wfRaw[wki].getBoundingClientRect();
+          if (wkr.width >= 48 && wkr.height >= 24) wfContentKids.push(wfRaw[wki]);
+        }
+        if (wfContentKids.length === 0 && wfRaw.length === 1) { wfCursor = wfRaw[0]; continue; }
+        break;
+      }
+      if (wfContentKids.length === 0) {
+        // Fall back to one block = the content root itself (still anchored).
+        if (wfQualifies(wfCursor)) wfContentKids = [wfCursor];
+        else if (wfChrome.length === 0) { wfFinishError('nothing to capture'); return; }
+      }
+
+      // Straggler pass: content OUTSIDE the content root that isn't semantic
+      // chrome — a floating button, banner, or toast mounted as a sibling of
+      // <main> would otherwise appear in the honest full-page "before" but
+      // get no block on the canvas. Walk the root→content-root path; at each
+      // level, every qualifying sibling with a real footprint becomes a
+      // block, unless the chrome pass already covers it.
+      var wfStragglers = [];
+      (function() {
+        var wfPath = [];
+        var wfNode = wfContent;
+        while (wfNode && wfNode !== wfRoot) { wfPath.push(wfNode); wfNode = wfNode.parentElement; }
+        if (wfNode !== wfRoot) return; // content root detached from the capture root
+        wfPath.push(wfRoot);
+        for (var wpi = wfPath.length - 1; wpi >= 1; wpi--) {
+          var wpParent = wfPath[wpi];
+          var wpPathChild = wfPath[wpi - 1];
+          var wpKids = wfChildren(wpParent);
+          for (var wpk = 0; wpk < wpKids.length; wpk++) {
+            var wpKid = wpKids[wpk];
+            if (wpKid === wpPathChild) continue;
+            var wpr = wpKid.getBoundingClientRect();
+            if (wpr.width < 48 || wpr.height < 24) continue;
+            var wpCovered = false;
+            for (var wpc = 0; wpc < wfChrome.length && !wpCovered; wpc++) {
+              // Contains-a-chrome-block counts as covered too: blocking the
+              // wrapper would double-capture the header inside it.
+              if (wfChrome[wpc] === wpKid || wfChrome[wpc].contains(wpKid) || wpKid.contains(wfChrome[wpc])) wpCovered = true;
+            }
+            if (!wpCovered) wfStragglers.push(wpKid);
+          }
+        }
+      })();
+
+      var wfAll = [];
+      for (var wai = 0; wai < wfChrome.length; wai++) wfAll.push(wfChrome[wai]);
+      for (var waj = 0; waj < wfContentKids.length; waj++) {
+        if (wfAll.indexOf(wfContentKids[waj]) === -1) wfAll.push(wfContentKids[waj]);
+      }
+      for (var wak = 0; wak < wfStragglers.length; wak++) {
+        if (wfAll.indexOf(wfStragglers[wak]) === -1) wfAll.push(wfStragglers[wak]);
+      }
+      wfAll.sort(function(a, b) {
+        var pos = a.compareDocumentPosition(b);
+        if (pos & 4) return -1; // a precedes b
+        if (pos & 2) return 1;
+        return 0;
+      });
+      var wfTruncated = false;
+      if (wfAll.length > 24) { wfAll = wfAll.slice(0, 24); wfTruncated = true; }
+
+      var wfMetas = [];
+      for (var wmi = 0; wmi < wfAll.length; wmi++) {
+        var wmEl = wfAll[wmi];
+        var wmSrc = findSourceElement(wmEl);
+        var wmData = getSourceData(wmSrc.sourceEl);
+        var wmRect = wmEl.getBoundingClientRect();
+        var wmTag = wmEl.tagName.toLowerCase();
+        wfMetas.push({
+          eid: getEid(wmEl),
+          file: wmData.file, line: wmData.line, component: wmData.component,
+          source_tag: wmData.source_tag, tag: wmTag,
+          // First class name — the human-distinct identity for direction
+          // labels ('toolbar', 'layout'); component names repeat per page.
+          cls: (wmEl.classList && wmEl.classList[0]) || '',
+          role: (wmTag === 'header' || wmTag === 'nav' || wmTag === 'footer' || wmTag === 'aside') ? wmTag : 'content',
+          rect: { x: wmRect.x + (window.scrollX || 0), y: wmRect.y + (window.scrollY || 0), width: wmRect.width, height: wmRect.height },
+          dataUrl: null
+        });
+      }
+
+      function wfRun(h2c) {
+        var wfIdx = 0;
+        function wfCaptureNext() {
+          if (wfIdx >= wfMetas.length) { wfCaptureFull(); return; }
+          var meta = wfMetas[wfIdx];
+          sendToShell('wireframe:capture-progress', { index: wfIdx, total: wfMetas.length + 1, label: meta.component || meta.source_tag || meta.tag });
+          var capH = Math.min(meta.rect.height, 4000);
+          h2c(document.body, { useCORS: true, allowTaint: true, logging: false, scale: wfScale, x: meta.rect.x, y: meta.rect.y, width: meta.rect.width, height: capH })
+            .then(function(canvas) {
+              meta.dataUrl = canvas.toDataURL('image/png');
+              if (capH < meta.rect.height) meta.clipped = true;
+              wfIdx++; wfCaptureNext();
+            })
+            .catch(function(err) {
+              meta.dataUrl = null;
+              meta.error = (err && err.message) || 'capture failed';
+              wfIdx++; wfCaptureNext();
+            });
+        }
+        function wfCaptureFull() {
+          // Explode captures (rootEid) refine an existing canvas — the
+          // original full-page "before" stays the honest baseline. Instead,
+          // capture the root's SHELL: its own pixels (background, padding,
+          // the surface between children) with the captured child blocks
+          // visibility-hidden in the clone — the container's styling without
+          // ghost children burned in.
+          if (payload && payload.rootEid) {
+            var shellRoot = getEl(payload.rootEid);
+            if (!shellRoot) { wfFinish(null, null); return; }
+            sendToShell('wireframe:capture-progress', { index: wfMetas.length, total: wfMetas.length + 1, label: 'container shell' });
+            for (var smi = 0; smi < wfAll.length; smi++) wfAll[smi].setAttribute('data-annotask-wf-hide', '1');
+            var shellCleanup = function() {
+              for (var sci = 0; sci < wfAll.length; sci++) wfAll[sci].removeAttribute('data-annotask-wf-hide');
+            };
+            var shellRect = shellRoot.getBoundingClientRect();
+            h2c(document.body, {
+              useCORS: true, allowTaint: true, logging: false, scale: wfScale,
+              x: shellRect.x + (window.scrollX || 0), y: shellRect.y + (window.scrollY || 0),
+              width: shellRect.width, height: Math.min(shellRect.height, 4000),
+              onclone: function(docClone) {
+                var hidden = docClone.querySelectorAll('[data-annotask-wf-hide]');
+                for (var shi = 0; shi < hidden.length; shi++) hidden[shi].style.visibility = 'hidden';
+              }
+            }).then(function(canvas) { shellCleanup(); wfFinish(null, canvas.toDataURL('image/png')); })
+              .catch(function() { shellCleanup(); wfFinish(null, null); });
+            return;
+          }
+          sendToShell('wireframe:capture-progress', { index: wfMetas.length, total: wfMetas.length + 1, label: 'full page' });
+          // Scale 1: the full page only feeds the before/after composite, and
+          // a retina full-document PNG would blow the 4MB upload cap.
+          h2c(document.body, { useCORS: true, allowTaint: true, logging: false, scale: 1 })
+            .then(function(canvas) { wfFinish(canvas.toDataURL('image/png'), null); })
+            .catch(function() { wfFinish(null, null); });
+        }
+        function wfFinish(fullDataUrl, shellDataUrl) {
+          window.scrollTo(wfSavedX, wfSavedY);
+          var result = {
+            viewport: {
+              width: window.innerWidth, height: window.innerHeight,
+              docWidth: document.documentElement.scrollWidth,
+              docHeight: document.documentElement.scrollHeight,
+              scale: wfScale
+            },
+            blocks: wfMetas
+          };
+          if (wfTruncated) result.truncated = true;
+          if (fullDataUrl) result.fullDataUrl = fullDataUrl;
+          if (shellDataUrl) result.shellDataUrl = shellDataUrl;
+          respond(id, result);
+        }
+        wfCaptureNext();
+      }
+
+      function wfResolveH2c() {
+        var h2c = window.html2canvas;
+        if (h2c && typeof h2c !== 'function' && typeof h2c.default === 'function') h2c = h2c.default;
+        return (typeof h2c === 'function') ? h2c : null;
+      }
+
+      if (wfResolveH2c()) {
+        wfRun(wfResolveH2c());
+      } else {
+        var wfScript = document.createElement('script');
+        wfScript.src = '/__annotask/vendor/html2canvas.min.js';
+        var wfSavedDefine;
+        if (typeof window.define === 'function' && window.define.amd) {
+          wfSavedDefine = window.define;
+          window.define = undefined;
+        }
+        wfScript.onload = function() {
+          if (wfSavedDefine !== undefined) window.define = wfSavedDefine;
+          var h2c = wfResolveH2c();
+          if (h2c) wfRun(h2c);
+          else wfFinishError('html2canvas not loaded');
+        };
+        wfScript.onerror = function() {
+          if (wfSavedDefine !== undefined) window.define = wfSavedDefine;
+          wfFinishError('failed to load html2canvas — check that /__annotask/ routes are accessible from the app origin');
+        };
+        document.head.appendChild(wfScript);
+      }
+      return;
+    }
+
+    if (type === 'preview:component') {
+      // Render a real component instance OFFSCREEN in the iframe (so it gets
+      // the app's true styles + provider context), snapshot it with
+      // html2canvas, then tear it down. Returns the honest fidelity so the
+      // shell can show a thumbnail or an explicit placeholder. Load the
+      // component on demand first if it isn't on the current route.
+      ensureComponentLoaded(payload.componentName, payload.module).then(function() {
+      // Snapshot on the app's REAL surface, not a hardcoded white card — a
+      // dropped component should look like it belongs on the page behind it.
+      var pvSurface = resolveAppSurface();
+      var pvContainer = document.createElement('div');
+      pvContainer.setAttribute('data-annotask-preview', 'true');
+      pvContainer.style.cssText = 'position:fixed;left:-99999px;top:0;z-index:-1;width:' + (payload.width || 320) + 'px;padding:12px;background:' + pvSurface.background + ';color:' + pvSurface.color + ';box-sizing:border-box;';
+      document.body.appendChild(pvContainer);
+      // Repeat a list/loop binding into N stacked instances so the sketch shows
+      // the real v-for. Each instance mounts into its own point with optional
+      // per-row props; unmounts are composited (a single mount overwrites the
+      // container's __annotask_unmount, so N copies would leak without this).
+      var pvRepeat = Math.max(1, Math.min(payload.repeat || 1, 24));
+      var pvInstanceProps = payload.instanceProps || null;
+      var pvUnmounts = [];
+      var pvFirstPoint = pvContainer;
+      var pvRes = { mounted: false, reason: null, fidelity: undefined, detail: null };
+      var pvWrap = pvContainer;
+      if (pvRepeat > 1) {
+        pvWrap = document.createElement('div');
+        pvWrap.style.cssText = 'display:flex;flex-direction:column;gap:8px;';
+        pvContainer.appendChild(pvWrap);
+      }
+      for (var pvI = 0; pvI < pvRepeat; pvI++) {
+        var pvPoint = pvRepeat > 1 ? document.createElement('div') : pvContainer;
+        if (pvRepeat > 1) pvWrap.appendChild(pvPoint);
+        if (pvI === 0) pvFirstPoint = pvPoint;
+        var pvProps = payload.props || {};
+        var pvOverlay = pvInstanceProps ? (pvInstanceProps[pvI] || pvInstanceProps[0]) : null;
+        if (pvOverlay) {
+          var pvMerged = {};
+          for (var pvK1 in pvProps) { if (Object.prototype.hasOwnProperty.call(pvProps, pvK1)) pvMerged[pvK1] = pvProps[pvK1]; }
+          for (var pvK2 in pvOverlay) { if (Object.prototype.hasOwnProperty.call(pvOverlay, pvK2)) pvMerged[pvK2] = pvOverlay[pvK2]; }
+          pvProps = pvMerged;
+        }
+        var pvOne = tryMountComponent(pvPoint, payload.componentName, pvProps);
+        if (pvI === 0) pvRes = pvOne; // first instance decides reported status/fidelity
+        if (pvOne.mounted && pvPoint.__annotask_unmount) pvUnmounts.push(pvPoint.__annotask_unmount);
+      }
+      function pvCleanup() {
+        for (var pvU = pvUnmounts.length - 1; pvU >= 0; pvU--) { try { pvUnmounts[pvU](); } catch(e) {} }
+        try { pvContainer.remove(); } catch(e) {}
+      }
+      if (!pvRes.mounted) {
+        pvCleanup();
+        respond(id, { mounted: false, reason: pvRes.reason || null, fidelity: pvRes.fidelity, detail: pvRes.detail || null });
+        return;
+      }
+      function pvSnapshot() {
+        var h2c = window.html2canvas;
+        if (h2c && typeof h2c !== 'function' && typeof h2c.default === 'function') h2c = h2c.default;
+        if (typeof h2c !== 'function') { pvCleanup(); respond(id, { mounted: true, fidelity: pvRes.fidelity, error: 'html2canvas not loaded' }); return; }
+        // Retina-sharp: render at devicePixelRatio (capped 2x) like the page
+        // capture. The PNG is hi-res but the block keeps its CSS size, so report
+        // the unscaled (CSS) dimensions — else the block would land 2x too big.
+        var pvScale = Math.min(window.devicePixelRatio || 1, 2);
+        h2c(pvContainer, { useCORS: true, logging: false, allowTaint: true, scale: pvScale, backgroundColor: pvSurface.background, width: pvContainer.offsetWidth, height: pvContainer.offsetHeight }).then(function(canvas) {
+          var dataUrl = canvas.toDataURL('image/png');
+          pvCleanup();
+          respond(id, { mounted: true, fidelity: pvRes.fidelity, dataUrl: dataUrl, width: Math.round(canvas.width / pvScale), height: Math.round(canvas.height / pvScale) });
+        }).catch(function(err) {
+          pvCleanup();
+          respond(id, { mounted: true, fidelity: pvRes.fidelity, error: (err && err.message) || 'snapshot failed' });
+        });
+      }
+      function pvAfterFrames() {
+        // Two frames so async React/Svelte/Solid renders settle before snapshot.
+        requestAnimationFrame(function() { requestAnimationFrame(function() {
+          if (isEmptyMount(pvFirstPoint)) { pvCleanup(); respond(id, { mounted: false, reason: 'rendered-empty', fidelity: 'placeholder' }); return; }
+          pvSnapshot();
+        }); });
+      }
+      if (window.html2canvas) { pvAfterFrames(); }
+      else {
+        var pvScript = document.createElement('script');
+        pvScript.src = '/__annotask/vendor/html2canvas.min.js';
+        var savedDefinePv;
+        if (typeof window.define === 'function' && window.define.amd) { savedDefinePv = window.define; window.define = undefined; }
+        pvScript.onload = function() { if (savedDefinePv !== undefined) window.define = savedDefinePv; pvAfterFrames(); };
+        pvScript.onerror = function() { if (savedDefinePv !== undefined) window.define = savedDefinePv; pvCleanup(); respond(id, { mounted: true, fidelity: pvRes.fidelity, error: 'failed to load html2canvas' }); };
+        document.head.appendChild(pvScript);
+      }
+      });
+      return;
+    }
+
     if (type === 'layout:scan') {
       var layoutResults = [];
       var allEls = document.querySelectorAll('*');
@@ -1050,6 +1540,7 @@ export function bridgeMessages(): string {
       var ipTarget = getEl(payload.targetEid);
       if (!ipTarget) { respond(id, { placeholderEid: '' }); return; }
       var ipEl = createPlaceholder(payload);
+      if (payload.instanceId) ipEl.setAttribute('data-annotask-instance', payload.instanceId);
       var ipRef = ipTarget;
       switch (payload.position) {
         case 'before': ipRef.parentElement && ipRef.parentElement.insertBefore(ipEl, ipRef); break;
@@ -1082,34 +1573,62 @@ export function bridgeMessages(): string {
       return;
     }
 
-    if (type === 'move:element') {
-      var meEl = getEl(payload.eid);
-      var meTarget = getEl(payload.targetEid);
-      if (meEl && meTarget) {
-        switch (payload.position) {
-          case 'before': meTarget.parentElement && meTarget.parentElement.insertBefore(meEl, meTarget); break;
-          case 'after': meTarget.parentElement && meTarget.parentElement.insertBefore(meEl, meTarget.nextSibling); break;
-          case 'append': meTarget.appendChild(meEl); break;
-          case 'prepend': meTarget.insertBefore(meEl, meTarget.firstChild); break;
-        }
-      }
-      respond(id, {});
-      return;
-    }
-
     if (type === 'insert:vue-component' || type === 'insert:component') {
       var vcTarget = getEl(payload.targetEid);
-      if (!vcTarget) { respond(id, { eid: '', mounted: false }); return; }
+      if (!vcTarget) { respond(id, { eid: '', mounted: false, reason: 'no-runtime', fidelity: 'placeholder' }); return; }
+      // Load the component on demand first if it isn't on the current route.
+      ensureComponentLoaded(payload.componentName, payload.module).then(function() {
       var vcContainer = document.createElement('div');
       vcContainer.setAttribute('data-annotask-placeholder', 'true');
+      // Tag the container with its wireframe instance id — placement identity
+      // for click/selection, drop-target refusal, capture exclusion, and
+      // reapply's DOM-idempotency probe.
+      if (payload.instanceId) vcContainer.setAttribute('data-annotask-instance', payload.instanceId);
+      // Placement identity: the click handler reads this for the selection's
+      // component field (placements select as placements, not their internals).
+      vcContainer.setAttribute('data-annotask-component-name', payload.componentName);
       switch (payload.position) {
         case 'before': vcTarget.parentElement && vcTarget.parentElement.insertBefore(vcContainer, vcTarget); break;
         case 'after': vcTarget.parentElement && vcTarget.parentElement.insertBefore(vcContainer, vcTarget.nextSibling); break;
         case 'append': vcTarget.appendChild(vcContainer); break;
         case 'prepend': vcTarget.insertBefore(vcContainer, vcTarget.firstChild); break;
       }
-      var mounted = tryMountComponent(vcContainer, payload.componentName, payload.props);
-      respond(id, { eid: getEid(vcContainer), mounted: mounted });
+      // Layout affordances so a live mount isn't collapsed to zero width in a
+      // flex/grid row (mirrors insert:placeholder). box-sizing keeps padding sane.
+      vcContainer.style.boxSizing = 'border-box';
+      var vcParent = (payload.position === 'append' || payload.position === 'prepend') ? vcTarget : vcTarget.parentElement;
+      if (vcParent) {
+        var vcCs = window.getComputedStyle(vcParent);
+        if ((vcCs.display.indexOf('flex') >= 0 || vcCs.display.indexOf('grid') >= 0) && !vcContainer.style.width) {
+          var vcRow = vcCs.flexDirection === 'row' || vcCs.flexDirection === 'row-reverse' || vcCs.display.indexOf('grid') >= 0;
+          if (vcRow) vcContainer.style.flex = '1';
+        }
+      }
+      var vcRes = tryMountComponent(vcContainer, payload.componentName, payload.props);
+      // Honest fidelity: stamp the container and render a VISIBLY different state
+      // per outcome so a failed mount is never a silent empty div.
+      vcContainer.setAttribute('data-annotask-fidelity', vcRes.fidelity);
+      if (vcRes.reason) vcContainer.setAttribute('data-annotask-mount-reason', vcRes.reason);
+      if (!vcRes.mounted) {
+        renderUnmountedBadge(vcContainer, payload.componentName, vcRes.reason);
+      } else {
+        renderFidelityPill(vcContainer, vcRes.fidelity);
+      }
+      // Settle two frames so async React/Svelte/Solid renders finish and their
+      // scheduleEmptyCheck has run (it may flip fidelity → placeholder + badge).
+      // Then respond with the SETTLED truth read off the container, not the
+      // optimistic pre-settle result — so the drop reports what the preview
+      // snapshot would. Vue mounts synchronously, so this is just a short delay.
+      requestAnimationFrame(function() { requestAnimationFrame(function() {
+        var settledFidelity = vcContainer.getAttribute('data-annotask-fidelity') || vcRes.fidelity;
+        var settledMounted = vcContainer.hasAttribute('data-annotask-mounted');
+        var settledReason = vcContainer.getAttribute('data-annotask-mount-reason') || vcRes.reason || null;
+        // A live mount that measured zero height would be invisible — floor it
+        // so the user actually sees the (real) render.
+        if (settledMounted && vcContainer.offsetHeight === 0) vcContainer.style.minHeight = '24px';
+        respond(id, { eid: getEid(vcContainer), mounted: settledMounted, reason: settledReason, fidelity: settledFidelity });
+      }); });
+      });
       return;
     }
 
diff --git a/src/plugin/bridge/registry.ts b/src/plugin/bridge/registry.ts
index fdf5ebe..8dff8c6 100644
--- a/src/plugin/bridge/registry.ts
+++ b/src/plugin/bridge/registry.ts
@@ -23,11 +23,58 @@ export function bridgeRegistry(): string {
   }
 
   // ── PostMessage Helpers ───────────────────────────────
-  var shellOrigin = '*'; // Will be tightened on first shell message
+  // shellOrigin stays null until the first validated shell message locks it
+  // to that exact origin (see the message handler in messages.ts). It is
+  // never '*' — posting app data to a wildcard origin would let any page
+  // that iframes the dev app read pushes (console error stacks, network
+  // call URLs, hover/click context).
+  var shellOrigin = null;
+
+  // Bounded pre-lock queue: meaningful pushes that fire before the shell has
+  // announced itself (initial network:page-load, early console errors) wait
+  // here and flush to the locked origin. High-frequency transient events are
+  // dropped instead — replaying stale hover state after lock would only
+  // confuse the shell, and queueing them would evict the meaningful entries.
+  var PRE_LOCK_QUEUE_MAX = 50;
+  var preLockQueue = [];
+  var PRE_LOCK_TRANSIENT = { 'hover:enter': true, 'hover:leave': true, 'data:hover': true };
+
+  // Mirrors the server's isLocalHostname (src/server/origin.ts). Implemented
+  // here because the bridge is standalone vanilla JS injected into the app
+  // page — it cannot import server modules. Port-agnostic on purpose: the
+  // webpack standalone topology serves the shell from a different localhost
+  // port than the app, so a same-origin check would break it.
+  function isLocalBridgeOrigin(origin) {
+    if (!origin) return false;
+    var host = '';
+    try { host = new URL(origin).hostname; } catch (e) { return false; }
+    return host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1';
+  }
+
+  function lockShellOrigin(origin) {
+    shellOrigin = origin;
+    var queued = preLockQueue.splice(0, preLockQueue.length);
+    for (var qi = 0; qi < queued.length; qi++) {
+      try { window.parent.postMessage(queued[qi], shellOrigin); } catch (e) {}
+    }
+  }
 
   function sendToShell(type, payload, id) {
     var msg = { type: type, payload: payload || {}, source: 'annotask-client' };
     if (id) msg.id = id;
+    if (shellOrigin === null) {
+      // bridge:ready is the one wildcard exception: it carries no app data
+      // and the shell needs it to bootstrap before it has ever messaged us
+      // (in the cross-origin webpack standalone topology the shell cannot
+      // poll the iframe's globals to detect readiness).
+      if (type === 'bridge:ready') {
+        window.parent.postMessage(msg, '*');
+        return;
+      }
+      if (PRE_LOCK_TRANSIENT[type]) return;
+      if (preLockQueue.length < PRE_LOCK_QUEUE_MAX) preLockQueue.push(msg);
+      return;
+    }
     window.parent.postMessage(msg, shellOrigin);
   }
 
diff --git a/src/plugin/index.ts b/src/plugin/index.ts
index 333716f..74d7eed 100644
--- a/src/plugin/index.ts
+++ b/src/plugin/index.ts
@@ -1,6 +1,8 @@
 import type { Plugin, ViteDevServer } from 'vite'
 import fs from 'node:fs'
-import { transformFile, transformHTML } from './transform.js'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import { transformFile, transformHTML, injectComponentRegistry } from './transform.js'
 import { bridgeClientScript } from './bridge-client.js'
 import { createAnnotaskServer } from '../server/index.js'
 import { writeServerInfo, writeMfeServerInfo } from '../server/discovery.js'
@@ -70,8 +72,13 @@ export function annotask(options: AnnotaskOptions = {}): Plugin[] {
       if (!fs.existsSync(id)) return null
 
       const raw = fs.readFileSync(id, 'utf-8')
-      const annotated = transformFile(raw, id, projectRoot, mfe)
-      return annotated ?? raw
+      const annotated = transformFile(raw, id, projectRoot, mfe) ?? raw
+      // Keystone: register this file's imported components into
+      // window.__ANNOTASK_COMPONENTS__ so the bridge can live-mount real project
+      // components (Vue/React/local + library) when a wireframe/insert drops one.
+      // The Vite plugin previously injected the framework runtimes but never the
+      // component map — so only globally-registered Vue components could mount.
+      return injectComponentRegistry(annotated, id)
     },
 
     transform(code, id) {
@@ -119,10 +126,45 @@ export function annotask(options: AnnotaskOptions = {}): Plugin[] {
     apply: 'serve',
 
     configureServer(server: ViteDevServer) {
+      // Hosts beyond localhost / IP literals that may reach /__annotask/*
+      // (the API middleware's DNS-rebinding gate). Seeded from Vite's own
+      // `server.allowedHosts` and the host the server actually announces, so
+      // Annotask is never stricter than the app it's embedded in. Mutable
+      // array + getter because the bind address is only known on 'listening'.
+      const extraAllowedHosts: string[] = []
+      const viteAllowed = server.config.server.allowedHosts
+      if (viteAllowed === true) extraAllowedHosts.push('*')
+      else if (Array.isArray(viteAllowed)) extraAllowedHosts.push(...viteAllowed)
+      const cfgHost = server.config.server.host
+      if (typeof cfgHost === 'string' && cfgHost.length > 0) extraAllowedHosts.push(cfgHost)
+
       const uiServer = createAnnotaskServer({
         projectRoot,
         apiSchemaUrls: options.apiSchemaUrls,
         apiSchemaFiles: options.apiSchemaFiles,
+        allowedHosts: () => extraAllowedHosts,
+      })
+
+      // Resolve a bare module specifier (e.g. "primevue/button") to the RAW
+      // source file as an /@fs/ URL so the iframe can dynamically import an
+      // off-route catalog component for preview/placement. We deliberately
+      // resolve the raw file (via Node, not Vite's optimizer) so importing it
+      // serves+transforms a single module whose sub-deps map to already-
+      // optimized chunks — avoiding a dep re-optimization full-page reload.
+      const requireFromRoot = createRequire(pathToFileURL(projectRoot + '/package.json').href)
+      server.middlewares.use((req, res, next) => {
+        if (!req.url || !req.url.startsWith('/__annotask/preview-module')) return next()
+        res.setHeader('Content-Type', 'application/json')
+        const spec = new URL(req.url, 'http://localhost').searchParams.get('spec')
+        if (!spec) { res.statusCode = 400; res.end('{"error":"missing spec"}'); return }
+        try {
+          const abs = requireFromRoot.resolve(spec).replace(/\\/g, '/')
+          const root = projectRoot.replace(/\\/g, '/')
+          const url = abs.startsWith(root + '/') ? abs.slice(root.length) : '/@fs/' + abs.replace(/^\//, '')
+          res.end(JSON.stringify({ url }))
+        } catch (e) {
+          res.statusCode = 404; res.end(JSON.stringify({ error: String((e as Error)?.message || e) }))
+        }
       })
 
       // Mount middleware on Vite's connect instance
@@ -141,6 +183,23 @@ export function annotask(options: AnnotaskOptions = {}): Plugin[] {
         const port = typeof addr === 'object' && addr ? addr.port : 5173
         const host = typeof addr === 'object' && addr ? addr.address : undefined
         writeServerInfo(projectRoot, port, host, mfe)
+        // The announced host must also pass the Host gate — skills/CLI built
+        // from server.json send it verbatim in their Host header.
+        if (host) extraAllowedHosts.push(host)
+        // Loud warning when bound beyond loopback (e.g. `vite --host`): the
+        // Annotask API is unauthenticated and can spawn agents that write source
+        // + run shell at the project root. On a non-loopback bind, anyone on the
+        // LAN can reach it. See SECURITY.md. (Loopback binds stay quiet.)
+        const loopback = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1', 'localhost'])
+        if (host && !loopback.has(host)) {
+          console.warn(
+            `[Annotask] ⚠ SECURITY: bound to ${host}:${port} (beyond localhost). ` +
+            `The Annotask dev API is UNAUTHENTICATED and can run your agent CLI ` +
+            `with file-write + shell access at the project root — anyone on this ` +
+            `network can reach it. Set ANNOTASK_MAX_PERMISSION=plan|default to cap ` +
+            `it, and prefer an SSH tunnel over --host. See SECURITY.md.`,
+          )
+        }
       })
 
       console.log('[Annotask] Design tool available at /__annotask/')
diff --git a/src/plugin/transform.ts b/src/plugin/transform.ts
index d95f368..0b6a351 100644
--- a/src/plugin/transform.ts
+++ b/src/plugin/transform.ts
@@ -71,6 +71,71 @@ export function parseImports(code: string): Map<string, string> {
   return out
 }
 
+// ── Component registry epilogue ─────────────────────────
+//
+// Populates `window.__ANNOTASK_COMPONENTS__` with a file's imported components
+// so the bridge's `tryMountComponent` can live-mount REAL project components
+// when a wireframe/insert drops one — the keystone that makes "real components
+// render on drop" true on Vite (the Vite plugin previously injected the
+// framework runtimes but never the component map, so only globally-registered
+// Vue components could mount).
+//
+// Supersedes the webpack loader's inline registration and fixes its blind
+// spots: it covers NAMED imports (`import { Button } from '@mantine/core'`),
+// ALIASED imports (registered under the EXPORT name so a lookup by the catalog
+// name resolves the local binding), and RELATIVE/local imports
+// (`./PlanetCard.vue`) — the loader only handled default, non-relative imports.
+//
+// PascalCase-only so hooks/utilities (`ref`, `useRoute`) don't pollute the
+// registry; each entry is `typeof`-guarded so a type-only binding that got
+// stripped at compile time never throws.
+const REG_NAMED_IMPORT_RE = /import\s+(?!type\b)(?:[A-Za-z0-9_$]+\s*,\s*)?\{([^}]+)\}\s*from\s*['"`][^'"`]+['"`]/g
+const REG_DEFAULT_IMPORT_RE = /import\s+([A-Z][A-Za-z0-9_$]*)\s*(?:,\s*\{[^}]*\})?\s*from\s*['"`][^'"`]+['"`]/g
+
+/** Collect `exportName → localBinding` for every PascalCase component import. */
+function collectComponentImports(code: string): Map<string, string> {
+  const out = new Map<string, string>()
+  let m: RegExpExecArray | null
+  REG_NAMED_IMPORT_RE.lastIndex = 0
+  while ((m = REG_NAMED_IMPORT_RE.exec(code)) !== null) {
+    for (const raw of m[1].split(',').map(s => s.trim()).filter(Boolean)) {
+      if (/^type\s/.test(raw)) continue
+      const parts = raw.split(/\s+as\s+/).map(s => s.trim())
+      const exportName = parts[0]
+      const binding = parts[parts.length - 1]
+      if (!/^[A-Z][A-Za-z0-9_$]*$/.test(exportName)) continue
+      if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(binding)) continue
+      if (!out.has(exportName)) out.set(exportName, binding)
+    }
+  }
+  REG_DEFAULT_IMPORT_RE.lastIndex = 0
+  while ((m = REG_DEFAULT_IMPORT_RE.exec(code)) !== null) {
+    const name = m[1]
+    if (!out.has(name)) out.set(name, name)
+  }
+  return out
+}
+
+/**
+ * Append the component-registry epilogue to an already-transformed source file.
+ * Injected before the last `</script>` for Vue/Svelte SFCs (so the bindings are
+ * in scope) and at module end for JSX/TSX. No-op when there's nothing to
+ * register. Idempotent and side-effect-light (one window-guarded IIFE).
+ */
+export function injectComponentRegistry(transformed: string, filePath: string): string {
+  const imports = collectComponentImports(transformed)
+  if (imports.size === 0) return transformed
+  const body = [...imports.entries()]
+    .map(([name, binding]) => `if(typeof ${binding}!=='undefined')__uf_r[${JSON.stringify(name)}]=${binding};`)
+    .join('')
+  const epilogue = `\n;(function(){if(typeof window==='undefined')return;var __uf_r=window.__ANNOTASK_COMPONENTS__=window.__ANNOTASK_COMPONENTS__||{};${body}})();\n`
+  if ((filePath.endsWith('.vue') || filePath.endsWith('.svelte')) && transformed.includes('</script>')) {
+    const idx = transformed.lastIndexOf('</script>')
+    return transformed.slice(0, idx) + epilogue + transformed.slice(idx)
+  }
+  return transformed + epilogue
+}
+
 // ── Vue SFC ─────────────────────────────────────────────
 
 /**
@@ -149,7 +214,11 @@ export function transformSvelte(
       relativeFile,
       componentName,
       regionStartLine,
-      { skipTags: SVELTE_SKIP_TAGS, mfe, imports }
+      // trackBraces: Svelte attribute expressions use bare `{expr}` — the
+      // `>` in `onclick={() => ...}` or `class={a > b}` must not terminate
+      // the tag early. Full jsxMode would be wrong here: its type-context
+      // heuristic treats `text<span>` as a generic and skips real markup.
+      { skipTags: SVELTE_SKIP_TAGS, trackBraces: true, mfe, imports }
     )
 
     if (injected) {
@@ -257,13 +326,19 @@ export function transformAstro(
   const relativeFile = relativePath(filePath, projectRoot)
   const componentName = extractComponentName(filePath)
 
-  // Find frontmatter block (--- ... ---)
+  // Find frontmatter block (--- ... ---). Astro frontmatter opens at the top
+  // of the file and both fences sit alone on their own lines — a bare
+  // indexOf('---') would mis-anchor on a `---` appearing later in markup
+  // content or inside a frontmatter string.
   const frontmatterRanges: Range[] = []
-  const fmStart = code.indexOf('---')
-  if (fmStart !== -1) {
-    const fmEnd = code.indexOf('---', fmStart + 3)
-    if (fmEnd !== -1) {
-      frontmatterRanges.push({ start: fmStart, end: fmEnd + 3 })
+  const fmOpen = code.match(/^\uFEFF?(?:[ \t]*\r?\n)*---\r?\n/)
+  if (fmOpen) {
+    const fmStart = fmOpen[0].indexOf('---')
+    const closeRe = /^---[ \t\r]*$/gm
+    closeRe.lastIndex = fmOpen[0].length
+    const fmClose = closeRe.exec(code)
+    if (fmClose) {
+      frontmatterRanges.push({ start: fmStart, end: fmClose.index + fmClose[0].length })
     }
   }
 
@@ -352,8 +427,16 @@ function extractIsBinding(tagSource: string): string | null {
 }
 
 interface InjectOptions {
-  /** Enable JSX mode: track {} brace depth, skip TS generics */
+  /** Enable JSX mode: track {} brace depth, skip TS generics, and treat
+   *  statement-scope strings/comments/regexes as opaque (JSX is interleaved
+   *  with JavaScript, so `const a = "<div>"` must not be instrumented) */
   jsxMode?: boolean
+  /** Track `{}` brace depth inside tags WITHOUT the other jsxMode behaviors.
+   *  Svelte markup needs this: attribute expressions like `onclick={() => ...}`
+   *  contain bare `>` that would otherwise end the tag early — but Svelte text
+   *  content sits directly against tags (`count is {n}<span>`), so jsxMode's
+   *  type-context heuristic would misread real markup as TS generics. */
+  trackBraces?: boolean
   /** Tags to skip (won't have attributes injected) */
   skipTags?: Set<string>
   /** MFE identity for multi-project setups */
@@ -365,6 +448,22 @@ interface InjectOptions {
   imports?: Map<string, string>
 }
 
+/**
+ * Scope frame for the jsxMode top-level scanner. The stack distinguishes the
+ * contexts where `<tag` is legal JSX (statement scope, `{...}` expressions,
+ * `${...}` interpolations) from the contexts where it is plain text or string
+ * content (JSX element children, raw template-literal text). String, comment,
+ * and regex literals are skipped inline within JS-like scopes and never land
+ * on the stack. An empty stack means JS statement scope.
+ */
+interface JsxScope {
+  /** jsx = element children, expr = `{...}` in children, template = raw
+   *  template-literal text, interp = `${...}` inside a template literal */
+  kind: 'jsx' | 'expr' | 'template' | 'interp'
+  /** Brace nesting for expr/interp — the scope pops when `}` arrives at depth 0 */
+  depth: number
+}
+
 /**
  * Walk through HTML/JSX markup and inject data-annotask-* attributes on
  * every element's opening tag.
@@ -381,6 +480,7 @@ export function injectAttributes(
 ): string | null {
   const skipTags = options?.skipTags ?? DEFAULT_SKIP_TAGS
   const jsxMode = options?.jsxMode ?? false
+  const trackBraces = jsxMode || (options?.trackBraces ?? false)
   const mfe = options?.mfe
   const imports = options?.imports
 
@@ -389,7 +489,106 @@ export function injectAttributes(
   let changed = false
   let i = 0
 
+  // jsxMode scope stack — see JsxScope. Stays empty for non-JSX callers.
+  const scopes: JsxScope[] = []
+
   while (i < template.length) {
+    if (jsxMode) {
+      const top = scopes.length > 0 ? scopes[scopes.length - 1] : undefined
+
+      if (top === undefined || top.kind === 'expr' || top.kind === 'interp') {
+        // JS statement/expression scope — strings, comments, and regex
+        // literals are opaque here. Without this, `const a = "<div>x</div>"`
+        // gets attributes injected INSIDE the string literal (a hard syntax
+        // error for double-quoted strings, since the injection itself uses
+        // double quotes; template literals were silently mutated).
+        const ch = template[i]
+        if (ch === '/' && template[i + 1] === '/') {
+          const nl = template.indexOf('\n', i + 2)
+          i = nl === -1 ? template.length : nl + 1
+          continue
+        }
+        if (ch === '/' && template[i + 1] === '*') {
+          const end = template.indexOf('*/', i + 2)
+          i = end === -1 ? template.length : end + 2
+          continue
+        }
+        if (ch === '"' || ch === "'") {
+          i = skipStringLiteral(template, i)
+          continue
+        }
+        if (ch === '`') {
+          scopes.push({ kind: 'template', depth: 0 })
+          i++
+          continue
+        }
+        if (ch === '/' && regexCanStart(template, i)) {
+          i = skipRegexLiteral(template, i)
+          continue
+        }
+        if (ch === '{') {
+          if (top) top.depth++
+          i++
+          continue
+        }
+        if (ch === '}') {
+          // Terminates the expr/interp scope at depth 0; a stray `}` at
+          // statement scope (function body close) is just skipped.
+          if (top) {
+            if (top.depth === 0) scopes.pop()
+            else top.depth--
+          }
+          i++
+          continue
+        }
+        if (ch === '<' && template[i + 1] === '>') {
+          // JSX fragment open — the tag scanner below only fires on
+          // `<` + letter, so fragments would otherwise go untracked and the
+          // matching `</>` would pop a real element's children scope.
+          scopes.push({ kind: 'jsx', depth: 0 })
+          i += 2
+          continue
+        }
+        // Fall through to the tag scanner — JSX is legal in this scope.
+      } else if (top.kind === 'template') {
+        // Raw template-literal text — tags here are string content, not JSX.
+        // Only `${` re-enters a JS scope where JSX is legal again (and must
+        // still be transformed — see transform-react tests for `${cond ? <span/> : null}`).
+        const ch = template[i]
+        if (ch === '\\') {
+          i += 2
+          continue
+        }
+        if (ch === '`') {
+          scopes.pop()
+          i++
+          continue
+        }
+        if (ch === '$' && template[i + 1] === '{') {
+          scopes.push({ kind: 'interp', depth: 0 })
+          i += 2
+          continue
+        }
+        i++
+        continue
+      } else {
+        // JSX element children — quotes, slashes, and backticks are plain
+        // text here (`<div>it's 1/2</div>`); only `{` opens an expression
+        // scope and `<>` a nested fragment.
+        if (template[i] === '{') {
+          scopes.push({ kind: 'expr', depth: 0 })
+          i++
+          continue
+        }
+        if (template[i] === '<' && template[i + 1] === '>') {
+          scopes.push({ kind: 'jsx', depth: 0 })
+          i += 2
+          continue
+        }
+        // Fall through to the comment/closing-tag/tag handling below.
+      }
+    }
+
     // Skip comments
     if (template.startsWith('<!--', i)) {
       const end = template.indexOf('-->', i + 4)
@@ -401,6 +600,11 @@ export function injectAttributes(
     if (template.startsWith('</', i)) {
       const end = template.indexOf('>', i + 2)
       i = end === -1 ? template.length : end + 1
+      // A closing tag (or `</>` fragment close) ends the current children
+      // scope. Guarded on kind so a stray closer never pops an expr/template.
+      if (jsxMode && scopes.length > 0 && scopes[scopes.length - 1].kind === 'jsx') {
+        scopes.pop()
+      }
       continue
     }
 
@@ -414,10 +618,16 @@ export function injectAttributes(
       while (i < template.length && /[a-zA-Z0-9\-:]/.test(template[i])) i++
       const tagName = template.slice(nameStart, i)
 
+      // Inside JSX element children, `<` + letter is ALWAYS a tag — type
+      // syntax is not legal there, and the isTypeContext heuristic would
+      // misread inline text before a tag (`1/2 <em>`) as a generic.
+      const inJsxChildren =
+        jsxMode && scopes.length > 0 && scopes[scopes.length - 1].kind === 'jsx'
+
       // In JSX mode, skip React fragments (empty tag name won't reach here,
       // but <> starts with < followed by > which isn't [a-zA-Z])
       // Skip known TypeScript generics
-      if (jsxMode && TS_GENERIC_NAMES.has(tagName)) {
+      if (jsxMode && !inJsxChildren && TS_GENERIC_NAMES.has(tagName)) {
         // This is a TS generic like Array<string>, not a JSX tag
         // Find the closing > accounting for nested generics
         i = skipGeneric(template, i)
@@ -426,24 +636,33 @@ export function injectAttributes(
 
       // In JSX mode, check if this looks like a type context
       // (preceded by : or as or extends or implements)
-      if (jsxMode && isTypeContext(template, tagStart)) {
+      if (jsxMode && !inJsxChildren && isTypeContext(template, tagStart)) {
         i = skipGeneric(template, i)
         continue
       }
 
+      // Scan past attributes to find the closing > or />
+      const tagEndIndex = findTagEnd(template, i, trackBraces)
+
+      const tagSource = template.slice(tagStart, tagEndIndex)
+
+      // Track element nesting for the jsxMode scope stack: a non-self-closing,
+      // non-void opening tag puts the scanner into JSX-children scope, where
+      // quotes/comments are plain text. Computed for skipped/instrumented tags
+      // too — otherwise `<script>...</script>` in JSX would desync the stack.
+      const opensChildren =
+        jsxMode && !tagSource.endsWith('/>') && !VOID_TAGS.has(tagName.toLowerCase())
+
       // Skip tags we don't want to instrument
       if (skipTags.has(tagName) || skipTags.has(tagName.toLowerCase())) {
-        i = findTagEnd(template, i, jsxMode)
+        if (opensChildren) scopes.push({ kind: 'jsx', depth: 0 })
+        i = tagEndIndex
         continue
       }
 
-      // Scan past attributes to find the closing > or />
-      const tagEndIndex = findTagEnd(template, i, jsxMode)
-
-      const tagSource = template.slice(tagStart, tagEndIndex)
-
       // Skip if already instrumented
       if (tagSource.includes('data-annotask-file')) {
+        if (opensChildren) scopes.push({ kind: 'jsx', depth: 0 })
         i = tagEndIndex
         continue
       }
@@ -480,6 +699,8 @@ export function injectAttributes(
       changed = true
       i = tagEndIndex
 
+      if (opensChildren) scopes.push({ kind: 'jsx', depth: 0 })
+
       continue
     }
 
@@ -494,15 +715,95 @@ export function injectAttributes(
 
 const DEFAULT_SKIP_TAGS = new Set(['script', 'style', 'template', 'slot'])
 
+/** Elements that never have children in HTML — opening one must NOT push a
+ *  JSX-children scope. Astro markup may write these HTML-style (`<br>`)
+ *  without a closing tag, which would otherwise desync the scope stack. */
+const VOID_TAGS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr',
+])
+
+/**
+ * Skip a `'...'` or `"..."` string literal starting at `i` (the opening
+ * quote). Returns the index just past the closing quote. Bails at a raw
+ * newline (plain strings can't span lines) so a stray quote in odd input
+ * never swallows the rest of the file.
+ */
+function skipStringLiteral(code: string, i: number): number {
+  const quote = code[i]
+  i++
+  while (i < code.length) {
+    const ch = code[i]
+    if (ch === '\\') i++
+    else if (ch === quote) return i + 1
+    else if (ch === '\n') return i
+    i++
+  }
+  return i
+}
+
+/** Keywords after which a `/` starts a regex literal, not division. */
+const REGEX_PRECEDING_KEYWORDS = new Set([
+  'return', 'typeof', 'instanceof', 'in', 'of', 'new', 'delete', 'void',
+  'throw', 'case', 'do', 'else', 'yield', 'await',
+])
+
+/**
+ * Heuristic: can the `/` at position `i` start a regex literal (vs. being a
+ * division operator)? Mirrors the standard JS lexer rule — a regex may only
+ * appear where an expression is expected: after an operator/opening
+ * punctuation or an expression keyword, never directly after an identifier,
+ * number literal, or closing `)`/`]`.
+ */
+function regexCanStart(code: string, i: number): boolean {
+  let j = i - 1
+  while (j >= 0 && /\s/.test(code[j])) j--
+  if (j < 0) return true
+  const ch = code[j]
+  if (/[a-zA-Z0-9_$]/.test(ch)) {
+    // Identifier or number before `/` means division — unless it's a keyword
+    // that expects an expression (`return /re/`, `typeof /re/`, ...).
+    const wordEnd = j + 1
+    while (j >= 0 && /[a-zA-Z0-9_$]/.test(code[j])) j--
+    return REGEX_PRECEDING_KEYWORDS.has(code.slice(j + 1, wordEnd))
+  }
+  return ch !== ')' && ch !== ']'
+}
+
+/**
+ * Skip a regex literal starting at `i` (the opening `/`). Returns the index
+ * just past the closing `/` (flags are plain identifier chars — the normal
+ * scanner walks them). Bails at a raw newline, since regex literals cannot
+ * span lines — that caps the damage to one character if the division-vs-regex
+ * heuristic ever misfires.
+ */
+function skipRegexLiteral(code: string, i: number): number {
+  const start = i
+  i++ // past opening '/'
+  let inClass = false
+  while (i < code.length) {
+    const ch = code[i]
+    if (ch === '\\') i++
+    else if (ch === '\n') return start + 1
+    else if (ch === '[') inClass = true
+    else if (ch === ']') inClass = false
+    else if (ch === '/' && !inClass) return i + 1
+    i++
+  }
+  return start + 1
+}
+
 /**
  * Starting from position `i` (after the tag name), scan forward past
  * all attributes and find the closing `>`. Handles quoted strings
  * so that `>` inside `"..."`, `'...'`, or `` `...` `` doesn't end the tag.
  *
- * In JSX mode, also tracks `{}` brace depth so that `>` inside
- * JSX expression attributes (e.g., `{x > 5}`) doesn't end the tag.
+ * With `trackBraces` (JSX mode, and Svelte markup whose attributes use bare
+ * `{expr}` values), also tracks `{}` brace depth so that `>` inside
+ * expression attributes (e.g., `{x > 5}`, `onclick={() => fn()}`) doesn't
+ * end the tag.
  */
-export function findTagEnd(template: string, i: number, jsxMode = false): number {
+export function findTagEnd(template: string, i: number, trackBraces = false): number {
   let inQuote: string | null = null
   let braceDepth = 0
   // Stack of saved (inQuote, braceDepth) pairs for nested template literals.
@@ -540,9 +841,9 @@ export function findTagEnd(template: string, i: number, jsxMode = false): number
         stack.push({ inQuote, braceDepth })
         inQuote = '`'
         braceDepth = 0
-      } else if (jsxMode && ch === '{') {
+      } else if (trackBraces && ch === '{') {
         braceDepth++
-      } else if (jsxMode && ch === '}' && braceDepth > 0) {
+      } else if (trackBraces && ch === '}' && braceDepth > 0) {
         braceDepth--
       } else if (ch === '>' && braceDepth === 0) {
         return i + 1
diff --git a/src/schema.ts b/src/schema.ts
index af6b096..d8b6af4 100644
--- a/src/schema.ts
+++ b/src/schema.ts
@@ -1,3 +1,6 @@
+// Type-only — wireframe-types.ts has no runtime imports, so no cycle.
+import type { WireframeDataBinding } from './shared/wireframe-types'
+
 export interface ViewportInfo {
   width: number | null
   height: number | null
@@ -64,12 +67,14 @@ export type AnnotaskChange =
   | StyleUpdateChange
   | ClassUpdateChange
   | ScopedStyleUpdateChange
-  | PropUpdateChange
+  | ComponentPropUpdateChange
+  | TextUpdateChange
   | ComponentInsertChange
   | ComponentMoveChange
   | ComponentDeleteChange
   | AnnotationChange
   | SectionRequestChange
+  | WireframeDirectionChange
 
 interface BaseChange {
   id: string
@@ -107,12 +112,40 @@ export interface ScopedStyleUpdateChange extends BaseChange {
   after: Record<string, string>
 }
 
-/** @experimental Not yet emitted at runtime. Component prop value changes */
-export interface PropUpdateChange extends BaseChange {
-  type: 'prop_update'
-  component: string
-  before: Record<string, unknown>
-  after: Record<string, unknown>
+/**
+ * One component-prop value change at a usage site (from the properties panel).
+ * Per-prop (not a before/after dict) so edits collapse by (file, line, prop),
+ * undo one field at a time, and read unambiguously for the agent.
+ */
+export interface ComponentPropUpdateChange extends BaseChange {
+  type: 'component_prop_update'
+  /** Component tag as written at the usage site (e.g. 'Button', 'PlanetCard'). */
+  element: string
+  prop: string
+  /** Undefined when the prop wasn't set at the usage site (binding: 'new'). */
+  before: unknown
+  after: unknown
+  /**
+   * Honesty proof carried to the agent:
+   *  'literal'            — plain attribute (label="Reset"); rewrite the attribute value
+   *  'expression-literal' — literal through binding syntax (:count="3", count={3}); keep the syntax
+   *  'new'                — prop not present at the usage site; add it
+   * Bound expressions never appear here — the shell refuses to edit them.
+   */
+  binding: 'literal' | 'expression-literal' | 'new'
+  /** Scanned type string ('boolean', "'small' | 'large'") — serialization hint. */
+  prop_type?: string
+}
+
+/** Literal text-content change on an element (from the properties panel).
+ *  Only emitted when the source content is a single literal text run —
+ *  bound/mixed content is refused at the UI layer. */
+export interface TextUpdateChange extends BaseChange {
+  type: 'text_update'
+  /** DOM tag of the element (e.g. 'h1'). */
+  element: string
+  before: string
+  after: string
 }
 
 /** Insert a new element/component */
@@ -129,7 +162,8 @@ export interface ComponentInsertChange extends Omit<BaseChange, 'component'> {
   }
 }
 
-/** Move/reorder an element */
+/** Legacy — emitted by the removed Reposition tool; no longer produced, but
+ *  agents still apply it when present in older tasks/reports. */
 export interface ComponentMoveChange extends BaseChange {
   type: 'component_move'
   element: {
@@ -178,6 +212,72 @@ export interface SectionRequestChange extends BaseChange {
   prompt: string
 }
 
+/** Document CSS px in the wireframe canvas's capture coordinate space. */
+export interface WireframeRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/**
+ * One snapshot-wireframe direction — what the user's sketch encodes for ONE
+ * canvas block, computed by diffing the original capture against the current
+ * canvas at "Implement this wireframe" time. `file`/`line` (BaseChange) anchor
+ * at the block's captured source, or for adds at the nearest anchored
+ * neighbor block. Pixel geometry is a HINT; relational facts are the
+ * contract — agents implement the intent with idiomatic layout, not absolute
+ * positioning. `measured` is tool-derived geometry and `note` is the user's
+ * verbatim words: never conflate the two channels.
+ */
+export interface WireframeDirectionChange extends BaseChange {
+  type: 'wireframe_direction'
+  op: 'move' | 'resize' | 'delete' | 'add' | 'note'
+  /** The block's identity as captured/created — tool-derived, never invented. */
+  block: { label: string; component?: string; tag?: string }
+  /** TOOL-MEASURED spatial facts. Never user-authored. */
+  measured?: {
+    before?: WireframeRect
+    after?: WireframeRect
+    dx?: number
+    dy?: number
+    /** Resize as % of original (wPct: 150 = +50% wider). */
+    wPct?: number
+    hPct?: number
+    /** Relational facts computed from box geometry, highest-value first —
+     *  e.g. "now above the filters toolbar (was below)". Max 3. */
+    relations?: string[]
+  }
+  /** op 'add' only. Component names/modules are REAL scanner output.
+   *  'duplicate' = another copy of a captured block's anchored markup. */
+  added?: {
+    kind: 'component' | 'placeholder' | 'duplicate'
+    componentName?: string
+    library?: string
+    module?: string
+    /** Owning MFE id in a multi-MFE workspace — the package the agent must
+     *  import the component from (and scope example search to). Absent in
+     *  single-MFE projects; codegen then uses library/module as before. */
+    mfe?: string
+    props?: Record<string, unknown>
+    previewProps?: Record<string, unknown>
+    /** placeholder: the user's label, verbatim. Stays visibly a placeholder. */
+    label?: string
+    /** USER-WRITTEN markdown spec (drawn sections). Travels VERBATIM — never
+     *  blended with measured geometry; the description quotes only its first
+     *  line. */
+    md?: string
+    /** Wire THIS real catalog data source. The agent re-grounds it before
+     *  use and never invents fields — see WIREFRAME_APPLY.md. */
+    data?: WireframeDataBinding
+    /** Where it goes relative to the anchored neighbor (file/line above). */
+    position: 'before' | 'after' | 'append' | 'prepend'
+  }
+  /** USER-SAID, verbatim (the block's canvas note). Rides any op; op 'note'
+   *  when the note is the only change on the block. */
+  note?: string
+}
+
 /**
  * Minimal component reference stored inside a task's `context` object.
  * Attached in two places:
@@ -467,6 +567,66 @@ export type DataSourceDetailsResult =
   | DataSourceDetailsAmbiguous
   | DataSourceDetailsNotFound
 
+/**
+ * One node of a walkable response shape — `schemaToShape()` output
+ * (data-source-shape.ts). Derived from a REAL schema only; residual `$ref`
+ * cycle markers and GraphQL `$type` names degrade to honest `ref` leaves,
+ * never fabricated key trees.
+ */
+export interface DataShapeNode {
+  kind: 'object' | 'array' | 'scalar' | 'ref' | 'unknown'
+  /** JSON-schema scalar type when kind 'scalar' ('string', 'number', …). */
+  scalar?: string
+  /** Object children by key, when kind 'object'. */
+  children?: Record<string, DataShapeNode>
+  /** Array item shape, when kind 'array'. */
+  item?: DataShapeNode
+  /** Named type (cycle marker / GraphQL $type), when kind 'ref'. */
+  ref?: string
+  /** Example/default value declared by the API contract at this node — REAL
+   *  contract sample data (api-schema tier only), used to preview bound props
+   *  honestly. For an array, an example array of items when the schema provides
+   *  one. Never synthesized. */
+  example?: unknown
+}
+
+/**
+ * Shape resolution for one data source — the binding picker's honesty-tagged
+ * ladder result. `shape_source` says which rung answered:
+ *   'api-schema'     — a real API contract matched the entry's endpoint;
+ *                      `shape` is walkable, `match_confidence` is the
+ *                      endpoint-match score.
+ *   'source-details' — regex-inferred hints only (`return_type` /
+ *                      `referenced_types` / `signature`, with the regex
+ *                      `details_confidence`); NO `shape` tree — expanding a
+ *                      type name into keys would fabricate.
+ *   'none'           — nothing known; the picker offers free-text entry,
+ *                      visibly blind.
+ */
+export interface DataSourceShape {
+  name: string
+  kind: DataSource['kind']
+  file: string
+  endpoint?: string
+  method?: string
+  shape_source: 'api-schema' | 'source-details' | 'none'
+  /** Walkable response shape — present only for 'api-schema'. */
+  shape?: DataShapeNode
+  /** Short schema-type name (e.g. "Planet[]") for agent follow-up. */
+  schema_ref?: string
+  schema_kind?: ApiSchema['kind']
+  /** resolveEndpoint score 0..1 ('api-schema' rung). */
+  match_confidence?: number
+  /** Regex-resolution confidence ('source-details' rung). */
+  details_confidence?: 'high' | 'medium' | 'low'
+  /** Verbatim inferred hints ('source-details' rung). */
+  return_type?: string
+  referenced_types?: string[]
+  signature?: string
+}
+
+export type DataSourceShapeResult = DataSourceShape | DataSourceDetailsAmbiguous | DataSourceDetailsNotFound
+
 /**
  * A single element-rendering site that consumes a data source. The pair
  * (file, line) maps directly onto the `data-annotask-file` + `data-annotask-line`
@@ -605,6 +765,23 @@ export interface ScreenshotMeta {
   section_bounds?: { x: number; y: number; w: number; h: number }
 }
 
+/**
+ * Per-task aggregate of provider token usage. Rolled up from each assistant
+ * turn's `ThreadMessage.usage` (input/output + Anthropic cache buckets), plus
+ * a `turns` counter and the timestamp of the last update so the UI can show
+ * "last activity X ago" without re-reading the JSONL log.
+ */
+export interface TokenUsage {
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheCreationTokens: number
+  /** Number of provider turns folded into the totals above. */
+  turns: number
+  /** Epoch ms of the most recent contribution. */
+  lastUpdated: number
+}
+
 /** A single question the agent asks the user */
 export interface AgentFeedbackQuestion {
   id: string
@@ -622,40 +799,6 @@ export interface AgentFeedbackEntry {
   answers?: Array<{ id: string; value: string }>
 }
 
-/**
- * A backend-contract edit performed during a task. Two call sites:
- *   - `api_update` tasks: primary deliverable; context.api_edits[] is how the
- *     agent records every schema/route change needed.
- *   - Non-api_update tasks (usually `annotation`): when the user approves a
- *     cross-boundary edit via needs_info, the agent records the edit here so
- *     triage can see that this task crossed the frontend/backend line. Keeps
- *     lineage on the original task — no spawned child.
- */
-export interface ApiEdit {
-  schema_location: string
-  schema_kind: 'openapi' | 'graphql' | 'trpc' | 'jsonschema'
-  operation?: { method: string; path: string }
-  change_summary: string
-}
-
-/**
- * Structured context on an `api_update` task. Populated at creation time from
- * the Data view; the agent reads these fields (plus the task's description
- * and any linked data-source metadata) to know what the backend edit needs to
- * accomplish.
- */
-export interface ApiUpdateContext {
-  data_source_name: string
-  data_source_kind: DataSource['kind']
-  schema_location: string
-  schema_kind: 'openapi' | 'graphql' | 'trpc' | 'jsonschema'
-  endpoint?: string
-  operation?: { method: string; path: string; response_schema?: unknown; request_schema?: unknown }
-  desired_change: string
-  rationale?: string
-  api_edits?: ApiEdit[]
-}
-
 /**
  * Canonical list of task types recognized across HTTP, MCP, CLI, shell UI,
  * and task-summary lifting. Single source of truth — consumers must derive
@@ -669,11 +812,32 @@ export const TASK_TYPES = [
   'a11y_fix',
   'error_fix',
   'perf_fix',
-  'api_update',
+  'wireframe_apply',
 ] as const
 
 export type TaskType = typeof TASK_TYPES[number]
 
+/**
+ * Permission mode for agent actions. Three modes, two tiers (global + task):
+ *   - `default` — CLI asks for non-trivial tool use (its own default behavior)
+ *   - `plan`    — read-only. Enforced natively where possible (claude's
+ *                 `--permission-mode plan`, codex's read-only sandbox) and via
+ *                 a model-level system-prompt directive on CLIs that lack a
+ *                 native plan flag (opencode, copilot headless).
+ *   - `bypass`  — bypass all permission checks (historical default)
+ *
+ * Resolved per-task as `task ?? global`. The persona tier was dropped — it
+ * added a dropdown nobody used and the chip menu in the Conversation tab
+ * already covers the "per-task tighten/loosen" flow.
+ *
+ * acceptEdits was removed in the same cut: only claude-local could
+ * meaningfully distinguish it from `default`, so it was theater on the other
+ * three CLIs.
+ */
+export const PERMISSION_MODES = ['default', 'plan', 'bypass'] as const
+
+export type PermissionMode = typeof PERMISSION_MODES[number]
+
 /** Task in the review pipeline */
 export interface AnnotaskTask {
   id: string
@@ -699,6 +863,13 @@ export interface AnnotaskTask {
   blocked_reason?: string                // why agent cannot apply this task (markdown)
   resolution?: string                    // brief note on what the agent did
   visual?: Record<string, unknown>       // annotation visual state for restoration
+  /** Aggregate provider token usage across this task's conversation turns. */
+  tokenUsage?: TokenUsage
+  /**
+   * Per-task permission-mode override. Wins over the persona and global
+   * tiers when set. Absent = inherit (resolver falls back to persona, then global).
+   */
+  permissionMode?: PermissionMode
   createdAt: number
   updatedAt: number
 }
diff --git a/src/server/__tests__/agent-models.test.ts b/src/server/__tests__/agent-models.test.ts
new file mode 100644
index 0000000..a08e9b4
--- /dev/null
+++ b/src/server/__tests__/agent-models.test.ts
@@ -0,0 +1,154 @@
+/**
+ * Server-side agent-models hardening checks.
+ *
+ * The live network probes (opencode subprocess) are not run here — they're
+ * covered by the on-demand smoke tests. We exercise the pure parsers and the
+ * cache behavior instead, which is where the regressions that triggered this
+ * hardening showed up:
+ *   - opencode emitting ANSI escapes inside a TTY proxy
+ *   - opencode prefixing the active row with `→` / `*` / bullet glyphs
+ *   - `refresh: true` failing to bypass the 5-minute in-process cache
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  parseOpenCodeModels,
+  parseCodexModelsCache,
+  listAgentModels,
+  invalidateAgentModels,
+} from '../agent-models.js'
+
+describe('parseOpenCodeModels', () => {
+  it('parses plain provider/model lines', () => {
+    const out = parseOpenCodeModels(
+      'anthropic/claude-sonnet-4-6\nopenai/gpt-5.4\nopenai/gpt-4o-mini\n',
+    )
+    expect(out.map(m => m.id)).toEqual([
+      'anthropic/claude-sonnet-4-6',
+      'openai/gpt-5.4',
+      'openai/gpt-4o-mini',
+    ])
+    expect(out.every(m => m.source === 'discovered')).toBe(true)
+  })
+
+  it('strips ANSI control sequences before parsing', () => {
+    const ansi = '\x1B[2manthropic/claude-sonnet-4-6\x1B[0m\n\x1B[32m→\x1B[0m openai/gpt-5.4\n'
+    const out = parseOpenCodeModels(ansi)
+    expect(out.map(m => m.id)).toEqual([
+      'anthropic/claude-sonnet-4-6',
+      'openai/gpt-5.4',
+    ])
+  })
+
+  it('drops leading decoration characters from the active row', () => {
+    const out = parseOpenCodeModels(
+      '> anthropic/claude-sonnet-4-6\n  openai/gpt-5.4\n* openai/gpt-4o-mini  (active)\n',
+    )
+    expect(out.map(m => m.id)).toEqual([
+      'anthropic/claude-sonnet-4-6',
+      'openai/gpt-5.4',
+      'openai/gpt-4o-mini',
+    ])
+  })
+
+  it('preserves multi-segment ids like vllm/Qwen/Model-7B', () => {
+    const out = parseOpenCodeModels('vllm/Qwen/Qwen2.5-7B-Instruct-AWQ\n')
+    expect(out[0].id).toBe('vllm/Qwen/Qwen2.5-7B-Instruct-AWQ')
+  })
+
+  it('accepts JSON output from a future opencode build', () => {
+    const json = JSON.stringify({
+      models: [
+        { id: 'anthropic/claude-sonnet-4-6', label: 'Sonnet 4.6' },
+        'openai/gpt-5.4',
+      ],
+    })
+    const out = parseOpenCodeModels(json)
+    expect(out.map(m => m.id)).toEqual([
+      'anthropic/claude-sonnet-4-6',
+      'openai/gpt-5.4',
+    ])
+  })
+
+  it('dedupes repeated entries', () => {
+    const out = parseOpenCodeModels(
+      'anthropic/claude-sonnet-4-6\nanthropic/claude-sonnet-4-6\nopenai/gpt-5.4\n',
+    )
+    expect(out.map(m => m.id)).toEqual([
+      'anthropic/claude-sonnet-4-6',
+      'openai/gpt-5.4',
+    ])
+  })
+
+  it('ignores blank input', () => {
+    expect(parseOpenCodeModels('')).toEqual([])
+    expect(parseOpenCodeModels('   \n  \n')).toEqual([])
+  })
+})
+
+describe('parseCodexModelsCache', () => {
+  it('reads slug + display_name from the codex cache', () => {
+    const raw = JSON.stringify({
+      models: [
+        { slug: 'gpt-5.4', display_name: 'GPT-5.4' },
+        { slug: 'gpt-5.2' },
+        { /* bad */ },
+      ],
+    })
+    const out = parseCodexModelsCache(raw)
+    expect(out).toEqual([
+      { id: 'gpt-5.4', label: 'GPT-5.4', source: 'discovered' },
+      { id: 'gpt-5.2', label: 'gpt-5.2', source: 'discovered' },
+    ])
+  })
+})
+
+describe('listAgentModels cache behavior', () => {
+  it('returns the static catalog (Auto + canonical ids, no error) for providers with no probe', async () => {
+    invalidateAgentModels()
+    const catalog = await listAgentModels('anthropic')
+    expect(catalog.discovered).toBe(false)
+    expect(catalog.error).toBeUndefined()
+    expect(catalog.models[0].id).toBe('') // Auto option
+    expect(catalog.models.length).toBeGreaterThan(1)
+    expect(catalog.models.slice(1).every((m) => m.source === 'static')).toBe(true)
+    // Sanity: the canonical Anthropic ids are present.
+    expect(catalog.models.map((m) => m.id)).toContain('claude-opus-4-7')
+  })
+
+  it('claude-local serves opus/sonnet/haiku aliases as a static catalog', async () => {
+    invalidateAgentModels()
+    const catalog = await listAgentModels('claude-local')
+    const ids = catalog.models.map((m) => m.id)
+    expect(ids).toEqual(['', 'opus', 'sonnet', 'haiku'])
+    expect(catalog.error).toBeUndefined()
+    expect(catalog.discovered).toBe(false)
+  })
+
+  it('returns a copilot-local-specific error explaining the CLI has no headless model list', async () => {
+    invalidateAgentModels()
+    // copilot-local intentionally does NOT probe the HTTP /models endpoint
+    // — the CLI's --model flag rejects those ids. Verify we surface that
+    // distinction in the error so the user knows where to look.
+    const catalog = await listAgentModels('copilot-local')
+    expect(catalog.discovered).toBe(false)
+    expect(catalog.models).toHaveLength(1)
+    expect(catalog.error).toBeTruthy()
+    expect(catalog.error).toMatch(/Copilot CLI doesn't expose a model list/i)
+    expect(catalog.error).toMatch(/\/model/)
+  })
+
+  it('refresh: true forces a fresh fetch', async () => {
+    invalidateAgentModels()
+    const first = await listAgentModels('anthropic')
+    // Inject a timestamp far enough in the future to detect a fresh probe.
+    const before = first.cachedAt
+    // Default call hits the cache and returns the same cachedAt.
+    const cached = await listAgentModels('anthropic')
+    expect(cached.cachedAt).toBe(before)
+    // refresh: true bypasses the cache and re-stamps cachedAt.
+    await new Promise((r) => setTimeout(r, 5))
+    const refreshed = await listAgentModels('anthropic', { refresh: true })
+    expect(refreshed.cachedAt).toBeGreaterThan(before)
+  })
+})
diff --git a/src/server/__tests__/agent-spawn-http.test.ts b/src/server/__tests__/agent-spawn-http.test.ts
new file mode 100644
index 0000000..8de2161
--- /dev/null
+++ b/src/server/__tests__/agent-spawn-http.test.ts
@@ -0,0 +1,363 @@
+/**
+ * HTTP-level tests for the agent-spawn route: the REAL createAPIMiddleware
+ * wired to a REAL createAgentSpawnHandler over a real socket — only the child
+ * process itself is faked (spawnImpl seam). The unit suite
+ * (agent-spawn.test.ts) covers handler internals with fake req/res objects;
+ * this file covers what only the middleware layer can: the same-port origin
+ * gate (api.test.ts stubs handleSpawn, so it does NOT cover this), SSE
+ * status/headers/framing on the wire, the concurrency refusal, client-
+ * disconnect kills, and the ANNOTASK_MAX_PERMISSION cap as a caller sees it.
+ */
+import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest'
+import http from 'node:http'
+import { EventEmitter } from 'node:events'
+import type { ChildProcessWithoutNullStreams, spawn as nodeSpawn } from 'node:child_process'
+import { createAPIMiddleware } from '../api.js'
+import { createAgentSpawnHandler } from '../agent-spawn.js'
+import { emptyWireframeDocument, type WireframeDocument } from '../../shared/wireframe-types.js'
+import type { DesignSessionDocument } from '../../shared/design-session-types.js'
+
+const SPAWN_PATH = '/__annotask/api/agent/spawn'
+const MAX_LINE = 1_048_576 // mirrors MAX_BUFFERED_LINE_BYTES in agent-spawn.ts
+
+// ── Fake child process (mirrors FakeChild in agent-spawn.test.ts) ──
+// `pid` is deliberately ABSENT here: killChild then takes the direct
+// child.kill path instead of process.kill(-pid), so no real signal can ever
+// escape the test process. The group-kill (-pid) path is covered by the unit
+// suite with a spied process.kill.
+class FakeStream extends EventEmitter {
+  setEncoding() { /* noop */ }
+  write(_data: unknown, cb?: () => void) { if (cb) cb(); return true }
+  end() { /* noop */ }
+}
+class FakeChild extends EventEmitter {
+  stdin = new FakeStream()
+  stdout = new FakeStream()
+  stderr = new FakeStream()
+  killed = false
+  closed = false
+  kill() { this.killed = true; return true }
+  /** Resolve the handler's wait by emitting the child's `close` (idempotent
+   *  so the afterEach drain can't double-emit on already-finished children). */
+  finish(code = 0) {
+    if (this.closed) return
+    this.closed = true
+    this.emit('close', code, null)
+  }
+}
+
+/** Poll until `cond` holds — bridges "request sent" to "handler spawned child". */
+function waitFor(cond: () => boolean, what: string, timeoutMs = 2_000): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const start = Date.now()
+    const tick = () => {
+      if (cond()) return resolve()
+      if (Date.now() - start > timeoutMs) return reject(new Error(`timed out waiting for ${what}`))
+      setTimeout(tick, 5)
+    }
+    tick()
+  })
+}
+
+function request(
+  server: http.Server,
+  method: string,
+  path: string,
+  body?: unknown,
+  extraHeaders?: Record<string, string>,
+): Promise<{ status: number; headers: http.IncomingHttpHeaders; data: any; raw: string }> {
+  return new Promise((resolve, reject) => {
+    const port = (server.address() as { port: number }).port
+    const options: http.RequestOptions = {
+      method,
+      hostname: 'localhost',
+      port,
+      path,
+      headers: { ...extraHeaders, ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+    }
+    const req = http.request(options, (res) => {
+      let raw = ''
+      res.on('data', (chunk) => { raw += chunk })
+      res.on('end', () => {
+        let data: any
+        try { data = JSON.parse(raw) } catch { data = raw }
+        resolve({ status: res.statusCode!, headers: res.headers, data, raw })
+      })
+    })
+    req.on('error', reject)
+    if (body !== undefined) req.write(JSON.stringify(body))
+    req.end()
+  })
+}
+
+describe('agent-spawn over HTTP (real middleware + real spawn handler)', () => {
+  let server: http.Server
+  const spawned: FakeChild[] = []
+  const spawnImpl = (() => {
+    const child = new FakeChild()
+    spawned.push(child)
+    return child as unknown as ChildProcessWithoutNullStreams
+  }) as unknown as typeof nodeSpawn
+  const agentSpawn = createAgentSpawnHandler({ spawnImpl })
+
+  let wireframeDoc: WireframeDocument = emptyWireframeDocument()
+  const options = {
+    projectRoot: '/tmp/annotask-spawn-http-test',
+    getReport: () => ({ version: '1.0', changes: [] }),
+    getConfig: () => ({ version: '1.0' }),
+    getDesignSpec: () => ({ version: '1.0', initialized: false }),
+    getTasks: () => ({ version: '1.0', tasks: [] }),
+    addTask: (task: Record<string, unknown>) => ({ id: 'task-test', status: 'pending', ...task }),
+    updateTask: () => ({ error: 'Task not found' }),
+    deleteTask: () => ({ error: 'Task not found' }),
+    saveInteractionHistory: async () => { /* no-op for tests */ },
+    readInteractionHistory: async () => null,
+    saveRenderedHtml: async () => { /* no-op for tests */ },
+    readRenderedHtml: async () => null,
+    getPerformance: () => null,
+    setPerformance: () => { /* no-op for tests */ },
+    ingestNetworkCalls: () => { /* no-op for tests */ },
+    getRuntimeEndpointCatalog: () => ({ version: '1.0' as const, updatedAt: 0, endpoints: [] }),
+    clearRuntimeEndpoints: () => { /* no-op for tests */ },
+    taskThread: {
+      read: async () => [],
+      append: async (_id: string, input: { role: 'user' | 'assistant' | 'system' | 'tool'; content: string }) => ({
+        id: 'msg-test', ts: 0, role: input.role, content: input.content,
+      }),
+      update: async (_id: string, msgId: string, patch: { content?: string }) => ({
+        id: msgId, ts: 0, role: 'assistant' as const, content: patch.content ?? '',
+      }),
+      subscribe: () => () => { /* no-op */ },
+      clear: async () => { /* no-op */ },
+    },
+    // The one REAL collaborator under test.
+    agentSpawn,
+    agentDetect: {
+      detect: async () => ({
+        'claude-local': { found: false },
+        'codex-local': { found: false },
+        'opencode-local': { found: false },
+        'copilot-local': { found: false },
+        copilot: { found: false },
+        openrouter: { hasEnv: false },
+        ts: 0,
+      }),
+      invalidate: () => { /* no-op */ },
+    },
+    initRunner: {
+      start: () => ({ running: false, steps: [] }),
+      cancel: () => { /* no-op */ },
+      commit: async () => ({ running: false, steps: [], result: 'success' as const }),
+      skip: async () => ({ running: false, steps: [], result: 'success' as const }),
+      reset: () => ({ running: false, steps: [] }),
+      getState: () => ({ running: false, steps: [] }),
+    },
+    getAgentConfigs: async () => ({ version: 1 as const, agents: {} }),
+    setAgentConfig: async () => ({ version: 1 as const, agents: {} }),
+    getWireframe: async () => wireframeDoc,
+    setWireframe: async (doc: WireframeDocument) => { wireframeDoc = doc; return doc },
+    getDesignSession: async () => ({ version: '1.0' as const, sessionId: 'ds-test', startedAt: 0, updatedAt: 0, entries: [] }),
+    setDesignSession: async (doc: DesignSessionDocument) => doc,
+    clearDesignSession: async () => ({ version: '1.0' as const, sessionId: 'ds-test', startedAt: 0, updatedAt: 0, entries: [] }),
+    snapshots: {
+      snapshotFiles: async () => undefined,
+      sealBatch: async () => undefined,
+      sealBatchByTask: async () => undefined,
+      revertBatch: async () => ({ reverted: [], skipped: [] }),
+      revertAll: async () => ({ reverted: [], skipped: [] }),
+      commit: async () => undefined,
+      detachFile: async () => undefined,
+      state: async () => ({ files: {}, batches: [] }),
+      flush: async () => undefined,
+    },
+    usageLedger: {
+      append: async (e: { scope: 'task' | 'init' | 'apply' | 'chat' }) => ({ ts: 0, scope: e.scope, inputTokens: 0, outputTokens: 0 }),
+      readAll: async () => [],
+      summary: async () => ({
+        totals: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+        byScope: {
+          task: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+          init: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+          apply: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+          chat: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0, turns: 0 },
+        },
+        byProvider: {},
+        firstAt: null,
+        lastAt: null,
+      }),
+      recent: async () => [],
+    },
+  }
+
+  beforeAll(async () => {
+    const middleware = createAPIMiddleware(options)
+    server = http.createServer((req, res) => {
+      middleware(req, res, () => { res.statusCode = 404; res.end('Not found') })
+    })
+    await new Promise<void>((resolve) => server.listen(0, resolve))
+  })
+
+  afterAll(async () => {
+    agentSpawn.registry.killAll()
+    await new Promise<void>((resolve) => server.close(() => resolve()))
+  })
+
+  afterEach(async () => {
+    delete process.env.ANNOTASK_MAX_PERMISSION
+    // Drain: close any children a failed assertion left parked so their SSE
+    // responses end and the active-run registry empties before the next test.
+    for (const c of spawned) c.finish(0)
+    await waitFor(() => agentSpawn.registry.size() === 0, 'active runs to drain')
+    spawned.length = 0
+  })
+
+  function serverPort(): number {
+    return (server.address() as { port: number }).port
+  }
+
+  it('403s a cross-port localhost Origin with origin_port_mismatch', async () => {
+    const port = serverPort()
+    const badPort = port === 9999 ? 9998 : 9999 // ephemeral ports can collide with the canned value
+    const before = spawned.length
+    const { status, data } = await request(server, 'POST', SPAWN_PATH, { cli: 'claude', args: [] }, {
+      Origin: `http://localhost:${badPort}`,
+    })
+    expect(status).toBe(403)
+    expect(data.error.code).toBe('origin_port_mismatch')
+    expect(spawned.length).toBe(before) // refused before any child was spawned
+  })
+
+  it('streams SSE (run → stdout → exit) for a same-port Origin', async () => {
+    const before = spawned.length
+    const resP = request(server, 'POST', SPAWN_PATH, { cli: 'claude', args: ['--print'] }, {
+      Origin: `http://localhost:${serverPort()}`,
+    })
+    await waitFor(() => spawned.length > before, 'child spawn')
+    const child = spawned[spawned.length - 1]
+    child.stdout.emit('data', 'hello world\n')
+    child.finish(0)
+    const { status, headers, raw } = await resP
+    expect(status).toBe(200)
+    expect(headers['content-type']).toBe('text/event-stream')
+    expect(raw).toMatch(/event: run\ndata: \{"runId":"run-[^"]+"\}\n\n/)
+    expect(raw).toContain('event: stdout\ndata: hello world\n')
+    expect(raw).toContain('event: exit\ndata: {"code":0,"signal":null}')
+  })
+
+  it('passes with no Origin header at all (non-browser client, e.g. curl)', async () => {
+    const before = spawned.length
+    const resP = request(server, 'POST', SPAWN_PATH, { cli: 'codex', args: ['exec'] })
+    await waitFor(() => spawned.length > before, 'child spawn')
+    spawned[spawned.length - 1].finish(0)
+    const { status, headers, raw } = await resP
+    expect(status).toBe(200)
+    expect(headers['content-type']).toBe('text/event-stream')
+    expect(raw).toContain('event: run')
+  })
+
+  it('refuses the 5th concurrent spawn with 503 too_many_agents', async () => {
+    const before = spawned.length
+    const inflight: Array<ReturnType<typeof request>> = []
+    for (let i = 0; i < 4; i++) {
+      inflight.push(request(server, 'POST', SPAWN_PATH, { cli: 'claude', args: [] }))
+    }
+    await waitFor(() => spawned.length === before + 4, 'four parked children')
+    expect(agentSpawn.registry.size()).toBe(4)
+
+    const fifth = await request(server, 'POST', SPAWN_PATH, { cli: 'claude', args: [] })
+    expect(fifth.status).toBe(503)
+    expect(fifth.data.error.code).toBe('too_many_agents')
+    expect(spawned.length).toBe(before + 4) // no fifth child was forked
+
+    // Drain the four parked runs and confirm their streams completed normally.
+    for (const c of spawned.slice(before)) c.finish(0)
+    const results = await Promise.all(inflight)
+    for (const r of results) expect(r.status).toBe(200)
+  })
+
+  it('kills the child when the client disconnects mid-stream', async () => {
+    const before = spawned.length
+    const clientReq = http.request({
+      method: 'POST',
+      hostname: 'localhost',
+      port: serverPort(),
+      path: SPAWN_PATH,
+      headers: { 'Content-Type': 'application/json' },
+    })
+    clientReq.on('error', () => { /* expected after destroy */ })
+    clientReq.on('response', (res) => {
+      res.on('data', () => { /* keep the stream flowing */ })
+      res.on('error', () => { /* expected after destroy */ })
+    })
+    clientReq.end(JSON.stringify({ cli: 'claude', args: [] }))
+
+    await waitFor(() => spawned.length > before, 'child spawn')
+    const child = spawned[spawned.length - 1]
+    expect(child.killed).toBe(false)
+
+    clientReq.destroy()
+    await waitFor(() => child.killed, 'child kill on client disconnect')
+    child.finish(143) // simulate the SIGTERM landing so the run drains
+  })
+
+  describe('ANNOTASK_MAX_PERMISSION cap at the route level', () => {
+    it('403s a bypass spawn under cap=default — canonical flag AND synonym spellings', async () => {
+      process.env.ANNOTASK_MAX_PERMISSION = 'default'
+      const before = spawned.length
+
+      const direct = await request(server, 'POST', SPAWN_PATH, {
+        cli: 'claude', args: ['--print', '--dangerously-skip-permissions'],
+      })
+      expect(direct.status).toBe(403)
+      expect(direct.data.error.code).toBe('permission_exceeds_cap')
+
+      // Regression: the synonym pair form used to derive as `plan` and walk
+      // straight past the cap.
+      const synonym = await request(server, 'POST', SPAWN_PATH, {
+        cli: 'claude', args: ['--print', '--permission-mode', 'bypassPermissions'],
+      })
+      expect(synonym.status).toBe(403)
+      expect(synonym.data.error.code).toBe('permission_exceeds_cap')
+
+      // Same hole on codex: sandbox-removal via the pair form.
+      const codexSynonym = await request(server, 'POST', SPAWN_PATH, {
+        cli: 'codex', args: ['exec', '--sandbox', 'danger-full-access'],
+      })
+      expect(codexSynonym.status).toBe(403)
+      expect(codexSynonym.data.error.code).toBe('permission_exceeds_cap')
+
+      expect(spawned.length).toBe(before) // every refusal happened pre-spawn
+    })
+
+    it('still allows a default-level spawn under cap=default', async () => {
+      process.env.ANNOTASK_MAX_PERMISSION = 'default'
+      const before = spawned.length
+      const resP = request(server, 'POST', SPAWN_PATH, { cli: 'codex', args: ['exec', '--full-auto'] })
+      await waitFor(() => spawned.length > before, 'child spawn')
+      spawned[spawned.length - 1].finish(0)
+      const { status } = await resP
+      expect(status).toBe(200)
+    })
+  })
+
+  it('truncates a >1MiB single-line stdout chunk and repeats data: prefixes for multi-line payloads', async () => {
+    const before = spawned.length
+    const resP = request(server, 'POST', SPAWN_PATH, { cli: 'claude', args: [] })
+    await waitFor(() => spawned.length > before, 'child spawn')
+    const child = spawned[spawned.length - 1]
+
+    // One newline-free chunk over the cap: flushed truncated, remainder dropped.
+    child.stdout.emit('data', 'x'.repeat(MAX_LINE + 64))
+    // One oversized chunk WITH an embedded newline: the truncated flush is a
+    // multi-line SSE payload, so the frame must repeat the `data: ` prefix.
+    child.stdout.emit('data', 'first\nsecond' + 'z'.repeat(MAX_LINE))
+    child.finish(0)
+
+    const { status, raw } = await resP
+    expect(status).toBe(200)
+    const single = /event: stdout\ndata: (x+)\n\n/.exec(raw)
+    expect(single).not.toBeNull()
+    expect(single![1].length).toBe(MAX_LINE)
+    expect(raw).toContain('event: stdout\ndata: first\ndata: second')
+  })
+})
diff --git a/src/server/__tests__/agent-spawn.test.ts b/src/server/__tests__/agent-spawn.test.ts
new file mode 100644
index 0000000..8e2d1f8
--- /dev/null
+++ b/src/server/__tests__/agent-spawn.test.ts
@@ -0,0 +1,378 @@
+import { describe, it, expect, afterEach, vi } from 'vitest'
+import { EventEmitter } from 'node:events'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { ChildProcessWithoutNullStreams, spawn as nodeSpawn } from 'node:child_process'
+import { parseSpawnBody, permissionLevelOfArgs, maxPermissionCap, exceedsPermissionCap, createAgentSpawnHandler, __test } from '../agent-spawn.js'
+import {
+  initPermissionFlagsFor,
+  claudePermissionFlags,
+  codexPermissionFlags,
+  opencodePermissionFlags,
+  copilotPermissionFlags,
+  normalizeHeadlessMode,
+} from '../../embedded/permission-mode-flags.js'
+
+// ── Mocks so the registry/lifecycle can be tested without a real subprocess ──
+class FakeStream extends EventEmitter {
+  setEncoding() { /* noop */ }
+  write(_data: unknown, cb?: () => void) { if (cb) cb(); return true }
+  end() { /* noop */ }
+}
+class FakeChild extends EventEmitter {
+  stdin = new FakeStream()
+  stdout = new FakeStream()
+  stderr = new FakeStream()
+  killed = false
+  /** Unset by default so killChild takes the direct child.kill path. Group-kill
+   *  tests set it explicitly (with process.kill spied) to exercise -pid signaling. */
+  pid?: number
+  kill() { this.killed = true; return true }
+  /** Resolve the handler's wait by emitting the child's `close`. */
+  finish(code = 0) { this.emit('close', code, null) }
+}
+class FakeRes extends EventEmitter {
+  statusCode = 200
+  ended = false
+  body = ''
+  setHeader() { /* noop */ }
+  flushHeaders() { /* noop */ }
+  write(s: string) { this.body += s; return true }
+  end(s?: string) { if (s) this.body += s; this.ended = true; this.emit('close'); return this }
+}
+function fakeReq() { return new EventEmitter() as unknown as IncomingMessage }
+function fakeRes() { return new FakeRes() as unknown as ServerResponse & FakeRes }
+function fakeSpawn(child: FakeChild): typeof nodeSpawn {
+  return (() => child as unknown as ChildProcessWithoutNullStreams) as unknown as typeof nodeSpawn
+}
+
+describe('parseSpawnBody', () => {
+  it('accepts a well-formed body', () => {
+    const out = parseSpawnBody({ cli: 'claude', args: ['--print', '-p', 'hi'] })
+    expect(typeof out === 'string').toBe(false)
+    if (typeof out !== 'string') {
+      expect(out.cli).toBe('claude')
+      expect(out.args).toEqual(['--print', '-p', 'hi'])
+    }
+  })
+
+  it('rejects non-allowed CLIs', () => {
+    const out = parseSpawnBody({ cli: 'rm', args: ['-rf', '/'] })
+    expect(typeof out).toBe('string')
+    expect(out as string).toMatch(/must be one of/)
+  })
+
+  it('rejects non-array args', () => {
+    const out = parseSpawnBody({ cli: 'claude', args: 'not an array' })
+    expect(typeof out).toBe('string')
+  })
+
+  it('drops unknown env keys silently', () => {
+    const out = parseSpawnBody({
+      cli: 'claude',
+      args: [],
+      env: { PATH: '/etc', ANTHROPIC_MODEL: 'sonnet-4', NOT_ALLOWED: 'x' },
+    })
+    expect(typeof out === 'string').toBe(false)
+    if (typeof out !== 'string') {
+      expect(out.env).toEqual({ ANTHROPIC_MODEL: 'sonnet-4' })
+      // PATH is dangerous to override; it must NOT make it through.
+      expect(out.env?.PATH).toBeUndefined()
+    }
+  })
+
+  it('rejects non-string args entries', () => {
+    const out = parseSpawnBody({ cli: 'claude', args: ['--print', 42] })
+    expect(typeof out).toBe('string')
+  })
+
+  it('treats body that is not an object as invalid', () => {
+    expect(typeof parseSpawnBody(null)).toBe('string')
+    expect(typeof parseSpawnBody('hi')).toBe('string')
+    expect(typeof parseSpawnBody([])).toBe('string')
+  })
+})
+
+describe('allow-list integrity', () => {
+  it('contains exactly the four expected binaries', () => {
+    expect([...__test.ALLOWED_CLIS].sort()).toEqual(['claude', 'codex', 'copilot', 'opencode'])
+  })
+
+  it('does not include PATH/HOME in safe env keys', () => {
+    expect(__test.SAFE_ENV_KEYS.has('PATH')).toBe(false)
+    expect(__test.SAFE_ENV_KEYS.has('HOME')).toBe(false)
+  })
+})
+
+describe('permissionLevelOfArgs (server-side flag re-derivation)', () => {
+  it('detects bypass-level flags across CLIs', () => {
+    expect(permissionLevelOfArgs(['--print', '--dangerously-skip-permissions'])).toBe('bypass')
+    expect(permissionLevelOfArgs(['exec', '--dangerously-bypass-approvals-and-sandbox'])).toBe('bypass')
+    expect(permissionLevelOfArgs(['--allow-all', '--allow-all-tools', '--no-ask-user'])).toBe('bypass')
+  })
+
+  it('detects default-level (sandboxed/minimal) flags', () => {
+    expect(permissionLevelOfArgs(['exec', '--full-auto'])).toBe('default')
+    expect(permissionLevelOfArgs(['--allow-all-tools', '--no-ask-user', '-p', 'hi'])).toBe('default')
+    expect(permissionLevelOfArgs(['--print', '--permission-mode', 'default'])).toBe('default')
+  })
+
+  it('treats plan / no-flag argv as the safest level', () => {
+    expect(permissionLevelOfArgs(['--print', '--permission-mode', 'plan'])).toBe('plan')
+    expect(permissionLevelOfArgs(['exec', '--sandbox', 'read-only'])).toBe('plan')
+    expect(permissionLevelOfArgs(['run', '--format=json'])).toBe('plan')
+  })
+
+  // Synonym spellings the client never emits but a crafted request could
+  // substitute — each used to derive as `plan` and slip under the cap.
+  it('treats claude --permission-mode bypassPermissions as bypass (pair and = forms)', () => {
+    expect(permissionLevelOfArgs(['--print', '--permission-mode', 'bypassPermissions'])).toBe('bypass')
+    expect(permissionLevelOfArgs(['--print', '--permission-mode=bypassPermissions'])).toBe('bypass')
+  })
+
+  it('treats claude --permission-mode acceptEdits (and unknown future modes) as at least default', () => {
+    expect(permissionLevelOfArgs(['--print', '--permission-mode', 'acceptEdits'])).toBe('default')
+    expect(permissionLevelOfArgs(['--print', '--permission-mode', 'someFutureMode'])).toBe('default')
+  })
+
+  it('treats codex --sandbox danger-full-access as bypass (pair, =, and -s forms)', () => {
+    expect(permissionLevelOfArgs(['exec', '--sandbox', 'danger-full-access'])).toBe('bypass')
+    expect(permissionLevelOfArgs(['exec', '--sandbox=danger-full-access'])).toBe('bypass')
+    expect(permissionLevelOfArgs(['exec', '-s', 'danger-full-access'])).toBe('bypass')
+  })
+
+  it('treats codex --sandbox workspace-write as default', () => {
+    expect(permissionLevelOfArgs(['exec', '--sandbox', 'workspace-write'])).toBe('default')
+  })
+
+  it('treats codex --ask-for-approval never as bypass unless the sandbox is explicitly read-only', () => {
+    // No sandbox flag: the effective sandbox comes from config.toml — assume worst.
+    expect(permissionLevelOfArgs(['exec', '--ask-for-approval', 'never'])).toBe('bypass')
+    expect(permissionLevelOfArgs(['exec', '-a', 'never', '--sandbox', 'workspace-write'])).toBe('bypass')
+    expect(permissionLevelOfArgs(['exec', '-a=never', '--sandbox', 'workspace-write'])).toBe('bypass')
+    // OS-enforced read-only sandbox: never-ask grants nothing extra.
+    expect(permissionLevelOfArgs(['exec', '-a', 'never', '--sandbox', 'read-only'])).toBe('plan')
+  })
+
+  it('maps every client-emitted flag set (permission-mode-flags.ts) to its true level', () => {
+    // claude: 1:1 native modes.
+    expect(permissionLevelOfArgs(claudePermissionFlags('plan'))).toBe('plan')
+    expect(permissionLevelOfArgs(claudePermissionFlags('default'))).toBe('default')
+    expect(permissionLevelOfArgs(claudePermissionFlags('bypass'))).toBe('bypass')
+    // codex: sandbox-driven.
+    expect(permissionLevelOfArgs(codexPermissionFlags('plan'))).toBe('plan')
+    expect(permissionLevelOfArgs(codexPermissionFlags('default'))).toBe('default')
+    expect(permissionLevelOfArgs(codexPermissionFlags('bypass'))).toBe('bypass')
+    // opencode: plan/default emit no flags (the CLI prompts/stalls instead of
+    // writing), so the safest `plan` floor is correct for both.
+    expect(permissionLevelOfArgs(opencodePermissionFlags('plan'))).toBe('plan')
+    expect(permissionLevelOfArgs(opencodePermissionFlags('default'))).toBe('plan')
+    expect(permissionLevelOfArgs(opencodePermissionFlags('bypass'))).toBe('bypass')
+    // ...but what the client *actually* spawns for requested-default on
+    // opencode is the headless-normalized mode (default → bypass).
+    expect(permissionLevelOfArgs(opencodePermissionFlags(normalizeHeadlessMode('default', 'opencode')))).toBe('bypass')
+    // copilot: plan and default share flags (plan is prompt-enforced), so plan
+    // derives as `default` — conservative over-count, never an under-count.
+    expect(permissionLevelOfArgs(copilotPermissionFlags('plan'))).toBe('default')
+    expect(permissionLevelOfArgs(copilotPermissionFlags('default'))).toBe('default')
+    expect(permissionLevelOfArgs(copilotPermissionFlags('bypass'))).toBe('bypass')
+  })
+})
+
+describe('maxPermissionCap (ANNOTASK_MAX_PERMISSION)', () => {
+  afterEach(() => { delete process.env.ANNOTASK_MAX_PERMISSION })
+
+  it('defaults to bypass (no restriction) when unset or invalid', () => {
+    delete process.env.ANNOTASK_MAX_PERMISSION
+    expect(maxPermissionCap()).toBe('bypass')
+    process.env.ANNOTASK_MAX_PERMISSION = 'nonsense'
+    expect(maxPermissionCap()).toBe('bypass')
+  })
+
+  it('reads plan and default caps (case-insensitive, trimmed)', () => {
+    process.env.ANNOTASK_MAX_PERMISSION = ' Plan '
+    expect(maxPermissionCap()).toBe('plan')
+    process.env.ANNOTASK_MAX_PERMISSION = 'default'
+    expect(maxPermissionCap()).toBe('default')
+  })
+})
+
+describe('exceedsPermissionCap applied to init flags (the init-pipeline floor)', () => {
+  afterEach(() => { delete process.env.ANNOTASK_MAX_PERMISSION })
+  const bins = ['claude', 'codex', 'opencode', 'copilot'] as const
+
+  it('no cap → init agent is never blocked on any CLI', () => {
+    delete process.env.ANNOTASK_MAX_PERMISSION
+    for (const bin of bins) {
+      expect(exceedsPermissionCap(initPermissionFlagsFor(bin))).toBeNull()
+    }
+  })
+
+  it("cap=default → blocks claude/opencode (bypass) but allows codex/copilot (sandboxed default)", () => {
+    process.env.ANNOTASK_MAX_PERMISSION = 'default'
+    expect(exceedsPermissionCap(initPermissionFlagsFor('claude'))).toMatchObject({ level: 'bypass', cap: 'default' })
+    expect(exceedsPermissionCap(initPermissionFlagsFor('opencode'))).toMatchObject({ level: 'bypass', cap: 'default' })
+    expect(exceedsPermissionCap(initPermissionFlagsFor('codex'))).toBeNull()
+    expect(exceedsPermissionCap(initPermissionFlagsFor('copilot'))).toBeNull()
+  })
+
+  it('cap=plan → blocks every init agent (init must write, plan cannot)', () => {
+    process.env.ANNOTASK_MAX_PERMISSION = 'plan'
+    for (const bin of bins) {
+      expect(exceedsPermissionCap(initPermissionFlagsFor(bin))).not.toBeNull()
+    }
+  })
+})
+
+describe('parseSpawnBody — taskId', () => {
+  it('accepts a valid task id and rejects malformed ones', () => {
+    const ok = parseSpawnBody({ cli: 'claude', args: [], taskId: 'task-abc_1-XYZ' })
+    expect(typeof ok === 'string').toBe(false)
+    if (typeof ok !== 'string') expect(ok.taskId).toBe('task-abc_1-XYZ')
+    expect(typeof parseSpawnBody({ cli: 'claude', args: [], taskId: '../evil' })).toBe('string')
+    expect(typeof parseSpawnBody({ cli: 'claude', args: [], taskId: 'nope' })).toBe('string')
+    expect(typeof parseSpawnBody({ cli: 'claude', args: [], taskId: 123 })).toBe('string')
+    // Absent taskId is fine (free-form chat / non-task runs).
+    expect(typeof parseSpawnBody({ cli: 'claude', args: [] }) === 'string').toBe(false)
+  })
+})
+
+describe('run registry — per-task dedup + orphan hook', () => {
+  it('rejects a second spawn for a task already running (cross-tab dedup)', async () => {
+    const child = new FakeChild()
+    const handler = createAgentSpawnHandler({ spawnImpl: fakeSpawn(child) })
+
+    // Run 1 starts and parks awaiting the child's close.
+    const p1 = handler.handleSpawn(fakeReq(), fakeRes(), { cli: 'claude', args: [], taskId: 'task-dup' }, '/tmp')
+    expect(handler.registry.taskRunning('task-dup')).toBe(true)
+
+    // Run 2 for the SAME task is refused with 409 — no second child.
+    const res2 = fakeRes()
+    await handler.handleSpawn(fakeReq(), res2, { cli: 'claude', args: [], taskId: 'task-dup' }, '/tmp')
+    expect(res2.statusCode).toBe(409)
+    expect(res2.body).toContain('already running')
+    expect(handler.registry.taskRunning('task-dup')).toBe(true) // run 1 still holds it
+
+    // Finishing run 1 releases the task slot.
+    child.finish(0)
+    await p1
+    expect(handler.registry.taskRunning('task-dup')).toBe(false)
+  })
+
+  it('fires onRunEnd with the task id when a run ends (orphan-finalization hook)', async () => {
+    const ended: string[] = []
+    const child = new FakeChild()
+    const handler = createAgentSpawnHandler({ spawnImpl: fakeSpawn(child), onRunEnd: (id) => ended.push(id) })
+    const p = handler.handleSpawn(fakeReq(), fakeRes(), { cli: 'claude', args: [], taskId: 'task-orphan' }, '/tmp')
+    child.finish(0)
+    await p
+    expect(ended).toEqual(['task-orphan'])
+  })
+
+  it('does not dedup or fire the hook for runs without a taskId', async () => {
+    const ended: string[] = []
+    const child = new FakeChild()
+    const handler = createAgentSpawnHandler({ spawnImpl: fakeSpawn(child), onRunEnd: (id) => ended.push(id) })
+    const p = handler.handleSpawn(fakeReq(), fakeRes(), { cli: 'claude', args: [] }, '/tmp')
+    expect(handler.registry.size()).toBe(1)
+    child.finish(0)
+    await p
+    expect(ended).toEqual([]) // no taskId → no orphan reconciliation
+  })
+})
+
+describe('origin policy', () => {
+  // Spawn routes use originMatchesPort — that gate lives in api.ts and is
+  // exercised end-to-end (real middleware + real spawn handler over a real
+  // socket) in agent-spawn-http.test.ts. (api.test.ts stubs handleSpawn, so
+  // it does NOT cover it.) Here we verify the unit-level contract:
+  // gh is no longer spawnable.
+  it('rejects gh as a CLI', () => {
+    const out = parseSpawnBody({ cli: 'gh', args: ['pr', 'list'] })
+    expect(typeof out).toBe('string')
+    expect(out as string).toMatch(/must be one of/)
+  })
+})
+
+describe('process-group kill', () => {
+  // Beyond Linux's pid_max (4_194_304) and macOS's (99_998): if an unref'd
+  // SIGKILL grace timer ever fires after the process.kill spy is restored,
+  // the real syscall can only land on ESRCH — never on a live process group.
+  const FAKE_PID = 2 ** 30
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+    vi.useRealTimers()
+  })
+
+  it('spawns detached on POSIX so the child leads its own process group', async () => {
+    let captured: { detached?: boolean } | undefined
+    const child = new FakeChild()
+    const spawnImpl = ((_cmd: string, _args: string[], opts: { detached?: boolean }) => {
+      captured = opts
+      return child as unknown as ChildProcessWithoutNullStreams
+    }) as unknown as typeof nodeSpawn
+    const handler = createAgentSpawnHandler({ spawnImpl })
+    const p = handler.handleSpawn(fakeReq(), fakeRes(), { cli: 'claude', args: [] }, '/tmp')
+    child.finish(0)
+    await p
+    expect(captured?.detached).toBe(process.platform !== 'win32')
+  })
+
+  it('kills the process group: SIGTERM, then SIGKILL after the grace period', async () => {
+    if (process.platform === 'win32') return // no process groups on Windows
+    vi.useFakeTimers()
+    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true)
+    const child = new FakeChild()
+    child.pid = FAKE_PID
+    const handler = createAgentSpawnHandler({ spawnImpl: fakeSpawn(child) })
+    const req = fakeReq()
+    const p = handler.handleSpawn(req, fakeRes(), { cli: 'claude', args: [] }, '/tmp')
+
+    // Client disconnect → killChild → group SIGTERM.
+    ;(req as unknown as EventEmitter).emit('close')
+    expect(killSpy).toHaveBeenCalledWith(-FAKE_PID, 'SIGTERM')
+    expect(child.killed).toBe(false) // group signal used, not the direct child.kill
+
+    // Grace period elapses with the child still alive → group SIGKILL.
+    vi.advanceTimersByTime(2_000)
+    expect(killSpy).toHaveBeenCalledWith(-FAKE_PID, 'SIGKILL')
+
+    // A second disconnect event must not re-signal (killed-flag idempotency).
+    const calls = killSpy.mock.calls.length
+    ;(req as unknown as EventEmitter).emit('close')
+    expect(killSpy.mock.calls.length).toBe(calls)
+
+    child.finish(143)
+    await p
+  })
+
+  it('falls back to the direct child.kill when the group signal throws ESRCH', async () => {
+    if (process.platform === 'win32') return
+    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => {
+      throw Object.assign(new Error('kill ESRCH'), { code: 'ESRCH' })
+    })
+    const child = new FakeChild()
+    child.pid = FAKE_PID
+    const handler = createAgentSpawnHandler({ spawnImpl: fakeSpawn(child) })
+    const req = fakeReq()
+    const p = handler.handleSpawn(req, fakeRes(), { cli: 'claude', args: [] }, '/tmp')
+    ;(req as unknown as EventEmitter).emit('close')
+    expect(killSpy).toHaveBeenCalledWith(-FAKE_PID, 'SIGTERM')
+    expect(child.killed).toBe(true) // graceful fallback still terminated the child
+    child.finish(143)
+    await p
+  })
+
+  it('uses the direct child.kill when the child has no pid (spawn seam / failed spawn)', async () => {
+    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true)
+    const child = new FakeChild() // pid stays undefined
+    const handler = createAgentSpawnHandler({ spawnImpl: fakeSpawn(child) })
+    const req = fakeReq()
+    const p = handler.handleSpawn(req, fakeRes(), { cli: 'claude', args: [] }, '/tmp')
+    ;(req as unknown as EventEmitter).emit('close')
+    expect(killSpy).not.toHaveBeenCalled()
+    expect(child.killed).toBe(true)
+    child.finish(143)
+    await p
+  })
+})
diff --git a/src/server/__tests__/apply-cli-matrix.test.ts b/src/server/__tests__/apply-cli-matrix.test.ts
new file mode 100644
index 0000000..792a6cc
--- /dev/null
+++ b/src/server/__tests__/apply-cli-matrix.test.ts
@@ -0,0 +1,257 @@
+/**
+ * LIVE task-apply e2e smoke — all 4 local CLIs against the marketing playground.
+ *
+ * Proves the *apply* half of the embedded-agent feature end to end: a real
+ * pending design task is handed to a real local CLI, the CLI edits the project
+ * source, the change lands on disk, and the task advances to `review`. This is
+ * the live counterpart to the mocked `useEmbeddedAgent` unit tests and the
+ * init-only `init-cli-matrix-stress.test.ts`.
+ *
+ * Resettable target: each CLI gets an isolated temp copy of the marketing
+ * playground materialized from the `demo/marketing-before` git tag (the flawed
+ * "AI first-draft" state) — so runs are repeatable and never touch the working
+ * tree. Discarded after each run (keep with ANNOTASK_CLI_MATRIX_KEEP=1).
+ *
+ * Permission: we deliberately pass NO permissionMode, so each provider falls
+ * back to its Auto default (`defaultPermissionModeFor`): claude/opencode →
+ * bypass, codex/copilot → sandboxed/minimal. This asserts the *safe out-of-box
+ * default actually applies a task* on every CLI.
+ *
+ * Skipped by default. Enable with ANNOTASK_LIVE_CLI=1:
+ *   ANNOTASK_LIVE_CLI=1 pnpm test:apply-matrix
+ *   ANNOTASK_LIVE_CLI=1 ANNOTASK_LIVE_ONLY=claude,codex pnpm test:apply-matrix
+ */
+import { describe, it, expect, afterAll } from 'vitest'
+import http from 'node:http'
+import type { AddressInfo } from 'node:net'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+import { createAgentSpawnHandler } from '../agent-spawn.js'
+import { createAgentDetector } from '../agent-detect.js'
+import { createProjectState } from '../state.js'
+import { ClaudeLocalProvider } from '../../embedded/claude-local-provider.js'
+import { CodexLocalProvider } from '../../embedded/codex-local-provider.js'
+import { OpencodeLocalProvider } from '../../embedded/opencode-local-provider.js'
+import { CopilotLocalProvider } from '../../embedded/copilot-local-provider.js'
+import type { LLMProvider, ProviderEvent } from '../../embedded/provider.js'
+import {
+  LIVE_CLI_ENABLED,
+  isLiveCliEnabled,
+  liveModelFor,
+  type LiveProviderKey,
+} from '../../embedded/__tests__/live-cli-helpers.js'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = path.resolve(HERE, '..', '..', '..')
+const BEFORE_TAG = 'demo/marketing-before'
+const MARKETING_REL = 'playgrounds/simple/marketing'
+
+const KEEP_WORKSPACES = process.env.ANNOTASK_CLI_MATRIX_KEEP === '1'
+const CLI_KEYS: LiveProviderKey[] = ['claude-local', 'codex-local', 'opencode-local', 'copilot-local']
+const describeIf = LIVE_CLI_ENABLED ? describe : describe.skip
+const PER_CLI_TIMEOUT_MS = 6 * 60_000
+
+/** Materialize one file from the demo/marketing-before tag (the flawed baseline). */
+function fileFromBeforeTag(relInPlayground: string): string {
+  return execFileSync('git', ['show', `${BEFORE_TAG}:${MARKETING_REL}/${relInPlayground}`], {
+    cwd: REPO_ROOT,
+    encoding: 'utf-8',
+    maxBuffer: 8 * 1024 * 1024,
+  })
+}
+
+/** The seeded "real issue": the hero CTA buttons are cramped. A deterministic
+ *  style_update so the assertion is unambiguous. */
+function seedTaskPayload(): Record<string, unknown> {
+  return {
+    type: 'style_update',
+    description: 'The hero CTA buttons feel cramped — give them more vertical padding and round the corners a little more.',
+    file: 'src/style.css',
+    line: 58,
+    context: {
+      changes: [
+        { element: '.btn', property: 'padding', before: '11px 20px', after: '14px 20px' },
+        { element: '.btn', property: 'border-radius', before: '10px', after: '12px' },
+      ],
+    },
+  }
+}
+
+function buildApplyPrompts(task: { id: string; type: string; description: string; file: string; context?: { changes?: Array<Record<string, string>> } }) {
+  const systemPrompt = [
+    'You are an automated UI-fix agent applying ONE design task to a local web project.',
+    'Use your file-editing tools to change the project source so the task is satisfied.',
+    'Make ONLY the change the task describes. Do not start a dev server, do not ask questions,',
+    'do not touch unrelated files. When the edit is saved to disk, you are done — stop.',
+  ].join('\n')
+  const changes = (task.context?.changes ?? [])
+    .map((c) => `  - ${c.element} ${c.property}: \`${c.before}\` -> \`${c.after}\``)
+    .join('\n')
+  const userPrompt = [
+    'Apply this pending Annotask design task, then stop.',
+    '',
+    `Task ${task.id} (${task.type}): ${task.description}`,
+    '',
+    `Edit this exact file in your current working directory: ${task.file}`,
+    'That file exists in THIS project — open and edit it directly. Do NOT search the',
+    'filesystem for other stylesheets or edit any file outside this project root.',
+    'Make exactly these CSS changes to the `.btn` rule:',
+    changes,
+  ].join('\n')
+  return { systemPrompt, userPrompt }
+}
+
+function buildProvider(key: LiveProviderKey, model: string, spawnUrl: string): LLMProvider {
+  switch (key) {
+    case 'claude-local':   return new ClaudeLocalProvider({ model, spawnUrl })
+    case 'opencode-local': return new OpencodeLocalProvider({ model, spawnUrl })
+    case 'codex-local':    return new CodexLocalProvider({ model, spawnUrl })
+    case 'copilot-local':  return new CopilotLocalProvider({ model, spawnUrl })
+  }
+}
+
+describeIf('apply CLI matrix — marketing playground (live)', () => {
+  const createdRoots: string[] = []
+  const detector = createAgentDetector()
+
+  afterAll(async () => {
+    if (KEEP_WORKSPACES) return
+    for (const root of createdRoots) {
+      await fsp.rm(root, { recursive: true, force: true }).catch(() => { /* best effort */ })
+    }
+  })
+
+  async function probe(key: LiveProviderKey): Promise<{ runnable: boolean; reason?: string }> {
+    const snap = await detector.detect()
+    const s = snap[key]
+    if (!s.found) return { runnable: false, reason: `${key} CLI not on PATH` }
+    if (!s.loggedIn) return { runnable: false, reason: `${key} CLI is installed but not logged in` }
+    return { runnable: true }
+  }
+
+  async function runApply(key: LiveProviderKey): Promise<void> {
+    const probed = await probe(key)
+    if (!probed.runnable) {
+      // eslint-disable-next-line no-console
+      console.warn(`[apply] ${key} skipped: ${probed.reason}`)
+      return
+    }
+
+    // 1. Isolated temp workspace. Copy the WHOLE marketing playground (minus
+    //    node_modules/.annotask/dist/.git) so the CLI sees a real project root
+    //    (package.json) and resolves files relative to it — without this anchor,
+    //    opencode falls back to a default project root and edits the wrong tree.
+    //    Then overwrite the two editable files with the flawed "before" baseline.
+    const ws = await fsp.mkdtemp(path.join(os.tmpdir(), `annotask-apply-${key}-`))
+    createdRoots.push(ws)
+    await fsp.cp(path.join(REPO_ROOT, MARKETING_REL), ws, {
+      recursive: true,
+      filter: (src) => !/[/\\](node_modules|\.annotask|dist|\.git)([/\\]|$)/.test(src),
+    })
+    await fsp.writeFile(path.join(ws, 'index.html'), fileFromBeforeTag('index.html'))
+    await fsp.writeFile(path.join(ws, 'src', 'style.css'), fileFromBeforeTag('src/style.css'))
+    // Make the temp dir a real git repo so each CLI's project-root + file-search
+    // is scoped HERE. Without a .git, opencode walks up, finds none, and falls
+    // back to a default project (the real annotask repo) — editing the wrong tree.
+    const git = (args: string[]) => execFileSync('git', args, { cwd: ws, stdio: 'ignore' })
+    git(['init', '-q'])
+    git(['add', '-A'])
+    git(['-c', 'user.email=ci@annotask.test', '-c', 'user.name=annotask-ci', 'commit', '-q', '-m', 'baseline'])
+    const cssPath = path.join(ws, 'src', 'style.css')
+    const before = await fsp.readFile(cssPath, 'utf-8')
+
+    // 2. Seed a real pending task, then lock it (pending -> in_progress),
+    //    mirroring the embedded runner's lockTaskOnStart.
+    const state = createProjectState(ws, () => { /* no ws broadcast in tests */ })
+    const task = (await state.addTask(seedTaskPayload())) as { id: string; type: string; description: string; file: string; context?: { changes?: Array<Record<string, string>> } }
+    await state.updateTask(task.id, { status: 'in_progress' })
+
+    // 3. Spawn server bound to THIS workspace (handleSpawn cwd = ws).
+    const handler = createAgentSpawnHandler()
+    const server = http.createServer(async (req, res) => {
+      if (req.url !== '/__annotask/api/agent/spawn' || req.method !== 'POST') {
+        res.statusCode = 404; res.end(); return
+      }
+      const chunks: Buffer[] = []
+      for await (const c of req) chunks.push(c as Buffer)
+      let parsed: unknown
+      try { parsed = JSON.parse(Buffer.concat(chunks).toString('utf-8')) }
+      catch { res.statusCode = 400; res.end('bad json'); return }
+      await handler.handleSpawn(req, res, parsed, ws)
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as AddressInfo
+    const spawnUrl = `http://127.0.0.1:${port}/__annotask/api/agent/spawn`
+
+    try {
+      // 4. Drive the real CLI through the provider — NO permissionMode, so it
+      //    uses the safe Auto default (the thing we want to prove applies tasks).
+      const model = liveModelFor(key)
+      const provider = buildProvider(key, model, spawnUrl)
+      const { systemPrompt, userPrompt } = buildApplyPrompts(task)
+
+      const started = Date.now()
+      let sawDone = false, sawTool = false, usageIn = 0, usageOut = 0
+      let errorString: string | null = null
+      const textParts: string[] = []
+      for await (const ev of provider.stream(
+        [{ role: 'user', content: userPrompt }], [], { systemPrompt, model, taskId: task.id },
+      ) as AsyncIterable<ProviderEvent>) {
+        if (ev.type === 'text') textParts.push(ev.text)
+        else if (ev.type === 'tool_call') sawTool = true
+        else if (ev.type === 'usage') { usageIn += ev.inputTokens; usageOut += ev.outputTokens }
+        else if (ev.type === 'done') sawDone = true
+        else if (ev.type === 'error') errorString = ev.error
+      }
+      const elapsed = Date.now() - started
+
+      // 5. Assert the edit actually landed in source — scoped to the base
+      //    `.btn { … }` rule so an unrelated `12px`/`14px` elsewhere in the CSS
+      //    can't produce a false positive. (`\.btn\s*\{` won't match `.btn.primary`.)
+      const after = await fsp.readFile(cssPath, 'utf-8')
+      const changed = after !== before
+      const btnRule = after.match(/\.btn\s*\{[^}]*\}/)?.[0] ?? ''
+      const hasPadding = /padding:\s*14px\s+20px/.test(btnRule)
+      const hasRadius = /border-radius:\s*12px/.test(btnRule)
+
+      // 6. Advance the task to review on a clean, correct apply (mirrors markTaskForReview).
+      if (sawDone && changed && hasPadding && hasRadius) {
+        await state.updateTask(task.id, { status: 'review', resolution: 'Applied button padding + radius.' })
+      }
+      const finalStatus = state.getTasks().tasks.find((t: { id: string }) => t.id === task.id)?.status
+
+      // eslint-disable-next-line no-console
+      console.log(
+        `[apply] ${key} model=${model} ${elapsed}ms tokens=${usageIn}/${usageOut} ` +
+        `done=${sawDone} tool=${sawTool} changed=${changed} padding=${hasPadding} radius=${hasRadius} status=${finalStatus}`,
+      )
+      if (!changed) {
+        // eslint-disable-next-line no-console
+        console.log(`[apply] ${key} DID NOT EDIT — agent text tail: ${JSON.stringify(textParts.join('').slice(-400))}`)
+      }
+
+      if (errorString) throw new Error(`[${key}] provider emitted error: ${errorString}`)
+      expect(sawDone, `${key}: stream never emitted 'done'`).toBe(true)
+      // The load-bearing proof is the on-disk edit, not the tool_call event:
+      // copilot applies the change without surfacing tool_call events in its
+      // stream, so `sawTool` is informational only (logged above).
+      expect(changed, `${key}: src/style.css was not modified`).toBe(true)
+      expect(hasPadding, `${key}: .btn padding 14px 20px was not applied`).toBe(true)
+      expect(hasRadius, `${key}: .btn border-radius 12px was not applied`).toBe(true)
+      expect(finalStatus, `${key}: task did not reach 'review'`).toBe('review')
+    } finally {
+      await state.flush()
+      state.dispose()
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+    }
+  }
+
+  for (const key of CLI_KEYS) {
+    const runner = isLiveCliEnabled(key) ? it.concurrent : it.skip
+    runner(`${key} applies a style_update to real source`, () => runApply(key), PER_CLI_TIMEOUT_MS)
+  }
+})
diff --git a/src/server/__tests__/apply-session-matrix.test.ts b/src/server/__tests__/apply-session-matrix.test.ts
new file mode 100644
index 0000000..9649f9f
--- /dev/null
+++ b/src/server/__tests__/apply-session-matrix.test.ts
@@ -0,0 +1,677 @@
+/**
+ * LIVE design-session apply e2e — real local CLIs writing the session's
+ * properties-panel edits into source, with the snapshot engine proving
+ * byte-exact undo afterwards. The M4 acceptance counterpart to
+ * `apply-cli-matrix.test.ts` (which covers classic style_update tasks).
+ *
+ * Flow per CLI: isolated temp Vue project → seed session entries (a literal
+ * text edit + a literal prop edit) → applyDesignSession (snapshot + ONE
+ * wireframe_apply task with context.session) → real CLI applies → task →
+ * review → verifyAppliedEntries flips entries written → revertApplyBatch
+ * restores the original bytes exactly.
+ *
+ * Skipped by default. Enable with ANNOTASK_LIVE_CLI=1:
+ *   ANNOTASK_LIVE_CLI=1 npx vitest run src/server/__tests__/apply-session-matrix.test.ts
+ *   ANNOTASK_LIVE_CLI=1 ANNOTASK_LIVE_ONLY=claude npx vitest run …
+ */
+import { describe, it, expect, afterAll } from 'vitest'
+import http from 'node:http'
+import type { AddressInfo } from 'node:net'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+
+import { createAgentSpawnHandler } from '../agent-spawn.js'
+import { createAgentDetector } from '../agent-detect.js'
+import { createProjectState } from '../state.js'
+import { createSessionStore } from '../session-store.js'
+import { createSnapshotStore } from '../file-snapshots.js'
+import { applyDesignSession, verifyAppliedEntries, revertApplyBatch, type ApplySessionOptions } from '../apply-session.js'
+import { clearBindingClassifyCache } from '../binding-classify.js'
+import { ClaudeLocalProvider } from '../../embedded/claude-local-provider.js'
+import { CodexLocalProvider } from '../../embedded/codex-local-provider.js'
+import { OpencodeLocalProvider } from '../../embedded/opencode-local-provider.js'
+import { CopilotLocalProvider } from '../../embedded/copilot-local-provider.js'
+import type { LLMProvider, ProviderEvent } from '../../embedded/provider.js'
+import {
+  LIVE_CLI_ENABLED,
+  isLiveCliEnabled,
+  liveModelFor,
+  type LiveProviderKey,
+} from '../../embedded/__tests__/live-cli-helpers.js'
+import type { DesignSessionDocument, SessionEntry } from '../../shared/design-session-types.js'
+
+const KEEP_WORKSPACES = process.env.ANNOTASK_CLI_MATRIX_KEEP === '1'
+const CLI_KEYS: LiveProviderKey[] = ['claude-local', 'codex-local', 'opencode-local', 'copilot-local']
+const describeIf = LIVE_CLI_ENABLED ? describe : describe.skip
+const PER_CLI_TIMEOUT_MS = 6 * 60_000
+
+const PAGE_VUE = `<template>
+  <section class="planets-page">
+    <h1 class="title">Planets</h1>
+    <p class="subtitle">A tour of the solar system.</p>
+    <BaseButton label="Reset" kind="ghost" />
+  </section>
+</template>
+
+<script setup lang="ts">
+import BaseButton from '../components/BaseButton.vue'
+</script>
+`
+
+const BUTTON_VUE = `<script setup lang="ts">
+defineProps<{ label: string; kind?: string }>()
+</script>
+
+<template>
+  <button class="base-button" :data-kind="kind">{{ label }}</button>
+</template>
+`
+
+function sessionEntries(): SessionEntry[] {
+  return [
+    {
+      id: 'se-1', ordinal: 1, ts: 1, route: '/planets',
+      change: {
+        id: 'c-1', type: 'text_update', description: 'Change the page heading text to “Worlds”',
+        file: 'src/pages/Page.vue', section: 'template', line: 3, element: 'h1',
+        before: 'Planets', after: 'Worlds',
+      } as SessionEntry['change'],
+      anchor: { file: 'src/pages/Page.vue', line: 3, targetTag: 'h1' },
+      evidence: { classification: 'literal' },
+      live: { status: 'pending' },
+    },
+    {
+      id: 'se-2', ordinal: 2, ts: 2, route: '/planets',
+      change: {
+        id: 'c-2', type: 'component_prop_update', description: 'Set BaseButton label to "Clear filters"',
+        file: 'src/pages/Page.vue', section: 'template', line: 5, element: 'BaseButton',
+        prop: 'label', before: 'Reset', after: 'Clear filters', binding: 'literal', propType: 'string',
+      } as SessionEntry['change'],
+      anchor: { file: 'src/pages/Page.vue', line: 5, targetTag: 'BaseButton' },
+      evidence: { classification: 'literal' },
+      live: { status: 'pending' },
+    },
+  ]
+}
+
+function buildPrompts(task: { id: string; description: string; file: string; context?: Record<string, unknown> }) {
+  const session = (task.context as { session?: { entries?: Array<{ change: Record<string, unknown>; anchor: Record<string, unknown> }> } } | undefined)?.session
+  const lines = (session?.entries ?? []).map((e) => {
+    const c = e.change
+    if (c.type === 'text_update') return `  - In ${e.anchor.file} line ${e.anchor.line}: change the <${c.element}> text from \`${c.before}\` to \`${c.after}\``
+    return `  - In ${e.anchor.file} line ${e.anchor.line}: change <${c.element}> prop \`${c.prop}\` from \`${c.before}\` to \`${c.after}\` (plain literal attribute)`
+  })
+  const systemPrompt = [
+    'You are an automated UI-fix agent applying ONE design-session task to a local web project.',
+    'Use your file-editing tools to make exactly the listed edits. Do not start a dev server,',
+    'do not ask questions, do not touch unrelated files or any file outside this project root.',
+    'Never edit files under .annotask/. When the edits are saved to disk, you are done — stop.',
+  ].join('\n')
+  const userPrompt = [
+    'Apply this pending Annotask design-session task, then stop.',
+    '',
+    `Task ${task.id}: ${task.description}`,
+    '',
+    'Make exactly these edits:',
+    ...lines,
+  ].join('\n')
+  return { systemPrompt, userPrompt }
+}
+
+function buildProvider(key: LiveProviderKey, model: string, spawnUrl: string): LLMProvider {
+  switch (key) {
+    case 'claude-local':   return new ClaudeLocalProvider({ model, spawnUrl })
+    case 'opencode-local': return new OpencodeLocalProvider({ model, spawnUrl })
+    case 'codex-local':    return new CodexLocalProvider({ model, spawnUrl })
+    case 'copilot-local':  return new CopilotLocalProvider({ model, spawnUrl })
+  }
+}
+
+describeIf('design-session apply matrix (live)', () => {
+  const createdRoots: string[] = []
+  const detector = createAgentDetector()
+
+  afterAll(async () => {
+    if (KEEP_WORKSPACES) return
+    for (const root of createdRoots) {
+      await fsp.rm(root, { recursive: true, force: true }).catch(() => { /* best effort */ })
+    }
+  })
+
+  async function probe(key: LiveProviderKey): Promise<{ runnable: boolean; reason?: string }> {
+    const snap = await detector.detect()
+    const s = snap[key]
+    if (!s.found) return { runnable: false, reason: `${key} CLI not on PATH` }
+    if (!s.loggedIn) return { runnable: false, reason: `${key} CLI is installed but not logged in` }
+    return { runnable: true }
+  }
+
+  async function runSessionApply(key: LiveProviderKey): Promise<void> {
+    const probed = await probe(key)
+    if (!probed.runnable) {
+      // eslint-disable-next-line no-console
+      console.warn(`[apply-session] ${key} skipped: ${probed.reason}`)
+      return
+    }
+
+    // 1. Isolated minimal Vue project (git-rooted so the CLI scopes here).
+    const ws = await fsp.mkdtemp(path.join(os.tmpdir(), `annotask-session-${key}-`))
+    createdRoots.push(ws)
+    await fsp.mkdir(path.join(ws, 'src/pages'), { recursive: true })
+    await fsp.mkdir(path.join(ws, 'src/components'), { recursive: true })
+    await fsp.writeFile(path.join(ws, 'package.json'), JSON.stringify({ name: 'session-fixture', private: true }, null, 2))
+    await fsp.writeFile(path.join(ws, 'src/pages/Page.vue'), PAGE_VUE)
+    await fsp.writeFile(path.join(ws, 'src/components/BaseButton.vue'), BUTTON_VUE)
+    const git = (args: string[]) => execFileSync('git', args, { cwd: ws, stdio: 'ignore' })
+    git(['init', '-q'])
+    git(['add', '-A'])
+    git(['-c', 'user.email=ci@annotask.test', '-c', 'user.name=annotask-ci', 'commit', '-q', '-m', 'baseline'])
+    const pagePath = path.join(ws, 'src/pages/Page.vue')
+
+    // 2. Seed the session journal + real stores, then Apply (snapshot + task).
+    const state = createProjectState(ws, () => { /* no ws broadcast in tests */ })
+    const sessionStore = createSessionStore(ws)
+    const current = await sessionStore.get()
+    const doc: DesignSessionDocument = { version: '1.0', sessionId: 'ds-live', startedAt: 1, updatedAt: 1, rev: current.rev, entries: sessionEntries() }
+    await sessionStore.set(doc)
+    const options: ApplySessionOptions = {
+      projectRoot: ws,
+      getDesignSession: () => sessionStore.get(),
+      setDesignSession: (d) => sessionStore.set(d),
+      getWireframe: () => state.getWireframe(),
+      setWireframe: (d) => state.setWireframe(d),
+      addTask: (t) => state.addTask(t),
+      snapshots: createSnapshotStore(ws),
+    }
+    const applied = await applyDesignSession(options, '/planets')
+    expect('error' in applied).toBe(false)
+    if ('error' in applied) return
+    const task = state.getTasks().tasks.find((t) => t.id === applied.taskId) as { id: string; description: string; file: string; context?: Record<string, unknown> }
+    await state.updateTask(task.id, { status: 'in_progress' })
+
+    // 3. Spawn server bound to THIS workspace.
+    const handler = createAgentSpawnHandler()
+    const server = http.createServer(async (req, res) => {
+      if (req.url !== '/__annotask/api/agent/spawn' || req.method !== 'POST') {
+        res.statusCode = 404; res.end(); return
+      }
+      const chunks: Buffer[] = []
+      for await (const c of req) chunks.push(c as Buffer)
+      let parsed: unknown
+      try { parsed = JSON.parse(Buffer.concat(chunks).toString('utf-8')) }
+      catch { res.statusCode = 400; res.end('bad json'); return }
+      await handler.handleSpawn(req, res, parsed, ws)
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as AddressInfo
+    const spawnUrl = `http://127.0.0.1:${port}/__annotask/api/agent/spawn`
+
+    try {
+      // 4. Real CLI applies the session task (safe Auto permission default).
+      const model = liveModelFor(key)
+      const provider = buildProvider(key, model, spawnUrl)
+      const { systemPrompt, userPrompt } = buildPrompts(task)
+      let sawDone = false
+      let errorString: string | null = null
+      for await (const ev of provider.stream(
+        [{ role: 'user', content: userPrompt }], [], { systemPrompt, model, taskId: task.id },
+      ) as AsyncIterable<ProviderEvent>) {
+        if (ev.type === 'done') sawDone = true
+        else if (ev.type === 'error') errorString = ev.error
+      }
+      expect(errorString).toBeNull()
+      expect(sawDone).toBe(true)
+
+      // 5. Both edits landed in source.
+      const after = await fsp.readFile(pagePath, 'utf-8')
+      expect(after).toContain('Worlds')
+      expect(after).toContain('Clear filters')
+
+      // 6. review → verification flips entries written; the batch seals.
+      await state.updateTask(task.id, { status: 'review' })
+      clearBindingClassifyCache()
+      await verifyAppliedEntries(options, task.id)
+      const verified = await sessionStore.get()
+      for (const e of verified.entries) {
+        expect(e.live.status, `${key}: entry ${e.id} → ${JSON.stringify(e.live)}`).toBe('written')
+      }
+
+      // 7. Undo last apply: byte-exact restore.
+      const undo = await revertApplyBatch(options, applied.batchId)
+      expect(undo.skipped).toEqual([])
+      expect(await fsp.readFile(pagePath, 'utf-8')).toBe(PAGE_VUE)
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+      await state.flush()
+      state.dispose()
+    }
+  }
+
+  for (const key of CLI_KEYS) {
+    it.skipIf(!isLiveCliEnabled(key))(
+      `${key} applies a design session, verification marks entries written, undo restores bytes`,
+      async () => { await runSessionApply(key) },
+      PER_CLI_TIMEOUT_MS,
+    )
+  }
+
+  // ── W3: wireframe directions (snapshot-sketch apply) ──────────────────────
+  // The realistic /planets rearrangement from the handoff: move the grid above
+  // the filters, add a "pagination here" placeholder, note on the filters.
+  // Directions are trust-verified (no literal to look for) — the proof here is
+  // the SOURCE: sibling order flipped, placeholder present, bytes restorable.
+
+  const PAGE2_VUE = `<template>
+  <section class="planets-page">
+    <h1 class="title">Planets</h1>
+    <section class="filters">
+      <input class="search" placeholder="Search planets" />
+      <select class="sort"><option>Distance</option><option>Name</option></select>
+    </section>
+    <div class="planet-grid">
+      <article class="planet-card">Mercury</article>
+      <article class="planet-card">Venus</article>
+    </div>
+  </section>
+</template>
+`
+
+  function directionEntries(): SessionEntry[] {
+    const base = { ordinal: 1, ts: 1, route: '/planets', live: { status: 'pending' as const } }
+    return [
+      {
+        ...base, id: 'wd-grid-move',
+        change: {
+          id: 'c-wd-1', type: 'wireframe_direction', op: 'move',
+          description: 'MOVE the planet-grid (src/pages/Page.vue:8): now above the filters (was below); position 0,180 → 0,90 (measured)',
+          file: 'src/pages/Page.vue', section: 'template', line: 8,
+          block: { label: 'planet-grid', tag: 'div' },
+          measured: {
+            before: { x: 0, y: 180, width: 800, height: 600 },
+            after: { x: 0, y: 90, width: 800, height: 600 },
+            dx: 0, dy: -90, relations: ['now above the filters (was below)'],
+          },
+        } as SessionEntry['change'],
+        anchor: { file: 'src/pages/Page.vue', line: 8, targetTag: 'div' },
+      },
+      {
+        ...base, id: 'wd-pagination', ordinal: 2, ts: 2,
+        change: {
+          id: 'c-wd-2', type: 'wireframe_direction', op: 'add',
+          description: 'ADD placeholder "pagination here" (user-sketched box 360x80; keep it visibly a placeholder) after the planet-grid (src/pages/Page.vue:8)',
+          file: 'src/pages/Page.vue', section: 'template', line: 8,
+          block: { label: 'pagination here' },
+          measured: { after: { x: 80, y: 710, width: 360, height: 80 } },
+          added: { kind: 'placeholder', label: 'pagination here', position: 'after' },
+        } as SessionEntry['change'],
+        anchor: { file: 'src/pages/Page.vue', line: 8, targetTag: 'div' },
+      },
+      {
+        ...base, id: 'wd-filters-note', ordinal: 3, ts: 3,
+        change: {
+          id: 'c-wd-3', type: 'wireframe_direction', op: 'note',
+          description: 'NOTE on the filters (src/pages/Page.vue:4): user said: "put the search box and the sort dropdown on one row"',
+          file: 'src/pages/Page.vue', section: 'template', line: 4,
+          block: { label: 'filters', tag: 'section' },
+          note: 'put the search box and the sort dropdown on one row',
+        } as SessionEntry['change'],
+        anchor: { file: 'src/pages/Page.vue', line: 4, targetTag: 'section' },
+      },
+    ]
+  }
+
+  function buildDirectionPrompts(task: { id: string; description: string }) {
+    const systemPrompt = [
+      'You are an automated UI agent implementing ONE Annotask wireframe task in a local web project.',
+      'The user rearranged a snapshot sketch of the page; the task lists anchored directions.',
+      'Pixel positions are hints — implement the INTENT with idiomatic layout (reorder siblings,',
+      'flex/grid changes), never absolute positioning. Placeholders stay visibly labeled',
+      'placeholders — never fabricate data. Use your file-editing tools; do not start a dev',
+      'server, do not ask questions, never edit files under .annotask/. When the edits are',
+      'saved to disk, you are done — stop.',
+    ].join('\n')
+    const userPrompt = [
+      'Implement this pending Annotask wireframe task, then stop.',
+      '',
+      task.description,
+    ].join('\n')
+    return { systemPrompt, userPrompt }
+  }
+
+  async function runDirectionsApply(key: LiveProviderKey): Promise<void> {
+    const probed = await probe(key)
+    if (!probed.runnable) {
+      // eslint-disable-next-line no-console
+      console.warn(`[apply-session directions] ${key} skipped: ${probed.reason}`)
+      return
+    }
+
+    const ws = await fsp.mkdtemp(path.join(os.tmpdir(), `annotask-directions-${key}-`))
+    createdRoots.push(ws)
+    await fsp.mkdir(path.join(ws, 'src/pages'), { recursive: true })
+    await fsp.writeFile(path.join(ws, 'package.json'), JSON.stringify({ name: 'directions-fixture', private: true }, null, 2))
+    await fsp.writeFile(path.join(ws, 'src/pages/Page.vue'), PAGE2_VUE)
+    const git = (args: string[]) => execFileSync('git', args, { cwd: ws, stdio: 'ignore' })
+    git(['init', '-q'])
+    git(['add', '-A'])
+    git(['-c', 'user.email=ci@annotask.test', '-c', 'user.name=annotask-ci', 'commit', '-q', '-m', 'baseline'])
+    const pagePath = path.join(ws, 'src/pages/Page.vue')
+
+    const state = createProjectState(ws, () => { /* no ws broadcast in tests */ })
+    const sessionStore = createSessionStore(ws)
+    const current = await sessionStore.get()
+    const doc: DesignSessionDocument = { version: '1.0', sessionId: 'ds-directions', startedAt: 1, updatedAt: 1, rev: current.rev, entries: directionEntries() }
+    await sessionStore.set(doc)
+    const options: ApplySessionOptions = {
+      projectRoot: ws,
+      getDesignSession: () => sessionStore.get(),
+      setDesignSession: (d) => sessionStore.set(d),
+      getWireframe: () => state.getWireframe(),
+      setWireframe: (d) => state.setWireframe(d),
+      addTask: (t) => state.addTask(t),
+      snapshots: createSnapshotStore(ws),
+    }
+    const applied = await applyDesignSession(options, '/planets')
+    expect('error' in applied).toBe(false)
+    if ('error' in applied) return
+    const task = state.getTasks().tasks.find((t) => t.id === applied.taskId) as { id: string; description: string }
+    expect(task.description).toContain('Implement the wireframe sketch on /planets')
+    await state.updateTask(task.id, { status: 'in_progress' })
+
+    const handler = createAgentSpawnHandler()
+    const server = http.createServer(async (req, res) => {
+      if (req.url !== '/__annotask/api/agent/spawn' || req.method !== 'POST') {
+        res.statusCode = 404; res.end(); return
+      }
+      const chunks: Buffer[] = []
+      for await (const c of req) chunks.push(c as Buffer)
+      let parsed: unknown
+      try { parsed = JSON.parse(Buffer.concat(chunks).toString('utf-8')) }
+      catch { res.statusCode = 400; res.end('bad json'); return }
+      await handler.handleSpawn(req, res, parsed, ws)
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as AddressInfo
+    const spawnUrl = `http://127.0.0.1:${port}/__annotask/api/agent/spawn`
+
+    try {
+      const model = liveModelFor(key)
+      const provider = buildProvider(key, model, spawnUrl)
+      const { systemPrompt, userPrompt } = buildDirectionPrompts(task)
+      let sawDone = false
+      let errorString: string | null = null
+      for await (const ev of provider.stream(
+        [{ role: 'user', content: userPrompt }], [], { systemPrompt, model, taskId: task.id },
+      ) as AsyncIterable<ProviderEvent>) {
+        if (ev.type === 'done') sawDone = true
+        else if (ev.type === 'error') errorString = ev.error
+      }
+      expect(errorString).toBeNull()
+      expect(sawDone).toBe(true)
+
+      // The INTENT landed: grid now precedes the filters; a visible pagination
+      // placeholder exists. (The filters note is open-ended by design — its
+      // success is not literally checkable, which is exactly why directions
+      // are trust-verified.)
+      const after = await fsp.readFile(pagePath, 'utf-8')
+      expect(after.indexOf('planet-grid'), `${key}: grid must come before filters\n${after}`).toBeLessThan(after.indexOf('class="filters"'))
+      expect(after).toMatch(/pagination/i)
+
+      // review → directions flip written on trust; the batch seals.
+      await state.updateTask(task.id, { status: 'review' })
+      clearBindingClassifyCache()
+      await verifyAppliedEntries(options, task.id)
+      const verified = await sessionStore.get()
+      for (const e of verified.entries) {
+        expect(e.live.status, `${key}: entry ${e.id} → ${JSON.stringify(e.live)}`).toBe('written')
+      }
+
+      // Undo last apply: byte-exact restore.
+      const undo = await revertApplyBatch(options, applied.batchId)
+      expect(undo.skipped).toEqual([])
+      expect(await fsp.readFile(pagePath, 'utf-8')).toBe(PAGE2_VUE)
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+      await state.flush()
+      state.dispose()
+    }
+  }
+
+  for (const key of CLI_KEYS) {
+    it.skipIf(!isLiveCliEnabled(key))(
+      `${key} implements wireframe directions, trust-verify marks them written, undo restores bytes`,
+      async () => { await runDirectionsApply(key) },
+      PER_CLI_TIMEOUT_MS,
+    )
+  }
+
+  // ── D6: data-bound add direction (wireframe binding apply) ────────────────
+  // A PlanetCard component bound to the REAL usePlanets composable. The page
+  // starts with an EMPTY content section and ZERO planet names anywhere, so
+  // fabrication is assertable: the agent must import + call the real source
+  // and render the bound fields — never invent data, never rewrite the
+  // composable or the card.
+
+  const PAGE3_VUE = `<template>
+  <section class="planets-page">
+    <h1 class="title">Planets</h1>
+    <section class="content">
+    </section>
+  </section>
+</template>
+`
+
+  const TYPES_TS = `export interface Planet {
+  name: string
+  type: string
+}
+`
+
+  const USE_PLANETS_TS = `import { ref } from 'vue'
+import type { Planet } from '../types'
+
+export function usePlanets() {
+  const planets = ref<Planet[]>([])
+  const loading = ref(false)
+  async function load(): Promise<void> {
+    loading.value = true
+    try {
+      const res = await fetch('/api/solar/planets')
+      planets.value = (await res.json()).planets
+    } finally {
+      loading.value = false
+    }
+  }
+  return { planets, loading, load }
+}
+`
+
+  const PLANET_CARD_VUE = `<script setup lang="ts">
+defineProps<{ name: string; type: string }>()
+</script>
+
+<template>
+  <article class="planet-card">
+    <strong>{{ name }}</strong>
+    <span class="type">{{ type }}</span>
+  </article>
+</template>
+`
+
+  function bindingDirectionEntries(): SessionEntry[] {
+    return [
+      {
+        id: 'wd-card-binding', ordinal: 1, ts: 1, route: '/planets', live: { status: 'pending' as const },
+        change: {
+          id: 'c-wd-b1', type: 'wireframe_direction', op: 'add',
+          description: 'ADD component <PlanetCard> inside the content section (src/pages/Page.vue:4); bind to the composable usePlanets → planets[] (show name, type) [shape: source-details]',
+          file: 'src/pages/Page.vue', section: 'template', line: 4,
+          block: { label: 'planet cards', component: 'PlanetCard', tag: 'section' },
+          measured: { after: { x: 0, y: 120, width: 800, height: 400 } },
+          added: {
+            kind: 'component',
+            componentName: 'PlanetCard',
+            library: 'Project',
+            module: 'src/components/PlanetCard.vue',
+            position: 'append',
+            data: {
+              kind: 'composable',
+              name: 'usePlanets',
+              module: 'src/composables/usePlanets.ts',
+              path: 'planets[]',
+              fields: ['name', 'type'],
+              shape_source: 'source-details',
+            },
+          },
+        } as SessionEntry['change'],
+        anchor: { file: 'src/pages/Page.vue', line: 4, targetTag: 'section' },
+      },
+    ]
+  }
+
+  // Production parity: the real agent reads context.session.entries — append
+  // the entry's serialized `added` payload (binding included) to the prompt
+  // the same way the playbook tells it to read the task context.
+  function buildBindingPrompts(task: { id: string; description: string; context?: Record<string, unknown> }) {
+    const session = (task.context as { session?: { entries?: Array<{ change: Record<string, unknown> }> } } | undefined)?.session
+    const added = (session?.entries ?? []).map((e) => JSON.stringify({ added: e.change.added }, null, 2))
+    const systemPrompt = [
+      'You are an automated UI agent implementing ONE Annotask wireframe task in a local web project.',
+      'The task adds a data-bound component. `added.data` names a REAL data source in this project —',
+      'wire THAT source the way the project defines it (same import path, same call pattern), loop',
+      'over the collection named by `data.path`, and render the keys in `data.fields`. Never invent',
+      'data, fields, or sample items; never rewrite the data source or the component you are placing.',
+      'Use your file-editing tools; do not start a dev server, do not ask questions, never edit files',
+      'under .annotask/. When the edits are saved to disk, you are done — stop.',
+    ].join('\n')
+    const userPrompt = [
+      'Implement this pending Annotask wireframe task, then stop.',
+      '',
+      task.description,
+      '',
+      'Structured direction payload:',
+      ...added,
+    ].join('\n')
+    return { systemPrompt, userPrompt }
+  }
+
+  async function runBindingApply(key: LiveProviderKey): Promise<void> {
+    const probed = await probe(key)
+    if (!probed.runnable) {
+      // eslint-disable-next-line no-console
+      console.warn(`[apply-session binding] ${key} skipped: ${probed.reason}`)
+      return
+    }
+
+    const ws = await fsp.mkdtemp(path.join(os.tmpdir(), `annotask-binding-${key}-`))
+    createdRoots.push(ws)
+    await fsp.mkdir(path.join(ws, 'src/pages'), { recursive: true })
+    await fsp.mkdir(path.join(ws, 'src/components'), { recursive: true })
+    await fsp.mkdir(path.join(ws, 'src/composables'), { recursive: true })
+    await fsp.writeFile(path.join(ws, 'package.json'), JSON.stringify({ name: 'binding-fixture', private: true }, null, 2))
+    await fsp.writeFile(path.join(ws, 'src/pages/Page.vue'), PAGE3_VUE)
+    await fsp.writeFile(path.join(ws, 'src/types.ts'), TYPES_TS)
+    await fsp.writeFile(path.join(ws, 'src/composables/usePlanets.ts'), USE_PLANETS_TS)
+    await fsp.writeFile(path.join(ws, 'src/components/PlanetCard.vue'), PLANET_CARD_VUE)
+    const git = (args: string[]) => execFileSync('git', args, { cwd: ws, stdio: 'ignore' })
+    git(['init', '-q'])
+    git(['add', '-A'])
+    git(['-c', 'user.email=ci@annotask.test', '-c', 'user.name=annotask-ci', 'commit', '-q', '-m', 'baseline'])
+    const pagePath = path.join(ws, 'src/pages/Page.vue')
+
+    const state = createProjectState(ws, () => { /* no ws broadcast in tests */ })
+    const sessionStore = createSessionStore(ws)
+    const current = await sessionStore.get()
+    const doc: DesignSessionDocument = { version: '1.0', sessionId: 'ds-binding', startedAt: 1, updatedAt: 1, rev: current.rev, entries: bindingDirectionEntries() }
+    await sessionStore.set(doc)
+    const options: ApplySessionOptions = {
+      projectRoot: ws,
+      getDesignSession: () => sessionStore.get(),
+      setDesignSession: (d) => sessionStore.set(d),
+      getWireframe: () => state.getWireframe(),
+      setWireframe: (d) => state.setWireframe(d),
+      addTask: (t) => state.addTask(t),
+      snapshots: createSnapshotStore(ws),
+    }
+    const applied = await applyDesignSession(options, '/planets')
+    expect('error' in applied).toBe(false)
+    if ('error' in applied) return
+    const task = state.getTasks().tasks.find((t) => t.id === applied.taskId) as { id: string; description: string; context?: Record<string, unknown> }
+    await state.updateTask(task.id, { status: 'in_progress' })
+
+    const handler = createAgentSpawnHandler()
+    const server = http.createServer(async (req, res) => {
+      if (req.url !== '/__annotask/api/agent/spawn' || req.method !== 'POST') {
+        res.statusCode = 404; res.end(); return
+      }
+      const chunks: Buffer[] = []
+      for await (const c of req) chunks.push(c as Buffer)
+      let parsed: unknown
+      try { parsed = JSON.parse(Buffer.concat(chunks).toString('utf-8')) }
+      catch { res.statusCode = 400; res.end('bad json'); return }
+      await handler.handleSpawn(req, res, parsed, ws)
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as AddressInfo
+    const spawnUrl = `http://127.0.0.1:${port}/__annotask/api/agent/spawn`
+
+    try {
+      const model = liveModelFor(key)
+      const provider = buildProvider(key, model, spawnUrl)
+      const { systemPrompt, userPrompt } = buildBindingPrompts(task)
+      let sawDone = false
+      let errorString: string | null = null
+      for await (const ev of provider.stream(
+        [{ role: 'user', content: userPrompt }], [], { systemPrompt, model, taskId: task.id },
+      ) as AsyncIterable<ProviderEvent>) {
+        if (ev.type === 'done') sawDone = true
+        else if (ev.type === 'error') errorString = ev.error
+      }
+      expect(errorString).toBeNull()
+      expect(sawDone).toBe(true)
+
+      // The REAL source is wired: imports + call + loop over planets, fields rendered.
+      const after = await fsp.readFile(pagePath, 'utf-8')
+      expect(after, `${key}: must import the real composable\n${after}`).toMatch(/from ['"]\.{1,2}\/composables\/usePlanets['"]/)
+      expect(after).toMatch(/usePlanets\(/)
+      expect(after).toMatch(/from ['"]\.{1,2}\/components\/PlanetCard(\.vue)?['"]/)
+      expect(after).toMatch(/v-for=/)
+      expect(after).toMatch(/:name=/)
+      expect(after).toMatch(/:type=/)
+      // NEGATIVE: no fabricated sample data — the fixture contains zero planet
+      // names, and the agent must not have invented any.
+      expect(after).not.toMatch(/Mercury|Venus|Earth|Mars|Jupiter/)
+      // The agent wired, it didn't rewrite: source + card byte-identical.
+      expect(await fsp.readFile(path.join(ws, 'src/composables/usePlanets.ts'), 'utf-8')).toBe(USE_PLANETS_TS)
+      expect(await fsp.readFile(path.join(ws, 'src/components/PlanetCard.vue'), 'utf-8')).toBe(PLANET_CARD_VUE)
+
+      // review → the binding direction flips written on trust; the batch seals.
+      await state.updateTask(task.id, { status: 'review' })
+      clearBindingClassifyCache()
+      await verifyAppliedEntries(options, task.id)
+      const verified = await sessionStore.get()
+      for (const e of verified.entries) {
+        expect(e.live.status, `${key}: entry ${e.id} → ${JSON.stringify(e.live)}`).toBe('written')
+      }
+
+      // Undo last apply: byte-exact restore.
+      const undo = await revertApplyBatch(options, applied.batchId)
+      expect(undo.skipped).toEqual([])
+      expect(await fsp.readFile(pagePath, 'utf-8')).toBe(PAGE3_VUE)
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+      await state.flush()
+      state.dispose()
+    }
+  }
+
+  for (const key of CLI_KEYS) {
+    it.skipIf(!isLiveCliEnabled(key))(
+      `${key} wires a data-bound add direction to the REAL source, never fabricates, undo restores bytes`,
+      async () => { await runBindingApply(key) },
+      PER_CLI_TIMEOUT_MS,
+    )
+  }
+})
diff --git a/src/server/__tests__/apply-session.test.ts b/src/server/__tests__/apply-session.test.ts
new file mode 100644
index 0000000..4b7ba4e
--- /dev/null
+++ b/src/server/__tests__/apply-session.test.ts
@@ -0,0 +1,413 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { applyDesignSession, verifyAppliedEntries, revertApplyBatch, releaseApplyTask, acceptApplyTask, type ApplySessionOptions } from '../apply-session'
+import { createSessionStore } from '../session-store'
+import { createWireframeStore } from '../wireframe-store'
+import { createSnapshotStore } from '../file-snapshots'
+import { clearBindingClassifyCache } from '../binding-classify'
+import type { DesignSessionDocument, SessionEntry } from '../../shared/design-session-types'
+import type { WireframeInstance } from '../../shared/wireframe-types'
+
+const PAGE = `<template>
+  <div class="page">
+    <h1 class="title">Planets</h1>
+    <Button label="Reset" />
+  </div>
+</template>
+`
+
+function textEntry(id: string, after = 'Worlds'): SessionEntry {
+  return {
+    id, ordinal: 1, ts: 1, route: '/planets',
+    change: {
+      id: `c-${id}`, type: 'text_update', description: `Change text to “${after}”`,
+      file: 'src/Page.vue', section: 'template', line: 3, element: 'h1', before: 'Planets', after,
+    } as SessionEntry['change'],
+    anchor: { file: 'src/Page.vue', line: 3, targetTag: 'h1' },
+    live: { status: 'pending' },
+  }
+}
+
+function propEntry(id: string): SessionEntry {
+  return {
+    id, ordinal: 2, ts: 2, route: '/planets',
+    change: {
+      id: `c-${id}`, type: 'component_prop_update', description: 'Set Button label to "Clear"',
+      file: 'src/Page.vue', section: 'template', line: 4, element: 'Button',
+      prop: 'label', before: 'Reset', after: 'Clear', binding: 'literal',
+    } as SessionEntry['change'],
+    anchor: { file: 'src/Page.vue', line: 4, targetTag: 'Button' },
+    live: { status: 'pending' },
+  }
+}
+
+function instance(id: string): WireframeInstance {
+  return {
+    id, kind: 'component',
+    anchor: { file: 'src/Page.vue', line: 2, position: 'append', targetTag: 'div' },
+    inserted: { tag: 'planetcard', componentName: 'PlanetCard' },
+    fidelity: 'live', mounted: true, status: 'placed', createdAt: 1,
+  }
+}
+
+function directionEntry(id: string, route = '/planets', ordinal = 1): SessionEntry {
+  return {
+    id, ordinal, ts: ordinal, route,
+    change: {
+      id: `c-${id}`, type: 'wireframe_direction', op: 'move',
+      description: 'MOVE the grid (src/Page.vue:2): now above the filters (was below)',
+      file: 'src/Page.vue', section: 'template', line: 2,
+      block: { label: 'grid', tag: 'div' },
+      measured: {
+        before: { x: 0, y: 180, width: 800, height: 600 },
+        after: { x: 0, y: 90, width: 800, height: 600 },
+        dx: 0, dy: -90, relations: ['now above the filters (was below)'],
+      },
+    } as SessionEntry['change'],
+    anchor: { file: 'src/Page.vue', line: 2, targetTag: 'div' },
+    live: { status: 'pending' },
+  }
+}
+
+describe('apply-session', () => {
+  let root: string
+  let options: ApplySessionOptions
+  let tasks: Array<Record<string, unknown>>
+
+  async function seedSession(entries: SessionEntry[]): Promise<void> {
+    const store = createSessionStore(root)
+    const current = await store.get()
+    const doc: DesignSessionDocument = { version: '1.0', sessionId: 'ds-test', startedAt: 1, updatedAt: 1, rev: current.rev, entries }
+    await store.set(doc)
+  }
+
+  beforeEach(async () => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-apply-'))
+    clearBindingClassifyCache()
+    await fsp.mkdir(path.join(root, 'src'), { recursive: true })
+    await fsp.writeFile(path.join(root, 'src/Page.vue'), PAGE, 'utf-8')
+    tasks = []
+    const sessionStore = createSessionStore(root)
+    const wireframeStore = createWireframeStore(root)
+    options = {
+      projectRoot: root,
+      getDesignSession: () => sessionStore.get(),
+      setDesignSession: (doc) => sessionStore.set(doc),
+      getWireframe: () => wireframeStore.get(),
+      setWireframe: (doc) => wireframeStore.set(doc),
+      addTask: (task) => {
+        const t = { ...task, id: `task-${tasks.length + 1}` }
+        tasks.push(t)
+        return t
+      },
+      snapshots: createSnapshotStore(root),
+    }
+  })
+
+  afterEach(async () => {
+    await fsp.rm(root, { recursive: true, force: true })
+  })
+
+  it('apply: snapshots the touched files, creates ONE task with both context halves, stamps statuses', async () => {
+    await seedSession([textEntry('se-1'), propEntry('se-2')])
+    const wf = await options.getWireframe()
+    await options.setWireframe({ ...wf, updatedAt: 1, routes: [{ route: '/planets', instances: [instance('wfi-1')] }] })
+
+    const result = await applyDesignSession(options, '/planets')
+    expect('error' in result).toBe(false)
+    if ('error' in result) return
+
+    // ONE task, both context halves, envelope cruft stripped.
+    expect(tasks).toHaveLength(1)
+    const ctx = tasks[0].context as { wireframe: { instances: unknown[] }; session: { session_id: string; entries: Array<Record<string, unknown>> } }
+    expect(ctx.wireframe.instances).toHaveLength(1)
+    expect(ctx.session.session_id).toBe('ds-test')
+    expect(ctx.session.entries.map((e) => e.id)).toEqual(['se-1', 'se-2'])
+    expect(ctx.session.entries[0].eid).toBeUndefined()
+
+    // Snapshot journal exists BEFORE any agent could run.
+    const snap = await options.snapshots.state()
+    expect(Object.keys(snap.files)).toEqual(['src/Page.vue'])
+    expect(snap.batches.map((b) => b.id)).toEqual([result.batchId])
+
+    // Instances 'building', entries 'applying'.
+    const wfAfter = await options.getWireframe()
+    expect(wfAfter.routes[0].instances[0]).toMatchObject({ status: 'building', taskId: result.taskId })
+    const session = await options.getDesignSession()
+    for (const e of session.entries) {
+      expect(e.live).toMatchObject({ status: 'applying', applyBatchId: result.batchId })
+      expect(e.taskId).toBe(result.taskId)
+    }
+  })
+
+  it('apply: nothing pending → error, no task', async () => {
+    const result = await applyDesignSession(options, '/planets')
+    expect(result).toEqual({ error: 'nothing to apply' })
+    expect(tasks).toHaveLength(0)
+  })
+
+  it('verify: a landed edit flips written (exact-anchor proof); a missing one flips failed; the batch seals', async () => {
+    await seedSession([textEntry('se-1'), propEntry('se-2')])
+    const result = await applyDesignSession(options, '/planets')
+    if ('error' in result) throw new Error('apply failed')
+
+    // "The agent" applies ONLY the text edit.
+    await fsp.writeFile(path.join(root, 'src/Page.vue'), PAGE.replace('Planets', 'Worlds'), 'utf-8')
+    clearBindingClassifyCache()
+
+    await verifyAppliedEntries(options, result.taskId)
+
+    const session = await options.getDesignSession()
+    const byId = Object.fromEntries(session.entries.map((e) => [e.id, e]))
+    expect(byId['se-1'].live.status).toBe('written')
+    expect(byId['se-2'].live.status).toBe('failed')
+    expect(byId['se-2'].live.error).toMatch(/not found in source/)
+
+    const snap = await options.snapshots.state()
+    expect(snap.batches[0].status).toBe('done')
+  })
+
+  it('undo-batch: restores pre-apply bytes and returns the batch entries to pending', async () => {
+    await seedSession([textEntry('se-1')])
+    const result = await applyDesignSession(options, '/planets')
+    if ('error' in result) throw new Error('apply failed')
+
+    await fsp.writeFile(path.join(root, 'src/Page.vue'), PAGE.replace('Planets', 'Worlds'), 'utf-8')
+    clearBindingClassifyCache()
+    await verifyAppliedEntries(options, result.taskId)
+
+    const undo = await revertApplyBatch(options, result.batchId)
+    expect(undo.reverted).toEqual(['src/Page.vue'])
+    expect(await fsp.readFile(path.join(root, 'src/Page.vue'), 'utf-8')).toBe(PAGE)
+
+    const session = await options.getDesignSession()
+    expect(session.entries[0].live.status).toBe('pending')
+    expect(session.entries[0].taskId).toBeUndefined()
+  })
+
+  it('accept: keeps the agent bytes, drops the snapshot journal, clears the task entries, signals rotation', async () => {
+    await seedSession([textEntry('se-1')])
+    const result = await applyDesignSession(options, '/planets')
+    if ('error' in result) throw new Error('apply failed')
+
+    const agentBytes = PAGE.replace('Planets', 'Worlds')
+    await fsp.writeFile(path.join(root, 'src/Page.vue'), agentBytes, 'utf-8')
+    clearBindingClassifyCache()
+    await verifyAppliedEntries(options, result.taskId)
+
+    const { rotated } = await acceptApplyTask(options, result.taskId)
+    expect(rotated).toBe(true)
+    // Bytes kept (the new baseline), journal gone.
+    expect(await fsp.readFile(path.join(root, 'src/Page.vue'), 'utf-8')).toBe(agentBytes)
+    expect((await options.snapshots.state()).files).toEqual({})
+    expect((await options.getDesignSession()).entries).toEqual([])
+  })
+
+  it('release (task deleted mid-run): applying entries return to pending; the batch seals failed and stays revertible', async () => {
+    await seedSession([textEntry('se-1')])
+    const result = await applyDesignSession(options, '/planets')
+    if ('error' in result) throw new Error('apply failed')
+
+    // Agent half-wrote, then the task was deleted.
+    await fsp.writeFile(path.join(root, 'src/Page.vue'), PAGE.replace('Planets', 'Half'), 'utf-8')
+    await releaseApplyTask(options, result.taskId)
+
+    const session = await options.getDesignSession()
+    expect(session.entries[0].live.status).toBe('pending')
+    expect(session.entries[0].taskId).toBeUndefined()
+
+    // The batch is sealed 'failed' (not left 'running'), so the undo guard lets
+    // it through — undo restores the clean pre-apply bytes despite the half-write.
+    const snap = await options.snapshots.state()
+    expect(snap.batches).toHaveLength(1)
+    expect(snap.batches[0].status).toBe('failed')
+    const undo = await revertApplyBatch(options, result.batchId)
+    expect(undo.reverted).toEqual(['src/Page.vue'])
+    expect(await fsp.readFile(path.join(root, 'src/Page.vue'), 'utf-8')).toBe(PAGE)
+  })
+
+  it('re-apply after deny re-seals the batch so undo stays byte-exact', async () => {
+    await seedSession([textEntry('se-1')])
+    const result = await applyDesignSession(options, '/planets')
+    if ('error' in result) throw new Error('apply failed')
+
+    // First agent run + review: the edit lands, the entry flips written.
+    await fsp.writeFile(path.join(root, 'src/Page.vue'), PAGE.replace('Planets', 'Worlds'), 'utf-8')
+    clearBindingClassifyCache()
+    await verifyAppliedEntries(options, result.taskId)
+    expect((await options.getDesignSession()).entries[0].live.status).toBe('written')
+
+    // User DENIES; the agent re-runs on the SAME task and writes DIFFERENT
+    // bytes, then review fires again. No entry is 'applying' now (it's written),
+    // so the re-seal must key off the task — otherwise lastAppliedHash stays at
+    // v1 while disk holds v2, and undo would falsely cry "edited outside Annotask".
+    await fsp.writeFile(path.join(root, 'src/Page.vue'), PAGE.replace('Planets', 'Galaxies'), 'utf-8')
+    clearBindingClassifyCache()
+    await verifyAppliedEntries(options, result.taskId)
+
+    const undo = await revertApplyBatch(options, result.batchId)
+    expect(undo.skipped).toEqual([])
+    expect(undo.reverted).toEqual(['src/Page.vue'])
+    expect(await fsp.readFile(path.join(root, 'src/Page.vue'), 'utf-8')).toBe(PAGE)
+  })
+
+  it('verify seals a pure-instances apply (no session entries) so its batch is revertible', async () => {
+    // Build-this-route: placements only, no panel edits — toVerify is empty, but
+    // the batch still needs a hash baseline or undo can't restore it.
+    const wf = await options.getWireframe()
+    await options.setWireframe({ ...wf, updatedAt: 1, routes: [{ route: '/planets', instances: [instance('wfi-1')] }] })
+    const result = await applyDesignSession(options, '/planets')
+    if ('error' in result) throw new Error('apply failed')
+
+    await fsp.writeFile(path.join(root, 'src/Page.vue'), PAGE.replace('Planets', 'Worlds'), 'utf-8')
+    await verifyAppliedEntries(options, result.taskId)
+
+    const snap = await options.snapshots.state()
+    expect(snap.batches[0].status).toBe('done')
+    const undo = await revertApplyBatch(options, result.batchId)
+    expect(undo.reverted).toEqual(['src/Page.vue'])
+    expect(await fsp.readFile(path.join(root, 'src/Page.vue'), 'utf-8')).toBe(PAGE)
+  })
+
+  describe('wireframe directions (W3)', () => {
+    it('apply is route-scoped for directions, session-wide for legacy entries, and stamps the screenshot + canvas', async () => {
+      await seedSession([
+        directionEntry('wd-here', '/planets', 1),
+        directionEntry('wd-elsewhere', '/moons', 2),
+        textEntry('se-style'), // legacy entries stay session-wide
+      ])
+      const wf = await options.getWireframe()
+      await options.setWireframe({
+        ...wf, updatedAt: 1,
+        routes: [{
+          route: '/planets', instances: [],
+          canvas: {
+            capturedAt: 1,
+            viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+            blocks: [],
+          },
+        }],
+      })
+
+      const result = await applyDesignSession(options, '/planets', { screenshot: 'screenshot-1-abc.png' })
+      expect('error' in result).toBe(false)
+      if ('error' in result) return
+
+      expect(tasks).toHaveLength(1)
+      expect(tasks[0].screenshot).toBe('screenshot-1-abc.png')
+      expect(String(tasks[0].description)).toContain('Implement the wireframe sketch on /planets')
+      expect(String(tasks[0].description)).toContain('Pixel positions are hints')
+      const ctx = tasks[0].context as { session: { entries: Array<{ id: string }> } }
+      expect(ctx.session.entries.map((e) => e.id).sort()).toEqual(['se-style', 'wd-here'])
+
+      // The other route's direction stays pending; the canvas locks to the task.
+      const session = await options.getDesignSession()
+      expect(session.entries.find((e) => e.id === 'wd-elsewhere')!.live.status).toBe('pending')
+      const wfAfter = await options.getWireframe()
+      expect(wfAfter.routes[0].canvas).toMatchObject({ status: 'building', taskId: result.taskId })
+    })
+
+    it('an add direction with md + data rides into the task context VERBATIM (entryForTask passes change whole)', async () => {
+      const md = '## Related planets\n- name and type for each'
+      const data = {
+        kind: 'composable', name: 'usePlanets', module: 'src/composables/usePlanets.ts',
+        path: 'planets[]', fields: ['name', 'type'], shape_source: 'api-schema',
+      }
+      const entry = directionEntry('wd-sec', '/planets', 1)
+      const change = entry.change as unknown as Record<string, unknown>
+      change.op = 'add'
+      change.added = { kind: 'placeholder', label: 'related planets', md, data, position: 'after' }
+      await seedSession([entry])
+
+      const result = await applyDesignSession(options, '/planets')
+      if ('error' in result) throw new Error(result.error)
+
+      const ctx = tasks[0].context as { session: { entries: Array<{ change: { added?: { md?: string; data?: unknown } } }> } }
+      expect(ctx.session.entries).toHaveLength(1)
+      expect(ctx.session.entries[0].change.added!.md).toBe(md)
+      expect(ctx.session.entries[0].change.added!.data).toEqual(data)
+    })
+
+    it('an anchorless add (no donor → file "") mints the task and snapshots nothing — never crashes the apply', async () => {
+      // A page with no data-annotask anchors: the add has nowhere to ground, so
+      // file/line come back ''. The OLD code threw on snapshotFiles('') AFTER
+      // minting the task, stranding an orphan task with no batch (and feeding
+      // the lifecycle wedge). Now empty anchors are filtered out of the set.
+      const entry: SessionEntry = {
+        id: 'wd-floating', ordinal: 1, ts: 1, route: '/planets',
+        change: {
+          id: 'c-wd-floating', type: 'wireframe_direction', op: 'add',
+          description: 'ADD component <Hero> on the page',
+          file: '', section: 'template', line: 0,
+          block: { label: 'Hero' },
+          added: { kind: 'component', componentName: 'Hero', position: 'append' },
+          measured: { after: { x: 0, y: 0, width: 320, height: 120 } },
+        } as unknown as SessionEntry['change'],
+        anchor: { file: '', line: 0 },
+        live: { status: 'pending' },
+      }
+      await seedSession([entry])
+
+      const result = await applyDesignSession(options, '/planets')
+      expect('error' in result).toBe(false)
+      if ('error' in result) return
+      expect(tasks).toHaveLength(1)
+      // No file snapshotted (the only anchor was empty) — but the batch exists
+      // and stays revertible, and the direction still rides the task context.
+      const snap = await options.snapshots.state()
+      expect(Object.keys(snap.files)).toEqual([])
+      expect(snap.batches.map((b) => b.id)).toEqual([result.batchId])
+      const ctx = tasks[0].context as { session: { entries: Array<{ id: string }> } }
+      expect(ctx.session.entries.map((e) => e.id)).toEqual(['wd-floating'])
+    })
+
+    it('verify trusts directions with NO source read — the anchor file may be gone entirely', async () => {
+      await seedSession([directionEntry('wd-1')])
+      const result = await applyDesignSession(options, '/planets')
+      if ('error' in result) throw new Error(result.error)
+
+      // The agent legitimately restructured: the anchored file no longer exists.
+      await fsp.rm(path.join(root, 'src/Page.vue'))
+
+      await verifyAppliedEntries(options, result.taskId)
+      const session = await options.getDesignSession()
+      expect(session.entries[0].live.status).toBe('written')
+      const snap = await options.snapshots.state()
+      expect(snap.batches[0].status).toBe('done') // sealed
+    })
+
+    it('undo-batch returns direction entries to pending with the taskId cleared', async () => {
+      await seedSession([directionEntry('wd-1')])
+      const before = await fsp.readFile(path.join(root, 'src/Page.vue'), 'utf-8')
+      const result = await applyDesignSession(options, '/planets')
+      if ('error' in result) throw new Error(result.error)
+
+      // Agent rewrites, then review seals the batch — undo is only reachable on
+      // a sealed batch (the running-batch guard refuses an unsealed one).
+      await fsp.writeFile(path.join(root, 'src/Page.vue'), '<template><p>agent rewrote</p></template>', 'utf-8')
+      await verifyAppliedEntries(options, result.taskId)
+      const reverted = await revertApplyBatch(options, result.batchId)
+      expect(reverted.reverted).toEqual(['src/Page.vue'])
+      expect(await fsp.readFile(path.join(root, 'src/Page.vue'), 'utf-8')).toBe(before)
+
+      const session = await options.getDesignSession()
+      expect(session.entries[0].live.status).toBe('pending')
+      expect(session.entries[0].taskId).toBeUndefined()
+    })
+
+    it('accept clears direction entries and rotates an emptied session', async () => {
+      await seedSession([directionEntry('wd-1')])
+      const result = await applyDesignSession(options, '/planets')
+      if ('error' in result) throw new Error(result.error)
+      await verifyAppliedEntries(options, result.taskId)
+
+      const { rotated } = await acceptApplyTask(options, result.taskId)
+      expect(rotated).toBe(true)
+      expect((await options.getDesignSession()).entries).toEqual([])
+      expect((await options.snapshots.state()).batches).toEqual([])
+    })
+  })
+})
diff --git a/src/server/__tests__/binding-classify.test.ts b/src/server/__tests__/binding-classify.test.ts
new file mode 100644
index 0000000..d795d11
--- /dev/null
+++ b/src/server/__tests__/binding-classify.test.ts
@@ -0,0 +1,233 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { classifyBindings, clearBindingClassifyCache } from '../binding-classify'
+
+// Mirrors the real /planets acceptance surface: a multi-line component usage
+// inside v-for, literal attrs, expression-literals, bound text, literal text.
+const PLANETS_PAGE_VUE = `<template>
+  <div class="planets-page">
+    <h1 class="title">Planets</h1>
+    <p class="subtitle">{{ planets.length }} worlds</p>
+    <span class="mixed"><em>hot</em> {{ sun.temp }} degrees</span>
+    <Button label="Reset" :count="3" :active="selected !== null" @click="reset" />
+    <section class="grid">
+      <PlanetCard
+        v-for="planet in filtered"
+        :key="planet.id"
+        :planet="planet"
+        :active="selected?.id === planet.id"
+        @select="onSelect"
+      />
+    </section>
+    <Chip v-bind="chipProps" label="Spread" />
+  </div>
+</template>
+<script setup lang="ts">
+import PlanetCard from '../components/PlanetCard.vue'
+const filtered = []
+</script>
+`
+
+const PLANETS_PAGE_TSX = `import PlanetCard from './PlanetCard'
+
+export default function PlanetsPage() {
+  const planets: Array<{ id: string; name: string }> = []
+  return (
+    <div className="planets-page">
+      <h1 className="title">Planets</h1>
+      <p className="subtitle">{planets.length} worlds</p>
+      <Button label="Reset" count={3} negative={-1} active={planets.length > 0} disabled />
+      <section className="grid">
+        {planets.map((planet) => (
+          <PlanetCard key={planet.id} planet={planet} active={false} onSelect={() => {}} />
+        ))}
+      </section>
+      <Chip {...chipProps} label="Spread" />
+    </div>
+  )
+}
+`
+
+const PLANETS_PAGE_SVELTE = `<script>
+  import PlanetCard from './PlanetCard.svelte'
+  let planets = []
+</script>
+
+<div class="planets-page">
+  <h1 class="title">Planets</h1>
+  <p class="subtitle">{planets.length} worlds</p>
+  <Button label="Reset" count={3} active={planets.length > 0} />
+  {#each planets as planet}
+    <PlanetCard planet={planet} active={false} />
+  {/each}
+</div>
+`
+
+describe('binding-classify', () => {
+  let root: string
+
+  async function write(rel: string, content: string): Promise<string> {
+    const abs = path.join(root, rel)
+    await fsp.mkdir(path.dirname(abs), { recursive: true })
+    await fsp.writeFile(abs, content, 'utf-8')
+    return rel
+  }
+
+  beforeEach(async () => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-bc-'))
+    clearBindingClassifyCache()
+    await write('src/pages/PlanetsPage.vue', PLANETS_PAGE_VUE)
+    await write('src/pages/PlanetsPage.tsx', PLANETS_PAGE_TSX)
+    await write('src/pages/PlanetsPage.svelte', PLANETS_PAGE_SVELTE)
+  })
+
+  afterEach(async () => {
+    await fsp.rm(root, { recursive: true, force: true })
+  })
+
+  describe('vue', () => {
+    it('classifies literal attrs, expression-literals, and bound expressions on one element', async () => {
+      const r = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 6, { tag: 'Button' })
+      expect(r.analyzer).toBe('vue-sfc')
+      expect(r.error).toBeUndefined()
+      const byName = Object.fromEntries(r.props.map((p) => [p.name, p]))
+      expect(byName.label).toMatchObject({ kind: 'literal', source: 'Reset' })
+      expect(byName.label.expression_literal).toBeUndefined()
+      expect(byName.count).toMatchObject({ kind: 'literal', source: '3', expression_literal: true })
+      expect(byName.active).toMatchObject({ kind: 'bound', source: 'selected !== null' })
+      // Event handlers are not editable props.
+      expect(byName.click).toBeUndefined()
+      expect(r.loop).toBeUndefined()
+      expect(r.excerpt_hash).toHaveLength(16)
+    })
+
+    it('sees attrs on continuation lines of a multi-line opening tag and the enclosing v-for', async () => {
+      const r = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 8, { tag: 'PlanetCard' })
+      expect(r.error).toBeUndefined()
+      const byName = Object.fromEntries(r.props.map((p) => [p.name, p]))
+      expect(byName.planet).toMatchObject({ kind: 'bound', source: 'planet' })
+      expect(byName.active.kind).toBe('bound')
+      // v-for on the element itself.
+      expect(r.loop).toMatchObject({ iterable: 'filtered', alias: 'planet' })
+    })
+
+    it('marks every prop unknown under v-bind spread', async () => {
+      const r = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 16, { tag: 'Chip' })
+      expect(r.error).toBeUndefined()
+      const label = r.props.find((p) => p.name === 'label')
+      expect(label).toMatchObject({ kind: 'unknown' })
+      expect(label!.reason).toMatch(/spread/)
+    })
+
+    it('classifies text: literal, bound interpolation, mixed content', async () => {
+      const h1 = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 3, { tag: 'h1' })
+      expect(h1.text).toMatchObject({ kind: 'literal', source: 'Planets' })
+
+      const p = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 4, { tag: 'p' })
+      expect(p.text.kind).toBe('mixed') // "{{ planets.length }} worlds" = interpolation + text
+
+      const span = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 5, { tag: 'span' })
+      expect(span.text.kind).toBe('mixed')
+    })
+
+    it('errors read-only when the element is missing or the line is ambiguous', async () => {
+      const missing = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 2, { tag: 'PlanetCard' })
+      expect(missing.error).toMatch(/not found/)
+      expect(missing.props).toEqual([])
+      expect(missing.text.kind).toBe('unknown')
+
+      // Two elements on one line without a tag filter → ambiguous.
+      await write('src/Two.vue', '<template>\n  <div><span>a</span><span>b</span></div>\n</template>\n')
+      const ambiguous = await classifyBindings(root, 'src/Two.vue', 2, { tag: 'span' })
+      expect(ambiguous.error).toMatch(/ambiguous/)
+    })
+  })
+
+  describe('jsx (react + solid)', () => {
+    it('classifies literals, expression-literals, negatives, boolean shorthand, and bound props', async () => {
+      const r = await classifyBindings(root, 'src/pages/PlanetsPage.tsx', 9, { tag: 'Button' })
+      expect(r.analyzer).toBe('jsx')
+      expect(r.error).toBeUndefined()
+      const byName = Object.fromEntries(r.props.map((p) => [p.name, p]))
+      expect(byName.label).toMatchObject({ kind: 'literal', source: 'Reset' })
+      expect(byName.count).toMatchObject({ kind: 'literal', source: '3', expression_literal: true })
+      expect(byName.negative).toMatchObject({ kind: 'literal', source: '-1', expression_literal: true })
+      expect(byName.disabled).toMatchObject({ kind: 'literal', source: 'true', expression_literal: true })
+      expect(byName.active.kind).toBe('bound')
+      expect(byName.onSelect).toBeUndefined()
+    })
+
+    it('detects the enclosing .map() loop', async () => {
+      const r = await classifyBindings(root, 'src/pages/PlanetsPage.tsx', 12, { tag: 'PlanetCard' })
+      expect(r.error).toBeUndefined()
+      expect(r.loop).toMatchObject({ iterable: 'planets', alias: 'planet' })
+      const planet = r.props.find((p) => p.name === 'planet')
+      expect(planet!.kind).toBe('bound')
+    })
+
+    it('marks every prop unknown under {...spread}', async () => {
+      const r = await classifyBindings(root, 'src/pages/PlanetsPage.tsx', 15, { tag: 'Chip' })
+      const label = r.props.find((p) => p.name === 'label')
+      expect(label).toMatchObject({ kind: 'unknown' })
+      expect(label!.reason).toMatch(/spread/)
+    })
+
+    it('classifies text content', async () => {
+      const h1 = await classifyBindings(root, 'src/pages/PlanetsPage.tsx', 7, { tag: 'h1' })
+      expect(h1.text).toMatchObject({ kind: 'literal', source: 'Planets' })
+      const p = await classifyBindings(root, 'src/pages/PlanetsPage.tsx', 8, { tag: 'p' })
+      expect(p.text.kind).toBe('mixed')
+    })
+  })
+
+  describe('svelte', () => {
+    it('classifies attrs and the enclosing {#each} loop', async () => {
+      const button = await classifyBindings(root, 'src/pages/PlanetsPage.svelte', 9, { tag: 'Button' })
+      expect(button.analyzer).toBe('svelte')
+      expect(button.error).toBeUndefined()
+      const byName = Object.fromEntries(button.props.map((p) => [p.name, p]))
+      expect(byName.label).toMatchObject({ kind: 'literal', source: 'Reset' })
+      expect(byName.count).toMatchObject({ kind: 'literal', source: '3', expression_literal: true })
+      expect(byName.active.kind).toBe('bound')
+
+      const card = await classifyBindings(root, 'src/pages/PlanetsPage.svelte', 11, { tag: 'PlanetCard' })
+      expect(card.error).toBeUndefined()
+      expect(card.loop).toMatchObject({ iterable: 'planets', alias: 'planet' })
+    })
+
+    it('classifies text content', async () => {
+      const h1 = await classifyBindings(root, 'src/pages/PlanetsPage.svelte', 7, { tag: 'h1' })
+      expect(h1.text).toMatchObject({ kind: 'literal', source: 'Planets' })
+    })
+  })
+
+  describe('honesty fallbacks', () => {
+    it('treats unsupported file types as wholly read-only', async () => {
+      await write('src/page.astro', '<h1>Hello</h1>\n')
+      const r = await classifyBindings(root, 'src/page.astro', 1)
+      expect(r.analyzer).toBe('none')
+      expect(r.error).toMatch(/unsupported/)
+      expect(r.text.kind).toBe('unknown')
+    })
+
+    it('rejects escaping paths', async () => {
+      const r = await classifyBindings(root, '../outside.vue', 1)
+      expect(r.error).toMatch(/Invalid|escap/i)
+    })
+
+    it('excerpt_hash is stable across calls and changes when the source changes', async () => {
+      const a = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 6, { tag: 'Button' })
+      clearBindingClassifyCache()
+      const b = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 6, { tag: 'Button' })
+      expect(a.excerpt_hash).toBe(b.excerpt_hash)
+
+      await write('src/pages/PlanetsPage.vue', PLANETS_PAGE_VUE.replace('label="Reset"', 'label="Clear"'))
+      clearBindingClassifyCache()
+      const c = await classifyBindings(root, 'src/pages/PlanetsPage.vue', 6, { tag: 'Button' })
+      expect(c.excerpt_hash).not.toBe(a.excerpt_hash)
+    })
+  })
+})
diff --git a/src/server/__tests__/cli-matrix-report.test.ts b/src/server/__tests__/cli-matrix-report.test.ts
new file mode 100644
index 0000000..2aa2047
--- /dev/null
+++ b/src/server/__tests__/cli-matrix-report.test.ts
@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest'
+import { renderMdxReport, type ReportInput } from './cli-matrix-report.js'
+
+function fixture(overrides: Partial<ReportInput> = {}): ReportInput {
+  return {
+    timestamp: '2026-05-19T20:00:00.000Z',
+    totalWallMs: 132_400,
+    suiteVersion: '1.0',
+    workspaceKept: false,
+    runs: [
+      {
+        key: 'claude-local',
+        model: 'claude-sonnet-4-6',
+        status: 'pass',
+        elapsedMs: 91_000,
+        tokens: { inputTokens: 12_000, outputTokens: 1_400, cacheReadTokens: 8_000, cacheCreationTokens: 1_000 },
+        assertions: [
+          { name: 'design-spec.json exists', ok: true },
+          { name: 'colors >= 3', ok: true, detail: '7 detected' },
+          { name: 'style guide non-template', ok: true },
+          { name: 'agents.json filled', ok: true, detail: '4/4 personas' },
+          { name: 'token usage > 0', ok: true },
+        ],
+        designSpec: {
+          colorCount: 7,
+          colors: [{ name: 'primary', value: '#3366ff' }, { name: 'surface', value: '#fff' }],
+          themes: [{ id: 'light', name: 'Light' }, { id: 'dark', name: 'Dark' }],
+        },
+        styleGuideExcerpt: '# Project style guide\n\nNaming: PascalCase components.',
+        agents: [{ id: 'general', firstSentence: 'Senior Vue 3 + single-spa developer.' }],
+        agentLinesTail: ['Reading package.json', 'Wrote design-spec.json'],
+        workspacePath: '/tmp/annotask-cli-matrix/claude-local-abc',
+      },
+      {
+        key: 'opencode-local',
+        model: 'github-copilot/gpt-5.4',
+        status: 'fail',
+        reason: 'colors < 3 (detected 0)',
+        elapsedMs: 132_400,
+        tokens: { inputTokens: 15_000, outputTokens: 800, cacheReadTokens: 0, cacheCreationTokens: 0 },
+        assertions: [
+          { name: 'design-spec.json exists', ok: true },
+          { name: 'colors >= 3', ok: false, detail: 'got 0' },
+        ],
+      },
+      {
+        key: 'codex-local',
+        model: 'gpt-5.4',
+        status: 'skip',
+        reason: 'codex CLI not logged in',
+        elapsedMs: 0,
+        tokens: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 },
+        assertions: [],
+      },
+    ],
+    ...overrides,
+  }
+}
+
+describe('renderMdxReport', () => {
+  it('emits frontmatter with the run metadata', () => {
+    const md = renderMdxReport(fixture())
+    expect(md.startsWith('---\n')).toBe(true)
+    expect(md).toContain('timestamp: "2026-05-19T20:00:00.000Z"')
+    expect(md).toContain('totalWallMs: 132400')
+    expect(md).toContain('workspaceKept: false')
+  })
+
+  it('orders the matrix claude → codex → opencode → copilot regardless of input order', () => {
+    const md = renderMdxReport(fixture())
+    const headings = [...md.matchAll(/^## .*(claude-local|codex-local|opencode-local|copilot-local)$/gm)]
+      .map((m) => m[1])
+    expect(headings).toEqual(['claude-local', 'codex-local', 'opencode-local'])
+  })
+
+  it('renders a summary table with one row per run', () => {
+    const md = renderMdxReport(fixture())
+    expect(md).toContain('| CLI | model | status | elapsed (s) |')
+    expect(md).toMatch(/\| claude-local \| claude-sonnet-4-6 \| ✓ pass \|/)
+    expect(md).toMatch(/\| opencode-local \|.*\| ✗ fail \|/)
+    expect(md).toMatch(/\| codex-local \|.*\| ○ skip \|/)
+  })
+
+  it('embeds design-spec excerpt and style guide for passing runs', () => {
+    const md = renderMdxReport(fixture())
+    expect(md).toContain('### Design spec excerpt')
+    expect(md).toContain('"colorCount": 7')
+    expect(md).toContain('### STYLE_GUIDE.md excerpt')
+    expect(md).toContain('# Project style guide')
+  })
+
+  it('renders assertion list with ✓/✗ icons and detail text', () => {
+    const md = renderMdxReport(fixture())
+    expect(md).toContain('- ✓ design-spec.json exists')
+    expect(md).toContain('- ✓ colors >= 3 — 7 detected')
+    expect(md).toContain('- ✗ colors >= 3 — got 0')
+  })
+
+  it('omits the workspace footer when no workspaces were kept', () => {
+    const md = renderMdxReport(fixture())
+    expect(md).not.toContain('## Workspaces kept on disk')
+  })
+
+  it('includes the workspace footer when ANNOTASK_CLI_MATRIX_KEEP=1', () => {
+    const md = renderMdxReport(fixture({ workspaceKept: true }))
+    expect(md).toContain('## Workspaces kept on disk')
+    expect(md).toContain('/tmp/annotask-cli-matrix/claude-local-abc')
+  })
+
+  it('escapes pipe characters in cells so the markdown table stays valid', () => {
+    const md = renderMdxReport(fixture({
+      runs: [
+        {
+          key: 'claude-local',
+          model: 'a|b',
+          status: 'fail',
+          reason: 'pipe | in | reason',
+          elapsedMs: 1000,
+          tokens: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 },
+          assertions: [],
+        },
+      ],
+    }))
+    expect(md).toContain('pipe \\| in \\| reason')
+  })
+})
diff --git a/src/server/__tests__/cli-matrix-report.ts b/src/server/__tests__/cli-matrix-report.ts
new file mode 100644
index 0000000..b5d4a48
--- /dev/null
+++ b/src/server/__tests__/cli-matrix-report.ts
@@ -0,0 +1,210 @@
+/**
+ * MDX report writer for the CLI matrix init suite.
+ *
+ * Pure string assembly — no MDX runtime needed. The output is hand-rolled
+ * markdown with YAML frontmatter that any MDX-aware viewer renders fine.
+ *
+ * Consumed by `init-cli-matrix-stress.test.ts`; unit-tested by
+ * `cli-matrix-report.test.ts` so the formatting stays stable without
+ * needing a live CLI run.
+ */
+
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import type { LiveProviderKey } from '../../embedded/__tests__/live-cli-helpers.js'
+
+export type RunStatus = 'pass' | 'fail' | 'skip'
+
+export interface AssertionResult {
+  name: string
+  ok: boolean
+  detail?: string
+}
+
+export interface DesignSpecExcerpt {
+  colorCount: number
+  colors: Array<{ name?: string; value?: string }>
+  themes: Array<{ id?: string; name?: string }>
+}
+
+export interface AgentDirectionsSummary {
+  id: string
+  firstSentence: string
+}
+
+export interface PerCliRun {
+  key: LiveProviderKey
+  model: string
+  status: RunStatus
+  reason?: string
+  elapsedMs: number
+  tokens: {
+    inputTokens: number
+    outputTokens: number
+    cacheReadTokens: number
+    cacheCreationTokens: number
+  }
+  assertions: AssertionResult[]
+  designSpec?: DesignSpecExcerpt
+  styleGuideExcerpt?: string
+  agents?: AgentDirectionsSummary[]
+  agentLinesTail?: string[]
+  workspacePath?: string
+}
+
+export interface ReportInput {
+  timestamp: string
+  totalWallMs: number
+  suiteVersion: string
+  runs: PerCliRun[]
+  workspaceKept: boolean
+}
+
+const CLI_ORDER: LiveProviderKey[] = [
+  'claude-local',
+  'codex-local',
+  'opencode-local',
+  'copilot-local',
+]
+
+export async function writeMdxReport(input: ReportInput, outPath: string): Promise<void> {
+  await fsp.mkdir(path.dirname(outPath), { recursive: true })
+  await fsp.writeFile(outPath, renderMdxReport(input), 'utf-8')
+}
+
+export function renderMdxReport(input: ReportInput): string {
+  const ordered = orderRuns(input.runs)
+  const sections = [
+    renderFrontmatter(input, ordered),
+    `# Annotask CLI matrix — stress-test init`,
+    ``,
+    `Generated ${input.timestamp}. Total wall time: ${formatSeconds(input.totalWallMs)}s.`,
+    ``,
+    renderSummaryTable(ordered),
+    ...ordered.map(renderCliSection),
+    renderArtifactsFooter(input, ordered),
+  ]
+  return sections.filter((s) => s.length > 0).join('\n') + '\n'
+}
+
+function orderRuns(runs: PerCliRun[]): PerCliRun[] {
+  const byKey = new Map(runs.map((r) => [r.key, r] as const))
+  const ordered: PerCliRun[] = []
+  for (const k of CLI_ORDER) {
+    const r = byKey.get(k)
+    if (r) ordered.push(r)
+  }
+  return ordered
+}
+
+function renderFrontmatter(input: ReportInput, ordered: PerCliRun[]): string {
+  const lines = [
+    '---',
+    `timestamp: ${JSON.stringify(input.timestamp)}`,
+    `suiteVersion: ${JSON.stringify(input.suiteVersion)}`,
+    `totalWallMs: ${input.totalWallMs}`,
+    `workspaceKept: ${input.workspaceKept}`,
+    `matrix:`,
+    ...ordered.map((r) => `  - { key: ${JSON.stringify(r.key)}, model: ${JSON.stringify(r.model)}, status: ${JSON.stringify(r.status)} }`),
+    '---',
+    '',
+  ]
+  return lines.join('\n')
+}
+
+function renderSummaryTable(runs: PerCliRun[]): string {
+  const header = [
+    '## Summary',
+    '',
+    '| CLI | model | status | elapsed (s) | input | output | cache R | cache W | note |',
+    '|-----|-------|--------|-------------|-------|--------|---------|---------|------|',
+  ]
+  const rows = runs.map((r) => {
+    const icon = statusIcon(r.status)
+    return `| ${r.key} | ${r.model || '—'} | ${icon} ${r.status} | ${formatSeconds(r.elapsedMs)} | ${r.tokens.inputTokens} | ${r.tokens.outputTokens} | ${r.tokens.cacheReadTokens} | ${r.tokens.cacheCreationTokens} | ${escapeCell(r.reason ?? '')} |`
+  })
+  return [...header, ...rows, ''].join('\n')
+}
+
+function renderCliSection(run: PerCliRun): string {
+  const lines: string[] = [
+    `## ${statusIcon(run.status)} ${run.key}`,
+    '',
+    '| key | value |',
+    '|-----|-------|',
+    `| model | \`${escapeCell(run.model || '—')}\` |`,
+    `| status | ${run.status} |`,
+    `| elapsed | ${formatSeconds(run.elapsedMs)}s |`,
+    `| input tokens | ${run.tokens.inputTokens} |`,
+    `| output tokens | ${run.tokens.outputTokens} |`,
+    `| cache read | ${run.tokens.cacheReadTokens} |`,
+    `| cache write | ${run.tokens.cacheCreationTokens} |`,
+  ]
+  if (run.reason) lines.push(`| reason | ${escapeCell(run.reason)} |`)
+  if (run.workspacePath) lines.push(`| workspace | \`${run.workspacePath}\` |`)
+  lines.push('')
+
+  if (run.assertions.length > 0) {
+    lines.push('### Assertions', '')
+    for (const a of run.assertions) {
+      const tick = a.ok ? '✓' : '✗'
+      const detail = a.detail ? ` — ${a.detail}` : ''
+      lines.push(`- ${tick} ${a.name}${detail}`)
+    }
+    lines.push('')
+  }
+
+  if (run.designSpec) {
+    lines.push('### Design spec excerpt', '')
+    const compact = {
+      colorCount: run.designSpec.colorCount,
+      colors: run.designSpec.colors.slice(0, 5),
+      themes: run.designSpec.themes,
+    }
+    lines.push('```json', JSON.stringify(compact, null, 2), '```', '')
+  }
+
+  if (run.styleGuideExcerpt) {
+    lines.push('### STYLE_GUIDE.md excerpt', '')
+    lines.push('```markdown', run.styleGuideExcerpt, '```', '')
+  }
+
+  if (run.agents && run.agents.length > 0) {
+    lines.push('### Agent directions', '')
+    for (const a of run.agents) {
+      lines.push(`- **${a.id}** — ${a.firstSentence}`)
+    }
+    lines.push('')
+  }
+
+  if (run.agentLinesTail && run.agentLinesTail.length > 0) {
+    lines.push('### Agent transcript tail', '')
+    lines.push('```text', ...run.agentLinesTail, '```', '')
+  }
+
+  return lines.join('\n')
+}
+
+function renderArtifactsFooter(input: ReportInput, ordered: PerCliRun[]): string {
+  if (!input.workspaceKept) return ''
+  const lines = ['## Workspaces kept on disk', '']
+  for (const r of ordered) {
+    if (r.workspacePath) lines.push(`- ${r.key}: \`${r.workspacePath}\``)
+  }
+  lines.push('')
+  return lines.join('\n')
+}
+
+function statusIcon(s: RunStatus): string {
+  if (s === 'pass') return '✓'
+  if (s === 'fail') return '✗'
+  return '○'
+}
+
+function formatSeconds(ms: number): string {
+  return (ms / 1000).toFixed(1)
+}
+
+function escapeCell(s: string): string {
+  return s.replace(/\|/g, '\\|').replace(/\n/g, ' ').slice(0, 200)
+}
diff --git a/src/server/__tests__/data-source-shape.test.ts b/src/server/__tests__/data-source-shape.test.ts
new file mode 100644
index 0000000..79a559c
--- /dev/null
+++ b/src/server/__tests__/data-source-shape.test.ts
@@ -0,0 +1,323 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { schemaToShape, resolveDataSourceShape } from '../data-source-shape.js'
+import { clearDataSourceCache } from '../data-source-scanner.js'
+import { clearApiSchemaCache } from '../api-schema-scanner.js'
+import { resolveEndpoint } from '../api-schema-resolver.js'
+import type { ApiSchemaCatalog, DataSourceShape } from '../../schema.js'
+
+describe('schemaToShape — pure walker', () => {
+  it('walks nested objects and array-of-object', () => {
+    expect(schemaToShape({
+      type: 'object',
+      properties: {
+        items: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, price: { type: 'number' } } } },
+        total: { type: 'integer' },
+      },
+    })).toEqual({
+      kind: 'object',
+      children: {
+        items: { kind: 'array', item: { kind: 'object', children: { name: { kind: 'scalar', scalar: 'string' }, price: { kind: 'scalar', scalar: 'number' } } } },
+        total: { kind: 'scalar', scalar: 'integer' },
+      },
+    })
+  })
+
+  it('captures the contract example/default at each node (api-schema sample data)', () => {
+    // Per-field example + a full array example of objects.
+    const shape = schemaToShape({
+      type: 'object',
+      properties: {
+        planets: {
+          type: 'array',
+          example: [{ name: 'Mercury', type: 'rocky' }, { name: 'Venus', type: 'rocky' }],
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', example: 'Earth' },
+              type: { type: 'string', default: 'rocky' },
+            },
+          },
+        },
+      },
+    })
+    const planets = shape.children!.planets
+    expect(planets.example).toEqual([{ name: 'Mercury', type: 'rocky' }, { name: 'Venus', type: 'rocky' }])
+    expect(planets.item!.children!.name.example).toBe('Earth')
+    expect(planets.item!.children!.type.example).toBe('rocky') // falls back to `default`
+  })
+
+  it('omits example when the schema declares none', () => {
+    expect(schemaToShape({ type: 'string' })).toEqual({ kind: 'scalar', scalar: 'string' })
+  })
+
+  it('degrades residual $ref cycle markers to named ref leaves', () => {
+    expect(schemaToShape({ type: 'object', properties: { parent: { $ref: '#/components/schemas/Cat' } } }))
+      .toEqual({ kind: 'object', children: { parent: { kind: 'ref', ref: 'Cat' } } })
+  })
+
+  it('degrades GraphQL $type markers to named ref leaves', () => {
+    expect(schemaToShape({ $type: 'Planet[]' })).toEqual({ kind: 'ref', ref: 'Planet[]' })
+  })
+
+  it('merges allOf object members', () => {
+    expect(schemaToShape({
+      allOf: [
+        { type: 'object', properties: { id: { type: 'string' } } },
+        { type: 'object', properties: { name: { type: 'string' } } },
+      ],
+    })).toEqual({ kind: 'object', children: { id: { kind: 'scalar', scalar: 'string' }, name: { kind: 'scalar', scalar: 'string' } } })
+  })
+
+  it('allOf composes with an explicit object type and with sibling properties', () => {
+    // `{ type:'object', allOf:[…] }` — inherited keys must not be swallowed.
+    expect(schemaToShape({
+      type: 'object',
+      allOf: [{ type: 'object', properties: { id: { type: 'string' } } }],
+    })).toEqual({ kind: 'object', children: { id: { kind: 'scalar', scalar: 'string' } } })
+    // Composition + extension: own properties override inherited ones.
+    expect(schemaToShape({
+      allOf: [{ type: 'object', properties: { id: { type: 'string' }, name: { type: 'integer' } } }],
+      properties: { name: { type: 'string' }, extra: { type: 'boolean' } },
+    })).toEqual({
+      kind: 'object',
+      children: {
+        id: { kind: 'scalar', scalar: 'string' },
+        name: { kind: 'scalar', scalar: 'string' }, // own wins
+        extra: { kind: 'scalar', scalar: 'boolean' },
+      },
+    })
+  })
+
+  it('takes the first object-ish oneOf/anyOf variant', () => {
+    expect(schemaToShape({
+      oneOf: [{ type: 'string' }, { type: 'object', properties: { ok: { type: 'boolean' } } }],
+    })).toEqual({ kind: 'object', children: { ok: { kind: 'scalar', scalar: 'boolean' } } })
+    expect(schemaToShape({ anyOf: [{ type: 'number' }] })).toEqual({ kind: 'unknown' })
+  })
+
+  it('caps recursion depth instead of walking forever', () => {
+    // Self-nesting deeper than the cap — the tail degrades to unknown.
+    let node: Record<string, unknown> = { type: 'string' }
+    for (let i = 0; i < 12; i++) node = { type: 'object', properties: { child: node } }
+    let walked = schemaToShape(node)
+    let depth = 0
+    while (walked.kind === 'object' && walked.children?.child) { walked = walked.children.child; depth++ }
+    expect(walked.kind).toBe('unknown')
+    expect(depth).toBeGreaterThan(4)
+  })
+
+  it('returns unknown for unwalkable input', () => {
+    expect(schemaToShape({})).toEqual({ kind: 'unknown' })
+    expect(schemaToShape({ type: 7 as never })).toEqual({ kind: 'unknown' })
+  })
+})
+
+describe('resolveEndpoint — method-mismatch deranking (sanity)', () => {
+  it('a method mismatch still matches the path but with reduced confidence', () => {
+    const catalog: ApiSchemaCatalog = {
+      schemas: [{
+        kind: 'openapi', source: 'file', location: 'openapi.json', in_repo: true,
+        operation_count: 1,
+        operations: [{ method: 'GET', path: '/api/cats', response_schema: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' } } } }, schema_refs: ['Cat'] }],
+      }],
+      scannedAt: 0,
+    }
+    const exact = resolveEndpoint(catalog, '/api/cats', 'GET')
+    const mismatched = resolveEndpoint(catalog, '/api/cats', 'POST')
+    expect(exact?.confidence).toBe(1)
+    expect(mismatched).not.toBeNull()
+    expect(mismatched!.confidence).toBeLessThan(1)
+  })
+})
+
+const OPENAPI_FIXTURE = {
+  openapi: '3.0.0',
+  info: { title: 'Cats API', version: '1.0.0' },
+  paths: {
+    '/api/cats': {
+      get: {
+        operationId: 'listCats',
+        responses: {
+          '200': {
+            content: {
+              'application/json': {
+                schema: { type: 'array', items: { $ref: '#/components/schemas/Cat' } },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+  components: {
+    schemas: {
+      Cat: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          price: { type: 'number' },
+          owner: { $ref: '#/components/schemas/Owner' },
+          // Self-reference — resolveRefs leaves a cycle marker the walker
+          // must degrade to a ref leaf, never expand.
+          parent: { $ref: '#/components/schemas/Cat' },
+        },
+      },
+      Owner: { type: 'object', properties: { email: { type: 'string' } } },
+    },
+  },
+}
+
+async function scaffold(files: Record<string, string>): Promise<string> {
+  const tmp = await fsp.mkdtemp(path.join(os.tmpdir(), 'annotask-shape-'))
+  await fsp.writeFile(path.join(tmp, 'package.json'), JSON.stringify({
+    name: 'root',
+    dependencies: { 'vue-router': '4.0.0' },
+  }))
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(tmp, rel)
+    await fsp.mkdir(path.dirname(abs), { recursive: true })
+    await fsp.writeFile(abs, content)
+  }
+  return tmp
+}
+
+describe('resolveDataSourceShape — honesty ladder', () => {
+  beforeEach(() => {
+    clearDataSourceCache()
+    clearApiSchemaCache()
+  })
+
+  it("rung 1: 'api-schema' — endpoint matches an OpenAPI operation; shape is walkable with cycle-safe refs", async () => {
+    const tmp = await scaffold({
+      'openapi.json': JSON.stringify(OPENAPI_FIXTURE),
+      'src/composables/useCats.ts': `
+        export function useCats() {
+          return fetch('/api/cats').then(r => r.json())
+        }
+      `,
+    })
+    try {
+      const result = await resolveDataSourceShape({
+        projectRoot: tmp, name: 'useCats',
+        schemaScan: { apiSchemaFiles: ['openapi.json'] }, // explicit files ⇒ no dev-server probes (offline)
+      })
+      expect('error' in result).toBe(false)
+      const shape = result as DataSourceShape
+      expect(shape.shape_source).toBe('api-schema')
+      expect(shape.schema_ref).toBe('Cat[]')
+      expect(shape.match_confidence).toBe(1)
+      expect(shape.schema_kind).toBe('openapi')
+      expect(shape.shape).toEqual({
+        kind: 'array',
+        item: {
+          kind: 'object',
+          children: {
+            name: { kind: 'scalar', scalar: 'string' },
+            price: { kind: 'scalar', scalar: 'number' },
+            owner: { kind: 'object', children: { email: { kind: 'scalar', scalar: 'string' } } },
+            parent: { kind: 'ref', ref: 'Cat' }, // cycle marker stays a leaf
+          },
+        },
+      })
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it("rung 2: 'source-details' — no schema match; verbatim return-type hints, NO fabricated tree", async () => {
+    const tmp = await scaffold({
+      'src/composables/useDogs.ts': `
+        export interface DogsResult { dogs: string[] }
+        export function useDogs(): DogsResult {
+          return { dogs: [] }
+        }
+      `,
+    })
+    try {
+      const result = await resolveDataSourceShape({
+        projectRoot: tmp, name: 'useDogs',
+        schemaScan: { apiSchemaFiles: ['missing.json'] },
+      })
+      expect('error' in result).toBe(false)
+      const shape = result as DataSourceShape
+      expect(shape.shape_source).toBe('source-details')
+      expect(shape.return_type).toBe('DogsResult')
+      expect(shape.details_confidence).toBeDefined()
+      expect(shape.shape).toBeUndefined() // never expanded from a type name
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it("rung 3: 'none' — un-annotated source with no schema match is visibly blind", async () => {
+    const tmp = await scaffold({
+      'src/composables/useStuff.ts': `
+        export function useStuff() {
+          return fetch('/internal/stuff').then(r => r.json())
+        }
+      `,
+    })
+    try {
+      const result = await resolveDataSourceShape({
+        projectRoot: tmp, name: 'useStuff',
+        schemaScan: { apiSchemaFiles: ['missing.json'] },
+      })
+      expect('error' in result).toBe(false)
+      const shape = result as DataSourceShape
+      expect(shape.shape_source).toBe('none')
+      expect(shape.shape).toBeUndefined()
+      expect(shape.return_type).toBeUndefined()
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('ambiguous names list candidates; re-calling with file resolves', async () => {
+    const sourceA = `
+      export function useCats() { return fetch('/api/cats').then(r => r.json()) }
+    `
+    const tmp = await scaffold({
+      'openapi.json': JSON.stringify(OPENAPI_FIXTURE),
+      'src/composables/useCats.ts': sourceA,
+      'src/legacy/useCats.ts': sourceA,
+    })
+    try {
+      const ambiguous = await resolveDataSourceShape({
+        projectRoot: tmp, name: 'useCats',
+        schemaScan: { apiSchemaFiles: ['openapi.json'] },
+      })
+      expect(ambiguous).toMatchObject({ error: 'ambiguous' })
+      const candidates = (ambiguous as { candidates: Array<{ file: string }> }).candidates
+      expect(candidates.length).toBe(2)
+
+      clearApiSchemaCache()
+      const resolved = await resolveDataSourceShape({
+        projectRoot: tmp, name: 'useCats', file: candidates[0].file,
+        schemaScan: { apiSchemaFiles: ['openapi.json'] },
+      })
+      expect('error' in resolved).toBe(false)
+      expect((resolved as DataSourceShape).shape_source).toBe('api-schema')
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+
+  it('unknown names return not_found', async () => {
+    const tmp = await scaffold({
+      'src/composables/useCats.ts': `export function useCats() { return fetch('/api/cats') }`,
+    })
+    try {
+      const result = await resolveDataSourceShape({
+        projectRoot: tmp, name: 'useNothing',
+        schemaScan: { apiSchemaFiles: ['missing.json'] },
+      })
+      expect(result).toEqual({ error: 'not_found', name: 'useNothing' })
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true })
+    }
+  })
+})
diff --git a/src/server/__tests__/file-snapshots.test.ts b/src/server/__tests__/file-snapshots.test.ts
new file mode 100644
index 0000000..dcb3766
--- /dev/null
+++ b/src/server/__tests__/file-snapshots.test.ts
@@ -0,0 +1,397 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { createSnapshotStore } from '../file-snapshots'
+
+const ORIGINAL = `<template>
+  <h1 class="title">Planets</h1>
+</template>
+`
+
+describe('file-snapshots', () => {
+  let root: string
+  let file: string
+
+  async function write(rel: string, content: string): Promise<void> {
+    const abs = path.join(root, rel)
+    await fsp.mkdir(path.dirname(abs), { recursive: true })
+    await fsp.writeFile(abs, content, 'utf-8')
+  }
+
+  async function read(rel: string): Promise<string> {
+    return fsp.readFile(path.join(root, rel), 'utf-8')
+  }
+
+  beforeEach(async () => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-snap-'))
+    file = 'src/PlanetsPage.vue'
+    await write(file, ORIGINAL)
+  })
+
+  afterEach(async () => {
+    await fsp.rm(root, { recursive: true, force: true })
+  })
+
+  it('snapshot → agent write → revertBatch restores pre-batch bytes byte-for-byte', async () => {
+    const store = createSnapshotStore(root)
+    await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+    // The journal must exist BEFORE the agent runs (crash safety).
+    expect(fs.existsSync(path.join(root, '.annotask', 'file-snapshots.json'))).toBe(true)
+
+    await write(file, ORIGINAL.replace('Planets', 'Worlds'))
+    await store.sealBatch('ab-1')
+
+    const result = await store.revertBatch('ab-1')
+    expect(result.reverted).toEqual([file])
+    expect(result.skipped).toEqual([])
+    expect(await read(file)).toBe(ORIGINAL)
+    // Fully-undone session → empty journal.
+    expect((await store.state()).files).toEqual({})
+    expect((await store.state()).batches).toEqual([])
+  })
+
+  it('captures the session base ONCE across batches; revertAll restores it', async () => {
+    const store = createSnapshotStore(root)
+    await store.snapshotFiles([file], { id: 'ab-1', taskId: 't1' })
+    await write(file, ORIGINAL.replace('Planets', 'Worlds'))
+    await store.sealBatch('ab-1')
+
+    await store.snapshotFiles([file], { id: 'ab-2', taskId: 't2' })
+    await write(file, ORIGINAL.replace('Planets', 'Galaxies'))
+    await store.sealBatch('ab-2')
+
+    const result = await store.revertAll()
+    expect(result.reverted).toEqual([file])
+    expect(await read(file)).toBe(ORIGINAL) // base, not the intermediate state
+    expect((await store.state()).files).toEqual({})
+  })
+
+  it('undoing the last batch restores the previous batch state (LIFO); older batches are refused', async () => {
+    const store = createSnapshotStore(root)
+    const afterBatch1 = ORIGINAL.replace('Planets', 'Worlds')
+    await store.snapshotFiles([file], { id: 'ab-1', taskId: 't1' })
+    await write(file, afterBatch1)
+    await store.sealBatch('ab-1')
+
+    await store.snapshotFiles([file], { id: 'ab-2', taskId: 't2' })
+    await write(file, ORIGINAL.replace('Planets', 'Galaxies'))
+    await store.sealBatch('ab-2')
+
+    await expect(store.revertBatch('ab-1')).rejects.toThrow(/most recent/)
+
+    await store.revertBatch('ab-2')
+    expect(await read(file)).toBe(afterBatch1)
+    await store.revertBatch('ab-1')
+    expect(await read(file)).toBe(ORIGINAL)
+  })
+
+  it('hash-guards restores: a user edit after the seal marks the file diverged and skips it', async () => {
+    const store = createSnapshotStore(root)
+    await store.snapshotFiles([file], { id: 'ab-1', taskId: 't1' })
+    await write(file, ORIGINAL.replace('Planets', 'Worlds'))
+    await store.sealBatch('ab-1')
+
+    // The user edits in their own editor after the agent ran.
+    const userEdit = (await read(file)) + '<!-- user edit -->\n'
+    await write(file, userEdit)
+
+    const result = await store.revertBatch('ab-1')
+    expect(result.reverted).toEqual([])
+    expect(result.skipped).toEqual([file])
+    expect(await read(file)).toBe(userEdit) // never clobbered
+
+    const state = await store.state()
+    expect(state.files[file]?.status).toBe('diverged')
+
+    // detachFile is the resolution: keep disk bytes, forget the file.
+    await store.detachFile(file)
+    expect((await store.state()).files[file]).toBeUndefined()
+    expect(await read(file)).toBe(userEdit)
+  })
+
+  it('REHYDRATES across restarts (never auto-reverts) and revertAll still works after', async () => {
+    const store = createSnapshotStore(root)
+    await store.snapshotFiles([file], { id: 'ab-1', taskId: 't1' })
+    const agentBytes = ORIGINAL.replace('Planets', 'Worlds')
+    await write(file, agentBytes)
+    await store.sealBatch('ab-1')
+    await store.flush()
+
+    // "Restart": a fresh store on the same root.
+    const restarted = createSnapshotStore(root)
+    // Agent-written work survives the restart.
+    expect(await read(file)).toBe(agentBytes)
+    const state = await restarted.state()
+    expect(state.batches.map((b) => b.id)).toEqual(['ab-1'])
+    expect(state.files[file]?.status).toBe('clean')
+
+    const result = await restarted.revertAll()
+    expect(result.reverted).toEqual([file])
+    expect(await read(file)).toBe(ORIGINAL)
+  })
+
+  it('migrates a legacy render-in-place draft journal with the old restore-and-clear semantics', async () => {
+    const modified = ORIGINAL + '<PlanetCard />\n'
+    await write(file, modified)
+    const legacy = {
+      'draft-1': {
+        absPath: path.join(root, file),
+        original: ORIGINAL,
+        modifiedHash: (await import('node:crypto')).createHash('sha256').update(modified).digest('hex'),
+      },
+    }
+    await write('.annotask/draft-edits.json', JSON.stringify(legacy))
+
+    const store = createSnapshotStore(root)
+    await store.flush()
+    expect(await read(file)).toBe(ORIGINAL)
+    expect(fs.existsSync(path.join(root, '.annotask', 'draft-edits.json'))).toBe(false)
+  })
+
+  it('commit keeps the bytes and drops the journal (task-accept path)', async () => {
+    const store = createSnapshotStore(root)
+    await store.snapshotFiles([file], { id: 'ab-1', taskId: 't1' })
+    const agentBytes = ORIGINAL.replace('Planets', 'Worlds')
+    await write(file, agentBytes)
+    await store.sealBatch('ab-1')
+
+    await store.commit()
+    expect(await read(file)).toBe(agentBytes)
+    expect((await store.state()).files).toEqual({})
+    expect(fs.existsSync(path.join(root, '.annotask', 'file-snapshots.json'))).toBe(false)
+  })
+
+  it('rejects snapshot targets outside the project root', async () => {
+    const store = createSnapshotStore(root)
+    await expect(store.snapshotFiles(['../outside.vue'], { id: 'ab-1', taskId: 't1' })).rejects.toThrow(/escapes/)
+    const outsideAbs = path.join(os.tmpdir(), 'annotask-outside.vue')
+    await expect(store.snapshotFiles([outsideAbs], { id: 'ab-2', taskId: 't2' })).rejects.toThrow(/escapes/)
+  })
+
+  describe('agent-created files (W4 netting — git projects)', () => {
+    function gitInit(): void {
+      const git = (args: string[]) => execFileSync('git', args, { cwd: root, stdio: 'ignore' })
+      git(['init', '-q'])
+      git(['add', '-A'])
+      git(['-c', 'user.email=ci@annotask.test', '-c', 'user.name=annotask-ci', 'commit', '-q', '-m', 'baseline'])
+    }
+
+    it('seal nets new untracked files into the batch; undo deletes pristine copies', async () => {
+      gitInit()
+      const store = createSnapshotStore(root)
+      // A pre-existing untracked file is the user's — never netted.
+      await write('src/UserDraft.vue', '<template>mine</template>')
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+
+      // The agent edits the snapshotted file AND creates a new component.
+      await write(file, ORIGINAL.replace('Planets', 'Worlds'))
+      await write('src/Pagination.vue', '<template><nav class="placeholder">pagination here</nav></template>')
+      await store.sealBatch('ab-1')
+
+      const state = await store.state()
+      expect(state.batches[0].created).toEqual(['src/Pagination.vue'])
+
+      const result = await store.revertBatch('ab-1')
+      expect(result.reverted.sort()).toEqual([file, 'src/Pagination.vue'].sort())
+      expect(result.skipped).toEqual([])
+      expect(await read(file)).toBe(ORIGINAL)
+      expect(fs.existsSync(path.join(root, 'src/Pagination.vue'))).toBe(false)
+      // The user's untracked draft was never touched.
+      expect(await read('src/UserDraft.vue')).toBe('<template>mine</template>')
+    })
+
+    it('a user-edited created file is kept (and reported skipped) on undo', async () => {
+      gitInit()
+      const store = createSnapshotStore(root)
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await write('src/New.vue', '<template>agent</template>')
+      await store.sealBatch('ab-1')
+
+      await write('src/New.vue', '<template>agent + my edits</template>')
+      const result = await store.revertBatch('ab-1')
+      expect(result.skipped).toEqual(['src/New.vue'])
+      expect(await read('src/New.vue')).toBe('<template>agent + my edits</template>')
+    })
+
+    it('revertAll (discard) deletes pristine created files across batches', async () => {
+      gitInit()
+      const store = createSnapshotStore(root)
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await write('src/A.vue', 'a')
+      await store.sealBatch('ab-1')
+      await store.snapshotFiles([file], { id: 'ab-2', taskId: 'task-2' })
+      await write('src/B.vue', 'b')
+      await store.sealBatch('ab-2')
+
+      const result = await store.revertAll()
+      expect(result.reverted).toContain('src/A.vue')
+      expect(result.reverted).toContain('src/B.vue')
+      expect(fs.existsSync(path.join(root, 'src/A.vue'))).toBe(false)
+      expect(fs.existsSync(path.join(root, 'src/B.vue'))).toBe(false)
+    })
+
+    it('non-git projects skip the net silently (snapshotted files still restore)', async () => {
+      const store = createSnapshotStore(root) // no git init
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await write(file, 'changed')
+      await write('src/New.vue', 'agent file survives undo without git')
+      await store.sealBatch('ab-1')
+      const state = await store.state()
+      expect(state.batches[0].created).toBeUndefined()
+      const result = await store.revertBatch('ab-1')
+      expect(result.reverted).toEqual([file])
+      expect(fs.existsSync(path.join(root, 'src/New.vue'))).toBe(true)
+    })
+  })
+
+  describe('byte-exact coverage — git auto-extend (undo covers the agent\'s whole footprint)', () => {
+    function gitInit(): void {
+      const git = (args: string[]) => execFileSync('git', args, { cwd: root, stdio: 'ignore' })
+      git(['init', '-q'])
+      // Repo-level identity so `git stash create` (the baseline) can commit.
+      git(['config', 'user.email', 'ci@annotask.test'])
+      git(['config', 'user.name', 'annotask-ci'])
+      git(['add', '-A'])
+      git(['commit', '-q', '-m', 'baseline'])
+    }
+    const SHARED = '<template><nav class="layout">shared layout</nav></template>\n'
+
+    it('undo restores a NON-anchor file the agent also edited (not just the predicted anchors)', async () => {
+      await write('src/Shared.vue', SHARED)
+      gitInit()
+      const store = createSnapshotStore(root)
+      // The apply predicts only the anchor file…
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      // …but the freeform agent edits the anchor AND a shared layout it was
+      // never told about — the case that made undo silently partial.
+      await write(file, ORIGINAL.replace('Planets', 'Worlds'))
+      await write('src/Shared.vue', SHARED.replace('shared layout', 'rebuilt layout'))
+      await store.sealBatch('ab-1')
+
+      // Seal folded the off-anchor file into the batch.
+      expect((await store.state()).batches[0].files).toContain('src/Shared.vue')
+
+      const result = await store.revertBatch('ab-1')
+      expect(result.reverted.sort()).toEqual([file, 'src/Shared.vue'].sort())
+      expect(await read(file)).toBe(ORIGINAL)
+      expect(await read('src/Shared.vue')).toBe(SHARED) // byte-exact, never a predicted anchor
+    })
+
+    it('undo RECREATES a file the agent deleted (byte-exact, from held bytes)', async () => {
+      await write('src/Doomed.vue', SHARED)
+      gitInit()
+      const store = createSnapshotStore(root)
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await fsp.rm(path.join(root, 'src/Doomed.vue')) // the agent deletes it
+      await store.sealBatch('ab-1')
+
+      expect((await store.state()).batches[0].files).toContain('src/Doomed.vue')
+      const result = await store.revertBatch('ab-1')
+      expect(result.reverted).toContain('src/Doomed.vue')
+      expect(fs.existsSync(path.join(root, 'src/Doomed.vue'))).toBe(true)
+      expect(await read('src/Doomed.vue')).toBe(SHARED)
+    })
+
+    it('a user edit to an auto-extended file after seal is honoured (diverged, not clobbered)', async () => {
+      await write('src/Shared.vue', SHARED)
+      gitInit()
+      const store = createSnapshotStore(root)
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await write('src/Shared.vue', SHARED.replace('shared layout', 'agent layout'))
+      await store.sealBatch('ab-1')
+
+      // The user keeps working on the agent's output, THEN undoes.
+      const mine = SHARED.replace('shared layout', 'agent layout + my tweak')
+      await write('src/Shared.vue', mine)
+      const result = await store.revertBatch('ab-1')
+      expect(result.skipped).toContain('src/Shared.vue')
+      expect(await read('src/Shared.vue')).toBe(mine) // never clobbered
+    })
+
+    it('discard restores every auto-extended file to the session base across batches', async () => {
+      await write('src/Shared.vue', SHARED)
+      gitInit()
+      const store = createSnapshotStore(root)
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await write('src/Shared.vue', SHARED.replace('shared layout', 'v1'))
+      await store.sealBatch('ab-1')
+      await store.snapshotFiles([file], { id: 'ab-2', taskId: 'task-2' })
+      await write('src/Shared.vue', SHARED.replace('shared layout', 'v2'))
+      await store.sealBatch('ab-2')
+
+      await store.revertAll()
+      expect(await read('src/Shared.vue')).toBe(SHARED) // session base, not v1/v2
+    })
+  })
+
+  describe('running-batch guard (no clobbering a live, unsealed apply)', () => {
+    it('revertBatch refuses a still-running batch — the agent may be mid-write', async () => {
+      const store = createSnapshotStore(root)
+      // snapshot but DON'T seal: the batch is 'running', files have no
+      // lastAppliedHash, so an unguarded restore would clobber blindly.
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await write(file, ORIGINAL.replace('Planets', 'half-written'))
+
+      await expect(store.revertBatch('ab-1')).rejects.toThrow(/still running/)
+      // The in-progress bytes are untouched.
+      expect(await read(file)).toBe(ORIGINAL.replace('Planets', 'half-written'))
+    })
+
+    it('revertAll refuses while any batch is still running', async () => {
+      const store = createSnapshotStore(root)
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await write(file, ORIGINAL.replace('Planets', 'half-written'))
+      await expect(store.revertAll()).rejects.toThrow(/still running/)
+      expect(await read(file)).toBe(ORIGINAL.replace('Planets', 'half-written'))
+    })
+
+    it('sealing the batch as failed makes it revertible again (the abandon path)', async () => {
+      const store = createSnapshotStore(root)
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await write(file, ORIGINAL.replace('Planets', 'half-written'))
+
+      // releaseApplyTask seals 'failed' on abandon — now the guard passes and
+      // undo restores the clean pre-apply bytes.
+      await store.sealBatchByTask('task-1', { failed: true })
+      const result = await store.revertBatch('ab-1')
+      expect(result.reverted).toEqual([file])
+      expect(await read(file)).toBe(ORIGINAL)
+    })
+  })
+
+  describe('sealBatchByTask (the review hook seals by task, not batch id)', () => {
+    it('seals the batch for a task and re-seals to the NEW bytes on a second review', async () => {
+      const store = createSnapshotStore(root)
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+
+      // First agent run + review.
+      const v1 = ORIGINAL.replace('Planets', 'Worlds')
+      await write(file, v1)
+      await store.sealBatchByTask('task-1')
+      expect((await store.state()).batches[0].status).toBe('done')
+
+      // Deny → re-apply: the SAME batch, the agent writes NEW bytes, review
+      // fires again. Without a re-seal the undo guard would think v2 diverged.
+      const v2 = ORIGINAL.replace('Planets', 'Galaxies')
+      await write(file, v2)
+      await store.sealBatchByTask('task-1')
+
+      // The file is NOT diverged (the seal caught up to v2)…
+      expect((await store.state()).files[file]?.status).toBe('clean')
+      // …and undo restores the clean pre-apply bytes byte-for-byte.
+      const result = await store.revertBatch('ab-1')
+      expect(result.reverted).toEqual([file])
+      expect(await read(file)).toBe(ORIGINAL)
+    })
+
+    it('is a no-op when no batch matches the task', async () => {
+      const store = createSnapshotStore(root)
+      await store.snapshotFiles([file], { id: 'ab-1', taskId: 'task-1' })
+      await expect(store.sealBatchByTask('task-unknown')).resolves.toBeUndefined()
+      expect((await store.state()).batches[0].status).toBe('running')
+    })
+  })
+})
diff --git a/src/server/__tests__/init-cli-matrix-stress.test.ts b/src/server/__tests__/init-cli-matrix-stress.test.ts
new file mode 100644
index 0000000..7a6a05d
--- /dev/null
+++ b/src/server/__tests__/init-cli-matrix-stress.test.ts
@@ -0,0 +1,423 @@
+/**
+ * CLI matrix init suite against the stress-test playground.
+ *
+ * Runs `createInitRunner` once per local CLI (claude, codex, opencode,
+ * copilot) against an isolated copy of `playgrounds/stress-test/`. All four
+ * CLIs run concurrently so total wall time ≈ slowest CLI.
+ *
+ * Each run asserts the three artifacts that init is supposed to produce:
+ *   - .annotask/design-spec.json   (parses, ≥3 colors, theme list non-empty)
+ *   - .annotask/STYLE_GUIDE.md     (non-template content)
+ *   - .annotask/agents.json        (all built-ins filled with provider locked
+ *                                   to the requested CLI)
+ *
+ * Skipped by default. Enable with `ANNOTASK_LIVE_CLI=1`:
+ *
+ *   ANNOTASK_LIVE_CLI=1 pnpm test:cli-matrix:stress
+ *
+ * Filter to a subset:
+ *
+ *   ANNOTASK_LIVE_CLI=1 ANNOTASK_LIVE_ONLY=claude,opencode pnpm test:cli-matrix:stress
+ *
+ * Keep the per-CLI workspace copies + MDX report for inspection:
+ *
+ *   ANNOTASK_LIVE_CLI=1 ANNOTASK_CLI_MATRIX_KEEP=1 pnpm test:cli-matrix:stress
+ *
+ * The MDX report lands at `reports/cli-matrix/<timestamp>/index.mdx`.
+ */
+
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+
+import { createInitRunner, type InitState } from '../init.js'
+import { createAgentDetector, type AgentDetectSnapshot, type AgentDetector } from '../agent-detect.js'
+import { BUILT_IN_PERSONAS } from '../../embedded/persona.js'
+import {
+  LIVE_CLI_ENABLED,
+  isLiveCliEnabled,
+  liveModelFor,
+  type LiveProviderKey,
+} from '../../embedded/__tests__/live-cli-helpers.js'
+import {
+  writeMdxReport,
+  type AssertionResult,
+  type PerCliRun,
+  type RunStatus,
+} from './cli-matrix-report.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..')
+const STRESS_TEST_ROOT = path.join(REPO_ROOT, 'playgrounds', 'stress-test')
+
+const KEEP_WORKSPACES = process.env.ANNOTASK_CLI_MATRIX_KEEP === '1'
+const POLL_INTERVAL_MS = 500
+const PER_CLI_TIMEOUT_MS = 12 * 60_000  // init does two CLI spawns; each has its own 5-min cap
+
+const CLI_KEYS: LiveProviderKey[] = [
+  'claude-local',
+  'codex-local',
+  'opencode-local',
+  'copilot-local',
+]
+
+const describeIf = LIVE_CLI_ENABLED ? describe : describe.skip
+
+interface MatrixContext {
+  startedAt: number
+  runs: PerCliRun[]
+}
+
+describeIf('CLI matrix init — stress-test', () => {
+  const context: MatrixContext = { startedAt: Date.now(), runs: [] }
+  const createdRoots: string[] = []
+
+  beforeAll(() => {
+    context.startedAt = Date.now()
+  })
+
+  afterAll(async () => {
+    const totalWallMs = Date.now() - context.startedAt
+    const timestamp = new Date().toISOString()
+    const reportDir = path.join(REPO_ROOT, 'reports', 'cli-matrix', timestamp.replace(/[:.]/g, '-'))
+    const reportPath = path.join(reportDir, 'index.mdx')
+    try {
+      await writeMdxReport(
+        {
+          timestamp,
+          totalWallMs,
+          suiteVersion: '1.0',
+          runs: context.runs,
+          workspaceKept: KEEP_WORKSPACES,
+        },
+        reportPath,
+      )
+      console.log(`[cli-matrix] report: ${reportPath}`)
+    } catch (err) {
+      console.warn(`[cli-matrix] failed to write report: ${(err as Error).message}`)
+    }
+
+    if (!KEEP_WORKSPACES) {
+      for (const root of createdRoots) {
+        await fsp.rm(root, { recursive: true, force: true }).catch(() => {})
+      }
+    }
+  })
+
+  for (const key of CLI_KEYS) {
+    it.concurrent(
+      `${key} → stress-test`,
+      async () => {
+        if (!isLiveCliEnabled(key)) {
+          const skipped = skipResult(key, liveModelFor(key), `filtered out by ANNOTASK_LIVE_ONLY`)
+          context.runs.push(skipped)
+          return
+        }
+        const run = await runOneCli(key, createdRoots)
+        context.runs.push(run)
+        if (run.status === 'fail') {
+          throw new Error(`${key} failed: ${run.reason ?? 'see assertion details'}`)
+        }
+      },
+      PER_CLI_TIMEOUT_MS + 60_000,
+    )
+  }
+})
+
+async function runOneCli(key: LiveProviderKey, createdRoots: string[]): Promise<PerCliRun> {
+  const model = liveModelFor(key)
+  const detector = createAgentDetector()
+  const snap = await detector.detect()
+  const status = snap[key]
+  if (!status.found) {
+    return skipResult(key, model, `${key} CLI not on PATH`)
+  }
+  if (!status.loggedIn) {
+    return skipResult(key, model, `${key} CLI is installed but not logged in`)
+  }
+
+  const workspaceRoot = await copyStressWorkspace(key)
+  createdRoots.push(workspaceRoot)
+
+  const startedAt = Date.now()
+  const agentLines: string[] = []
+  const stub = stubDetectorWith(snap, key)
+  let lastState: InitState | undefined
+
+  try {
+    const runner = createInitRunner({
+      projectRoot: workspaceRoot,
+      broadcast: (event, data) => {
+        if (event === 'init:progress' && data && typeof data === 'object') {
+          const lines = (data as { agentLines?: string[] }).agentLines
+          if (Array.isArray(lines)) {
+            // Replace rather than concat — broadcast carries the cumulative array
+            agentLines.length = 0
+            agentLines.push(...lines)
+          }
+        }
+      },
+      agentDetect: stub,
+    })
+
+    runner.start({
+      requestedProviderId: key,
+      requestedModel: model,
+      requestedEffort: 'auto',
+    })
+
+    lastState = await waitForCompletion(runner.getState.bind(runner), PER_CLI_TIMEOUT_MS)
+  } catch (err) {
+    return failResult(key, model, Date.now() - startedAt, agentLines, workspaceRoot,
+      `runner threw: ${(err as Error).message}`)
+  }
+
+  const elapsedMs = Date.now() - startedAt
+  const tokens = lastState?.tokenUsage ?? { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 }
+  const tokensExclTurns = {
+    inputTokens: tokens.inputTokens,
+    outputTokens: tokens.outputTokens,
+    cacheReadTokens: tokens.cacheReadTokens,
+    cacheCreationTokens: tokens.cacheCreationTokens,
+  }
+
+  const assertions: AssertionResult[] = []
+  const designSpec = await readDesignSpec(workspaceRoot)
+  const styleGuide = await readStyleGuide(workspaceRoot)
+  const agentsJson = await readAgentsJson(workspaceRoot)
+
+  assertions.push({
+    name: 'design-spec.json parses',
+    ok: designSpec.parsed !== null,
+    detail: designSpec.parseError ?? undefined,
+  })
+  assertions.push({
+    name: 'colors ≥ 3',
+    ok: designSpec.colorCount >= 3,
+    detail: `${designSpec.colorCount} detected`,
+  })
+  assertions.push({
+    name: 'themes non-empty',
+    ok: designSpec.themes.length > 0,
+    detail: `${designSpec.themes.length} themes`,
+  })
+  assertions.push({
+    name: 'STYLE_GUIDE.md non-template',
+    ok: styleGuide.exists && styleGuide.nonTemplate,
+    detail: !styleGuide.exists ? 'missing' : (styleGuide.nonTemplate ? `${styleGuide.length} chars` : 'looks identical to template'),
+  })
+  assertions.push({
+    name: 'agents.json — all built-ins filled',
+    ok: agentsJson.filledBuiltIns === BUILT_IN_PERSONAS.length,
+    detail: `${agentsJson.filledBuiltIns}/${BUILT_IN_PERSONAS.length}`,
+  })
+  assertions.push({
+    name: 'agents.json — providerId locked to requested',
+    ok: agentsJson.allProviderId === key,
+    detail: agentsJson.allProviderId ?? 'mixed',
+  })
+  assertions.push({
+    name: 'token usage > 0',
+    ok: (tokens.inputTokens + tokens.outputTokens) > 0,
+    detail: `${tokens.inputTokens} in / ${tokens.outputTokens} out`,
+  })
+
+  const failedAssertions = assertions.filter((a) => !a.ok)
+  const runStatus: RunStatus = failedAssertions.length === 0 ? 'pass' : 'fail'
+  const failReason = failedAssertions.map((a) => a.name + (a.detail ? ` (${a.detail})` : '')).join('; ')
+
+  return {
+    key,
+    model,
+    status: runStatus,
+    reason: runStatus === 'fail' ? failReason : undefined,
+    elapsedMs,
+    tokens: tokensExclTurns,
+    assertions,
+    designSpec: {
+      colorCount: designSpec.colorCount,
+      colors: designSpec.colors,
+      themes: designSpec.themes,
+    },
+    styleGuideExcerpt: styleGuide.excerpt,
+    agents: agentsJson.summaries,
+    agentLinesTail: agentLines.slice(-30),
+    workspacePath: workspaceRoot,
+  }
+}
+
+function skipResult(key: LiveProviderKey, model: string, reason: string): PerCliRun {
+  console.warn(`[cli-matrix] ${key} skipped: ${reason}`)
+  return {
+    key,
+    model,
+    status: 'skip',
+    reason,
+    elapsedMs: 0,
+    tokens: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 },
+    assertions: [],
+  }
+}
+
+function failResult(
+  key: LiveProviderKey,
+  model: string,
+  elapsedMs: number,
+  agentLines: string[],
+  workspacePath: string,
+  reason: string,
+): PerCliRun {
+  return {
+    key,
+    model,
+    status: 'fail',
+    reason,
+    elapsedMs,
+    tokens: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 },
+    assertions: [{ name: 'runner ran to completion', ok: false, detail: reason }],
+    agentLinesTail: agentLines.slice(-30),
+    workspacePath,
+  }
+}
+
+function stubDetectorWith(real: AgentDetectSnapshot, only: LiveProviderKey): AgentDetector {
+  const empty: AgentDetectSnapshot = {
+    'claude-local': { found: false },
+    'codex-local': { found: false },
+    'opencode-local': { found: false },
+    'copilot-local': { found: false },
+    copilot: { found: false },
+    openrouter: { hasEnv: false },
+    ts: Date.now(),
+  }
+  const snapshot: AgentDetectSnapshot = { ...empty, [only]: real[only] }
+  return {
+    detect: async () => snapshot,
+    invalidate: () => {},
+  }
+}
+
+async function copyStressWorkspace(key: LiveProviderKey): Promise<string> {
+  const dst = await fsp.mkdtemp(path.join(os.tmpdir(), `annotask-cli-matrix-${key}-`))
+  await fsp.cp(STRESS_TEST_ROOT, dst, {
+    recursive: true,
+    filter: (src) => {
+      const rel = path.relative(STRESS_TEST_ROOT, src)
+      if (rel === '') return true
+      const segments = rel.split(path.sep)
+      const blocked = new Set(['node_modules', 'dist', '.git', '.turbo', '.annotask', '.next', 'target'])
+      return !segments.some((seg) => blocked.has(seg))
+    },
+  })
+  return dst
+}
+
+async function waitForCompletion(getState: () => InitState, timeoutMs: number): Promise<InitState> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const state = getState()
+    if (!state.running && state.finishedAt) return state
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS))
+  }
+  throw new Error(`init did not finish within ${Math.round(timeoutMs / 1000)}s`)
+}
+
+interface DesignSpecRead {
+  parsed: Record<string, unknown> | null
+  parseError?: string
+  colorCount: number
+  colors: Array<{ name?: string; value?: string }>
+  themes: Array<{ id?: string; name?: string }>
+}
+
+async function readDesignSpec(workspaceRoot: string): Promise<DesignSpecRead> {
+  const specPath = path.join(workspaceRoot, '.annotask', 'design-spec.json')
+  let raw: string
+  try { raw = await fsp.readFile(specPath, 'utf-8') }
+  catch (err) { return { parsed: null, parseError: `read failed: ${(err as Error).message}`, colorCount: 0, colors: [], themes: [] } }
+  let parsed: any
+  try { parsed = JSON.parse(raw) }
+  catch (err) { return { parsed: null, parseError: `JSON parse failed: ${(err as Error).message}`, colorCount: 0, colors: [], themes: [] } }
+  const colorsRaw = Array.isArray(parsed?.colors) ? parsed.colors : []
+  const colors = colorsRaw.slice(0, 5).map((c: any) => ({
+    name: typeof c?.name === 'string' ? c.name : (typeof c?.role === 'string' ? c.role : undefined),
+    value: typeof c?.value === 'string' ? c.value : (typeof c?.hex === 'string' ? c.hex : undefined),
+  }))
+  const themesRaw = Array.isArray(parsed?.themes) ? parsed.themes : []
+  const themes = themesRaw.map((t: any) => ({
+    id: typeof t?.id === 'string' ? t.id : undefined,
+    name: typeof t?.name === 'string' ? t.name : undefined,
+  }))
+  return {
+    parsed,
+    colorCount: colorsRaw.length,
+    colors,
+    themes,
+  }
+}
+
+interface StyleGuideRead {
+  exists: boolean
+  length: number
+  excerpt?: string
+  nonTemplate: boolean
+}
+
+async function readStyleGuide(workspaceRoot: string): Promise<StyleGuideRead> {
+  const guidePath = path.join(workspaceRoot, '.annotask', 'STYLE_GUIDE.md')
+  let raw: string
+  try { raw = await fsp.readFile(guidePath, 'utf-8') }
+  catch { return { exists: false, length: 0, nonTemplate: false } }
+  // The template ships with the exact placeholder headings + empty sections.
+  // Any CLI that actually filled it in will replace at least one placeholder
+  // comment with real content. We check for two signals: length growth AND
+  // absence of all four placeholder comments untouched.
+  const placeholderCount = (raw.match(/<!--/g) ?? []).length
+  const nonTemplate = raw.length > 200 && placeholderCount < 4
+  return {
+    exists: true,
+    length: raw.length,
+    excerpt: raw.slice(0, 600),
+    nonTemplate,
+  }
+}
+
+interface AgentsJsonRead {
+  filledBuiltIns: number
+  allProviderId: string | null
+  summaries: Array<{ id: string; firstSentence: string }>
+}
+
+async function readAgentsJson(workspaceRoot: string): Promise<AgentsJsonRead> {
+  const filePath = path.join(workspaceRoot, '.annotask', 'agents.json')
+  let raw: string
+  try { raw = await fsp.readFile(filePath, 'utf-8') }
+  catch { return { filledBuiltIns: 0, allProviderId: null, summaries: [] } }
+  let parsed: any
+  try { parsed = JSON.parse(raw) }
+  catch { return { filledBuiltIns: 0, allProviderId: null, summaries: [] } }
+  const agents = (parsed && typeof parsed === 'object' && parsed.agents) || {}
+  let filled = 0
+  const providerIds = new Set<string>()
+  const summaries: Array<{ id: string; firstSentence: string }> = []
+  for (const persona of BUILT_IN_PERSONAS) {
+    const entry = agents[persona.id]
+    const directions = typeof entry?.projectDirections === 'string' ? entry.projectDirections.trim() : ''
+    if (directions.length > 0) filled += 1
+    if (typeof entry?.providerId === 'string') providerIds.add(entry.providerId)
+    if (directions) {
+      const firstSentence = directions.split(/(?<=[.!?])\s+/)[0]?.slice(0, 180) ?? ''
+      summaries.push({ id: persona.id, firstSentence })
+    } else {
+      summaries.push({ id: persona.id, firstSentence: '(empty)' })
+    }
+  }
+  return {
+    filledBuiltIns: filled,
+    allProviderId: providerIds.size === 1 ? [...providerIds][0] : null,
+    summaries,
+  }
+}
diff --git a/src/server/__tests__/init.test.ts b/src/server/__tests__/init.test.ts
new file mode 100644
index 0000000..e1ebfca
--- /dev/null
+++ b/src/server/__tests__/init.test.ts
@@ -0,0 +1,434 @@
+import { describe, expect, it } from 'vitest'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { __test, createInitRunner, buildInitCliInvocation } from '../init.js'
+import type { AgentDetectSnapshot } from '../agent-detect.js'
+import { BUILT_IN_PERSONAS } from '../../embedded/persona.js'
+
+function snap(overrides: Partial<AgentDetectSnapshot> = {}): AgentDetectSnapshot {
+  return {
+    'claude-local': { found: false, loggedIn: false },
+    'codex-local': { found: false, loggedIn: false },
+    'opencode-local': { found: false, loggedIn: false },
+    'copilot-local': { found: false, loggedIn: false },
+    copilot: { found: false, loggedIn: false },
+    openrouter: { hasEnv: false },
+    ts: 1,
+    ...overrides,
+  }
+}
+
+describe('buildInitCliInvocation — per-CLI init argv', () => {
+  const base = { skillBody: 'SKILL', userMessage: 'do the init' }
+
+  it('codex includes --skip-git-repo-check (regression: codex refuses non-git dirs without it)', () => {
+    const { args } = buildInitCliInvocation({ bin: 'codex', ...base })
+    expect(args).toEqual(expect.arrayContaining(['exec', '--json', '--full-auto', '--skip-git-repo-check']))
+    // The prompt rides as the trailing positional after `--`.
+    expect(args[args.length - 2]).toBe('--')
+  })
+
+  it('claude pipes the skill+prompt on stdin with bypass flags', () => {
+    const { args, stdin } = buildInitCliInvocation({ bin: 'claude', ...base })
+    expect(args).toEqual(expect.arrayContaining(['--print', '--output-format', 'stream-json', '--dangerously-skip-permissions']))
+    expect(stdin).toContain('SKILL')
+    expect(stdin).toContain('do the init')
+  })
+
+  it('copilot keeps --allow-all-tools and passes the prompt via -p', () => {
+    const { args } = buildInitCliInvocation({ bin: 'copilot', ...base })
+    expect(args).toEqual(expect.arrayContaining(['--output-format', 'json', '--allow-all-tools', '-p']))
+  })
+
+  it('opencode uses run --format=json with the bypass toggle', () => {
+    const { args } = buildInitCliInvocation({ bin: 'opencode', ...base })
+    expect(args).toEqual(expect.arrayContaining(['run', '--print-logs', '--format=json', '--dangerously-skip-permissions', '--']))
+  })
+
+  it('threads model + reasoning effort when provided (codex)', () => {
+    const { args } = buildInitCliInvocation({ bin: 'codex', model: 'gpt-5.4', effort: 'high', ...base })
+    expect(args).toEqual(expect.arrayContaining(['--model', 'gpt-5.4', '-c', 'model_reasoning_effort=high']))
+  })
+
+  it("omits effort flags for 'auto'/'minimal'", () => {
+    const { args } = buildInitCliInvocation({ bin: 'codex', effort: 'auto', ...base })
+    expect(args).not.toContain('-c')
+  })
+})
+
+describe('init CLI selection', () => {
+  it('honors the requested opencode provider when multiple CLIs are ready', () => {
+    const selected = __test.selectInitCli(snap({
+      'claude-local': { found: true, loggedIn: true },
+      'opencode-local': { found: true, loggedIn: true },
+    }), 'opencode-local')
+
+    expect(selected?.id).toBe('opencode-local')
+  })
+
+  it('rejects the requested local CLI when found but not logged in', () => {
+    const selected = __test.selectInitCli(snap({
+      'claude-local': { found: true, loggedIn: true },
+      'opencode-local': { found: true, loggedIn: false },
+    }), 'opencode-local')
+
+    expect(selected).toBeNull()
+  })
+
+  it('surfaces a targeted message when the requested CLI is found but not logged in', () => {
+    const s = snap({
+      'opencode-local': { found: true, loggedIn: false },
+    })
+    const reason = __test.initCliNotReadyReason(s, 'opencode-local')
+    expect(reason).toMatch(/installed but not logged in/)
+  })
+
+  it('does not silently switch to Claude when the requested CLI is missing', () => {
+    const selected = __test.selectInitCli(snap({
+      'claude-local': { found: true, loggedIn: true },
+      'opencode-local': { found: false, loggedIn: false },
+    }), 'opencode-local')
+
+    expect(selected).toBeNull()
+  })
+})
+
+async function withTempAgentsFile(
+  contents: unknown,
+  fn: (filePath: string) => Promise<void>,
+): Promise<void> {
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'annotask-init-test-'))
+  const filePath = path.join(dir, 'agents.json')
+  if (contents != null) {
+    await fsp.writeFile(filePath, JSON.stringify(contents, null, 2), 'utf-8')
+  }
+  try {
+    await fn(filePath)
+  } finally {
+    await fsp.rm(dir, { recursive: true, force: true })
+  }
+}
+
+describe('enforceSelectedRuntime', () => {
+  it('overwrites pre-existing Claude provider/model/effort with the selected runtime', async () => {
+    const existing = {
+      version: 1,
+      agents: {
+        general:     { projectDirections: 'pre-existing general directions',     providerId: 'claude-local', model: 'sonnet', effort: 'medium' },
+        designer:    { projectDirections: 'pre-existing designer directions',    providerId: 'claude-local', model: 'sonnet', effort: 'medium' },
+        a11y:        { projectDirections: 'pre-existing a11y directions',        providerId: 'claude-local', model: 'opus',   effort: 'high'   },
+        'bug-hunter':{ projectDirections: 'pre-existing bug-hunter directions',  providerId: 'claude-local', model: 'opus',   effort: 'high'   },
+      },
+    }
+
+    await withTempAgentsFile(existing, async (filePath) => {
+      await __test.enforceSelectedRuntime({
+        filePath,
+        providerId: 'opencode-local',
+        model: 'openai/gpt-5.5',
+        effort: 'high',
+        fallbackRoleText: true,
+      })
+
+      const written = JSON.parse(await fsp.readFile(filePath, 'utf-8'))
+      for (const persona of BUILT_IN_PERSONAS) {
+        const entry = written.agents[persona.id]
+        expect(entry.providerId).toBe('opencode-local')
+        expect(entry.model).toBe('openai/gpt-5.5')
+        expect(entry.effort).toBe('high')
+        // Pre-existing directions are preserved.
+        expect(entry.projectDirections).toBe(`pre-existing ${persona.id} directions`)
+      }
+    })
+  })
+
+  it('preserves custom (non-built-in) personas verbatim', async () => {
+    const existing = {
+      version: 1,
+      agents: {
+        general:        { projectDirections: 'd', providerId: 'claude-local', model: 'sonnet', effort: 'medium' },
+        'copy-editor':  { projectDirections: 'custom directions', providerId: 'openai', model: 'gpt-5', effort: 'low' },
+      },
+    }
+
+    await withTempAgentsFile(existing, async (filePath) => {
+      await __test.enforceSelectedRuntime({
+        filePath,
+        providerId: 'opencode-local',
+        model: 'openai/gpt-5.5',
+        effort: 'high',
+        fallbackRoleText: false,
+      })
+
+      const written = JSON.parse(await fsp.readFile(filePath, 'utf-8'))
+      expect(written.agents['copy-editor']).toEqual({
+        projectDirections: 'custom directions',
+        providerId: 'openai',
+        model: 'gpt-5',
+        effort: 'low',
+      })
+      // And the built-ins were rewritten to the selected runtime.
+      expect(written.agents.general.providerId).toBe('opencode-local')
+      expect(written.agents.general.model).toBe('openai/gpt-5.5')
+      expect(written.agents.general.effort).toBe('high')
+    })
+  })
+
+  it('seeds role-text fallback when projectDirections is empty and fallbackRoleText is true', async () => {
+    await withTempAgentsFile(null, async (filePath) => {
+      const result = await __test.enforceSelectedRuntime({
+        filePath,
+        providerId: 'codex-local',
+        model: 'gpt-5',
+        effort: 'medium',
+        fallbackRoleText: true,
+      })
+      expect(result.backfilled).toBe(BUILT_IN_PERSONAS.length)
+      const written = JSON.parse(await fsp.readFile(filePath, 'utf-8'))
+      for (const persona of BUILT_IN_PERSONAS) {
+        expect(written.agents[persona.id].projectDirections).toBe(persona.roleDirections)
+        expect(written.agents[persona.id].providerId).toBe('codex-local')
+        expect(written.agents[persona.id].model).toBe('gpt-5')
+        expect(written.agents[persona.id].effort).toBe('medium')
+      }
+    })
+  })
+
+  it('leaves projectDirections empty when fallbackRoleText is false', async () => {
+    await withTempAgentsFile(null, async (filePath) => {
+      await __test.enforceSelectedRuntime({
+        filePath,
+        providerId: 'opencode-local',
+        model: 'openai/gpt-5.5',
+        effort: 'high',
+        fallbackRoleText: false,
+      })
+      const written = JSON.parse(await fsp.readFile(filePath, 'utf-8'))
+      for (const persona of BUILT_IN_PERSONAS) {
+        expect(written.agents[persona.id].projectDirections).toBe('')
+        expect(written.agents[persona.id].providerId).toBe('opencode-local')
+      }
+    })
+  })
+})
+
+describe('buildAgentConfigsPrompt', () => {
+  const prompt = __test.buildAgentConfigsPrompt({
+    projectRoot: '/tmp/example',
+    framework: { name: 'vue', version: '3.5', styling: ['scoped-css'] },
+    totalPersonas: BUILT_IN_PERSONAS.length,
+  })
+
+  it('tells the CLI it may only edit projectDirections', () => {
+    expect(prompt).toMatch(/only edit the `projectDirections`/i)
+    expect(prompt).toMatch(/providerId.*model.*effort.*owned by Annotask/i)
+  })
+
+  it('does not ask the CLI to pick a model per persona', () => {
+    // Forbid prose that would invite the CLI to pick or write models/effort.
+    expect(prompt).not.toMatch(/pick (a|an|the)? ?model/i)
+    expect(prompt).not.toMatch(/choose (a|an|the)? ?model/i)
+    expect(prompt).not.toMatch(/select (a|an|the)? ?model/i)
+    expect(prompt).not.toMatch(/decide (the|which)? ?model/i)
+    expect(prompt).not.toMatch(/pick (a|an|the)? ?effort/i)
+    expect(prompt).not.toMatch(/choose (a|an|the)? ?effort/i)
+    expect(prompt).not.toMatch(/select (a|an|the)? ?effort/i)
+    expect(prompt).not.toMatch(/assign (a|an|the)? ?model/i)
+  })
+
+  it('does not embed concrete provider/model/effort values that could be copied', () => {
+    // Older versions wrote out the resolved values for the CLI to "keep" — a
+    // shape that invited the CLI to echo them back as if it had chosen them.
+    expect(prompt).not.toMatch(/providerId=opencode-local/)
+    expect(prompt).not.toMatch(/model="openai\/gpt-5\.5"/)
+    expect(prompt).not.toMatch(/effort=high/)
+  })
+})
+
+describe('detectFatalStderrLine', () => {
+  it('returns null for non-error opencode log lines', () => {
+    expect(__test.detectFatalStderrLine('opencode', 'INFO  2026-... service=default loading')).toBeNull()
+    expect(__test.detectFatalStderrLine('opencode', '')).toBeNull()
+  })
+
+  it('flags ConnectionRefused on the configured LLM provider', () => {
+    const line = 'ERROR 2026-05-20T19:34:07 +1ms service=llm providerID=vllm modelID=Qwen/Qwen2.5-7B-Instruct-AWQ error={"error":{"name":"AI_APICallError","cause":{"code":"ConnectionRefused","path":"http://127.0.0.1:8010/v1/chat/completions"}}}'
+    const result = __test.detectFatalStderrLine('opencode', line)
+    expect(result).toMatch(/LLM provider unreachable/)
+    expect(result).toContain('ConnectionRefused')
+    expect(result).toContain('http://127.0.0.1:8010/v1/chat/completions')
+  })
+
+  it('flags AI_APICallError without a structured cause', () => {
+    const line = 'ERROR 2026-... service=llm error={"error":{"name":"AI_APICallError"}}'
+    const result = __test.detectFatalStderrLine('opencode', line)
+    expect(result).toMatch(/LLM call failed: AI_APICallError/)
+  })
+
+  it('ignores non-llm ERROR lines (e.g. file watchers) that the CLI recovers from', () => {
+    const line = 'ERROR 2026-... service=file.watcher backend=inotify path=/foo failed to watch'
+    expect(__test.detectFatalStderrLine('opencode', line)).toBeNull()
+  })
+
+  it('only inspects opencode for now — other CLIs return null', () => {
+    const line = 'ERROR service=llm something broken'
+    expect(__test.detectFatalStderrLine('claude', line)).toBeNull()
+    expect(__test.detectFatalStderrLine('codex', line)).toBeNull()
+    expect(__test.detectFatalStderrLine('copilot', line)).toBeNull()
+  })
+})
+
+describe('initRunner.reset', () => {
+  function makeRunner() {
+    const broadcasts: Array<{ event: string; data: any }> = []
+    const runner = createInitRunner({
+      projectRoot: os.tmpdir(),
+      broadcast: (event, data) => broadcasts.push({ event, data }),
+      agentDetect: { detect: async () => snap(), invalidate: () => {} } as any,
+    })
+    return { runner, broadcasts }
+  }
+
+  it('drops step state and broadcasts a fresh progress event', () => {
+    const { runner, broadcasts } = makeRunner()
+    // Pre-load state as if a prior run completed: mutate via getState→start is
+    // hard, but reset() works on the closure state directly, so it's enough to
+    // call reset and observe the broadcast shape from a known starting point.
+    const before = runner.getState()
+    expect(before.steps.length).toBeGreaterThan(0)
+    expect(before.steps.every(s => s.status === 'pending')).toBe(true)
+
+    const after = runner.reset()
+    expect(after.running).toBe(false)
+    expect(after.steps.every(s => s.status === 'pending')).toBe(true)
+    expect(after.tokenUsage).toBeUndefined()
+    expect(after.result).toBeUndefined()
+
+    // Most-recent broadcast is the post-reset progress.
+    const last = broadcasts.at(-1)
+    expect(last?.event).toBe('init:progress')
+  })
+
+  it('is a no-op while a run is in flight (start() set running:true)', async () => {
+    // We can't easily run the full pipeline in unit tests, but we can verify
+    // the running-guard by stubbing the public surface: start() sets running
+    // synchronously, so calling reset() right after must keep that flag.
+    const { runner } = makeRunner()
+    const startedState = runner.start({})
+    expect(startedState.running).toBe(true)
+    const afterReset = runner.reset()
+    // Running flag preserved — reset bailed.
+    expect(afterReset.running).toBe(true)
+    runner.cancel()
+  })
+})
+
+describe('init commit/skip — atomic .annotask writes', () => {
+  async function withTempRoot(fn: (root: string) => Promise<void>): Promise<void> {
+    const root = await fsp.mkdtemp(path.join(os.tmpdir(), 'annotask-init-atomic-'))
+    try { await fn(root) } finally { await fsp.rm(root, { recursive: true, force: true }) }
+  }
+
+  function makeRunner(root: string) {
+    return createInitRunner({
+      projectRoot: root,
+      broadcast: () => {},
+      agentDetect: { detect: async () => snap(), invalidate: () => {} } as any,
+    })
+  }
+
+  /** Tmp-rename leftovers would mean a non-atomic (or crashed) write. */
+  async function annotaskEntries(root: string): Promise<string[]> {
+    return fsp.readdir(path.join(root, '.annotask'))
+  }
+
+  it('skip() writes design-spec.json via temp+rename with no temp file left behind', async () => {
+    await withTempRoot(async (root) => {
+      const runner = makeRunner(root)
+      const state = await runner.skip()
+      expect(state.result).toBe('success')
+
+      const spec = JSON.parse(await fsp.readFile(path.join(root, '.annotask', 'design-spec.json'), 'utf-8'))
+      expect(spec.initialized).toBe(true)
+      const entries = await annotaskEntries(root)
+      expect(entries.filter(f => f.includes('.tmp.'))).toHaveLength(0)
+    })
+  })
+
+  it('commit() writes design-spec.json + STYLE_GUIDE.md atomically', async () => {
+    await withTempRoot(async (root) => {
+      const runner = makeRunner(root)
+      // All scans skipped → the pipeline assembles a scaffold draft without
+      // spawning any CLI, then parks in awaiting_review for commit().
+      runner.start({
+        skipAgentScan: true,
+        skipAgentConfigs: true,
+        skipComponents: true,
+        skipDataSources: true,
+        skipApiSchemas: true,
+      })
+      for (let i = 0; i < 200 && runner.getState().result !== 'awaiting_review'; i++) {
+        await new Promise(r => setTimeout(r, 25))
+      }
+      expect(runner.getState().result).toBe('awaiting_review')
+
+      const state = await runner.commit({ styleGuide: '# Test Guide\n', overwriteStyleGuide: true })
+      expect(state.result).toBe('success')
+
+      const spec = JSON.parse(await fsp.readFile(path.join(root, '.annotask', 'design-spec.json'), 'utf-8'))
+      expect(spec.initialized).toBe(true)
+      expect(await fsp.readFile(path.join(root, '.annotask', 'STYLE_GUIDE.md'), 'utf-8')).toBe('# Test Guide\n')
+      const entries = await annotaskEntries(root)
+      expect(entries.filter(f => f.includes('.tmp.'))).toHaveLength(0)
+    })
+  })
+})
+
+describe('extractTextFromLine — opencode shapes', () => {
+  // Regression: prior to the v1.14+ fix the init pipeline only matched
+  // {type:'message', content:'...'}, so the wizard streamed zero agent
+  // lines whenever opencode emitted the modern part-wrapped envelope.
+  it('parses opencode v1.14+ text events with nested part.text', () => {
+    const line = '{"type":"text","sessionID":"s1","part":{"type":"text","text":"Hello to you"}}'
+    expect(__test.extractTextFromLine('opencode', line)).toBe('Hello to you')
+  })
+
+  it('parses opencode legacy top-level text', () => {
+    const line = '{"type":"text","text":"hi"}'
+    expect(__test.extractTextFromLine('opencode', line)).toBe('hi')
+  })
+
+  it('parses opencode legacy message envelope', () => {
+    const line = '{"type":"message","content":"hello there"}'
+    expect(__test.extractTextFromLine('opencode', line)).toBe('hello there')
+  })
+
+  it('returns null for opencode step_start / step_finish events (no displayable text)', () => {
+    expect(__test.extractTextFromLine('opencode', '{"type":"step_start","part":{}}')).toBeNull()
+    expect(__test.extractTextFromLine('opencode', '{"type":"step_finish","part":{"tokens":{"input":1,"output":2}}}')).toBeNull()
+  })
+
+  it('parses copilot assistant.message cumulative content (init log, not chunked deltas)', () => {
+    // Regression: previously read assistant.message_delta.deltaContent, which
+    // turned one paragraph into ~50 newline-separated word fragments in the
+    // wizard's agent-output panel ("I'll initialize Annotask\n\n by\n\n
+    // scanning the c\n\nodebase…").
+    const finalMsg = '{"type":"assistant.message","data":{"content":"I\'ll initialize Annotask by scanning the codebase.","outputTokens":21}}'
+    expect(__test.extractTextFromLine('copilot', finalMsg)).toBe("I'll initialize Annotask by scanning the codebase.")
+  })
+
+  it('ignores copilot per-chunk deltas to avoid mid-word newlines', () => {
+    const delta = '{"type":"assistant.message_delta","data":{"deltaContent":"I\'ll initialize"}}'
+    expect(__test.extractTextFromLine('copilot', delta)).toBeNull()
+  })
+
+  it('still parses opencode step_finish for usage tokens', () => {
+    const line = '{"type":"step_finish","part":{"tokens":{"input":1735,"output":9,"cache":{"read":6656,"write":0}}}}'
+    const u = __test.extractUsageFromLine('opencode', line)
+    expect(u).not.toBeNull()
+    expect(u?.inputTokens).toBe(1735)
+    expect(u?.outputTokens).toBe(9)
+    expect(u?.cacheReadTokens).toBe(6656)
+  })
+})
diff --git a/src/server/__tests__/origin.test.ts b/src/server/__tests__/origin.test.ts
new file mode 100644
index 0000000..5afa75a
--- /dev/null
+++ b/src/server/__tests__/origin.test.ts
@@ -0,0 +1,105 @@
+import { describe, it, expect, afterEach } from 'vitest'
+import { isAllowedHost, isLocalOrigin, originMatchesPort } from '../origin.js'
+
+describe('isLocalOrigin', () => {
+  it('accepts missing origin (same-origin / non-browser)', () => {
+    expect(isLocalOrigin(undefined)).toBe(true)
+  })
+
+  it('accepts localhost origins on any port', () => {
+    expect(isLocalOrigin('http://localhost:5173')).toBe(true)
+    expect(isLocalOrigin('http://localhost:3000')).toBe(true)
+    expect(isLocalOrigin('http://127.0.0.1:8080')).toBe(true)
+  })
+
+  it('rejects non-local origins', () => {
+    expect(isLocalOrigin('http://evil.com')).toBe(false)
+    expect(isLocalOrigin('http://192.168.1.1:5173')).toBe(false)
+  })
+})
+
+describe('originMatchesPort', () => {
+  it('accepts missing origin (same-origin / non-browser)', () => {
+    expect(originMatchesPort(undefined, 5173)).toBe(true)
+  })
+
+  it('accepts matching localhost port', () => {
+    expect(originMatchesPort('http://localhost:5173', 5173)).toBe(true)
+    expect(originMatchesPort('http://127.0.0.1:5173', 5173)).toBe(true)
+  })
+
+  it('rejects different localhost port', () => {
+    expect(originMatchesPort('http://localhost:3000', 5173)).toBe(false)
+    expect(originMatchesPort('http://127.0.0.1:9999', 5173)).toBe(false)
+  })
+
+  it('rejects non-local origins even with matching port', () => {
+    expect(originMatchesPort('http://evil.com:5173', 5173)).toBe(false)
+  })
+
+  it('falls back to port 80/443 when origin port is implicit', () => {
+    expect(originMatchesPort('http://localhost', 80)).toBe(true)
+    expect(originMatchesPort('https://localhost', 443)).toBe(true)
+    expect(originMatchesPort('http://localhost', 5173)).toBe(false)
+  })
+
+  it('accepts any local port when server port is unknown', () => {
+    expect(originMatchesPort('http://localhost:9999', undefined)).toBe(true)
+  })
+})
+
+describe('isAllowedHost (DNS-rebinding gate)', () => {
+  afterEach(() => {
+    delete process.env.ANNOTASK_ALLOWED_HOSTS
+  })
+
+  it('accepts a missing Host header (HTTP/1.0 / non-browser clients)', () => {
+    expect(isAllowedHost(undefined)).toBe(true)
+    expect(isAllowedHost('')).toBe(true)
+  })
+
+  it('accepts localhost hostnames on any port', () => {
+    expect(isAllowedHost('localhost')).toBe(true)
+    expect(isAllowedHost('localhost:5173')).toBe(true)
+    expect(isAllowedHost('127.0.0.1:8080')).toBe(true)
+    expect(isAllowedHost('[::1]:5173')).toBe(true)
+  })
+
+  it('accepts IP literals (a typed-in LAN address cannot be a rebound DNS name)', () => {
+    expect(isAllowedHost('192.168.1.5:5173')).toBe(true)
+    expect(isAllowedHost('10.0.0.7')).toBe(true)
+    expect(isAllowedHost('[fe80::1]:5173')).toBe(true)
+  })
+
+  it('rejects non-local hostnames by default', () => {
+    expect(isAllowedHost('evil.example')).toBe(false)
+    expect(isAllowedHost('evil.example:5173')).toBe(false)
+    expect(isAllowedHost('localhost.evil.example')).toBe(false)
+  })
+
+  it('rejects garbage Host values', () => {
+    expect(isAllowedHost('   ')).toBe(false)
+    expect(isAllowedHost('not a host')).toBe(false)
+  })
+
+  it('accepts hosts in extraAllowed (port-insensitive, case-insensitive)', () => {
+    expect(isAllowedHost('dev.example.com:5173', ['dev.example.com'])).toBe(true)
+    expect(isAllowedHost('DEV.Example.COM', ['dev.example.com'])).toBe(true)
+    expect(isAllowedHost('dev.example.com', ['dev.example.com:9999'])).toBe(true)
+    expect(isAllowedHost('other.example.com', ['dev.example.com'])).toBe(false)
+  })
+
+  it("supports '*' (Vite allowedHosts: true) and leading-dot suffix entries", () => {
+    expect(isAllowedHost('anything.example', ['*'])).toBe(true)
+    expect(isAllowedHost('app.example.com', ['.example.com'])).toBe(true)
+    expect(isAllowedHost('example.com', ['.example.com'])).toBe(true)
+    expect(isAllowedHost('notexample.com', ['.example.com'])).toBe(false)
+  })
+
+  it('honors ANNOTASK_ALLOWED_HOSTS (comma-separated)', () => {
+    process.env.ANNOTASK_ALLOWED_HOSTS = 'tunnel.example, myhost.local'
+    expect(isAllowedHost('tunnel.example:5173')).toBe(true)
+    expect(isAllowedHost('myhost.local')).toBe(true)
+    expect(isAllowedHost('evil.example')).toBe(false)
+  })
+})
diff --git a/src/server/__tests__/project-components.test.ts b/src/server/__tests__/project-components.test.ts
new file mode 100644
index 0000000..a65ae7d
--- /dev/null
+++ b/src/server/__tests__/project-components.test.ts
@@ -0,0 +1,90 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { scanProjectComponents, clearComponentCache } from '../component-scanner'
+
+const PLANET_CARD_VUE = `<script setup lang="ts">
+/** A card for one planet. */
+defineProps<{
+  planet: { id: string; name: string }
+  active?: boolean
+}>()
+</script>
+<template>
+  <article class="planet-card"><slot /></article>
+</template>
+`
+
+const BUTTON_TSX = `interface ButtonProps {
+  label: string
+  disabled?: boolean
+}
+export default function Button({ label, disabled }: ButtonProps) {
+  return <button disabled={disabled}>{label}</button>
+}
+`
+
+describe('scanProjectComponents', () => {
+  let root: string
+
+  async function write(rel: string, content: string): Promise<void> {
+    const abs = path.join(root, rel)
+    await fsp.mkdir(path.dirname(abs), { recursive: true })
+    await fsp.writeFile(abs, content, 'utf-8')
+  }
+
+  beforeEach(async () => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-pc-'))
+    clearComponentCache()
+    await write('src/components/PlanetCard.vue', PLANET_CARD_VUE)
+    await write('src/ui/Button.tsx', BUTTON_TSX)
+    // Non-components that must be skipped.
+    await write('src/router.ts', 'export const routes = []\n')
+    await write('src/utils.js', 'export function x() {}\n')
+  })
+
+  afterEach(async () => {
+    await fsp.rm(root, { recursive: true, force: true })
+    clearComponentCache()
+  })
+
+  it('catalogs PascalCase src/ components with ./src/… module specifiers, sorted', async () => {
+    const lib = await scanProjectComponents(root)
+    expect(lib.name).toBe('Project')
+    expect(lib.components.map((c) => c.name)).toEqual(['Button', 'PlanetCard'])
+    const card = lib.components.find((c) => c.name === 'PlanetCard')!
+    // The exact spec ensureComponentLoaded resolves via /__annotask/preview-module.
+    expect(card.module).toBe('./src/components/PlanetCard.vue')
+    expect(card.sourceFile).toBe(path.join(root, 'src/components/PlanetCard.vue'))
+    const propNames = card.props.map((p) => p.name)
+    expect(propNames).toContain('planet')
+    expect(propNames).toContain('active')
+    const button = lib.components.find((c) => c.name === 'Button')!
+    expect(button.module).toBe('./src/ui/Button.tsx')
+    expect(button.props.map((p) => p.name)).toContain('label')
+  })
+
+  it('returns an empty library when src/ is missing', async () => {
+    const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-pc-empty-'))
+    try {
+      clearComponentCache()
+      const lib = await scanProjectComponents(empty)
+      expect(lib.components).toEqual([])
+    } finally {
+      await fsp.rm(empty, { recursive: true, force: true })
+    }
+  })
+
+  it('caches per TTL and resets via clearComponentCache', async () => {
+    const first = await scanProjectComponents(root)
+    await write('src/components/NewThing.vue', '<template><div>x</div></template>\n')
+    // Warm cache → unchanged.
+    const cached = await scanProjectComponents(root)
+    expect(cached).toBe(first)
+    clearComponentCache()
+    const fresh = await scanProjectComponents(root)
+    expect(fresh.components.map((c) => c.name)).toContain('NewThing')
+  })
+})
diff --git a/src/server/__tests__/session-store.test.ts b/src/server/__tests__/session-store.test.ts
new file mode 100644
index 0000000..a0a9bbf
--- /dev/null
+++ b/src/server/__tests__/session-store.test.ts
@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { createSessionStore, RevConflictError } from '../session-store'
+import type { DesignSessionDocument, SessionEntry } from '../../shared/design-session-types'
+
+function entry(id: string, extra: Partial<SessionEntry> = {}): SessionEntry {
+  return {
+    id,
+    ordinal: 1,
+    ts: 1,
+    route: '/planets',
+    change: {
+      id: `c-${id}`, type: 'style_update', description: 'x', file: 'a.vue',
+      section: 'style', line: 9, element: 'h1', property: 'color', before: 'red', after: 'blue',
+    } as SessionEntry['change'],
+    anchor: { file: 'a.vue', line: 9 },
+    live: { status: 'pending' },
+    ...extra,
+  }
+}
+
+function doc(entries: SessionEntry[], rev?: number): DesignSessionDocument {
+  return { version: '1.0', sessionId: 'ds-1', startedAt: 1, updatedAt: 1, ...(rev !== undefined ? { rev } : {}), entries }
+}
+
+describe('session-store', () => {
+  let root: string
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-ds-'))
+  })
+
+  afterEach(async () => {
+    await fsp.rm(root, { recursive: true, force: true })
+  })
+
+  it('returns an empty document when design-session.json is missing', async () => {
+    const store = createSessionStore(root)
+    const empty = await store.get()
+    expect(empty.entries).toEqual([])
+    expect(empty.sessionId).toBeTruthy()
+    // Repeated GETs of the missing file agree on the fallback session id.
+    expect((await store.get()).sessionId).toBe(empty.sessionId)
+  })
+
+  it('round-trips a document through set() then get(), stamping the first rev', async () => {
+    const store = createSessionStore(root)
+    const saved = await store.set(doc([entry('se-1')]))
+    expect(saved.rev).toBe(1)
+    expect(fs.existsSync(path.join(root, '.annotask', 'design-session.json'))).toBe(true)
+    expect(await createSessionStore(root).get()).toEqual(saved)
+  })
+
+  it('falls back to the empty default on malformed JSON or a bad entry', async () => {
+    const dir = path.join(root, '.annotask')
+    await fsp.mkdir(dir, { recursive: true })
+    const file = path.join(dir, 'design-session.json')
+
+    await fsp.writeFile(file, '{ not valid json', 'utf-8')
+    expect((await createSessionStore(root).get()).entries).toEqual([])
+
+    // Entry-depth: one malformed entry poisons the whole on-disk doc.
+    await fsp.writeFile(file, JSON.stringify(doc([{ id: 'se-bad' } as never])), 'utf-8')
+    expect((await createSessionStore(root).get()).entries).toEqual([])
+  })
+
+  it('rejects a stale rev with RevConflictError and leaves the file untouched', async () => {
+    const store = createSessionStore(root)
+    const v1 = await store.set(doc([]))
+    await store.set(doc([entry('se-1')], v1.rev))
+    await expect(store.set(doc([entry('se-2')], v1.rev))).rejects.toBeInstanceOf(RevConflictError)
+    const current = await store.get()
+    expect(current.rev).toBe(2)
+    expect(current.entries.map((e) => e.id)).toEqual(['se-1'])
+  })
+
+  it('replace() bypasses CAS (server-owned discard) but still bumps the rev', async () => {
+    const store = createSessionStore(root)
+    const v1 = await store.set(doc([entry('se-1')]))
+    const replaced = await store.replace({ version: '1.0', sessionId: 'ds-2', startedAt: 9, updatedAt: 9, entries: [] })
+    expect(replaced.rev).toBe((v1.rev ?? 0) + 1)
+    expect(replaced.sessionId).toBe('ds-2')
+    // A CAS writer holding the old rev now loses cleanly.
+    await expect(store.set(doc([entry('se-3')], v1.rev))).rejects.toBeInstanceOf(RevConflictError)
+  })
+})
diff --git a/src/server/__tests__/state.test.ts b/src/server/__tests__/state.test.ts
index 6280de9..d89625a 100644
--- a/src/server/__tests__/state.test.ts
+++ b/src/server/__tests__/state.test.ts
@@ -1,9 +1,11 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
 import path from 'node:path'
 import os from 'node:os'
-import { createProjectState } from '../state'
+import { createProjectState, ensureAnnotaskIgnored } from '../state'
+import { createTaskThreadStore } from '../task-thread'
+import { assertTransition } from '../schemas'
 
 function mkTmpRoot(): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-state-test-'))
@@ -151,6 +153,115 @@ describe('createProjectState — task store serialization', () => {
     state.dispose()
   })
 
+  it('addTaskUsage accumulates token usage on the task', async () => {
+    const state = createProjectState(root, noopBroadcast)
+    const t = await state.addTask({ type: 'annotation', description: 'usage test' }) as any
+
+    const first = await state.addTaskUsage(t.id, {
+      inputTokens: 100,
+      outputTokens: 40,
+      cacheReadTokens: 5,
+    })
+    expect(first).not.toBeNull()
+    expect(first!.inputTokens).toBe(100)
+    expect(first!.outputTokens).toBe(40)
+    expect(first!.cacheReadTokens).toBe(5)
+    expect(first!.turns).toBe(1)
+    expect(first!.lastUpdated).toBeGreaterThan(0)
+
+    const second = await state.addTaskUsage(t.id, {
+      inputTokens: 200,
+      outputTokens: 80,
+      cacheCreationTokens: 10,
+    })
+    expect(second!.inputTokens).toBe(300)
+    expect(second!.outputTokens).toBe(120)
+    expect(second!.cacheReadTokens).toBe(5)
+    expect(second!.cacheCreationTokens).toBe(10)
+    expect(second!.turns).toBe(2)
+
+    const snap = state.getTasks().tasks[0] as any
+    expect(snap.tokenUsage.turns).toBe(2)
+    expect(snap.tokenUsage.inputTokens).toBe(300)
+    await state.flush()
+    state.dispose()
+  })
+
+  it('addTaskUsage returns null for unknown task ids (silently no-ops)', async () => {
+    const state = createProjectState(root, noopBroadcast)
+    const result = await state.addTaskUsage('task-does-not-exist', { inputTokens: 1, outputTokens: 1 })
+    expect(result).toBeNull()
+    await state.flush()
+    state.dispose()
+  })
+
+  it('quarantines a corrupt tasks.json before falling back to empty', async () => {
+    const dir = path.join(root, '.annotask')
+    fs.mkdirSync(dir, { recursive: true })
+    const corruptBytes = '{"version":"1.0","tasks":[{"id":"task-trunc'
+    fs.writeFileSync(path.join(dir, 'tasks.json'), corruptBytes)
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const state = createProjectState(root, noopBroadcast)
+    expect(state.getTasks().tasks).toHaveLength(0)
+
+    // The corrupt original is preserved next to tasks.json so the next
+    // mutation's atomic flush can't silently destroy it.
+    const quarantined = fs.readdirSync(dir).filter(f => f.startsWith('tasks.json.corrupt-'))
+    expect(quarantined).toHaveLength(1)
+    expect(fs.readFileSync(path.join(dir, quarantined[0]), 'utf-8')).toBe(corruptBytes)
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('quarantined'))
+    warn.mockRestore()
+    state.dispose()
+  })
+
+  it('does not quarantine when tasks.json simply does not exist', async () => {
+    const state = createProjectState(root, noopBroadcast)
+    expect(state.getTasks().tasks).toHaveLength(0)
+    const dir = path.join(root, '.annotask')
+    const entries = fs.existsSync(dir) ? fs.readdirSync(dir) : []
+    expect(entries.filter(f => f.includes('corrupt'))).toHaveLength(0)
+    state.dispose()
+  })
+
+  it('updateTask guard runs inside the lock — concurrent transition race has exactly one winner', async () => {
+    const state = createProjectState(root, noopBroadcast)
+    const t = await state.addTask({ type: 'annotation', description: 'race' }) as any
+
+    // Both callers validated `pending → in_progress` before queuing (the old
+    // pre-lock check would let both through). The guard re-asserts against
+    // the task as it exists under the mutex, so the second sees in_progress.
+    const guard = (task: Record<string, unknown>) => assertTransition(task.status, 'in_progress')
+    const [a, b] = await Promise.all([
+      state.updateTask(t.id, { status: 'in_progress' }, { guard }),
+      state.updateTask(t.id, { status: 'in_progress' }, { guard }),
+    ]) as any[]
+
+    const winners = [a, b].filter(r => r.error === undefined)
+    const losers = [a, b].filter(r => r.error === 'Invalid transition')
+    expect(winners).toHaveLength(1)
+    expect(losers).toHaveLength(1)
+    expect(losers[0].reason).toContain('Invalid state transition')
+    expect(state.getTasks().tasks[0].status).toBe('in_progress')
+    await state.flush()
+    state.dispose()
+  })
+
+  it('a rejected guard leaves the task untouched', async () => {
+    const state = createProjectState(root, noopBroadcast)
+    const t = await state.addTask({ type: 'annotation', description: 'guarded' }) as any
+    const r = await state.updateTask(t.id, { status: 'accepted' }, {
+      guard: (task) => assertTransition(task.status, 'accepted'),
+    }) as any
+    expect(r.error).toBe('Invalid transition')
+    const snap = state.getTasks().tasks[0]
+    expect(snap.status).toBe('pending')
+    // The accepted-branch cleanup must not have removed the task.
+    expect(state.getTasks().tasks).toHaveLength(1)
+    await state.flush()
+    state.dispose()
+  })
+
   it('loads an existing tasks.json on first read', async () => {
     const dir = path.join(root, '.annotask')
     fs.mkdirSync(dir, { recursive: true })
@@ -170,3 +281,193 @@ describe('createProjectState — task store serialization', () => {
     state.dispose()
   })
 })
+
+describe('transcript cleanup (onTaskRemoved → taskThread.clear)', () => {
+  let root: string
+  beforeEach(() => { root = mkTmpRoot() })
+  afterEach(async () => { await fsp.rm(root, { recursive: true, force: true }) })
+
+  /** Wire state + thread store the way src/server/index.ts does. */
+  function makeWiredState() {
+    const taskThread = createTaskThreadStore({ projectRoot: root })
+    const state = createProjectState(root, noopBroadcast, {
+      onTaskRemoved: (taskId) => { void taskThread.clear(taskId) },
+    })
+    return { state, taskThread }
+  }
+
+  function transcriptPath(taskId: string): string {
+    return path.join(root, '.annotask', 'conversations', `${taskId}.jsonl`)
+  }
+
+  /** The unlink chains off the flush continuation — poll briefly. */
+  async function waitGone(p: string): Promise<boolean> {
+    for (let i = 0; i < 40; i++) {
+      if (!fs.existsSync(p)) return true
+      await new Promise(r => setTimeout(r, 25))
+    }
+    return !fs.existsSync(p)
+  }
+
+  it('removes the conversation transcript when a task is accepted', async () => {
+    const { state, taskThread } = makeWiredState()
+    const t = await state.addTask({ type: 'annotation', description: 'chatty' }) as any
+    await taskThread.append(t.id, { role: 'user', content: 'please fix' })
+    expect(fs.existsSync(transcriptPath(t.id))).toBe(true)
+
+    await state.updateTask(t.id, { status: 'in_progress' })
+    await state.updateTask(t.id, { status: 'review' })
+    await state.updateTask(t.id, { status: 'accepted' })
+    await state.flush()
+
+    expect(await waitGone(transcriptPath(t.id))).toBe(true)
+    state.dispose()
+  })
+
+  it('removes the conversation transcript when a task is deleted', async () => {
+    const { state, taskThread } = makeWiredState()
+    const t = await state.addTask({ type: 'annotation', description: 'doomed' }) as any
+    await taskThread.append(t.id, { role: 'user', content: 'never mind' })
+    expect(fs.existsSync(transcriptPath(t.id))).toBe(true)
+
+    await state.deleteTask(t.id)
+    await state.flush()
+
+    expect(await waitGone(transcriptPath(t.id))).toBe(true)
+    state.dispose()
+  })
+
+  it('does not fire onTaskRemoved for plain status updates', async () => {
+    const removed: string[] = []
+    const state = createProjectState(root, noopBroadcast, {
+      onTaskRemoved: (id) => { removed.push(id) },
+    })
+    const t = await state.addTask({ type: 'annotation', description: 'alive' }) as any
+    await state.updateTask(t.id, { status: 'in_progress' })
+    await state.flush()
+    expect(removed).toHaveLength(0)
+    state.dispose()
+  })
+})
+
+describe('ensureAnnotaskIgnored', () => {
+  let root: string
+  beforeEach(() => { root = mkTmpRoot() })
+  afterEach(async () => { await fsp.rm(root, { recursive: true, force: true }) })
+
+  const gitignorePath = () => path.join(root, '.gitignore')
+
+  it('appends a .annotask/ entry once when the project is a git repo', () => {
+    fs.mkdirSync(path.join(root, '.git'))
+    fs.writeFileSync(gitignorePath(), 'node_modules/\n')
+
+    ensureAnnotaskIgnored(root)
+    const after = fs.readFileSync(gitignorePath(), 'utf-8')
+    expect(after).toContain('node_modules/')
+    expect(after).toContain('.annotask/')
+
+    // Idempotent — a second boot must not duplicate the entry.
+    ensureAnnotaskIgnored(root)
+    const matches = fs.readFileSync(gitignorePath(), 'utf-8').match(/^\.annotask\/$/gm)
+    expect(matches).toHaveLength(1)
+  })
+
+  it('creates .gitignore when missing and handles a file without trailing newline', () => {
+    fs.mkdirSync(path.join(root, '.git'))
+    ensureAnnotaskIgnored(root)
+    expect(fs.readFileSync(gitignorePath(), 'utf-8')).toContain('.annotask/')
+
+    // No-trailing-newline case: the entry must land on its own line.
+    fs.writeFileSync(gitignorePath(), 'dist')
+    ensureAnnotaskIgnored(root)
+    expect(fs.readFileSync(gitignorePath(), 'utf-8')).toMatch(/^dist\n/)
+    expect(fs.readFileSync(gitignorePath(), 'utf-8').match(/^\.annotask\/$/gm)).toHaveLength(1)
+  })
+
+  it('respects existing entry variants (.annotask, /.annotask/)', () => {
+    fs.mkdirSync(path.join(root, '.git'))
+    for (const variant of ['.annotask', '/.annotask/', '.annotask/']) {
+      fs.writeFileSync(gitignorePath(), `${variant}\n`)
+      ensureAnnotaskIgnored(root)
+      expect(fs.readFileSync(gitignorePath(), 'utf-8')).toBe(`${variant}\n`)
+    }
+  })
+
+  it('does nothing outside a git repo', () => {
+    ensureAnnotaskIgnored(root)
+    expect(fs.existsSync(gitignorePath())).toBe(false)
+  })
+
+  it('runs on createProjectState boot', () => {
+    fs.mkdirSync(path.join(root, '.git'))
+    const state = createProjectState(root, noopBroadcast)
+    expect(fs.readFileSync(gitignorePath(), 'utf-8')).toContain('.annotask/')
+    state.dispose()
+  })
+})
+
+describe('wireframe-snapshot GC (boot sweep)', () => {
+  let root: string
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-wfgc-'))
+  })
+
+  afterEach(async () => {
+    await fsp.rm(root, { recursive: true, force: true })
+  })
+
+  it('removes stale orphaned PNGs; keeps referenced and recent files', async () => {
+    const dir = path.join(root, '.annotask', 'wireframe-snapshots')
+    await fsp.mkdir(dir, { recursive: true })
+    await fsp.writeFile(path.join(root, '.annotask', 'wireframe.json'), JSON.stringify({
+      version: '1.0', updatedAt: 1, rev: 1,
+      routes: [{
+        route: '/planets', instances: [],
+        canvas: {
+          capturedAt: 1,
+          viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+          fullImage: 'wf-full-1.png',
+          blocks: [{
+            id: 'wfb-1', kind: 'captured', rect: { x: 0, y: 0, width: 100, height: 50 }, z: 1, createdAt: 1,
+            anchor: { file: 'a.vue', line: 1 }, originalRect: { x: 0, y: 0, width: 100, height: 50 },
+            image: 'wfb-1.png',
+          }],
+        },
+      }],
+    }))
+    const old = new Date(Date.now() - 2 * 60 * 60 * 1000)
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47])
+    for (const name of ['wfb-1.png', 'wf-full-1.png', 'orphan-old.png', 'orphan-fresh.png']) {
+      await fsp.writeFile(path.join(dir, name), png)
+    }
+    await fsp.utimes(path.join(dir, 'orphan-old.png'), old, old)
+    // Referenced files keep their (old) mtime too — reference beats age.
+    await fsp.utimes(path.join(dir, 'wfb-1.png'), old, old)
+
+    const state = createProjectState(root, noopBroadcast)
+    // The sweep is fire-and-forget — give it a few ticks to finish.
+    await new Promise((r) => setTimeout(r, 250))
+    state.dispose()
+
+    expect(fs.existsSync(path.join(dir, 'wfb-1.png')), 'referenced block image kept').toBe(true)
+    expect(fs.existsSync(path.join(dir, 'wf-full-1.png')), 'referenced full image kept').toBe(true)
+    expect(fs.existsSync(path.join(dir, 'orphan-fresh.png')), 'recent orphan kept (mtime guard)').toBe(true)
+    expect(fs.existsSync(path.join(dir, 'orphan-old.png')), 'stale orphan removed').toBe(false)
+  })
+
+  it('aborts entirely on a malformed wireframe.json — an unreadable doc must never read as "no references"', async () => {
+    const dir = path.join(root, '.annotask', 'wireframe-snapshots')
+    await fsp.mkdir(dir, { recursive: true })
+    await fsp.writeFile(path.join(root, '.annotask', 'wireframe.json'), '{ truncated json')
+    const old = new Date(Date.now() - 2 * 60 * 60 * 1000)
+    await fsp.writeFile(path.join(dir, 'maybe-referenced.png'), Buffer.from([0x89]))
+    await fsp.utimes(path.join(dir, 'maybe-referenced.png'), old, old)
+
+    const state = createProjectState(root, noopBroadcast)
+    await new Promise((r) => setTimeout(r, 250))
+    state.dispose()
+
+    expect(fs.existsSync(path.join(dir, 'maybe-referenced.png'))).toBe(true)
+  })
+})
diff --git a/src/server/__tests__/task-thread.test.ts b/src/server/__tests__/task-thread.test.ts
new file mode 100644
index 0000000..1fa77f5
--- /dev/null
+++ b/src/server/__tests__/task-thread.test.ts
@@ -0,0 +1,177 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { createTaskThreadStore } from '../task-thread.js'
+
+describe('TaskThreadStore', () => {
+  let projectRoot: string
+
+  beforeEach(async () => {
+    projectRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'annotask-thread-'))
+  })
+  afterEach(async () => {
+    await fsp.rm(projectRoot, { recursive: true, force: true })
+  })
+
+  it('appends and reads messages in order', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    await store.append('task-1', { role: 'user', content: 'hello' })
+    await store.append('task-1', { role: 'assistant', content: 'world', providerId: 'anthropic' })
+    const msgs = await store.read('task-1')
+    expect(msgs).toHaveLength(2)
+    expect(msgs[0].role).toBe('user')
+    expect(msgs[0].content).toBe('hello')
+    expect(msgs[1].role).toBe('assistant')
+    expect(msgs[1].providerId).toBe('anthropic')
+  })
+
+  it('rejects unsafe task ids', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    await expect(store.append('../escape', { role: 'user', content: 'x' })).rejects.toThrow()
+  })
+
+  it('returns [] for an unknown task', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    const msgs = await store.read('task-unknown-id')
+    expect(msgs).toEqual([])
+  })
+
+  it('respects afterId filter', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    const a = await store.append('task-2', { role: 'user', content: 'one' })
+    await store.append('task-2', { role: 'assistant', content: 'two' })
+    await store.append('task-2', { role: 'user', content: 'three' })
+    const rest = await store.read('task-2', { afterId: a.id })
+    expect(rest.map((m) => m.content)).toEqual(['two', 'three'])
+  })
+
+  it('fires onAppend after each write (used for ledger + per-task usage rollup)', async () => {
+    const seen: Array<{ taskId: string; usage: unknown }> = []
+    const store = createTaskThreadStore({
+      projectRoot,
+      onAppend: (taskId, msg) => { seen.push({ taskId, usage: msg.usage }) },
+    })
+    await store.append('task-hook', { role: 'user', content: 'hi' })
+    await store.append('task-hook', {
+      role: 'assistant',
+      content: 'hello',
+      usage: { inputTokens: 12, outputTokens: 3 },
+    })
+    expect(seen).toHaveLength(2)
+    expect(seen[0].usage).toBeUndefined()
+    expect(seen[1].usage).toEqual({ inputTokens: 12, outputTokens: 3 })
+  })
+
+  it('fans out to subscribers after the write lands', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    const seen: string[] = []
+    const unsubscribe = store.subscribe('task-3', (m) => { seen.push(m.content) })
+    await store.append('task-3', { role: 'user', content: 'live' })
+    expect(seen).toEqual(['live'])
+    unsubscribe()
+    await store.append('task-3', { role: 'user', content: 'after-unsub' })
+    expect(seen).toEqual(['live']) // unsubscribed
+  })
+
+  it('persists across store instances (real JSONL file)', async () => {
+    const a = createTaskThreadStore({ projectRoot })
+    await a.append('task-4', { role: 'user', content: 'persistent' })
+    const b = createTaskThreadStore({ projectRoot })
+    const msgs = await b.read('task-4')
+    expect(msgs).toHaveLength(1)
+    expect(msgs[0].content).toBe('persistent')
+  })
+
+  it('updates a message in place by id (streaming a partial turn)', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    await store.append('task-up', { role: 'user', content: 'go' })
+    const partial = await store.append('task-up', { role: 'assistant', content: '', isPartial: true })
+
+    const mid = await store.update('task-up', partial.id, {
+      content: 'work...',
+      blocks: [{ kind: 'text', text: 'work...' }],
+      lastEventAt: 123,
+    })
+    expect(mid?.content).toBe('work...')
+    expect(mid?.isPartial).toBe(true) // not cleared yet
+    expect(mid?.lastEventAt).toBe(123)
+
+    const final = await store.update('task-up', partial.id, { content: 'done', isPartial: false })
+    expect(final?.isPartial).toBe(false)
+
+    // Still exactly two lines — the partial line was rewritten, not appended.
+    const msgs = await store.read('task-up')
+    expect(msgs).toHaveLength(2)
+    expect(msgs[1].id).toBe(partial.id)
+    expect(msgs[1].content).toBe('done')
+    expect(msgs[1].blocks).toEqual([{ kind: 'text', text: 'work...' }])
+  })
+
+  it('update returns null for an unknown message id', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    await store.append('task-up2', { role: 'user', content: 'x' })
+    const res = await store.update('task-up2', 'msg-does-not-exist', { content: 'nope' })
+    expect(res).toBeNull()
+  })
+
+  it('fans out updates to subscribers (so observers stream a partial turn)', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    const seen: Array<{ content: string; isPartial?: boolean }> = []
+    store.subscribe('task-up3', (m) => { seen.push({ content: m.content, isPartial: m.isPartial }) })
+    const partial = await store.append('task-up3', { role: 'assistant', content: '', isPartial: true })
+    await store.update('task-up3', partial.id, { content: 'a' })
+    await store.update('task-up3', partial.id, { content: 'ab', isPartial: false })
+    expect(seen).toEqual([
+      { content: '', isPartial: true },
+      { content: 'a', isPartial: true },
+      { content: 'ab', isPartial: false },
+    ])
+  })
+
+  it('serializes interleaved append + update under the write lock', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    const partial = await store.append('task-up4', { role: 'assistant', content: '', isPartial: true })
+    // Fire an update and a fresh append without awaiting between them.
+    await Promise.all([
+      store.update('task-up4', partial.id, { content: 'streamed', isPartial: false }),
+      store.append('task-up4', { role: 'user', content: 'interrupt' }),
+    ])
+    const msgs = await store.read('task-up4')
+    expect(msgs).toHaveLength(2)
+    expect(msgs.find((m) => m.id === partial.id)?.content).toBe('streamed')
+    expect(msgs.some((m) => m.content === 'interrupt')).toBe(true)
+  })
+
+  it('tail-rewrites the streaming partial: many updates stay consistent on disk', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    await store.append('task-stream', { role: 'user', content: 'task' })
+    const partial = await store.append('task-stream', { role: 'assistant', content: '', isPartial: true })
+    // Simulate a streaming turn: many in-place updates to the last (partial) line.
+    for (let i = 1; i <= 25; i++) {
+      await store.update('task-stream', partial.id, { content: 'x'.repeat(i), isPartial: i < 25 })
+    }
+    // A FRESH store reads from disk only — proves the tail-rewrites left a valid
+    // JSONL file (exactly two lines, last one fully updated), not a corrupted tail.
+    const fresh = createTaskThreadStore({ projectRoot })
+    const msgs = await fresh.read('task-stream')
+    expect(msgs).toHaveLength(2)
+    expect(msgs[0].content).toBe('task')
+    expect(msgs[1].id).toBe(partial.id)
+    expect(msgs[1].content).toBe('x'.repeat(25))
+    expect(msgs[1].isPartial).toBe(false)
+  })
+
+  it('updates an earlier (non-last) message via the full-rewrite fallback', async () => {
+    const store = createTaskThreadStore({ projectRoot })
+    const first = await store.append('task-mid', { role: 'user', content: 'first' })
+    await store.append('task-mid', { role: 'assistant', content: 'second' })
+    await store.append('task-mid', { role: 'user', content: 'third' })
+    const updated = await store.update('task-mid', first.id, { content: 'FIRST-EDITED' })
+    expect(updated?.content).toBe('FIRST-EDITED')
+    const fresh = createTaskThreadStore({ projectRoot })
+    const msgs = await fresh.read('task-mid')
+    expect(msgs.map((m) => m.content)).toEqual(['FIRST-EDITED', 'second', 'third'])
+    expect(msgs).toHaveLength(3)
+  })
+})
diff --git a/src/server/__tests__/task-types.test.ts b/src/server/__tests__/task-types.test.ts
index 1618358..2996c73 100644
--- a/src/server/__tests__/task-types.test.ts
+++ b/src/server/__tests__/task-types.test.ts
@@ -13,7 +13,7 @@ describe('TASK_TYPES enforcement', () => {
       'a11y_fix',
       'error_fix',
       'perf_fix',
-      'api_update',
+      'wireframe_apply',
     ])
   })
 
@@ -51,24 +51,4 @@ describe('buildTaskSummary type coverage', () => {
     }
   })
 
-  it('lifts api_update context fields when present', () => {
-    const summary = buildTaskSummary({
-      id: 't',
-      type: 'api_update',
-      status: 'pending',
-      description: 'Add expires_at to Cat',
-      context: {
-        data_source_name: 'useCatsQuery',
-        data_source_kind: 'composable',
-        schema_location: 'openapi.yaml',
-        schema_kind: 'openapi',
-        endpoint: '/api/cats',
-        desired_change: 'Add expires_at field',
-      },
-    })
-    expect(summary.data_source_name).toBe('useCatsQuery')
-    expect(summary.schema_kind).toBe('openapi')
-    expect(summary.endpoint).toBe('/api/cats')
-    expect(summary.desired_change).toBe('Add expires_at field')
-  })
 })
diff --git a/src/server/__tests__/usage-ledger.test.ts b/src/server/__tests__/usage-ledger.test.ts
new file mode 100644
index 0000000..f0ff2e7
--- /dev/null
+++ b/src/server/__tests__/usage-ledger.test.ts
@@ -0,0 +1,119 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fsp from 'node:fs/promises'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createUsageLedger } from '../usage-ledger.js'
+
+describe('UsageLedger', () => {
+  let projectRoot: string
+
+  beforeEach(async () => {
+    projectRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'annotask-usage-'))
+  })
+  afterEach(async () => {
+    await fsp.rm(projectRoot, { recursive: true, force: true })
+  })
+
+  it('appends entries to .annotask/usage.jsonl', async () => {
+    const ledger = createUsageLedger({ projectRoot })
+    await ledger.append({
+      scope: 'task',
+      taskId: 'task-1',
+      providerId: 'claude-local',
+      inputTokens: 100,
+      outputTokens: 50,
+    })
+    const file = path.join(projectRoot, '.annotask', 'usage.jsonl')
+    const raw = await fsp.readFile(file, 'utf-8')
+    const lines = raw.split('\n').filter(l => l.trim().length > 0)
+    expect(lines).toHaveLength(1)
+    const parsed = JSON.parse(lines[0])
+    expect(parsed.scope).toBe('task')
+    expect(parsed.taskId).toBe('task-1')
+    expect(parsed.inputTokens).toBe(100)
+    expect(parsed.outputTokens).toBe(50)
+    expect(typeof parsed.ts).toBe('number')
+  })
+
+  it('skips entries with all-zero token counts', async () => {
+    const ledger = createUsageLedger({ projectRoot })
+    await ledger.append({ scope: 'task', taskId: 't-1', inputTokens: 0, outputTokens: 0 })
+    const file = path.join(projectRoot, '.annotask', 'usage.jsonl')
+    expect(fs.existsSync(file)).toBe(false)
+  })
+
+  it('clamps negative or NaN values to zero', async () => {
+    const ledger = createUsageLedger({ projectRoot })
+    await ledger.append({
+      scope: 'task',
+      inputTokens: -5 as unknown as number,
+      outputTokens: Number.NaN as unknown as number,
+      cacheReadTokens: 10,
+    })
+    const entries = await ledger.readAll()
+    expect(entries[0].inputTokens).toBe(0)
+    expect(entries[0].outputTokens).toBe(0)
+    expect(entries[0].cacheReadTokens).toBe(10)
+  })
+
+  it('summary() aggregates totals plus per-scope and per-provider breakdowns', async () => {
+    const ledger = createUsageLedger({ projectRoot })
+    await ledger.append({
+      scope: 'init', providerId: 'claude-local', inputTokens: 1000, outputTokens: 200,
+    })
+    await ledger.append({
+      scope: 'task', taskId: 't-1', providerId: 'claude-local', inputTokens: 500, outputTokens: 100,
+    })
+    await ledger.append({
+      scope: 'task', taskId: 't-2', providerId: 'anthropic', inputTokens: 300, outputTokens: 80, cacheReadTokens: 50,
+    })
+    const summary = await ledger.summary()
+    expect(summary.totals.inputTokens).toBe(1800)
+    expect(summary.totals.outputTokens).toBe(380)
+    expect(summary.totals.cacheReadTokens).toBe(50)
+    expect(summary.totals.turns).toBe(3)
+    expect(summary.byScope.task.turns).toBe(2)
+    expect(summary.byScope.task.inputTokens).toBe(800)
+    expect(summary.byScope.init.turns).toBe(1)
+    expect(summary.byScope.apply.turns).toBe(0)
+    expect(summary.byProvider['claude-local'].turns).toBe(2)
+    expect(summary.byProvider['claude-local'].inputTokens).toBe(1500)
+    expect(summary.byProvider['anthropic'].turns).toBe(1)
+    expect(summary.firstAt).not.toBeNull()
+    expect(summary.lastAt).not.toBeNull()
+    expect(summary.lastAt!).toBeGreaterThanOrEqual(summary.firstAt!)
+  })
+
+  it('returns empty summary when ledger has no entries', async () => {
+    const ledger = createUsageLedger({ projectRoot })
+    const summary = await ledger.summary()
+    expect(summary.totals.turns).toBe(0)
+    expect(summary.firstAt).toBeNull()
+    expect(summary.lastAt).toBeNull()
+  })
+
+  it('recent() returns newest entries first, capped to limit', async () => {
+    const ledger = createUsageLedger({ projectRoot })
+    for (let i = 1; i <= 5; i++) {
+      await ledger.append({ scope: 'task', taskId: `t-${i}`, inputTokens: i * 10, outputTokens: 1 })
+    }
+    const recent = await ledger.recent(3)
+    expect(recent).toHaveLength(3)
+    expect(recent[0].taskId).toBe('t-5')
+    expect(recent[1].taskId).toBe('t-4')
+    expect(recent[2].taskId).toBe('t-3')
+  })
+
+  it('tolerates malformed lines from external edits', async () => {
+    const ledger = createUsageLedger({ projectRoot })
+    await ledger.append({ scope: 'task', inputTokens: 1, outputTokens: 1 })
+    const file = path.join(projectRoot, '.annotask', 'usage.jsonl')
+    await fsp.appendFile(file, 'this is not json\n', 'utf-8')
+    await ledger.append({ scope: 'task', inputTokens: 2, outputTokens: 2 })
+    const all = await ledger.readAll()
+    expect(all).toHaveLength(2)
+    expect(all[0].inputTokens).toBe(1)
+    expect(all[1].inputTokens).toBe(2)
+  })
+})
diff --git a/src/server/__tests__/validation.test.ts b/src/server/__tests__/validation.test.ts
index 7f1b3be..cf6036e 100644
--- a/src/server/__tests__/validation.test.ts
+++ b/src/server/__tests__/validation.test.ts
@@ -56,6 +56,10 @@ describe('VALID_TRANSITIONS / validateTransition', () => {
     expect(validateTransition('review', 'denied')).toBeNull()
   })
 
+  it('allows in_progress → pending (relinquish lock: agent gave up / cancelled / errored)', () => {
+    expect(validateTransition('in_progress', 'pending')).toBeNull()
+  })
+
   it('returns null for unknown current status (legacy compat)', () => {
     expect(validateTransition('unknown', 'in_progress')).toBeNull()
   })
diff --git a/src/server/__tests__/wireframe-store.test.ts b/src/server/__tests__/wireframe-store.test.ts
new file mode 100644
index 0000000..9ebdc1b
--- /dev/null
+++ b/src/server/__tests__/wireframe-store.test.ts
@@ -0,0 +1,253 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { createWireframeStore, WireframeRevConflictError } from '../wireframe-store'
+import { emptyWireframeDocument, isWireframeDocument, type WireframeDocument, type WireframeInstance } from '../../shared/wireframe-types'
+
+function instance(id: string, extra: Partial<WireframeInstance> = {}): WireframeInstance {
+  return {
+    id,
+    kind: 'component',
+    anchor: { file: 'PlanetsPage.vue', line: 9, position: 'append' },
+    inserted: { tag: 'planetcard', componentName: 'PlanetCard' },
+    fidelity: 'live',
+    mounted: true,
+    createdAt: 1,
+    ...extra,
+  }
+}
+
+describe('wireframe-store', () => {
+  let root: string
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-wf-'))
+  })
+
+  afterEach(async () => {
+    await fsp.rm(root, { recursive: true, force: true })
+  })
+
+  it('returns an empty document when wireframe.json is missing', async () => {
+    const store = createWireframeStore(root)
+    expect(await store.get()).toEqual(emptyWireframeDocument())
+  })
+
+  it('round-trips a document through set() then get(), stamping the first rev', async () => {
+    const store = createWireframeStore(root)
+    const doc: WireframeDocument = {
+      version: '1.0',
+      updatedAt: 42,
+      routes: [
+        { route: '/planets', instances: [instance('wfi-1')] },
+      ],
+    }
+    const saved = await store.set(doc)
+    expect(saved).toEqual({ ...doc, rev: 1 })
+    // Persisted to disk and readable by a fresh store instance.
+    expect(fs.existsSync(path.join(root, '.annotask', 'wireframe.json'))).toBe(true)
+    expect(await createWireframeStore(root).get()).toEqual({ ...doc, rev: 1 })
+  })
+
+  it('falls back to the empty default on malformed JSON or a bad shape', async () => {
+    const dir = path.join(root, '.annotask')
+    await fsp.mkdir(dir, { recursive: true })
+    const file = path.join(dir, 'wireframe.json')
+
+    await fsp.writeFile(file, '{ not valid json', 'utf-8')
+    expect(await createWireframeStore(root).get()).toEqual(emptyWireframeDocument())
+
+    await fsp.writeFile(file, JSON.stringify({ version: '0.9', routes: 'nope' }), 'utf-8')
+    expect(await createWireframeStore(root).get()).toEqual(emptyWireframeDocument())
+
+    // Instance-depth: one malformed instance poisons the whole on-disk doc.
+    await fsp.writeFile(file, JSON.stringify({
+      version: '1.0', updatedAt: 1,
+      routes: [{ route: '/', instances: [{ id: 'wfi-x' /* no kind/anchor/inserted */ }] }],
+    }), 'utf-8')
+    expect(await createWireframeStore(root).get()).toEqual(emptyWireframeDocument())
+  })
+
+  describe('rev compare-and-set', () => {
+    it('increments rev on every successful set that round-trips the current rev', async () => {
+      const store = createWireframeStore(root)
+      const v1 = await store.set({ version: '1.0', updatedAt: 1, routes: [] })
+      expect(v1.rev).toBe(1)
+      const v2 = await store.set({ version: '1.0', updatedAt: 2, rev: v1.rev, routes: [] })
+      expect(v2.rev).toBe(2)
+      const v3 = await store.set({ version: '1.0', updatedAt: 3, rev: v2.rev, routes: [] })
+      expect(v3.rev).toBe(3)
+      expect((await store.get()).rev).toBe(3)
+    })
+
+    it('rejects a stale rev with WireframeRevConflictError', async () => {
+      const store = createWireframeStore(root)
+      const v1 = await store.set({ version: '1.0', updatedAt: 1, routes: [] })
+      await store.set({ version: '1.0', updatedAt: 2, rev: v1.rev, routes: [] })
+      await expect(store.set({ version: '1.0', updatedAt: 3, rev: v1.rev, routes: [] }))
+        .rejects.toBeInstanceOf(WireframeRevConflictError)
+      // The losing write must not have touched the file.
+      expect((await store.get()).rev).toBe(2)
+    })
+
+    it('rejects a missing rev once the doc has one', async () => {
+      const store = createWireframeStore(root)
+      await store.set({ version: '1.0', updatedAt: 1, routes: [] })
+      await expect(store.set({ version: '1.0', updatedAt: 2, routes: [] }))
+        .rejects.toBeInstanceOf(WireframeRevConflictError)
+    })
+
+    it('accepts one rev-less write against a legacy doc and stamps it', async () => {
+      // Simulate a doc written before the rev field existed.
+      const dir = path.join(root, '.annotask')
+      await fsp.mkdir(dir, { recursive: true })
+      await fsp.writeFile(path.join(dir, 'wireframe.json'), JSON.stringify({
+        version: '1.0', updatedAt: 1, routes: [{ route: '/', instances: [instance('wfi-legacy')] }],
+      }), 'utf-8')
+      const store = createWireframeStore(root)
+      const saved = await store.set({ version: '1.0', updatedAt: 2, routes: [] })
+      expect(saved.rev).toBe(1)
+      // From now on the CAS is enforced.
+      await expect(store.set({ version: '1.0', updatedAt: 3, routes: [] }))
+        .rejects.toBeInstanceOf(WireframeRevConflictError)
+    })
+  })
+})
+
+describe('isWireframeDocument instance-depth validation', () => {
+  function docWith(instances: unknown[]): unknown {
+    return { version: '1.0', updatedAt: 1, routes: [{ route: '/', instances }] }
+  }
+
+  it('accepts a well-formed document including the lifecycle fields', () => {
+    expect(isWireframeDocument(docWith([
+      instance('wfi-1', { status: 'building', taskId: 'task-1', previewProps: { label: 'Hi' } }),
+      instance('wfi-2'), // legacy: no status/taskId/previewProps
+    ]))).toBe(true)
+    expect(isWireframeDocument({ ...docWith([]) as Record<string, unknown>, rev: 4 })).toBe(true)
+  })
+
+  it('rejects an instance missing id / kind / anchor / inserted', () => {
+    expect(isWireframeDocument(docWith([{ ...instance('wfi-1'), id: undefined }]))).toBe(false)
+    expect(isWireframeDocument(docWith([{ ...instance('wfi-1'), kind: 'bogus' }]))).toBe(false)
+    expect(isWireframeDocument(docWith([{ ...instance('wfi-1'), anchor: null }]))).toBe(false)
+    expect(isWireframeDocument(docWith([{ ...instance('wfi-1'), inserted: 'planetcard' }]))).toBe(false)
+  })
+
+  it('rejects malformed anchor fields', () => {
+    expect(isWireframeDocument(docWith([instance('wfi-1', { anchor: { file: 7, line: 9, position: 'append' } as never })]))).toBe(false)
+    expect(isWireframeDocument(docWith([instance('wfi-1', { anchor: { file: 'a.vue', line: '9', position: 'append' } as never })]))).toBe(false)
+    expect(isWireframeDocument(docWith([instance('wfi-1', { anchor: { file: 'a.vue', line: 9, position: 'inside' } as never })]))).toBe(false)
+  })
+
+  it('rejects an inserted object without a string tag', () => {
+    expect(isWireframeDocument(docWith([instance('wfi-1', { inserted: { componentName: 'PlanetCard' } as never })]))).toBe(false)
+  })
+
+  it('rejects malformed optional lifecycle fields', () => {
+    expect(isWireframeDocument(docWith([instance('wfi-1', { status: 'done' as never })]))).toBe(false)
+    expect(isWireframeDocument(docWith([instance('wfi-1', { taskId: 42 as never })]))).toBe(false)
+    expect(isWireframeDocument(docWith([instance('wfi-1', { previewProps: ['nope'] as never })]))).toBe(false)
+  })
+
+  it('rejects a non-numeric rev', () => {
+    expect(isWireframeDocument({ version: '1.0', updatedAt: 1, rev: '3', routes: [] })).toBe(false)
+  })
+
+  it('one bad instance rejects the whole document (PUT boundary)', () => {
+    expect(isWireframeDocument(docWith([instance('wfi-good'), { id: 'wfi-bad' }]))).toBe(false)
+  })
+})
+
+describe('isWireframeDocument canvas-depth validation', () => {
+  const rect = { x: 0, y: 80, width: 800, height: 240 }
+
+  function block(id: string, extra: Record<string, unknown> = {}): Record<string, unknown> {
+    return {
+      id, kind: 'captured', rect, z: 1, createdAt: 1,
+      anchor: { file: 'src/pages/PlanetsPage.vue', line: 12, component: 'PlanetsPage', tag: 'div' },
+      originalRect: rect,
+      image: 'wfb-abc12-1.png',
+      ...extra,
+    }
+  }
+
+  function docWithCanvas(canvas: unknown): unknown {
+    return { version: '1.0', updatedAt: 1, routes: [{ route: '/planets', instances: [], canvas }] }
+  }
+
+  function canvasWith(blocks: unknown[], extra: Record<string, unknown> = {}): Record<string, unknown> {
+    return {
+      capturedAt: 1,
+      viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+      blocks,
+      ...extra,
+    }
+  }
+
+  it('accepts a route without a canvas (legacy docs) and a well-formed canvas', () => {
+    expect(isWireframeDocument({ version: '1.0', updatedAt: 1, routes: [{ route: '/', instances: [] }] })).toBe(true)
+    expect(isWireframeDocument(docWithCanvas(canvasWith([
+      block('wfb-1', { note: 'make this a carousel', deleted: true }),
+      { id: 'wfb-2', kind: 'palette', rect, z: 2, createdAt: 1, image: 'wfb-abc12-2.png', component: { tag: 'planetcard', componentName: 'PlanetCard', module: './components/PlanetCard.vue' }, fidelity: 'isolated-preview' },
+      { id: 'wfb-3', kind: 'placeholder', rect, z: 3, createdAt: 1, label: 'pagination here' },
+      block('wfb-4', { duplicateOf: 'wfb-1' }),
+    ], { fullImage: 'wf-full-1.png', status: 'building', taskId: 'task-1', truncated: true })))).toBe(true)
+  })
+
+  it('enforces per-kind substance: captured needs anchor+originalRect, palette needs component.tag, placeholder needs label', () => {
+    expect(isWireframeDocument(docWithCanvas(canvasWith([block('wfb-1', { anchor: undefined })])))).toBe(false)
+    expect(isWireframeDocument(docWithCanvas(canvasWith([block('wfb-1', { originalRect: undefined })])))).toBe(false)
+    expect(isWireframeDocument(docWithCanvas(canvasWith([{ id: 'wfb-2', kind: 'palette', rect, z: 1, createdAt: 1, component: { componentName: 'X' } }])))).toBe(false)
+    expect(isWireframeDocument(docWithCanvas(canvasWith([{ id: 'wfb-3', kind: 'placeholder', rect, z: 1, createdAt: 1, label: '' }])))).toBe(false)
+  })
+
+  it('rejects snapshot filenames that are not server-minted ids (traversal guard at the PUT boundary)', () => {
+    expect(isWireframeDocument(docWithCanvas(canvasWith([block('wfb-1', { image: '../escape.png' })])))).toBe(false)
+    expect(isWireframeDocument(docWithCanvas(canvasWith([block('wfb-1', { image: 'a/b.png' })])))).toBe(false)
+    expect(isWireframeDocument(docWithCanvas(canvasWith([block('wfb-1')], { fullImage: 'NOPE.PNG' })))).toBe(false)
+  })
+
+  it('rejects a malformed viewport, status, or rect', () => {
+    expect(isWireframeDocument(docWithCanvas(canvasWith([], { viewport: { width: 1280 } })))).toBe(false)
+    expect(isWireframeDocument(docWithCanvas(canvasWith([], { status: 'applied' })))).toBe(false)
+    expect(isWireframeDocument(docWithCanvas(canvasWith([block('wfb-1', { rect: { x: 0, y: 0, width: '800', height: 1 } })])))).toBe(false)
+  })
+
+  it('one bad block rejects the whole document', () => {
+    expect(isWireframeDocument(docWithCanvas(canvasWith([block('wfb-good'), { id: 'wfb-bad', kind: 'captured' }])))).toBe(false)
+  })
+
+  it('round-trips a canvas through the store', async () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'annotask-wfc-'))
+    try {
+      const store = createWireframeStore(root)
+      const doc: WireframeDocument = {
+        version: '1.0', updatedAt: 1,
+        routes: [{
+          route: '/planets',
+          instances: [],
+          canvas: {
+            capturedAt: 9,
+            viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+            fullImage: 'wf-full-1.png',
+            blocks: [{
+              id: 'wfb-1', kind: 'captured',
+              rect: { x: 0, y: 80, width: 800, height: 240 }, z: 1, createdAt: 1,
+              anchor: { file: 'src/pages/PlanetsPage.vue', line: 12 },
+              originalRect: { x: 0, y: 80, width: 800, height: 240 },
+              image: 'wfb-abc12-1.png',
+            }],
+          },
+        }],
+      }
+      const saved = await store.set(doc)
+      expect(saved.routes[0].canvas?.blocks).toHaveLength(1)
+      expect(await createWireframeStore(root).get()).toEqual({ ...doc, rev: 1 })
+    } finally {
+      await fsp.rm(root, { recursive: true, force: true })
+    }
+  })
+})
diff --git a/src/server/agent-configs.ts b/src/server/agent-configs.ts
new file mode 100644
index 0000000..53ff931
--- /dev/null
+++ b/src/server/agent-configs.ts
@@ -0,0 +1,64 @@
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import type { ProviderId, EffortLevel } from '../embedded/provider-config.js'
+
+export interface AgentConfigEntry {
+  /** Project-specific context written by the init agent, editable in settings. */
+  projectDirections: string
+  /** Per-agent provider override. When unset, the persona's built-in
+   *  providerId from src/embedded/persona.ts applies. */
+  providerId?: ProviderId
+  /** Per-agent model id. Empty string means "auto" (provider default). */
+  model?: string
+  /** Per-agent reasoning effort. `auto` means "let the provider pick". */
+  effort?: EffortLevel
+}
+
+export interface AgentConfigs {
+  version: 1
+  agents: Record<string, AgentConfigEntry>
+}
+
+export function createAgentConfigStore(projectRoot: string) {
+  const filePath = path.join(projectRoot, '.annotask', 'agents.json')
+
+  // No in-memory cache: the init pipeline writes agents.json directly via
+  // fsp.writeFile (bypassing this store), so a cache here would go stale and
+  // serve up the empty seed forever. The file is small — always read fresh.
+  async function load(): Promise<AgentConfigs> {
+    try {
+      const raw = JSON.parse(await fsp.readFile(filePath, 'utf-8'))
+      return {
+        version: 1,
+        agents: typeof raw.agents === 'object' && raw.agents !== null ? raw.agents : {},
+      }
+    } catch {
+      return { version: 1, agents: {} }
+    }
+  }
+
+  async function persist(data: AgentConfigs): Promise<void> {
+    const dir = path.dirname(filePath)
+    await fsp.mkdir(dir, { recursive: true })
+    const tmp = `${filePath}.tmp.${process.pid}.${Date.now()}`
+    await fsp.writeFile(tmp, JSON.stringify(data, null, 2), 'utf-8')
+    await fsp.rename(tmp, filePath)
+  }
+
+  return {
+    get: load,
+    set: async (personaId: string, entry: Partial<AgentConfigEntry>): Promise<AgentConfigs> => {
+      const current = await load()
+      const existing = current.agents[personaId] ?? { projectDirections: '' }
+      const next: AgentConfigs = {
+        version: 1,
+        agents: { ...current.agents, [personaId]: { ...existing, ...entry } },
+      }
+      await persist(next)
+      return next
+    },
+    invalidate: () => { /* no-op — load() always reads fresh from disk */ },
+  }
+}
+
+export type AgentConfigStore = ReturnType<typeof createAgentConfigStore>
diff --git a/src/server/agent-detect.ts b/src/server/agent-detect.ts
new file mode 100644
index 0000000..42c8c28
--- /dev/null
+++ b/src/server/agent-detect.ts
@@ -0,0 +1,215 @@
+/**
+ * Local-CLI detection probe.
+ *
+ * `GET /__annotask/api/agent/detect` returns a snapshot of which agent CLIs
+ * are installed on the user's PATH and whether they appear logged in.
+ *
+ * "Logged in" is best-effort — we check for the existence of the auth file
+ * each CLI maintains, not its validity. False positives are tolerable (the
+ * provider will surface a real error when the user actually runs); false
+ * negatives are the failure mode we work hard to avoid (claude-local
+ * provider only enables when this probe says yes).
+ *
+ * Docker / sandboxed envs: when Annotask runs inside a container, host-side
+ * CLI binaries and auth files aren't visible by default. Two env vars let the
+ * probe scan host-mounted paths instead of (or in addition to) the container's
+ * own PATH and $HOME:
+ *   - ANNOTASK_HOST_PATH — colon-separated dirs appended to PATH for `whichBin`
+ *   - ANNOTASK_HOST_HOME — alt home dir checked alongside `os.homedir()` for
+ *     auth files (e.g. mount `/host-home` and set this to it)
+ * The version probe still spawns the discovered binary; if the host path isn't
+ * actually executable from inside the container, the spawn just times out and
+ * `version` comes back undefined — `found` and `loggedIn` remain accurate.
+ *
+ * Cached for 30 seconds so the settings panel doesn't fork a dozen
+ * subprocesses every render.
+ */
+
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { spawn } from 'node:child_process'
+
+export interface CliStatus {
+  /** Binary found on PATH. */
+  found: boolean
+  /** Absolute path to the binary, when found. */
+  binPath?: string
+  /** Version string from `<cli> --version`, when probeable within the timeout. */
+  version?: string
+  /** Best-effort "is the user logged in" probe. */
+  loggedIn?: boolean
+}
+
+export interface AgentDetectSnapshot {
+  'claude-local': CliStatus
+  'codex-local': CliStatus
+  'opencode-local': CliStatus
+  'copilot-local': CliStatus
+  copilot: CliStatus
+  openrouter: { hasEnv: boolean }
+  /** When this snapshot was taken (ms since epoch). Clients display "checked X ago." */
+  ts: number
+}
+
+const CACHE_TTL_MS = 30_000
+const VERSION_TIMEOUT_MS = 1_000
+
+interface DetectorConfig {
+  bin: string
+  /** Files relative to $HOME whose existence implies "logged in." */
+  authFiles: string[]
+  /** Args to pass to the CLI to get a version. Some CLIs use `--version`, some `version`. */
+  versionArgs?: string[]
+}
+
+const DETECTORS: Record<'claude-local' | 'codex-local' | 'opencode-local' | 'copilot-local' | 'copilot', DetectorConfig> = {
+  'claude-local': {
+    bin: 'claude',
+    // `claude login` writes `.claude/auth.json` (or `.credentials.json` on older
+    // versions). Either implies logged in. The directory alone is not enough
+    // because Claude Code creates `.claude/` for project scaffolding too.
+    authFiles: ['.claude/auth.json', '.claude/.credentials.json'],
+    versionArgs: ['--version'],
+  },
+  'codex-local': {
+    bin: 'codex',
+    authFiles: ['.codex/auth.json', '.codex/auth.toml'],
+    versionArgs: ['--version'],
+  },
+  'opencode-local': {
+    bin: 'opencode',
+    authFiles: ['.local/share/opencode/auth.json', '.config/opencode/auth.json'],
+    versionArgs: ['--version'],
+  },
+  'copilot-local': {
+    bin: 'copilot',
+    // GitHub Copilot CLI writes `config.json` on first launch (set up at
+    // `firstLaunchAt`). Treat its existence as "logged in" — the CLI itself
+    // surfaces a clearer auth error if the session has expired.
+    authFiles: ['.copilot/config.json'],
+    versionArgs: ['--version'],
+  },
+  copilot: {
+    bin: 'gh',
+    // Copilot Chat accepts any GitHub OAuth token tied to an account with a
+    // Copilot subscription. The token can live in either of two places:
+    //   • `~/.config/github-copilot/{apps,hosts}.json` — written by the
+    //     GitHub Copilot IDE extension and the newer `copilot` CLI auth
+    //     flow.
+    //   • `~/.config/gh/hosts.yml` — written by `gh auth login`. The token
+    //     read path in copilot-provider falls back to this via `gh auth
+    //     token` when the IDE-extension files are absent.
+    // Either file's existence implies "user has a usable token somewhere".
+    authFiles: [
+      '.config/github-copilot/hosts.json',
+      '.config/github-copilot/apps.json',
+      '.config/gh/hosts.yml',
+    ],
+    versionArgs: ['--version'],
+  },
+}
+
+export interface AgentDetector {
+  detect(): Promise<AgentDetectSnapshot>
+  /** Force a re-probe on the next detect() call. */
+  invalidate(): void
+}
+
+export function createAgentDetector(): AgentDetector {
+  let cache: { ts: number; snapshot: AgentDetectSnapshot } | null = null
+
+  async function probe(cfg: DetectorConfig): Promise<CliStatus> {
+    const binPath = await whichBin(cfg.bin)
+    if (!binPath) return { found: false }
+    const homeDirs = [os.homedir()]
+    const hostHome = process.env.ANNOTASK_HOST_HOME
+    if (hostHome && hostHome !== os.homedir()) homeDirs.push(hostHome)
+    const authPaths = cfg.authFiles.flatMap((rel) => homeDirs.map((h) => path.join(h, rel)))
+    const [version, loggedIn] = await Promise.all([
+      cfg.versionArgs ? readVersion(binPath, cfg.versionArgs) : Promise.resolve(undefined),
+      anyExists(authPaths),
+    ])
+    return { found: true, binPath, version, loggedIn }
+  }
+
+  async function detect(): Promise<AgentDetectSnapshot> {
+    if (cache && Date.now() - cache.ts < CACHE_TTL_MS) return cache.snapshot
+    const [claude, codex, opencode, copilotLocal, copilot] = await Promise.all([
+      probe(DETECTORS['claude-local']),
+      probe(DETECTORS['codex-local']),
+      probe(DETECTORS['opencode-local']),
+      probe(DETECTORS['copilot-local']),
+      probe(DETECTORS.copilot),
+    ])
+    const snapshot: AgentDetectSnapshot = {
+      'claude-local': claude,
+      'codex-local': codex,
+      'opencode-local': opencode,
+      'copilot-local': copilotLocal,
+      copilot,
+      openrouter: { hasEnv: typeof process.env.OPENROUTER_API_KEY === 'string' && process.env.OPENROUTER_API_KEY.length > 0 },
+      ts: Date.now(),
+    }
+    cache = { ts: snapshot.ts, snapshot }
+    return snapshot
+  }
+
+  function invalidate(): void { cache = null }
+
+  return { detect, invalidate }
+}
+
+async function whichBin(name: string): Promise<string | undefined> {
+  // Path separator differs on Windows; we don't claim Windows support but
+  // detection should at least not throw there.
+  const sep = process.platform === 'win32' ? ';' : ':'
+  const exts = process.platform === 'win32' ? (process.env.PATHEXT?.split(';') ?? ['.EXE', '.CMD', '.BAT']) : ['']
+  // Append host-mounted dirs for dockerized installs (see file header).
+  const hostPath = process.env.ANNOTASK_HOST_PATH ?? ''
+  const PATH = hostPath ? `${process.env.PATH ?? ''}${sep}${hostPath}` : (process.env.PATH ?? '')
+  for (const dir of PATH.split(sep)) {
+    if (!dir) continue
+    for (const ext of exts) {
+      const candidate = path.join(dir, name + ext)
+      try {
+        const st = await fsp.stat(candidate)
+        if (st.isFile()) return candidate
+      } catch { /* not here */ }
+    }
+  }
+  return undefined
+}
+
+async function anyExists(paths: string[]): Promise<boolean> {
+  for (const p of paths) {
+    try {
+      await fsp.access(p)
+      return true
+    } catch { /* keep checking */ }
+  }
+  return false
+}
+
+function readVersion(binPath: string, args: string[]): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    let stdout = ''
+    const child = spawn(binPath, args, { shell: false, stdio: ['ignore', 'pipe', 'ignore'] })
+    const t = setTimeout(() => {
+      try { child.kill('SIGKILL') } catch { /* ignore */ }
+      resolve(undefined)
+    }, VERSION_TIMEOUT_MS)
+    child.stdout.setEncoding('utf-8')
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk
+      // Cap input — version strings are tiny; if more arrives, something's off.
+      if (stdout.length > 256) { try { child.kill('SIGKILL') } catch { /* ignore */ } }
+    })
+    child.on('error', () => { clearTimeout(t); resolve(undefined) })
+    child.on('close', () => {
+      clearTimeout(t)
+      const trimmed = stdout.trim()
+      resolve(trimmed.length > 0 ? trimmed.split('\n')[0] : undefined)
+    })
+  })
+}
diff --git a/src/server/agent-models.ts b/src/server/agent-models.ts
new file mode 100644
index 0000000..4ae1061
--- /dev/null
+++ b/src/server/agent-models.ts
@@ -0,0 +1,375 @@
+/**
+ * Model discovery for the embedded agent UI.
+ *
+ * Each local CLI exposes its installed models differently:
+ *   - opencode:    `opencode models` prints `provider/model` lines, one per
+ *                  entry. Captures everything including multi-segment paths
+ *                  like `vllm/Qwen/Qwen2.5-7B-Instruct-AWQ`.
+ *   - codex:       No `models` subcommand. Reads ~/.codex/models_cache.json
+ *                  which the Codex CLI maintains automatically (slug +
+ *                  display_name).
+ *   - claude:      No headless listing. The user sets a model id directly
+ *                  in provider config or uses Auto (CLI default).
+ *
+ * Discovery runs on demand from `GET /__annotask/api/agent/models?cli=NAME`,
+ * caches per CLI for 5 minutes, and always prepends an "Auto" entry.
+ * Probes are best-effort with a 5s timeout. When a probe fails or a
+ * provider has no probe at all, the catalog comes back with only "Auto" +
+ * an `error` string explaining the gap — there are no curated fallbacks.
+ * The UI uses `error` to block selection of a specific model id rather
+ * than silently serving guesses that the underlying CLI would later reject.
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { effectiveSpawnPath, hostUserSpawnOptions } from './agent-spawn.js'
+const execFileAsync = promisify(execFile)
+
+/**
+ * ANSI escape sequence stripper. opencode / gh copilot output sometimes
+ * arrives with terminal control sequences when stdout is a TTY proxy
+ * (e.g. running through a wrapper that doesn't honor `--no-color`).
+ * Stripping them is the difference between "Auto only" and a full list.
+ */
+const ANSI_RE = /\x1B\[[0-?]*[ -/]*[@-~]/g
+function stripAnsi(s: string): string {
+  return s.replace(ANSI_RE, '')
+}
+
+export type ProvideredId = 'claude-local' | 'codex-local' | 'opencode-local' | 'copilot-local' | 'anthropic' | 'openai' | 'openrouter' | 'openai-compatible' | 'paperclip'
+
+export interface ModelOption {
+  id: string
+  label: string
+  /**
+   * `auto` — synthetic "Auto (CLI default)" entry, present in every catalog.
+   * `discovered` — returned by a live probe against the provider's own
+   *   catalog (`opencode models`, the Codex model cache file). Trust
+   *   completely — these are the user's real options.
+   * `static` — provider has no headless model-list API, so we serve a
+   *   canonical short list of ids the CLI/HTTP endpoint is known to
+   *   accept (Claude's `opus`/`sonnet`/`haiku` aliases, Anthropic's
+   *   public model ids). NOT a "fallback" — this IS the catalog for
+   *   that provider; there's no probe to fall back from.
+   */
+  source: 'auto' | 'discovered' | 'static'
+}
+
+export interface AgentModelCatalog {
+  cli: ProvideredId
+  models: ModelOption[]
+  discovered: boolean
+  cachedAt: number
+  /**
+   * When non-empty, the live model list could not be obtained — either the
+   * provider has no probe implemented, or the probe ran and returned
+   * nothing. Consumers should block selection of a specific model and
+   * surface this to the user instead of pretending a curated list is the
+   * truth. `Auto (CLI default)` is still safe to use because the provider
+   * itself picks the model.
+   */
+  error?: string
+}
+
+const AUTO_OPTION: ModelOption = { id: '', label: 'Auto (CLI default)', source: 'auto' }
+
+/**
+ * Static catalogs for providers that have no headless model-list API.
+ *
+ * These are NOT fallbacks for failed probes — they're the authoritative
+ * catalog for providers that simply don't expose discovery. The Claude CLI
+ * resolves `opus`/`sonnet`/`haiku` to the current production model ids;
+ * Anthropic/OpenAI/OpenRouter publish stable model ids that the
+ * chat-completions endpoint accepts directly.
+ *
+ * Probed providers (codex-local, opencode-local, copilot-local) are
+ * intentionally absent from this map. If their probe returns nothing, we
+ * surface an error so the UI can block — guessing at their catalogs is what
+ * caused the original "gpt-5.4-mini may not exist" failure.
+ */
+const STATIC_CATALOGS: Partial<Record<ProvideredId, ModelOption[]>> = {
+  'claude-local': [
+    // CLI aliases — Claude Code resolves these to the current release.
+    { id: 'opus',   label: 'Opus 4.7',  source: 'static' },
+    { id: 'sonnet', label: 'Sonnet 4.6', source: 'static' },
+    { id: 'haiku',  label: 'Haiku 4.5', source: 'static' },
+  ],
+  anthropic: [
+    { id: 'claude-opus-4-7',          label: 'Opus 4.7',  source: 'static' },
+    { id: 'claude-sonnet-4-6',        label: 'Sonnet 4.6', source: 'static' },
+    { id: 'claude-haiku-4-5-20251001', label: 'Haiku 4.5', source: 'static' },
+  ],
+  openai: [
+    { id: 'gpt-5',      label: 'GPT-5',      source: 'static' },
+    { id: 'gpt-5-mini', label: 'GPT-5 mini', source: 'static' },
+    { id: 'gpt-4o',     label: 'GPT-4o',     source: 'static' },
+    { id: 'o3',         label: 'o3',         source: 'static' },
+  ],
+  openrouter: [
+    { id: 'anthropic/claude-sonnet-4-6', label: 'Sonnet 4.6 (Anthropic)', source: 'static' },
+    { id: 'openai/gpt-5',                 label: 'GPT-5 (OpenAI)',         source: 'static' },
+    { id: 'openai/gpt-4o-mini',           label: 'GPT-4o mini (OpenAI)',   source: 'static' },
+  ],
+  'openai-compatible': [
+    // Common ids people self-host. The user usually sets the model field
+    // to whatever their endpoint actually serves — these are suggestions.
+    { id: 'qwen2.5-coder', label: 'qwen2.5-coder', source: 'static' },
+    { id: 'llama3.1',      label: 'llama3.1',       source: 'static' },
+  ],
+  paperclip: [
+    { id: 'paperclip-default', label: 'Paperclip default', source: 'static' },
+  ],
+}
+
+const CACHE_TTL_MS = 5 * 60_000   // 5 min — model lists don't change often
+const PROBE_TIMEOUT_MS = 5_000
+const cache = new Map<string, AgentModelCatalog>()
+
+export interface ListAgentModelsOptions {
+  /** Skip the in-process cache and force a fresh probe. */
+  refresh?: boolean
+}
+
+export async function listAgentModels(cli: ProvideredId, opts: ListAgentModelsOptions = {}): Promise<AgentModelCatalog> {
+  const hit = cache.get(cli)
+  if (!opts.refresh && hit && Date.now() - hit.cachedAt < CACHE_TTL_MS) return hit
+
+  const discovered = await tryDiscover(cli)
+
+  // Live probe found real options — trust it as the authoritative list.
+  if (discovered.length > 0) {
+    return cacheAndReturn(cli, {
+      cli,
+      models: [AUTO_OPTION, ...discovered],
+      discovered: true,
+      cachedAt: Date.now(),
+    })
+  }
+
+  // No probe data. Two cases:
+  //   1. Provider has a static catalog (claude-local, anthropic, openai, …)
+  //      — that IS the catalog. No error; the UI shows the static list.
+  //   2. Provider was expected to probe but didn't return anything
+  //      (copilot, codex-local, opencode-local, copilot-local) — surface a
+  //      targeted error so the picker is blocked rather than guessing.
+  const staticList = STATIC_CATALOGS[cli]
+  if (staticList) {
+    return cacheAndReturn(cli, {
+      cli,
+      models: [AUTO_OPTION, ...staticList],
+      discovered: false,
+      cachedAt: Date.now(),
+    })
+  }
+
+  let error: string
+  if (cli === 'copilot-local') {
+    error = await copilotLocalNoListError()
+  } else {
+    error = `${cli}: no models returned by the live probe. Sign in to the provider's CLI / account, check network access, then refresh.`
+  }
+
+  return cacheAndReturn(cli, {
+    cli,
+    models: [AUTO_OPTION],
+    discovered: false,
+    cachedAt: Date.now(),
+    error,
+  })
+}
+
+function cacheAndReturn(cli: ProvideredId, catalog: AgentModelCatalog): AgentModelCatalog {
+  cache.set(cli, catalog)
+  return catalog
+}
+
+async function copilotLocalNoListError(): Promise<string> {
+  const def = await readCopilotCliDefaultModel()
+  const tail = def
+    ? ` Your CLI default is "${def}" — pick Auto to use it, or set a custom id matching one your account supports.`
+    : ' Use Auto (CLI default), or set a custom id matching one your account supports.'
+  return `The Copilot CLI doesn't expose a model list. Run \`copilot\` interactively and \`/model\` to see your options.${tail}`
+}
+
+export function invalidateAgentModels(cli?: ProvideredId): void {
+  if (cli) cache.delete(cli)
+  else cache.clear()
+}
+
+async function tryDiscover(cli: ProvideredId): Promise<ModelOption[]> {
+  switch (cli) {
+    case 'opencode-local': return probeOpenCode()
+    case 'codex-local': return probeCodex()
+    case 'copilot-local':
+      // CLI subprocess: the `copilot` binary's `--model` flag does NOT accept
+      // the HTTP catalog's ids (e.g. settings.json defaults to
+      // `claude-sonnet-4.5`, not the HTTP API's `claude-sonnet-4.6`). The
+      // CLI has no headless model-list command, so we deliberately return
+      // nothing and let listAgentModels() surface a copilot-local-specific
+      // error. See the message in listAgentModels() for the user guidance.
+      return []
+    default: return []
+  }
+}
+
+// ── opencode ──────────────────────────────────────────
+
+async function probeOpenCode(): Promise<ModelOption[]> {
+  // Retry once on transient failure — opencode occasionally exits non-zero
+  // on the first invocation after a fresh install while it lays down its
+  // config dir. The second call almost always succeeds.
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      // Hint NO_COLOR so newer opencode builds don't smuggle ANSI in; we
+      // still strip defensively in case the env hint is ignored.
+      const hostUser = hostUserSpawnOptions()
+      const { stdout } = await execFileAsync('opencode', ['models'], {
+        timeout: PROBE_TIMEOUT_MS,
+        uid: hostUser.uid,
+        gid: hostUser.gid,
+        env: { ...process.env, PATH: effectiveSpawnPath(), ...(hostUser.env ?? {}), NO_COLOR: '1', FORCE_COLOR: '0' },
+        maxBuffer: 8 * 1024 * 1024,
+      })
+      const parsed = parseOpenCodeModels(stdout)
+      if (parsed.length > 0) return parsed
+    } catch {
+      // fall through to retry / fallback
+    }
+  }
+  return []
+}
+
+/**
+ * Parse `opencode models` output.
+ *
+ * The command prints one entry per line in `provider/model` format.
+ * Models with nested paths (`vllm/Qwen/Qwen2.5-7B-Instruct-AWQ`) are
+ * captured as the full trimmed line — the previous regex stopped at the
+ * first two path segments and silently discarded the rest.
+ *
+ * Also accepts JSON (object with `models` array or bare array) in case
+ * a future opencode version adds `--format=json`.
+ */
+export function parseOpenCodeModels(stdout: string): ModelOption[] {
+  // Defensive: opencode sometimes ignores NO_COLOR and emits ANSI control
+  // sequences. Strip them before any parsing so the `provider/model` check
+  // below sees clean lines.
+  const trimmed = stripAnsi(stdout).trim()
+  if (!trimmed) return []
+
+  // JSON first
+  try {
+    const parsed = JSON.parse(trimmed)
+    if (Array.isArray(parsed)) {
+      return parsed.map(asModelOption).filter((m): m is ModelOption => m != null)
+    }
+    if (parsed && typeof parsed === 'object' && Array.isArray((parsed as any).models)) {
+      const list = (parsed as { models: unknown[] }).models
+      return list.map(asModelOption).filter((m: ModelOption | null): m is ModelOption => m != null)
+    }
+  } catch {
+    // not JSON — line parser below
+  }
+
+  // Line-based: one `provider/model[/path...]` per line. Recent opencode
+  // releases sometimes wrap the id with table decorations or status glyphs
+  // (e.g. `→ anthropic/claude-sonnet-4-5  (active)`). Pick the first
+  // whitespace-separated token that has a slash so multi-segment ids like
+  // `vllm/Qwen/Model-7B` survive intact while the decorations are dropped.
+  const out: ModelOption[] = []
+  const seen = new Set<string>()
+  for (const raw of trimmed.split(/\r?\n/)) {
+    // Strip common leading decoration characters opencode prepends to the
+    // active row (>, *, →, •, ✓ …) so the slash-detector sees the bare id.
+    const line = raw.replace(/^[\s>*→•✓✔•→-]+/, '').trim()
+    if (!line || line.startsWith('#') || line.startsWith('=')) continue
+    // Take the first slashed token (a provider/model id never contains
+    // whitespace). Anything after it (parens, version hints, "active") is
+    // discarded.
+    const token = line.split(/\s+/).find((t) => t.includes('/'))
+    if (!token) continue
+    // Sanity: a model id won't realistically be longer than 200 chars.
+    if (token.length > 200) continue
+    if (seen.has(token)) continue
+    seen.add(token)
+    out.push({ id: token, label: token, source: 'discovered' })
+  }
+  return out
+}
+
+// ── codex ─────────────────────────────────────────────
+
+/**
+ * Codex doesn't expose a headless `models` subcommand. The CLI maintains
+ * a local model catalog at `~/.codex/models_cache.json` — read that
+ * file directly so users always see what Codex actually knows about.
+ */
+async function probeCodex(): Promise<ModelOption[]> {
+  const cachePath = path.join(os.homedir(), '.codex', 'models_cache.json')
+  try {
+    const raw = await fsp.readFile(cachePath, 'utf-8')
+    return parseCodexModelsCache(raw)
+  } catch {
+    return []
+  }
+}
+
+export function parseCodexModelsCache(raw: string): ModelOption[] {
+  try {
+    const json = JSON.parse(raw)
+    const models: unknown[] = Array.isArray(json?.models) ? json.models : []
+    const out: ModelOption[] = []
+    const seen = new Set<string>()
+    for (const m of models) {
+      if (!m || typeof m !== 'object') continue
+      const o = m as Record<string, unknown>
+      const id = typeof o.slug === 'string' ? o.slug : null
+      if (!id || seen.has(id)) continue
+      seen.add(id)
+      const label = typeof o.display_name === 'string' ? o.display_name : id
+      out.push({ id, label, source: 'discovered' })
+    }
+    return out
+  } catch {
+    return []
+  }
+}
+
+// ── copilot-local (CLI subprocess) ────────────────────
+
+/**
+ * Best-effort read of the Copilot CLI's saved default model. Lives in
+ * `~/.copilot/settings.json` and is the *only* model the CLI guarantees
+ * will work for the current user without an interactive `/model` switch.
+ * Used purely to surface a helpful hint in the error message — never to
+ * populate the model dropdown (we don't have a way to enumerate the rest).
+ */
+async function readCopilotCliDefaultModel(): Promise<string | null> {
+  try {
+    const raw = await fsp.readFile(path.join(os.homedir(), '.copilot', 'settings.json'), 'utf-8')
+    const json = JSON.parse(raw) as { model?: unknown }
+    return typeof json.model === 'string' && json.model.length > 0 ? json.model : null
+  } catch {
+    return null
+  }
+}
+
+// ── helpers ───────────────────────────────────────────
+
+function asModelOption(raw: unknown): ModelOption | null {
+  if (typeof raw === 'string') return { id: raw, label: raw, source: 'discovered' }
+  if (raw && typeof raw === 'object') {
+    const o = raw as Record<string, unknown>
+    const id = typeof o.id === 'string' ? o.id : typeof o.name === 'string' ? o.name : null
+    if (!id) return null
+    const label = typeof o.label === 'string' ? o.label
+      : typeof o.displayName === 'string' ? o.displayName
+      : id
+    return { id, label, source: 'discovered' }
+  }
+  return null
+}
+
diff --git a/src/server/agent-spawn.ts b/src/server/agent-spawn.ts
new file mode 100644
index 0000000..ee5618f
--- /dev/null
+++ b/src/server/agent-spawn.ts
@@ -0,0 +1,574 @@
+/**
+ * Localhost-only subprocess spawner for local-CLI providers.
+ *
+ * The shell talks to the user's locally-installed agent CLIs (claude, codex,
+ * opencode) by POSTing a spawn request here. We spawn the process, stream
+ * its stdout/stderr back as text/event-stream, and let the caller abort via
+ * the request's AbortSignal (i.e. the browser closes the EventSource).
+ *
+ * Security posture:
+ *   - The Annotask dev server is only ever bound to localhost. Mutating
+ *     routes reject non-local origins, and spawn routes additionally
+ *     enforce same-port origin matching (see api.ts:originMatchesPort).
+ *   - `cli` must be in the allow-list — we never accept a free-form binary
+ *     name or absolute path. Argv passes through unparsed but is spawned
+ *     with `shell: false` so there's no shell-injection seam.
+ *   - cwd is always the project root; callers can't escape it via args.
+ *   - env is the dev server's env plus a small caller-supplied delta; we
+ *     never accept overrides for PATH or HOME so credentials in the user's
+ *     home directory stay where the CLI expects them. PATH is augmented
+ *     server-side with `ANNOTASK_HOST_PATH` (if set) so dockerized installs
+ *     can locate host-mounted CLI binaries — same env var used by the
+ *     CLI-detection probe.
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+
+/** Allow-listed CLI binary names. Free-form names are rejected. */
+const ALLOWED_CLIS = new Set(['claude', 'codex', 'opencode', 'copilot'])
+
+/** Task id shape (`task-<...>`). Keys the per-task run registry. */
+const SAFE_TASK_ID = /^task-[A-Za-z0-9_-]+$/
+
+/** Env keys the caller may add. PATH/HOME/USER/SHELL/etc. are never overridable. */
+const SAFE_ENV_KEYS = new Set([
+  'ANTHROPIC_MODEL',
+  'OPENAI_MODEL',
+  'OPENROUTER_API_KEY',
+  // Add more here as specific providers prove they need them.
+])
+
+/** Hard cap so a runaway CLI can't accumulate gigabytes of buffered stdout. */
+const MAX_BUFFERED_LINE_BYTES = 1_048_576
+/** Hard cap on total stderr we retain in memory. Truncates after this. */
+const MAX_STDERR_BUFFER_BYTES = 65_536
+/** Grace period before SIGKILL after SIGTERM on abort. */
+const KILL_GRACE_MS = 2_000
+/** Idle keepalive interval so proxies don't drop the connection. */
+const KEEPALIVE_INTERVAL_MS = 15_000
+/**
+ * Absolute server-side ceiling on a single spawned CLI run. Last-resort
+ * backstop *beneath* the client-side stall watchdog (default 10 min) — set
+ * higher so the client aborts first in the normal case; this only catches a
+ * child that outlives a disconnected/dead client. Kills the child on expiry.
+ */
+const MAX_SPAWN_DURATION_MS = 15 * 60_000
+/**
+ * Max concurrent CLI child processes. The client auto-run driver serializes
+ * per tab, but multiple open tabs or a buggy/looping client are not otherwise
+ * bounded — without a cap they could fan out N agents editing the same files
+ * at once. Excess spawns are refused with a `too_many_agents` error.
+ */
+const MAX_CONCURRENT_SPAWNS = 4
+
+/**
+ * PATH passed to spawned CLIs. Appends `ANNOTASK_HOST_PATH` (if set) so
+ * dockerized installs that mount host-side binaries can find them — matches
+ * the lookup behavior of the CLI-detection probe in `agent-detect.ts`.
+ *
+ * Exported so init.ts and agent-models.ts (which also fork CLIs) can use
+ * the same logic without duplicating the env-var handling.
+ */
+export function effectiveSpawnPath(): string {
+  const base = process.env.PATH ?? ''
+  const host = process.env.ANNOTASK_HOST_PATH
+  if (!host) return base
+  const sep = process.platform === 'win32' ? ';' : ':'
+  return base ? `${base}${sep}${host}` : host
+}
+
+/**
+ * When the dev server runs as root inside a container with a host home
+ * directory mounted (typical Docker layout), drop the spawned CLI to the
+ * uid/gid that owns that directory. Several CLIs (notably Claude Code with
+ * `--dangerously-skip-permissions`) refuse to run as root for safety; the
+ * host user ultimately owns the auth files the CLI needs to read, so
+ * matching their uid is the right call.
+ *
+ * Returns an empty object outside Docker (non-root, or no host home set),
+ * so this is a no-op for normal local installs.
+ */
+export function hostUserSpawnOptions(): { uid?: number; gid?: number; env?: Record<string, string> } {
+  // getuid is only defined on POSIX platforms.
+  const getuid = (process as NodeJS.Process & { getuid?: () => number }).getuid
+  if (typeof getuid !== 'function' || getuid.call(process) !== 0) return {}
+  const hostHome = process.env.ANNOTASK_HOST_HOME
+  if (!hostHome) return {}
+  try {
+    const st = fs.statSync(hostHome)
+    // Set HOME for the child so the CLI reads auth files from the mounted
+    // host home rather than the container's /root.
+    return { uid: st.uid, gid: st.gid, env: { HOME: hostHome } }
+  } catch {
+    return {}
+  }
+}
+
+export interface SpawnRequestBody {
+  cli: string
+  args: string[]
+  stdin?: string
+  env?: Record<string, string>
+  /** Optional task this run is applying. Keys the run registry so one task
+   *  can't be double-spawned (e.g. two tabs auto-running it) and so the run
+   *  end can be reported for orphaned-task finalization. */
+  taskId?: string
+}
+
+interface ActiveRun {
+  child: ChildProcessWithoutNullStreams
+  kill: () => void
+  taskId?: string
+}
+
+export interface AgentSpawnRegistry {
+  /** Kill a run by id. Returns true if a run was found. */
+  abort(runId: string): boolean
+  /** Number of currently active runs. Exposed for tests. */
+  size(): number
+  /** True iff a live run exists for this task id. */
+  taskRunning(taskId: string): boolean
+  /** Kill every active run. Called from server.dispose(). */
+  killAll(): void
+}
+
+export interface AgentSpawnOptions {
+  /**
+   * Fired once a run that carried a `taskId` ends (child closed or errored),
+   * for normal completion AND interrupted/orphaned runs alike. The wiring in
+   * index.ts uses it to finalize a task the client never transitioned (e.g.
+   * the orchestrating tab closed mid-run) — it grace-checks "still in_progress?"
+   * so a normal completion (client about to set `review`) is a no-op.
+   *
+   * `info.killed` is true when WE terminated the child (client disconnect,
+   * explicit abort, or the duration backstop) and false when it exited on its
+   * own — lets the finalizer word its reason honestly instead of always
+   * blaming a closed tab.
+   */
+  onRunEnd?: (taskId: string, info: { killed: boolean }) => void
+  /** Test seam: inject a child-process factory (defaults to node:child_process spawn). */
+  spawnImpl?: typeof spawn
+}
+
+export interface AgentSpawnHandler {
+  registry: AgentSpawnRegistry
+  /**
+   * Handle `POST /__annotask/api/agent/spawn`. Validates the body, spawns
+   * the child, and writes SSE events to `res`. Returns when the child exits.
+   */
+  handleSpawn(req: IncomingMessage, res: ServerResponse, body: unknown, projectRoot: string): Promise<void>
+}
+
+/**
+ * Optional server-side ceiling on the permission level a spawn may request.
+ * Set `ANNOTASK_MAX_PERMISSION=plan|default` to refuse any spawn whose argv
+ * carries flags exceeding it — a floor a same-origin page cannot talk past,
+ * for shared / CI / locked-down setups. Unset (or `bypass`) imposes no cap.
+ *
+ * Permission semantics are assembled client-side (the browser builds argv),
+ * so this is the one place the server re-derives the *level* from the flags
+ * and enforces a policy of its own rather than trusting the caller.
+ */
+const PERMISSION_LEVEL = { plan: 0, default: 1, bypass: 2 } as const
+export type PermissionLevelName = keyof typeof PERMISSION_LEVEL
+
+export function maxPermissionCap(): PermissionLevelName {
+  const raw = (process.env.ANNOTASK_MAX_PERMISSION ?? '').trim().toLowerCase()
+  return raw === 'plan' || raw === 'default' ? raw : 'bypass'
+}
+
+/** Flags that, if present, mean the run removes sandboxes / auto-approves all. */
+const BYPASS_FLAGS = new Set([
+  '--dangerously-skip-permissions', // claude, opencode
+  '--dangerously-bypass-approvals-and-sandbox', // codex
+  '--allow-all', // copilot
+])
+/** Flags that imply a sandboxed/minimal "default" level (still writes, but scoped). */
+const DEFAULT_FLAGS = new Set(['--full-auto', '--allow-all-tools'])
+
+/**
+ * Re-derive the highest permission level the given argv implies. Best-effort
+ * floor, not a full parser: it mirrors exactly what the client emits per CLI
+ * per mode (see ../embedded/permission-mode-flags.ts) PLUS the synonym
+ * spellings a crafted request could substitute for them — claude's
+ * `--permission-mode bypassPermissions`/`acceptEdits`, codex's
+ * `--sandbox danger-full-access` and `--ask-for-approval never`, and the
+ * `--flag=value` joined form of each. Bypass flags win over default-level
+ * flags; absence of any recognized flag is the safest `plan` level. When an
+ * allow-listed CLI grows new permission flags they MUST be added here, or
+ * the ANNOTASK_MAX_PERMISSION cap won't see them.
+ *
+ * Two deliberate asymmetries:
+ *   - copilot's plan and default modes emit identical flags (headless `-p`
+ *     requires `--allow-all-tools`; plan is prompt-enforced), so copilot plan
+ *     derives as `default` — a conservative over-count, never an under-count.
+ *   - codex `--ask-for-approval never` is only as dangerous as the sandbox it
+ *     pairs with: harmless under an explicit `read-only` sandbox, but with a
+ *     writable or absent sandbox flag the effective sandbox comes from the
+ *     user's config.toml (which we can't see) — assume `bypass`.
+ */
+export function permissionLevelOfArgs(args: string[]): PermissionLevelName {
+  let level: PermissionLevelName = 'plan'
+  const bump = (l: PermissionLevelName) => {
+    if (PERMISSION_LEVEL[l] > PERMISSION_LEVEL[level]) level = l
+  }
+  // codex's approval policy and sandbox interact — track both, resolve after.
+  let sandbox: string | undefined
+  let approvalNever = false
+
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i]
+    // Accept both `--flag value` and `--flag=value` spellings — every
+    // allow-listed CLI's arg parser does, so the floor must too.
+    const eq = token.startsWith('-') ? token.indexOf('=') : -1
+    const flag = eq > 0 ? token.slice(0, eq) : token
+    const value = eq > 0 ? token.slice(eq + 1) : args[i + 1]
+
+    if (BYPASS_FLAGS.has(flag)) return 'bypass'
+    if (DEFAULT_FLAGS.has(flag)) { bump('default'); continue }
+    if (flag === '--permission-mode') { // claude
+      if (value === 'bypassPermissions') return 'bypass'
+      // default / acceptEdits / unknown future modes: at least writes files.
+      if (value !== 'plan') bump('default')
+      continue
+    }
+    if (flag === '--sandbox' || flag === '-s') { // codex
+      sandbox = value
+      if (value === 'danger-full-access') return 'bypass'
+      // workspace-write / unknown future modes: writes, but OS-scoped.
+      if (value !== 'read-only') bump('default')
+      continue
+    }
+    if ((flag === '--ask-for-approval' || flag === '-a') && value === 'never') { // codex
+      approvalNever = true
+    }
+  }
+
+  if (approvalNever && sandbox !== 'read-only') return 'bypass'
+  return level
+}
+
+/**
+ * Return the (level, cap) pair when the given argv exceeds the configured
+ * `ANNOTASK_MAX_PERMISSION` ceiling, or `null` when it's within the cap. Shared
+ * by the per-task spawn handler and the init pipeline so both honor the same
+ * floor.
+ */
+export function exceedsPermissionCap(
+  args: string[],
+): { level: PermissionLevelName; cap: PermissionLevelName } | null {
+  const cap = maxPermissionCap()
+  const level = permissionLevelOfArgs(args)
+  return PERMISSION_LEVEL[level] > PERMISSION_LEVEL[cap] ? { level, cap } : null
+}
+
+/** Run a coarse validation on the body and return a SpawnRequestBody, or an error string. */
+export function parseSpawnBody(raw: unknown): SpawnRequestBody | string {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return 'body must be a JSON object'
+  const body = raw as Record<string, unknown>
+  if (typeof body.cli !== 'string') return '`cli` must be a string'
+  if (!ALLOWED_CLIS.has(body.cli)) return `\`cli\` must be one of: ${[...ALLOWED_CLIS].join(', ')}`
+  if (!Array.isArray(body.args)) return '`args` must be an array of strings'
+  for (const a of body.args) {
+    if (typeof a !== 'string') return '`args` entries must be strings'
+  }
+  if (body.stdin !== undefined && typeof body.stdin !== 'string') return '`stdin` must be a string when set'
+  let env: Record<string, string> | undefined
+  if (body.env !== undefined) {
+    if (!body.env || typeof body.env !== 'object' || Array.isArray(body.env)) return '`env` must be an object when set'
+    env = {}
+    for (const [k, v] of Object.entries(body.env as Record<string, unknown>)) {
+      if (!SAFE_ENV_KEYS.has(k)) continue // silently drop unknown keys
+      if (typeof v !== 'string') return `\`env.${k}\` must be a string`
+      env[k] = v
+    }
+  }
+  let taskId: string | undefined
+  if (body.taskId !== undefined) {
+    if (typeof body.taskId !== 'string' || !SAFE_TASK_ID.test(body.taskId)) return '`taskId` must be a task id when set'
+    taskId = body.taskId
+  }
+  return { cli: body.cli, args: body.args as string[], stdin: body.stdin as string | undefined, env, taskId }
+}
+
+export function createAgentSpawnHandler(opts: AgentSpawnOptions = {}): AgentSpawnHandler {
+  const active = new Map<string, ActiveRun>()
+  // taskId -> runId. Enforces one live run per task (cross-tab dedup).
+  const byTask = new Map<string, string>()
+
+  function newRunId(): string {
+    return `run-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`
+  }
+
+  function abort(runId: string): boolean {
+    const run = active.get(runId)
+    if (!run) return false
+    run.kill()
+    return true
+  }
+
+  function killAll(): void {
+    for (const run of active.values()) {
+      try { run.kill() } catch { /* ignore */ }
+    }
+    active.clear()
+    byTask.clear()
+  }
+
+  async function handleSpawn(
+    req: IncomingMessage,
+    res: ServerResponse,
+    rawBody: unknown,
+    projectRoot: string,
+  ): Promise<void> {
+    const parsed = parseSpawnBody(rawBody)
+    if (typeof parsed === 'string') {
+      res.statusCode = 400
+      res.setHeader('Content-Type', 'application/json')
+      res.end(JSON.stringify({ error: { code: 'validation_failed', message: parsed } }))
+      return
+    }
+
+    // Server-side permission floor. The browser assembles the permission flags;
+    // here we re-derive the level from the argv and refuse anything above the
+    // configured cap so a same-origin page can't hand-craft a bypass run.
+    const exceeded = exceedsPermissionCap(parsed.args)
+    if (exceeded) {
+      res.statusCode = 403
+      res.setHeader('Content-Type', 'application/json')
+      res.end(JSON.stringify({
+        error: {
+          code: 'permission_exceeds_cap',
+          message: `Spawn requested '${exceeded.level}' permission but ANNOTASK_MAX_PERMISSION caps at '${exceeded.cap}'.`,
+        },
+      }))
+      return
+    }
+
+    // Concurrency floor — bound the number of live child processes regardless
+    // of how many tabs/clients ask. (Checked before spawning, not registered.)
+    if (active.size >= MAX_CONCURRENT_SPAWNS) {
+      res.statusCode = 503
+      res.setHeader('Content-Type', 'application/json')
+      res.end(JSON.stringify({
+        error: {
+          code: 'too_many_agents',
+          message: `Too many agents running (${active.size}/${MAX_CONCURRENT_SPAWNS}). Wait for one to finish.`,
+        },
+      }))
+      return
+    }
+
+    const runId = newRunId()
+    // Per-task dedup: at most one live run per task. Closes the cross-tab
+    // double-spawn hole — two tabs each auto-running the same task would
+    // otherwise fork two CLIs editing the same files, which the client-side
+    // (per-tab) concurrency guard can't prevent. Reserve BEFORE the SSE headers
+    // so the rejection can still be a plain 409. (Sync between check and set.)
+    if (parsed.taskId) {
+      if (byTask.has(parsed.taskId)) {
+        res.statusCode = 409
+        res.setHeader('Content-Type', 'application/json')
+        res.end(JSON.stringify({
+          error: {
+            code: 'task_already_running',
+            message: `Task ${parsed.taskId} is already running in another tab or session.`,
+          },
+        }))
+        return
+      }
+      byTask.set(parsed.taskId, runId)
+    }
+
+    // SSE headers.
+    res.statusCode = 200
+    res.setHeader('Content-Type', 'text/event-stream')
+    res.setHeader('Cache-Control', 'no-store')
+    res.setHeader('Connection', 'keep-alive')
+    res.flushHeaders?.()
+
+    write(res, 'run', { runId })
+
+    let child: ChildProcessWithoutNullStreams
+    try {
+      const hostUser = hostUserSpawnOptions()
+      child = (opts.spawnImpl ?? spawn)(parsed.cli, parsed.args, {
+        cwd: projectRoot,
+        shell: false,
+        uid: hostUser.uid,
+        gid: hostUser.gid,
+        // POSIX: make the child a process-group leader so killChild can signal
+        // the whole group (`process.kill(-pid)`). Agent CLIs routinely fork
+        // grandchildren (shell commands, MCP servers) — killing only the
+        // direct child would orphan those mid-run on abort/disconnect.
+        // Windows has no process groups, so detaching buys nothing there.
+        detached: process.platform !== 'win32',
+        // Force PWD to match cwd. The inherited PWD points at wherever the dev
+        // server was launched, which usually equals projectRoot — but when it
+        // doesn't (monorepo / Docker / nested launch), CLIs that read $PWD for
+        // project-root detection (e.g. opencode) would operate on the wrong
+        // tree instead of the spawn cwd. Setting it last keeps it authoritative.
+        env: { ...process.env, PATH: effectiveSpawnPath(), ...(hostUser.env ?? {}), ...(parsed.env ?? {}), PWD: projectRoot },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+    } catch (err) {
+      if (parsed.taskId && byTask.get(parsed.taskId) === runId) byTask.delete(parsed.taskId)
+      write(res, 'error', (err as Error).message)
+      write(res, 'exit', { code: null, signal: null })
+      res.end()
+      return
+    }
+
+    let killed = false
+    // Signal the whole process group on POSIX (the child was spawned detached,
+    // i.e. as a group leader) so grandchildren the agent forked die with it.
+    // Falls back to the direct child.kill when there's no pid (spawn-time
+    // failure), when the group is already gone (ESRCH), and always on win32.
+    function killGroup(sig: NodeJS.Signals) {
+      if (process.platform !== 'win32' && typeof child.pid === 'number') {
+        try { process.kill(-child.pid, sig); return } catch { /* ESRCH/EPERM — fall through */ }
+      }
+      try { child.kill(sig) } catch { /* ignore */ }
+    }
+    function killChild() {
+      if (killed) return
+      killed = true
+      killGroup('SIGTERM')
+      setTimeout(() => { killGroup('SIGKILL') }, KILL_GRACE_MS).unref()
+    }
+    active.set(runId, { child, kill: killChild, taskId: parsed.taskId })
+
+    // Pipe stdin if provided. Attach the async error listener BEFORE writing:
+    // a child that closes its read end early emits an *asynchronous* EPIPE that
+    // the synchronous try/catch can't catch — left unhandled it throws and
+    // crashes the whole dev server, taking down every other in-flight run.
+    // Ending stdin in the write callback avoids ending mid-flush.
+    child.stdin.on('error', (err) => {
+      write(res, 'error', `stdin write failed: ${(err as Error).message}`)
+    })
+    if (parsed.stdin) {
+      child.stdin.write(parsed.stdin, () => {
+        try { child.stdin.end() } catch { /* ignore */ }
+      })
+    } else {
+      try { child.stdin.end() } catch { /* ignore */ }
+    }
+
+    // Keepalive ping so reverse proxies don't 504 on idle CLI startup.
+    const keepalive = setInterval(() => {
+      try { res.write(': keepalive\n\n') } catch { /* socket closed */ }
+    }, KEEPALIVE_INTERVAL_MS)
+    keepalive.unref()
+
+    // Abort on client disconnect. Belt-and-suspenders: some proxies close
+    // the response socket rather than the request, so we listen on both.
+    req.on('close', () => { killChild() })
+    res.on('close', () => { killChild() })
+
+    // Absolute duration backstop — kill a child that outlives the ceiling
+    // (e.g. its client died without closing the socket). Cleared on close.
+    const maxDuration = setTimeout(() => {
+      write(res, 'error', `Run exceeded the ${Math.round(MAX_SPAWN_DURATION_MS / 60_000)}-minute server limit; terminating.`)
+      killChild()
+    }, MAX_SPAWN_DURATION_MS)
+    maxDuration.unref()
+
+    // Line-buffered stdout — one SSE event per line. Same for stderr but we
+    // also accumulate the last MAX_STDERR_BUFFER_BYTES of stderr so we can
+    // surface it on a non-zero exit.
+    let stdoutBuf = ''
+    let stderrBuf = ''
+    let stderrTotal = ''
+
+    function pumpLines(buf: string, event: 'stdout' | 'stderr', total?: { append: (s: string) => void }) {
+      let nl
+      while ((nl = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, nl).replace(/\r$/, '')
+        buf = buf.slice(nl + 1)
+        if (total) total.append(line + '\n')
+        write(res, event, line)
+      }
+      return buf
+    }
+
+    child.stdout.setEncoding('utf-8')
+    child.stdout.on('data', (chunk: string) => {
+      stdoutBuf += chunk
+      if (stdoutBuf.length > MAX_BUFFERED_LINE_BYTES) {
+        // A single line longer than the cap — flush it and drop the rest.
+        write(res, 'stdout', stdoutBuf.slice(0, MAX_BUFFERED_LINE_BYTES))
+        stdoutBuf = ''
+        return
+      }
+      stdoutBuf = pumpLines(stdoutBuf, 'stdout')
+    })
+
+    child.stderr.setEncoding('utf-8')
+    child.stderr.on('data', (chunk: string) => {
+      stderrBuf += chunk
+      if (stderrBuf.length > MAX_BUFFERED_LINE_BYTES) {
+        write(res, 'stderr', stderrBuf.slice(0, MAX_BUFFERED_LINE_BYTES))
+        stderrBuf = ''
+        return
+      }
+      stderrBuf = pumpLines(stderrBuf, 'stderr', {
+        append: (s) => {
+          if (stderrTotal.length < MAX_STDERR_BUFFER_BYTES) {
+            stderrTotal += s.slice(0, MAX_STDERR_BUFFER_BYTES - stderrTotal.length)
+          }
+        },
+      })
+    })
+
+    await new Promise<void>((resolve) => {
+      let resolved = false
+      const finish = () => { if (!resolved) { resolved = true; resolve() } }
+
+      child.on('error', (err) => {
+        write(res, 'error', err.message)
+        finish()
+      })
+      child.on('close', (code, signal) => {
+        // Flush trailing stdout/stderr (no terminating newline).
+        if (stdoutBuf.length > 0) write(res, 'stdout', stdoutBuf)
+        if (stderrBuf.length > 0) write(res, 'stderr', stderrBuf)
+        write(res, 'exit', { code, signal: signal ?? null })
+        finish()
+      })
+    })
+
+    clearInterval(keepalive)
+    clearTimeout(maxDuration)
+    active.delete(runId)
+    if (parsed.taskId && byTask.get(parsed.taskId) === runId) byTask.delete(parsed.taskId)
+    try { res.end() } catch { /* already ended */ }
+    // Report the run end so a task the client never finalized (orphaned by a
+    // closed tab) can be reconciled server-side. Fired for normal completions
+    // too — the handler grace-checks status, so those no-op.
+    if (parsed.taskId) {
+      try { opts.onRunEnd?.(parsed.taskId, { killed }) } catch { /* never let a sink break cleanup */ }
+    }
+  }
+
+  return {
+    registry: { abort, killAll, size: () => active.size, taskRunning: (taskId) => byTask.has(taskId) },
+    handleSpawn,
+  }
+}
+
+/** Write one SSE event. JSON-stringifies object data; passes strings through. */
+function write(res: ServerResponse, event: string, data: unknown): void {
+  const payload = typeof data === 'string' ? data : JSON.stringify(data)
+  // SSE: events with multi-line payloads must repeat the `data:` prefix.
+  const lines = payload.split('\n')
+  let frame = `event: ${event}\n`
+  for (const line of lines) frame += `data: ${line}\n`
+  frame += '\n'
+  try { res.write(frame) } catch { /* socket may be closed */ }
+}
+
+/** Exposed for tests. */
+export const __test = { ALLOWED_CLIS, SAFE_ENV_KEYS }
diff --git a/src/server/api-schema-scanner.ts b/src/server/api-schema-scanner.ts
index 2c659ff..79b2ec8 100644
--- a/src/server/api-schema-scanner.ts
+++ b/src/server/api-schema-scanner.ts
@@ -161,13 +161,18 @@ async function scanUncached(projectRoot: string, opts: ScanOptions): Promise<Api
   }
   const hasExplicit = (opts.apiSchemaFiles?.length ?? 0) + (opts.apiSchemaUrls?.length ?? 0) > 0
 
-  // 2. Filesystem auto-discovery — walk the whole workspace so schemas under
-  //    sibling MFEs or a top-level services/ dir are picked up.
+  // 2. Filesystem auto-discovery — scope to the RUNNING package, not the whole
+  //    workspace. Walking ws.root surfaced sibling apps' schema files (a Vue app
+  //    showed unrelated go-api / rust-api openapi.json from other playgrounds) —
+  //    the same over-reach fixed in the component + data-source scanners. The
+  //    running app's real backend is still discovered at RUNTIME via the
+  //    dev-server + docker-compose probes below, so a monorepo's shared
+  //    services/ backend still "just works" without reading sibling files.
   if (!hasExplicit) {
     const files: string[] = []
-    await walk(ws.root, files, ws.root)
+    await walk(projectRoot, files, projectRoot)
     for (const fp of files) {
-      const parsed = await tryParseFile(ws.root, nodePath.relative(ws.root, fp))
+      const parsed = await tryParseFile(projectRoot, nodePath.relative(projectRoot, fp))
       if (parsed) {
         // Dedupe by location
         if (!schemas.some(s => s.location === parsed.location)) schemas.push(parsed)
diff --git a/src/server/api.ts b/src/server/api.ts
index ed16bb5..eb567f9 100644
--- a/src/server/api.ts
+++ b/src/server/api.ts
@@ -7,11 +7,26 @@ import {
   CreateTaskBody,
   UpdateTaskBody,
   UploadScreenshotBody,
+  UploadWireframeSnapshotBody,
   parseWith,
   assertTransition,
 } from './schemas.js'
 import { mergeRuntimeOrphansIntoEntries, findMatchingStaticEntries } from './runtime-endpoints.js'
 import type { NetworkCall, RuntimeEndpoint, RuntimeEndpointCatalog } from '../schema.js'
+import type { TaskThreadStore, ThreadMessage, ThreadRole, UpdateInput } from './task-thread.js'
+import type { WorkStreamBlock } from '../shared/work-stream.js'
+import type { AgentSpawnHandler } from './agent-spawn.js'
+import type { AgentDetector } from './agent-detect.js'
+import type { InitRunner, ScanOptions } from './init.js'
+import type { UsageLedger } from './usage-ledger.js'
+import type { AgentConfigs, AgentConfigEntry } from './agent-configs.js'
+import { isWireframeDocument, WIREFRAME_SNAPSHOT_FILENAME_RE, type WireframeDocument } from '../shared/wireframe-types.js'
+import { WireframeRevConflictError } from './wireframe-store.js'
+import { isDesignSessionDocument, type DesignSessionDocument } from '../shared/design-session-types.js'
+import { RevConflictError } from './json-cas-store.js'
+import type { SnapshotStore } from './file-snapshots.js'
+import { applyDesignSession, verifyAppliedEntries, revertApplyBatch, releaseApplyTask, acceptApplyTask, restampApplyEntries, closeWireframeLifecycle } from './apply-session.js'
+import { PROVIDER_IDS, EFFORT_LEVELS } from '../embedded/provider-config.js'
 
 export interface APIOptions {
   projectRoot: string
@@ -19,11 +34,22 @@ export interface APIOptions {
   apiSchemaUrls?: string[]
   /** Extra project-relative schema file paths. */
   apiSchemaFiles?: string[]
+  /**
+   * Hostnames allowed in the Host header beyond localhost / IP literals —
+   * DNS-rebinding gate (see `isAllowedHost`). A function because the bind
+   * host is only known after the dev server starts listening, which is after
+   * this middleware is constructed.
+   */
+  allowedHosts?: () => readonly string[]
   getReport: () => unknown
   getConfig: () => unknown
   getDesignSpec: () => unknown
   getTasks: () => { version: string; tasks: Array<Record<string, unknown>> }
-  updateTask: (id: string, updates: Record<string, unknown>) => unknown | Promise<unknown>
+  updateTask: (
+    id: string,
+    updates: Record<string, unknown>,
+    opts?: { guard?: (task: Record<string, unknown>) => string | null },
+  ) => unknown | Promise<unknown>
   deleteTask: (id: string) => unknown | Promise<unknown>
   addTask: (task: Record<string, unknown>) => unknown | Promise<unknown>
   saveInteractionHistory: (taskId: string, snapshot: unknown) => Promise<void>
@@ -38,6 +64,34 @@ export interface APIOptions {
   getRuntimeEndpointCatalog: () => RuntimeEndpointCatalog
   /** Drop the runtime endpoint catalog. */
   clearRuntimeEndpoints: () => void
+  /** Per-task conversation transcript store (chat messages). */
+  taskThread: TaskThreadStore
+  /** Spawns local CLIs (claude/codex/opencode/copilot) and streams their output. */
+  agentSpawn: AgentSpawnHandler
+  /** Probes for installed/logged-in local CLIs. */
+  agentDetect: AgentDetector
+  /** Drives the in-UI initialization pipeline. */
+  initRunner: InitRunner
+  /** Reads per-persona project directions from `.annotask/agents.json`. */
+  getAgentConfigs: () => Promise<AgentConfigs>
+  /** Writes one persona's project directions. */
+  setAgentConfig: (personaId: string, entry: Partial<AgentConfigEntry>) => Promise<AgentConfigs>
+  /** Reads the persisted multi-route wireframe document. */
+  getWireframe: () => Promise<WireframeDocument>
+  /** Replaces the wireframe document (whole-document PUT). */
+  setWireframe: (doc: WireframeDocument) => Promise<WireframeDocument>
+  /** Reads the persisted design-session journal. */
+  getDesignSession: () => Promise<DesignSessionDocument>
+  /** Replaces the design-session journal (CAS on rev). */
+  setDesignSession: (doc: DesignSessionDocument) => Promise<DesignSessionDocument>
+  /** Server-owned reset to a fresh empty session (discard). */
+  clearDesignSession: () => Promise<DesignSessionDocument>
+  /** File-snapshot engine — byte-exact undo/discard under the agent-apply loop. */
+  snapshots: SnapshotStore
+  /** Append-only token-usage ledger across init / task / apply runs. */
+  usageLedger: UsageLedger
+  /** Health of the tasks.json write path — surfaced via GET /api/status. */
+  getPersistenceHealth?: () => { ok: boolean; consecutiveFailures: number; lastError: string | null }
 }
 
 const MAX_BODY_SIZE = 4_194_304
@@ -60,6 +114,22 @@ function parseJSON(raw: string): { ok: true; data: unknown } | { ok: false } {
   try { return { ok: true, data: JSON.parse(raw) } } catch { return { ok: false } }
 }
 
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+/**
+ * Decode a `data:image/png;base64,…` URL into a buffer, verifying the PNG
+ * signature — Buffer.from() tolerates malformed base64 (it pads/drops bytes),
+ * so a bare regex match isn't enough to keep garbage out of the .png files
+ * we serve back to the shell.
+ */
+function decodePngDataUrl(dataUrl: string): Buffer | null {
+  const match = dataUrl.match(/^data:image\/png;base64,(.+)$/)
+  if (!match) return null
+  const buffer = Buffer.from(match[1], 'base64')
+  if (buffer.length < PNG_SIGNATURE.length || !buffer.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) return null
+  return buffer
+}
+
 /**
  * Error-response codes. Clients key off `error.code` to localize or react programmatically;
  * `error.message` is for human display and debugging.
@@ -71,8 +141,13 @@ export type ApiErrorCode =
   | 'validation_failed'
   | 'invalid_transition'
   | 'forbidden_origin'
+  | 'forbidden_host'
+  | 'origin_port_mismatch'
   | 'not_found'
   | 'missing_field'
+  | 'invalid_id'
+  | 'invalid_body'
+  | 'conflict'
 
 export interface ApiErrorBody {
   error: { code: ApiErrorCode; message: string }
@@ -84,22 +159,26 @@ function sendError(res: ServerResponse, status: number, message: string, code: A
   res.end(JSON.stringify(body))
 }
 
-import { isLocalOrigin } from './origin.js'
-import { scanComponentLibraries } from './component-scanner.js'
+import { isAllowedHost, isLocalOrigin, originMatchesPort } from './origin.js'
+import { scanComponentLibraries, scanProjectComponents } from './component-scanner.js'
 import { filterTasksByMfe } from '../shared/task-summary.js'
 import { getCodeContext } from './code-context.js'
+import { classifyBindings } from './binding-classify.js'
 import { getComponentExamples } from './component-examples.js'
 import { scanComponentUsage } from './component-usage.js'
 import { probeDataContext, resolveDataContext, resolveElementDataContext } from './data-context.js'
 import { scanDataSources } from './data-source-scanner.js'
 import { getDataSourceExamples } from './data-source-examples.js'
 import { resolveDataSourceDetails } from './data-source-details.js'
+import { resolveDataSourceShape } from './data-source-shape.js'
 import { resolveBindingGraph } from './binding-analysis/index.js'
 import { scanApiSchemas } from './api-schema-scanner.js'
 import { getWorkspaceCatalog } from './workspace-catalog.js'
 import { resolveEndpoint } from './api-schema-resolver.js'
 import { resolveWorkspace } from './workspace.js'
-import type { DataSource } from '../schema.js'
+import { getSystemPrompt } from '../skills/index.js'
+import { TASK_TYPES, type DataSource } from '../schema.js'
+import { listAgentModels, type ProvideredId } from './agent-models.js'
 
 /**
  * Look up the monorepo root (pnpm-workspace.yaml / npm `workspaces` / lerna.json)
@@ -137,8 +216,45 @@ function deriveDevServerUrl(req: IncomingMessage): string | undefined {
   return `${proto}://${host}`
 }
 
+/** Extract the port number from the Host header (e.g. "localhost:5173" → 5173). */
+function deriveServerPort(req: IncomingMessage): number | undefined {
+  const host = typeof req.headers.host === 'string' ? req.headers.host : ''
+  if (!host) return undefined
+  const colonIdx = host.lastIndexOf(':')
+  if (colonIdx === -1) return undefined
+  const p = parseInt(host.slice(colonIdx + 1), 10)
+  return Number.isFinite(p) ? p : undefined
+}
+
+/**
+ * Server-side wireframe lifecycle closure. When a `wireframe_apply` task is
+ * ACCEPTED its placements are done — remove them from wireframe.json so the
+ * shell never re-mounts a wireframe copy next to the agent's real component.
+ * When the task is DELETED the work was abandoned — revert its instances to
+ * 'placed' (and clear `taskId`) so the user can rebuild them. (A DENIED task
+ * keeps 'building': the agent retries the same task.)
+ *
+ * Best-effort by design: the task mutation has already committed, so a
+ * wireframe failure must not fail the response. CAS conflicts (another tab
+ * writing concurrently) retry the read-modify-write a few times; the worst
+ * case after exhausting retries is a stale placement the user can delete from
+ * the placements panel. `setWireframe` broadcasts `wireframe:updated`, so live
+ * shells re-load without polling.
+ */
 export function createAPIMiddleware(options: APIOptions) {
   return async (req: IncomingMessage, res: ServerResponse, next: () => void) => {
+    // DNS-rebinding gate — runs FIRST, for ALL methods. The Origin checks
+    // below only cover mutating requests; without a Host check a rebound page
+    // can read every GET endpoint (read-file, source excerpts, tasks,
+    // screenshots, transcripts). Vite's own allowedHosts middleware never
+    // sees /__annotask/* because Annotask registers ahead of it, so this is
+    // the only host gate these routes get. Covers the screenshot route too
+    // (it lives in this middleware, above the /api/ prefix check).
+    if (req.url?.startsWith('/__annotask/') && !isAllowedHost(req.headers.host, options.allowedHosts?.() ?? [])) {
+      res.setHeader('Content-Type', 'application/json')
+      return sendError(res, 403, 'Forbidden: host not allowed (see ANNOTASK_ALLOWED_HOSTS)', 'forbidden_host')
+    }
+
     // Serve screenshots (outside /api/ path)
     if (req.url?.startsWith('/__annotask/screenshots/') && req.method === 'GET') {
       const filename = (req.url.replace('/__annotask/screenshots/', '')).replace(/\?.*$/, '')
@@ -163,6 +279,31 @@ export function createAPIMiddleware(options: APIOptions) {
       return
     }
 
+    // Serve wireframe canvas snapshots (outside /api/ path) — same containment
+    // discipline as screenshots; filenames are shell-minted ids, never paths.
+    if (req.url?.startsWith('/__annotask/wireframe-snapshots/') && req.method === 'GET') {
+      const filename = (req.url.replace('/__annotask/wireframe-snapshots/', '')).replace(/\?.*$/, '')
+      if (!WIREFRAME_SNAPSHOT_FILENAME_RE.test(filename)) {
+        res.statusCode = 400; res.end('Invalid filename'); return
+      }
+      const snapshotsDir = nodePath.resolve(options.projectRoot, '.annotask', 'wireframe-snapshots')
+      const filePath = nodePath.resolve(snapshotsDir, filename)
+      if (!filePath.startsWith(snapshotsDir + nodePath.sep)) {
+        res.statusCode = 403; res.end('Forbidden'); return
+      }
+      try {
+        const data = await fsp.readFile(filePath)
+        res.setHeader('Content-Type', 'image/png')
+        res.setHeader('Cache-Control', 'private, max-age=3600')
+        const corsOrigin = getCorsOrigin(req)
+        if (corsOrigin) res.setHeader('Access-Control-Allow-Origin', corsOrigin)
+        res.end(data)
+      } catch {
+        res.statusCode = 404; res.end('Not found')
+      }
+      return
+    }
+
     if (!req.url?.startsWith('/__annotask/api/')) return next()
 
     const pathWithQuery = req.url.replace('/__annotask/api/', '')
@@ -227,6 +368,407 @@ export function createAPIMiddleware(options: APIOptions) {
       return
     }
 
+    // System prompt for the embedded agent. Composes the base `annotask-apply`
+    // skill body with the optional task-type companion (A11Y_RULES.md, etc.)
+    // so the in-shell runner gets the same prompt external editors see via
+    // MCP `initialize.instructions`, plus per-task-type guidance.
+    if (path === 'system-prompt' && req.method === 'GET') {
+      const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
+      const taskType = urlObj.searchParams.get('task_type') || undefined
+      if (taskType && !(TASK_TYPES as readonly string[]).includes(taskType)) {
+        return sendError(res, 400, `Unknown task type: ${taskType}`)
+      }
+      let prompt = ''
+      try {
+        prompt = getSystemPrompt({ taskType })
+      } catch {
+        // Bundled skills missing — return an empty prompt so the runner can
+        // fall back to its built-in placeholder rather than 500.
+        prompt = ''
+      }
+      res.end(JSON.stringify({ prompt, taskType: taskType ?? null }, null, 2))
+      return
+    }
+
+    // Project-wide token usage summary. GET /usage → aggregate totals,
+    // per-scope (task/init/apply/chat), and per-provider tallies. The Providers
+    // settings panel reads this to show cumulative spend, complementing the
+    // per-conversation budget cap.
+    if (path === 'usage' && req.method === 'GET') {
+      const summary = await options.usageLedger.summary()
+      res.end(JSON.stringify(summary, null, 2))
+      return
+    }
+    // GET /usage/recent?limit=N → most recent entries, newest first. Used by
+    // the activity log in Settings.
+    if (path === 'usage/recent' && req.method === 'GET') {
+      const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
+      const rawLimit = urlObj.searchParams.get('limit')
+      const parsedLimit = rawLimit ? Number(rawLimit) : 50
+      const limit = Number.isFinite(parsedLimit) && parsedLimit > 0
+        ? Math.min(500, Math.floor(parsedLimit))
+        : 50
+      const entries = await options.usageLedger.recent(limit)
+      res.end(JSON.stringify({ entries }, null, 2))
+      return
+    }
+
+    if (path === 'init/state' && req.method === 'GET') {
+      res.end(JSON.stringify(options.initRunner.getState(), null, 2))
+      return
+    }
+
+    // Per-scan-target metadata for the wizard's Re-scan UI. Only the two
+    // durable artifacts (design-spec.json — covers tokens/themes/framework
+    // produced from the components, data-source, and api-schema scans —
+    // and agents.json) are reported, so users can see when each was last
+    // written before picking which scanners to re-run.
+    if (path === 'init/scan-targets' && req.method === 'GET') {
+      const targets: Array<{ id: 'designSpec' | 'agentConfigs'; file: string }> = [
+        { id: 'designSpec',   file: 'design-spec.json' },
+        { id: 'agentConfigs', file: 'agents.json' },
+      ]
+      const out: Record<string, { exists: boolean; mtime: number | null }> = {}
+      for (const t of targets) {
+        const fp = nodePath.join(options.projectRoot, '.annotask', t.file)
+        try {
+          const stat = await fsp.stat(fp)
+          out[t.id] = { exists: true, mtime: stat.mtimeMs }
+        } catch {
+          out[t.id] = { exists: false, mtime: null }
+        }
+      }
+      res.end(JSON.stringify(out, null, 2))
+      return
+    }
+
+    if (path === 'init/start' && req.method === 'POST') {
+      let scanOptions: ScanOptions = {}
+      try {
+        const raw = await readBody(req)
+        if (raw.trim()) {
+          const parsed = parseJSON(raw)
+          if (parsed.ok && parsed.data && typeof parsed.data === 'object' && !Array.isArray(parsed.data)) {
+            const b = parsed.data as Record<string, unknown>
+            scanOptions = {
+              skipAgentScan: b.skipAgentScan === true,
+              skipAgentConfigs: b.skipAgentConfigs === true,
+              skipComponents: b.skipComponents === true,
+              skipDataSources: b.skipDataSources === true,
+              skipApiSchemas: b.skipApiSchemas === true,
+              requestedProviderId: typeof b.requestedProviderId === 'string' && (PROVIDER_IDS as readonly string[]).includes(b.requestedProviderId)
+                ? b.requestedProviderId as ScanOptions['requestedProviderId']
+                : undefined,
+              requestedModel: typeof b.requestedModel === 'string' ? b.requestedModel : undefined,
+              requestedEffort: typeof b.requestedEffort === 'string' && (EFFORT_LEVELS as readonly string[]).includes(b.requestedEffort)
+                ? b.requestedEffort as ScanOptions['requestedEffort']
+                : undefined,
+            }
+          }
+        }
+      } catch { /* no body is fine */ }
+      const state = options.initRunner.start(scanOptions)
+      res.end(JSON.stringify(state, null, 2))
+      return
+    }
+
+    if (path === 'init/cancel' && req.method === 'POST') {
+      options.initRunner.cancel()
+      res.end(JSON.stringify(options.initRunner.getState(), null, 2))
+      return
+    }
+
+    // Mark as initialized without committing token data — used when the user
+    // prefers to run the annotask-init skill in their editor agent instead.
+    if (path === 'init/skip' && req.method === 'POST') {
+      const state = await options.initRunner.skip()
+      res.end(JSON.stringify(state, null, 2))
+      return
+    }
+
+    if (path === 'init/commit' && req.method === 'POST') {
+      let raw: string
+      try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+      let body: Record<string, unknown> = {}
+      if (raw.trim().length > 0) {
+        const parsed = parseJSON(raw)
+        if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+        if (!parsed.data || typeof parsed.data !== 'object' || Array.isArray(parsed.data)) {
+          return sendError(res, 400, 'Request body must be a JSON object', 'body_not_object')
+        }
+        body = parsed.data as Record<string, unknown>
+      }
+      const commitBody = {
+        spec: typeof body.spec === 'object' && body.spec !== null && !Array.isArray(body.spec)
+          ? body.spec as Record<string, unknown>
+          : undefined,
+        styleGuide: typeof body.styleGuide === 'string' ? body.styleGuide : undefined,
+        overwriteStyleGuide: body.overwriteStyleGuide === true,
+      }
+      const state = await options.initRunner.commit(commitBody)
+      if (state.result === 'error') {
+        return sendError(res, 400, state.error ?? 'Commit failed')
+      }
+      res.end(JSON.stringify(state, null, 2))
+      return
+    }
+
+    // Per-persona project directions written by the init agent and editable in Settings.
+    if (path === 'agent-configs' && req.method === 'GET') {
+      const configs = await options.getAgentConfigs()
+      res.end(JSON.stringify(configs, null, 2))
+      return
+    }
+
+    {
+      const m = path.match(/^agent-configs\/([^/]+)$/)
+      if (m && req.method === 'PATCH') {
+        const personaId = decodeURIComponent(m[1])
+        if (!/^[a-z0-9-]+$/.test(personaId)) return sendError(res, 400, 'Invalid persona id', 'invalid_id')
+        let raw: string
+        try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+        const parsed = parseJSON(raw)
+        if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+        if (!parsed.data || typeof parsed.data !== 'object' || Array.isArray(parsed.data)) {
+          return sendError(res, 400, 'Request body must be a JSON object', 'body_not_object')
+        }
+        const b = parsed.data as Record<string, unknown>
+        const entry: Partial<AgentConfigEntry> = {}
+        if ('projectDirections' in b) {
+          if (typeof b.projectDirections !== 'string') {
+            return sendError(res, 400, 'Invalid projectDirections field', 'invalid_body')
+          }
+          entry.projectDirections = b.projectDirections
+        }
+        if ('providerId' in b) {
+          if (typeof b.providerId !== 'string' || !(PROVIDER_IDS as readonly string[]).includes(b.providerId)) {
+            return sendError(res, 400, 'Invalid providerId', 'invalid_body')
+          }
+          entry.providerId = b.providerId as AgentConfigEntry['providerId']
+        }
+        if ('model' in b) {
+          if (typeof b.model !== 'string') {
+            return sendError(res, 400, 'Invalid model field', 'invalid_body')
+          }
+          entry.model = b.model
+        }
+        if ('effort' in b) {
+          if (typeof b.effort !== 'string' || !(EFFORT_LEVELS as readonly string[]).includes(b.effort)) {
+            return sendError(res, 400, 'Invalid effort', 'invalid_body')
+          }
+          entry.effort = b.effort as AgentConfigEntry['effort']
+        }
+        if (Object.keys(entry).length === 0) {
+          return sendError(res, 400, 'Body must include at least one of projectDirections, providerId, model, effort', 'invalid_body')
+        }
+        const result = await options.setAgentConfig(personaId, entry)
+        res.end(JSON.stringify(result, null, 2))
+        return
+      }
+    }
+
+    // ── Wireframe document (.annotask/wireframe.json) ──
+    // GET returns the whole multi-route doc, or just one route's slice with
+    // `?route=PATH`. PUT replaces the whole document (the shell owns the
+    // in-memory merge and PUTs the full doc — small, single-writer file).
+    if (path === 'wireframe' && req.method === 'GET') {
+      const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
+      const route = urlObj.searchParams.get('route')
+      const doc = await options.getWireframe()
+      if (route) {
+        res.end(JSON.stringify({ ...doc, routes: doc.routes.filter(r => r.route === route) }, null, 2))
+        return
+      }
+      res.end(JSON.stringify(doc, null, 2))
+      return
+    }
+
+    if (path === 'wireframe' && req.method === 'PUT') {
+      let raw: string
+      try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+      const parsed = parseJSON(raw)
+      if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+      if (!parsed.data || typeof parsed.data !== 'object' || Array.isArray(parsed.data)) {
+        return sendError(res, 400, 'Request body must be a JSON object', 'body_not_object')
+      }
+      if (!isWireframeDocument(parsed.data)) {
+        return sendError(res, 400, 'Body must be a wireframe document { version: "1.0", updatedAt, routes[] } with well-formed instances', 'validation_failed')
+      }
+      try {
+        const saved = await options.setWireframe(parsed.data)
+        res.end(JSON.stringify(saved, null, 2))
+      } catch (err) {
+        // Stale/missing rev — another writer (tab, accept hook) committed
+        // first. The client must re-GET and merge; never auto-retry the write.
+        if (err instanceof WireframeRevConflictError) {
+          return sendError(res, 409, err.message, 'conflict')
+        }
+        throw err
+      }
+      return
+    }
+
+    // ── Design-session journal (.annotask/design-session.json) ──
+    // The ordered record of what the user did in the design tool. The shell
+    // owns the in-memory journal and PUTs the whole document (CAS on rev, like
+    // the wireframe doc). DELETE is the server-owned "discard session": it also
+    // removes the session's wireframe placements so a discard from any tab —
+    // even a fresh one after a crash — fully unwinds the session.
+    if (path === 'design-session' && req.method === 'GET') {
+      const doc = await options.getDesignSession()
+      res.end(JSON.stringify(doc, null, 2))
+      return
+    }
+
+    if (path === 'design-session' && req.method === 'PUT') {
+      let raw: string
+      try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+      const parsed = parseJSON(raw)
+      if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+      if (!parsed.data || typeof parsed.data !== 'object' || Array.isArray(parsed.data)) {
+        return sendError(res, 400, 'Request body must be a JSON object', 'body_not_object')
+      }
+      if (!isDesignSessionDocument(parsed.data)) {
+        return sendError(res, 400, 'Body must be a design-session document { version: "1.0", sessionId, startedAt, updatedAt, entries[] } with well-formed entries', 'validation_failed')
+      }
+      try {
+        const saved = await options.setDesignSession(parsed.data)
+        res.end(JSON.stringify(saved, null, 2))
+      } catch (err) {
+        if (err instanceof RevConflictError) {
+          return sendError(res, 409, err.message, 'conflict')
+        }
+        throw err
+      }
+      return
+    }
+
+    if (path === 'design-session' && req.method === 'DELETE') {
+      // Never discard over a live, unsealed apply — reverting its files would
+      // clobber the agent's in-progress bytes (no hash guard yet). The shell
+      // disables Discard while a run is in flight; this backstops other callers.
+      const snap = await options.snapshots.state()
+      if (snap.batches.some((b) => b.status === 'running')) {
+        return sendError(res, 409, 'An apply is still running — wait for it to finish before discarding', 'conflict')
+      }
+      const doc = await options.getDesignSession()
+      const instanceIds = new Set(doc.entries.map((e) => e.instanceId).filter((id): id is string => typeof id === 'string'))
+      let removedInstances = 0
+      // Discard is a full session reset: the session's placements AND every
+      // route's wireframe-canvas sketch go — same retry discipline as
+      // closeWireframeLifecycle (best-effort, CAS-retried).
+      const snapshotFiles: string[] = []
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const wf = await options.getWireframe()
+        let touched = false
+        let removed = 0
+        const routes = wf.routes.map((route) => {
+          const hasInstances = route.instances.some((i) => instanceIds.has(i.id))
+          if (!hasInstances && !route.canvas) return route
+          touched = true
+          const instances = route.instances.filter((i) => {
+            if (instanceIds.has(i.id)) { removed++; return false }
+            return true
+          })
+          if (route.canvas) {
+            for (const b of route.canvas.blocks) if (b.image) snapshotFiles.push(b.image)
+            if (route.canvas.fullImage) snapshotFiles.push(route.canvas.fullImage)
+          }
+          return { ...route, instances, canvas: undefined, updatedAt: Date.now() }
+        })
+        if (!touched) break
+        try {
+          await options.setWireframe({ ...wf, routes, updatedAt: Date.now() })
+          removedInstances = removed
+          break
+        } catch (err) {
+          snapshotFiles.length = 0
+          if (!(err instanceof WireframeRevConflictError)) {
+            console.warn('[Annotask] design-session discard: wireframe cleanup failed:', err)
+            break
+          }
+        }
+      }
+      // Snapshot PNGs are sketch material — drop them with the sketches.
+      const snapshotsDir = nodePath.resolve(options.projectRoot, '.annotask', 'wireframe-snapshots')
+      for (const f of new Set(snapshotFiles)) {
+        if (!WIREFRAME_SNAPSHOT_FILENAME_RE.test(f)) continue
+        const p = nodePath.resolve(snapshotsDir, f)
+        if (!p.startsWith(snapshotsDir + nodePath.sep)) continue
+        fsp.unlink(p).catch(() => { /* already gone */ })
+      }
+      // Restore every snapshot-tracked file to its session-base bytes
+      // (hash-guarded — files the user edited outside Annotask are skipped
+      // and reported, never clobbered).
+      let revertedFiles: string[] = []
+      let failedFiles: string[] = []
+      try {
+        const result = await options.snapshots.revertAll()
+        revertedFiles = result.reverted
+        failedFiles = result.skipped
+      } catch (err) {
+        console.warn('[Annotask] design-session discard: snapshot restore failed:', err)
+      }
+      await options.clearDesignSession()
+      res.end(JSON.stringify({ revertedFiles, failedFiles, removedInstances }, null, 2))
+      return
+    }
+
+    // ── Agent-apply loop ──
+    // "Apply now": snapshot the touched files, create ONE wireframe_apply task
+    // (context.wireframe placements + context.session panel edits), stamp
+    // statuses. The shell then drives the embedded agent on the returned task
+    // through the existing spawn pipeline; the PATCH→review hook below runs
+    // the verification pass and seals the batch.
+    if (path === 'design-session/apply' && req.method === 'POST') {
+      let raw: string
+      try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+      const parsed = parseJSON(raw)
+      if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+      const b = (parsed.data && typeof parsed.data === 'object' && !Array.isArray(parsed.data)) ? parsed.data as Record<string, unknown> : null
+      if (!b || typeof b.route !== 'string') return sendError(res, 400, 'Body must include route', 'invalid_body')
+      // Optional before/after composite — already uploaded via /screenshots;
+      // only a safe filename rides through to the task.
+      const screenshot = typeof b.screenshot === 'string' && isSafeScreenshot(b.screenshot) ? b.screenshot : undefined
+      const result = await applyDesignSession(options, b.route, screenshot ? { screenshot } : undefined)
+      if ('error' in result) return sendError(res, 400, result.error, 'invalid_body')
+      res.end(JSON.stringify(result, null, 2))
+      return
+    }
+
+    if (path === 'design-session/undo-batch' && req.method === 'POST') {
+      let raw: string
+      try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+      const parsed = parseJSON(raw)
+      if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+      const b = (parsed.data && typeof parsed.data === 'object' && !Array.isArray(parsed.data)) ? parsed.data as Record<string, unknown> : null
+      if (!b || typeof b.batchId !== 'string') return sendError(res, 400, 'Body must include batchId', 'invalid_body')
+      try {
+        const result = await revertApplyBatch(options, b.batchId)
+        res.end(JSON.stringify(result, null, 2))
+      } catch (err) {
+        return sendError(res, 409, (err as Error).message, 'conflict')
+      }
+      return
+    }
+
+    if (path === 'design-session/detach-file' && req.method === 'POST') {
+      let raw: string
+      try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+      const parsed = parseJSON(raw)
+      if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+      const b = (parsed.data && typeof parsed.data === 'object' && !Array.isArray(parsed.data)) ? parsed.data as Record<string, unknown> : null
+      if (!b || typeof b.file !== 'string') return sendError(res, 400, 'Body must include file', 'invalid_body')
+      await options.snapshots.detachFile(b.file)
+      res.end(JSON.stringify(await options.snapshots.state(), null, 2))
+      return
+    }
+
+    if (path === 'design-session/snapshots' && req.method === 'GET') {
+      res.end(JSON.stringify(await options.snapshots.state(), null, 2))
+      return
+    }
+
     if (path === 'tasks' && req.method === 'GET') {
       const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
       const mfeFilter = urlObj.searchParams.get('mfe')
@@ -262,9 +804,8 @@ export function createAPIMiddleware(options: APIOptions) {
       if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
       const bodyResult = parseWith(UploadScreenshotBody, parsed.data)
       if (!bodyResult.ok) return sendError(res, 400, bodyResult.error)
-      const match = bodyResult.data.data.match(/^data:image\/png;base64,(.+)$/)
-      if (!match) return sendError(res, 400, 'Invalid PNG data URL')
-      const buffer = Buffer.from(match[1], 'base64')
+      const buffer = decodePngDataUrl(bodyResult.data.data)
+      if (!buffer) return sendError(res, 400, 'Invalid PNG data URL')
       if (buffer.length > 4 * 1024 * 1024) return sendError(res, 413, 'Screenshot too large (max 4MB)')
       const filename = `screenshot-${Date.now()}-${crypto.randomBytes(8).toString('hex')}.png`
       const dir = nodePath.join(options.projectRoot, '.annotask', 'screenshots')
@@ -274,7 +815,43 @@ export function createAPIMiddleware(options: APIOptions) {
       return
     }
 
-    if (path.startsWith('tasks/') && req.method === 'GET') {
+    // Wireframe canvas snapshot PNGs. Upload is id-addressed (the shell mints
+    // block ids and re-uploads under the same id on recapture); delete is
+    // best-effort cleanup when a palette/placeholder block is removed.
+    if (path === 'wireframe-snapshots' && req.method === 'POST') {
+      let raw: string
+      try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+      const parsed = parseJSON(raw)
+      if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+      const bodyResult = parseWith(UploadWireframeSnapshotBody, parsed.data)
+      if (!bodyResult.ok) return sendError(res, 400, bodyResult.error)
+      const buffer = decodePngDataUrl(bodyResult.data.data)
+      if (!buffer) return sendError(res, 400, 'Invalid PNG data URL')
+      if (buffer.length > 4 * 1024 * 1024) return sendError(res, 413, 'Snapshot too large (max 4MB)')
+      const filename = `${bodyResult.data.id}.png`
+      const dir = nodePath.join(options.projectRoot, '.annotask', 'wireframe-snapshots')
+      await fsp.mkdir(dir, { recursive: true })
+      await fsp.writeFile(nodePath.join(dir, filename), buffer)
+      res.end(JSON.stringify({ filename }))
+      return
+    }
+
+    if (path.startsWith('wireframe-snapshots/') && req.method === 'DELETE') {
+      const filename = decodeURIComponent(path.replace('wireframe-snapshots/', ''))
+      if (!WIREFRAME_SNAPSHOT_FILENAME_RE.test(filename)) return sendError(res, 400, 'Invalid filename')
+      const dir = nodePath.resolve(options.projectRoot, '.annotask', 'wireframe-snapshots')
+      const filePath = nodePath.resolve(dir, filename)
+      if (!filePath.startsWith(dir + nodePath.sep)) return sendError(res, 403, 'Forbidden')
+      try { await fsp.unlink(filePath) } catch { /* already gone */ }
+      res.end(JSON.stringify({ deleted: filename }))
+      return
+    }
+
+    // Bare task-by-id GET. Subpaths (`tasks/:id/messages`, `tasks/:id/interaction-history`, …)
+    // are handled by their own dedicated blocks farther down — this catchall
+    // would otherwise short-circuit them with a "task not found" 404 because
+    // it'd try to look up "task-XXX/messages" as a literal task id.
+    if (path.startsWith('tasks/') && !path.slice('tasks/'.length).includes('/') && req.method === 'GET') {
       const id = decodeURIComponent(path.replace('tasks/', ''))
       if (!id) return sendError(res, 400, 'Missing task id')
       const taskData = options.getTasks()
@@ -284,7 +861,7 @@ export function createAPIMiddleware(options: APIOptions) {
       return
     }
 
-    if (path.startsWith('tasks/') && req.method === 'PATCH') {
+    if (path.startsWith('tasks/') && !path.slice('tasks/'.length).includes('/') && req.method === 'PATCH') {
       const id = decodeURIComponent(path.replace('tasks/', ''))
       if (!id) return sendError(res, 400, 'Missing task id')
       let raw: string
@@ -297,27 +874,88 @@ export function createAPIMiddleware(options: APIOptions) {
       const result = parseWith(UpdateTaskBody, parsed.data)
       if (!result.ok) return sendError(res, 400, result.error)
       const updates = result.data
-      if (updates.status !== undefined) {
-        const currentTask = options.getTasks().tasks.find(t => t.id === id)
-        if (currentTask) {
-          const reason = assertTransition(currentTask.status, updates.status)
-          if (reason) return sendError(res, 400, reason, 'invalid_transition')
-        }
-      }
-      const updated = await options.updateTask(id, updates as Record<string, unknown>) as any
+      // Transition validity is asserted INSIDE the task lock (state.updateTask
+      // runs the guard against the task it actually loads under the mutex).
+      // Checking here against options.getTasks() would be a TOCTOU race: two
+      // concurrent PATCHes (e.g. both pending → in_progress) could each pass
+      // the pre-check before either commits, and both would lock the task.
+      const guard = updates.status !== undefined
+        ? (task: Record<string, unknown>) => assertTransition(task.status, updates.status)
+        : undefined
+      // Capture the type BEFORE updating — an accepted task is removed from
+      // the store by state.updateTask, so it can't be looked up afterwards.
+      const taskBefore = options.getTasks().tasks.find(t => t.id === id)
+      const updated = await options.updateTask(id, updates as Record<string, unknown>, guard ? { guard } : undefined) as any
       if (updated && typeof updated === 'object' && updated.error === 'Task not found') {
         return sendError(res, 404, 'Task not found', 'not_found')
       }
+      if (updated && typeof updated === 'object' && updated.error === 'Invalid transition') {
+        return sendError(res, 400, updated.reason ?? 'Invalid state transition', 'invalid_transition')
+      }
+      // Lifecycle closure: accepting a wireframe_apply task retires its
+      // placements so they never re-mount beside the now-real component, and
+      // commits the apply batch (bytes are the new baseline — snapshots drop,
+      // session entries clear, an emptied session rotates to a fresh id).
+      if (updates.status === 'accepted' && taskBefore?.type === 'wireframe_apply') {
+        await closeWireframeLifecycle(options, id, 'remove')
+        try {
+          const { rotated } = await acceptApplyTask(options, id)
+          if (rotated) await options.clearDesignSession()
+        } catch (err) { console.warn('[Annotask] apply accept closure failed:', err) }
+      }
+      // Agent-apply verification: the agent finished (review) — re-read the
+      // source per session entry, flip written|failed, seal the batch's
+      // post-apply hashes. Best-effort: the task mutation already committed.
+      if (updates.status === 'review' && taskBefore?.type === 'wireframe_apply') {
+        try { await verifyAppliedEntries(options, id) }
+        catch (err) { console.warn('[Annotask] apply verification failed:', err) }
+      }
+      // Exit from a live in_progress run that isn't →review (verify seals) or
+      // →accepted (commit). The batch MUST be sealed either way — a 'running'
+      // batch left unsealed wedges undo + discard + re-apply all at once.
+      //   pending/blocked: the run gave up (crash/abort/stall) — fully abandon:
+      //     release 'applying' entries back to pending AND unlock the canvas
+      //     (releaseApplyTask now does both), so the sketch is editable again.
+      //   denied/needs_info: keep the entries + canvas for a retry/resume, but
+      //     still seal so undo/discard work while the user decides.
+      if (taskBefore?.type === 'wireframe_apply' && taskBefore?.status === 'in_progress') {
+        if (updates.status === 'pending' || updates.status === 'blocked') {
+          try { await releaseApplyTask(options, id) }
+          catch (err) { console.warn('[Annotask] apply release failed:', err) }
+        } else if (updates.status === 'denied' || updates.status === 'needs_info') {
+          try { await options.snapshots.sealBatchByTask(id, { failed: true }) }
+          catch (err) { console.warn('[Annotask] apply seal failed:', err) }
+        }
+      }
+      // Retry / resume (denied|blocked|needs_info|review → in_progress) re-arms
+      // verification: entries written/failed on the first review return to
+      // 'applying' so the next review re-checks them instead of showing stale
+      // verdicts. No-op on a first run (entries are already 'applying').
+      if (updates.status === 'in_progress' && taskBefore?.type === 'wireframe_apply'
+        && taskBefore?.status !== 'pending') {
+        try { await restampApplyEntries(options, id) }
+        catch (err) { console.warn('[Annotask] apply re-stamp failed:', err) }
+      }
       res.end(JSON.stringify(updated, null, 2))
       return
     }
 
-    if (path.startsWith('tasks/') && req.method === 'DELETE') {
+    if (path.startsWith('tasks/') && !path.slice('tasks/'.length).includes('/') && req.method === 'DELETE') {
       const id = decodeURIComponent(path.replace('tasks/', ''))
+      // Capture the type BEFORE deleting — the record is gone afterwards.
+      const taskBefore = options.getTasks().tasks.find(t => t.id === id)
       const deleted = await options.deleteTask(id) as any
       if (deleted && typeof deleted === 'object' && deleted.error === 'Task not found') {
         return sendError(res, 404, 'Task not found', 'not_found')
       }
+      // Lifecycle closure: deleting a wireframe_apply task abandons the batch.
+      // releaseApplyTask seals the (possibly half-written) batch so it stays
+      // revertible, returns its session entries to 'pending', and reverts its
+      // placements to 'placed' + unlocks the canvas sketch for editing.
+      if (taskBefore?.type === 'wireframe_apply') {
+        try { await releaseApplyTask(options, id) }
+        catch (err) { console.warn('[Annotask] apply release failed:', err) }
+      }
       res.end(JSON.stringify(deleted, null, 2))
       return
     }
@@ -405,20 +1043,199 @@ export function createAPIMiddleware(options: APIOptions) {
       }
     }
 
+    // Embedded chat: per-task conversation thread.
+    // GET    /tasks/:id/messages              → full snapshot (optional ?after=<id>)
+    // POST   /tasks/:id/messages              → append; broadcasts to subscribers
+    // GET    /tasks/:id/messages/stream       → SSE; honours Last-Event-ID for resume
+    {
+      const m = path.match(/^tasks\/([^/]+)\/messages(\/stream)?$/)
+      if (m) {
+        const id = decodeURIComponent(m[1])
+        const isStream = !!m[2]
+        if (isStream && req.method === 'GET') {
+          await handleThreadStream(req, res, options.taskThread, id)
+          return
+        }
+        if (req.method === 'GET') {
+          const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
+          const afterId = urlObj.searchParams.get('after') || undefined
+          const msgs = await options.taskThread.read(id, { afterId })
+          res.end(JSON.stringify({ taskId: id, messages: msgs }, null, 2))
+          return
+        }
+        if (req.method === 'POST') {
+          let raw: string
+          try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+          const parsed = parseJSON(raw)
+          if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+          const validated = validateThreadAppend(parsed.data)
+          if (typeof validated === 'string') return sendError(res, 400, validated)
+          const msg = await options.taskThread.append(id, validated)
+          res.end(JSON.stringify(msg, null, 2))
+          return
+        }
+      }
+    }
+
+    // PATCH /tasks/:id/messages/:msgId → update a message in place. Used by
+    // the embedded agent to stream a partial assistant turn (append once,
+    // then patch the same line as events arrive). Distinct matcher from the
+    // `messages(/stream)?` block above so the two never collide.
+    {
+      const m = path.match(/^tasks\/([^/]+)\/messages\/([^/]+)$/)
+      if (m && req.method === 'PATCH') {
+        const id = decodeURIComponent(m[1])
+        const msgId = decodeURIComponent(m[2])
+        let raw: string
+        try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+        const parsed = parseJSON(raw)
+        if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+        const validated = validateThreadPatch(parsed.data)
+        if (typeof validated === 'string') return sendError(res, 400, validated)
+        const msg = await options.taskThread.update(id, msgId, validated)
+        if (!msg) return sendError(res, 404, 'Message not found', 'not_found')
+        res.end(JSON.stringify(msg, null, 2))
+        return
+      }
+    }
+
+    // Embedded chat: spawn a local CLI provider as a subprocess.
+    // Spawn routes get a stricter same-port origin check (the general mutating
+    // gate above only checks localhost hostname). This prevents a page on a
+    // different localhost port from spawning CLIs that have credential access.
+    if (path === 'agent/spawn' && req.method === 'POST') {
+      if (!originMatchesPort(req.headers.origin as string | undefined, deriveServerPort(req))) {
+        return sendError(res, 403, 'Forbidden: origin port mismatch', 'origin_port_mismatch')
+      }
+      let raw: string
+      try { raw = await readBody(req) } catch { return sendError(res, 413, 'Request body too large', 'body_too_large') }
+      const parsed = parseJSON(raw)
+      if (!parsed.ok) return sendError(res, 400, 'Invalid JSON body', 'invalid_json')
+      // handleSpawn writes its own SSE headers; we hand it the parsed body
+      // and let it drive the response from here on out.
+      await options.agentSpawn.handleSpawn(req, res, parsed.data, options.projectRoot)
+      return
+    }
+    {
+      const m = path.match(/^agent\/spawn\/([^/]+)$/)
+      if (m && req.method === 'DELETE') {
+        if (!originMatchesPort(req.headers.origin as string | undefined, deriveServerPort(req))) {
+          return sendError(res, 403, 'Forbidden: origin port mismatch', 'origin_port_mismatch')
+        }
+        const runId = decodeURIComponent(m[1])
+        const ok = options.agentSpawn.registry.abort(runId)
+        if (!ok) return sendError(res, 404, 'Run not found', 'not_found')
+        res.end(JSON.stringify({ ok: true }))
+        return
+      }
+    }
+
+    // Embedded chat: detect installed/logged-in local CLIs.
+    if (path === 'agent/detect' && req.method === 'GET') {
+      const snapshot = await options.agentDetect.detect()
+      res.end(JSON.stringify(snapshot, null, 2))
+      return
+    }
+
+    // Per-provider model catalog. Best-effort live probe (opencode supports
+    // listing today); curated fallback for CLIs without a list command.
+    if (path === 'agent/models' && req.method === 'GET') {
+      const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
+      const cli = urlObj.searchParams.get('cli') as ProvideredId | null
+      if (!cli) return sendError(res, 400, 'Missing `cli` query parameter')
+      // `?refresh=1` forces a fresh probe — used by the shell's "Refresh"
+      // button on the model picker. Defaults to the 5-min in-process cache.
+      const refresh = urlObj.searchParams.get('refresh') === '1'
+      const catalog = await listAgentModels(cli, { refresh })
+      res.end(JSON.stringify(catalog, null, 2))
+      return
+    }
+
     if (path === 'components' && req.method === 'GET') {
       const catalog = await scanComponentLibraries(options.projectRoot)
       res.end(JSON.stringify(catalog, null, 2))
       return
     }
 
+    // The project's own src/ components as a ScannedLibrary — the palette's
+    // pinned "Project" group, and the prop-metadata source for local
+    // components in the properties panel.
+    if (path === 'project-components' && req.method === 'GET') {
+      const library = await scanProjectComponents(options.projectRoot)
+      res.end(JSON.stringify({ library, scannedAt: Date.now() }, null, 2))
+      return
+    }
+
     if (path === 'component-usage' && req.method === 'GET') {
       const result = await scanComponentUsage(options.projectRoot)
       res.end(JSON.stringify(result, null, 2))
       return
     }
 
+    // Read .annotask/STYLE_GUIDE.md — used by the init wizard's review step.
+    if (path === 'style-guide' && req.method === 'GET') {
+      const sgPath = nodePath.join(options.projectRoot, '.annotask', 'STYLE_GUIDE.md')
+      try {
+        const content = await fsp.readFile(sgPath, 'utf-8')
+        res.end(JSON.stringify({ content, exists: true }))
+      } catch {
+        res.end(JSON.stringify({ content: '', exists: false }))
+      }
+      return
+    }
+
+    // Read an arbitrary project file by relative path — used for the style-guide override input.
+    if (path === 'read-file' && req.method === 'GET') {
+      const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
+      const relPath = urlObj.searchParams.get('path') ?? ''
+      if (!relPath) return sendError(res, 400, 'Missing path parameter', 'missing_field')
+      // Prevent directory traversal
+      const resolved = nodePath.resolve(options.projectRoot, relPath)
+      if (!resolved.startsWith(options.projectRoot + nodePath.sep) && resolved !== options.projectRoot) {
+        return sendError(res, 403, 'Path must be within the project root', 'forbidden_origin')
+      }
+      try {
+        const content = await fsp.readFile(resolved, 'utf-8')
+        res.end(JSON.stringify({ content, path: relPath }))
+      } catch {
+        return sendError(res, 404, 'File not found', 'not_found')
+      }
+      return
+    }
+
     if (path === 'status' && req.method === 'GET') {
-      res.end(JSON.stringify({ status: 'ok', tool: 'annotask' }))
+      // Surface a session-reset flag when `.annotask/.session-reset` is
+      // present on disk. The justfile's `clear-init` target writes this
+      // sentinel so the shell can detect a developer-initiated reset and
+      // wipe browser-side state (localStorage) without the developer
+      // having to paste a snippet into DevTools.
+      const sentinel = nodePath.resolve(options.projectRoot, '.annotask', '.session-reset')
+      let sessionReset = false
+      try {
+        await fsp.access(sentinel)
+        sessionReset = true
+      } catch { /* not present — normal case */ }
+      const persistenceHealth = options.getPersistenceHealth?.()
+      res.end(JSON.stringify({
+        status: 'ok',
+        tool: 'annotask',
+        sessionReset,
+        // 'degraded' = task mutations are ACKed but failing to reach disk —
+        // a restart would lose them. Shell/CLI should surface this loudly.
+        persistence: persistenceHealth && !persistenceHealth.ok
+          ? { state: 'degraded', consecutiveFailures: persistenceHealth.consecutiveFailures, lastError: persistenceHealth.lastError }
+          : { state: 'ok' },
+      }))
+      return
+    }
+
+    if (path === 'session-reset' && req.method === 'DELETE') {
+      // Acknowledged by the shell after it wipes localStorage. We delete
+      // the on-disk sentinel so subsequent status polls report `false`
+      // and we don't re-clear on every reload.
+      const sentinel = nodePath.resolve(options.projectRoot, '.annotask', '.session-reset')
+      try { await fsp.unlink(sentinel) } catch { /* already gone — fine */ }
+      res.end(JSON.stringify({ ok: true }))
       return
     }
 
@@ -468,6 +1285,23 @@ export function createAPIMiddleware(options: APIOptions) {
       return
     }
 
+    // Round-trip honesty classification for one element — drives the
+    // properties panel's editable/read-only gating. file+line come from the
+    // element's data-annotask-* attrs; tag narrows when several elements share
+    // a line.
+    if (path === 'binding-classify' && req.method === 'GET') {
+      const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
+      const file = urlObj.searchParams.get('file') || ''
+      const lineArg = Number(urlObj.searchParams.get('line') || '0')
+      if (!file) return sendError(res, 400, 'Missing file')
+      if (!Number.isFinite(lineArg) || lineArg < 1) return sendError(res, 400, 'Missing or invalid line')
+      const tag = urlObj.searchParams.get('tag') || undefined
+      const workspaceRoot = await getWorkspaceRoot(options.projectRoot)
+      const result = await classifyBindings(options.projectRoot, file, lineArg, { tag, workspaceRoot })
+      res.end(JSON.stringify(result, null, 2))
+      return
+    }
+
     if (path === 'data-context/probe' && req.method === 'GET') {
       const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
       const file = urlObj.searchParams.get('file') || ''
@@ -728,6 +1562,31 @@ export function createAPIMiddleware(options: APIOptions) {
       return
     }
 
+    // Shape resolution for the wireframe binding picker. Query-param style
+    // (like api-operation) because kind/file disambiguators ride along.
+    if (path === 'data-source-shape' && req.method === 'GET') {
+      const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
+      const name = urlObj.searchParams.get('name') || ''
+      if (!name) return sendError(res, 400, 'Missing name parameter', 'missing_field')
+      const kind = (urlObj.searchParams.get('kind') || undefined) as DataSource['kind'] | undefined
+      const file = urlObj.searchParams.get('file') || undefined
+      const workspaceRoot = await getWorkspaceRoot(options.projectRoot)
+      const result = await resolveDataSourceShape({
+        projectRoot: options.projectRoot,
+        name,
+        kind,
+        file,
+        workspaceRoot,
+        schemaScan: {
+          devServerUrl: deriveDevServerUrl(req),
+          apiSchemaUrls: options.apiSchemaUrls,
+          apiSchemaFiles: options.apiSchemaFiles,
+        },
+      })
+      res.end(JSON.stringify(result, null, 2))
+      return
+    }
+
     if (path.startsWith('data-source-bindings/') && req.method === 'GET') {
       const name = decodeURIComponent(path.replace('data-source-bindings/', ''))
       if (!name) return sendError(res, 400, 'Missing data source name')
@@ -811,3 +1670,183 @@ function enrichEndpoint(
   return out
 }
 
+/**
+ * Validate a `POST /tasks/:id/messages` body. Returns either the normalised
+ * append input or a human-readable error string.
+ */
+interface ThreadAppendBody {
+  role: ThreadRole
+  content: string
+  providerId?: string
+  model?: string
+  usage?: ThreadMessage['usage']
+  toolCalls?: ThreadMessage['toolCalls']
+  toolUseId?: string
+  blocks?: WorkStreamBlock[]
+  isPartial?: boolean
+  lastEventAt?: number
+}
+
+function validateThreadAppend(raw: unknown): ThreadAppendBody | string {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return 'body must be an object'
+  const body = raw as Record<string, unknown>
+  if (body.role !== 'user' && body.role !== 'assistant' && body.role !== 'system' && body.role !== 'tool') {
+    return '`role` must be one of: user, assistant, system, tool'
+  }
+  if (typeof body.content !== 'string') return '`content` must be a string'
+  const out: ThreadAppendBody = {
+    role: body.role,
+    content: body.content,
+  }
+  if (typeof body.providerId === 'string') out.providerId = body.providerId
+  if (typeof body.model === 'string') out.model = body.model
+  if (typeof body.toolUseId === 'string') out.toolUseId = body.toolUseId
+  const usage = parseUsage(body.usage)
+  if (usage) out.usage = usage
+  if (Array.isArray(body.toolCalls)) {
+    out.toolCalls = []
+    for (const tc of body.toolCalls) {
+      if (tc && typeof tc === 'object') {
+        const t = tc as Record<string, unknown>
+        if (typeof t.id === 'string' && typeof t.name === 'string') {
+          out.toolCalls.push({ id: t.id, name: t.name, input: t.input })
+        }
+      }
+    }
+  }
+  if (Array.isArray(body.blocks)) {
+    const validated = validateBlocks(body.blocks)
+    if (validated.length > 0) out.blocks = validated
+  }
+  if (typeof body.isPartial === 'boolean') out.isPartial = body.isPartial
+  if (typeof body.lastEventAt === 'number') out.lastEventAt = body.lastEventAt
+  return out
+}
+
+/** Parse a loose `usage` object into the typed shape, or `undefined`. */
+function parseUsage(raw: unknown): ThreadMessage['usage'] | undefined {
+  if (!raw || typeof raw !== 'object') return undefined
+  const u = raw as Record<string, unknown>
+  if (typeof u.inputTokens !== 'number' || typeof u.outputTokens !== 'number') return undefined
+  return {
+    inputTokens: u.inputTokens,
+    outputTokens: u.outputTokens,
+    cacheReadTokens: typeof u.cacheReadTokens === 'number' ? u.cacheReadTokens : undefined,
+    cacheCreationTokens: typeof u.cacheCreationTokens === 'number' ? u.cacheCreationTokens : undefined,
+  }
+}
+
+/**
+ * Validate a `PATCH /tasks/:id/messages/:msgId` body — the in-place update
+ * used to stream a partial assistant turn. All fields optional; only the
+ * mutable subset is accepted (role/id/ts are immutable).
+ */
+function validateThreadPatch(raw: unknown): UpdateInput | string {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return 'body must be an object'
+  const body = raw as Record<string, unknown>
+  const out: UpdateInput = {}
+  if (typeof body.content === 'string') out.content = body.content
+  if (typeof body.providerId === 'string') out.providerId = body.providerId
+  if (typeof body.model === 'string') out.model = body.model
+  if (typeof body.isPartial === 'boolean') out.isPartial = body.isPartial
+  if (typeof body.lastEventAt === 'number') out.lastEventAt = body.lastEventAt
+  const usage = parseUsage(body.usage)
+  if (usage) out.usage = usage
+  if (Array.isArray(body.blocks)) out.blocks = validateBlocks(body.blocks)
+  return out
+}
+
+/**
+ * Loose validator for the `blocks` array. The wire shape is a discriminated
+ * union on `kind`; we accept the known kinds and silently drop unknown ones
+ * so a future block kind doesn't break older servers.
+ */
+function validateBlocks(raw: unknown[]): WorkStreamBlock[] {
+  const out: WorkStreamBlock[] = []
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue
+    const b = entry as Record<string, unknown>
+    if (b.kind === 'text' && typeof b.text === 'string') {
+      out.push({ kind: 'text', text: b.text })
+    } else if (
+      b.kind === 'tool_call'
+      && typeof b.id === 'string'
+      && typeof b.name === 'string'
+      && typeof b.summary === 'string'
+    ) {
+      out.push({ kind: 'tool_call', id: b.id, name: b.name, input: b.input ?? {}, summary: b.summary })
+    } else if (
+      b.kind === 'tool_result'
+      && typeof b.toolUseId === 'string'
+      && typeof b.summary === 'string'
+      && typeof b.raw === 'string'
+    ) {
+      out.push({
+        kind: 'tool_result',
+        toolUseId: b.toolUseId,
+        summary: b.summary,
+        raw: b.raw,
+        isError: b.isError === true ? true : undefined,
+      })
+    } else if (
+      b.kind === 'agent_question'
+      && typeof b.entryIndex === 'number'
+      && typeof b.label === 'string'
+    ) {
+      out.push({ kind: 'agent_question', entryIndex: b.entryIndex, label: b.label })
+    }
+  }
+  return out
+}
+
+/**
+ * SSE handler for `GET /tasks/:id/messages/stream`.
+ *
+ * Behaviour:
+ *   1. Honour `Last-Event-ID` (or `?after=`) — replay any messages added
+ *      since the client disconnected before going live.
+ *   2. Subscribe to the in-process listener set and forward new appends.
+ *   3. Heartbeat every 15s so reverse proxies don't drop idle connections.
+ *   4. On client disconnect, unsubscribe.
+ */
+async function handleThreadStream(
+  req: IncomingMessage,
+  res: ServerResponse,
+  store: TaskThreadStore,
+  taskId: string,
+): Promise<void> {
+  res.statusCode = 200
+  res.setHeader('Content-Type', 'text/event-stream')
+  res.setHeader('Cache-Control', 'no-store')
+  res.setHeader('Connection', 'keep-alive')
+  res.setHeader('X-Accel-Buffering', 'no')
+  res.flushHeaders?.()
+
+  function send(event: string, msg: ThreadMessage | string) {
+    const data = typeof msg === 'string' ? msg : JSON.stringify(msg)
+    const id = typeof msg === 'string' ? '' : `id: ${msg.id}\n`
+    res.write(`${id}event: ${event}\n`)
+    for (const line of data.split('\n')) res.write(`data: ${line}\n`)
+    res.write('\n')
+  }
+
+  // Replay anything the client missed.
+  const lastEventId = (req.headers['last-event-id'] as string | undefined) || undefined
+  const urlObj = new URL(req.url!, `http://${req.headers.host || 'localhost'}`)
+  const afterId = lastEventId ?? urlObj.searchParams.get('after') ?? undefined
+  const replay = await store.read(taskId, { afterId: afterId || undefined })
+  for (const m of replay) send('message', m)
+
+  // Heartbeat so reverse proxies don't drop the idle SSE connection.
+  const hb = setInterval(() => {
+    try { res.write(': heartbeat\n\n') } catch { /* socket closed */ }
+  }, 15_000)
+  hb.unref()
+
+  const unsubscribe = store.subscribe(taskId, (m) => send('message', m))
+  req.on('close', () => {
+    clearInterval(hb)
+    unsubscribe()
+    try { res.end() } catch { /* already ended */ }
+  })
+}
diff --git a/src/server/apply-session.ts b/src/server/apply-session.ts
new file mode 100644
index 0000000..4c92795
--- /dev/null
+++ b/src/server/apply-session.ts
@@ -0,0 +1,464 @@
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { RevConflictError } from './json-cas-store.js'
+import { WireframeRevConflictError } from './wireframe-store.js'
+import { classifyBindings } from './binding-classify.js'
+import { resolveProjectFile } from './path-safety.js'
+import type { SnapshotStore } from './file-snapshots.js'
+import type { DesignSessionDocument, SessionEntry } from '../shared/design-session-types.js'
+import type { WireframeDocument, WireframeInstance } from '../shared/wireframe-types.js'
+
+/**
+ * Agent-apply orchestration — the server half of "Apply now".
+ *
+ * The tool never authors application source. An apply batch:
+ *   1. collects the session's pending entries + the route's placed instances,
+ *   2. snapshots every file they touch (the byte-exact undo/discard net),
+ *   3. creates ONE wireframe_apply task carrying context.wireframe (the
+ *      placements, exactly as Build always has) + context.session (the
+ *      properties-panel edits),
+ *   4. stamps instances 'building' and entries 'applying'.
+ * The SHELL then drives the embedded agent on that task through the existing
+ * spawn pipeline (auto-run); when the agent flips the task to 'review', the
+ * verification pass below re-reads the source per entry and marks each one
+ * written | failed, then seals the batch's post-apply hashes.
+ */
+
+export interface ApplySessionOptions {
+  projectRoot: string
+  getDesignSession: () => Promise<DesignSessionDocument>
+  setDesignSession: (doc: DesignSessionDocument) => Promise<DesignSessionDocument>
+  getWireframe: () => Promise<WireframeDocument>
+  setWireframe: (doc: WireframeDocument) => Promise<WireframeDocument>
+  addTask: (task: Record<string, unknown>) => unknown | Promise<unknown>
+  snapshots: SnapshotStore
+}
+
+/** CAS-retried read-modify-write on the session journal. `mutate` returns
+ *  false to abort without writing. Best-effort (3 attempts), the
+ *  closeWireframeLifecycle discipline. */
+async function mutateSession(
+  options: Pick<ApplySessionOptions, 'getDesignSession' | 'setDesignSession'>,
+  mutate: (doc: DesignSessionDocument) => boolean,
+): Promise<DesignSessionDocument | null> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const doc = await options.getDesignSession()
+    if (!mutate(doc)) return doc
+    doc.updatedAt = Date.now()
+    try {
+      return await options.setDesignSession(doc)
+    } catch (err) {
+      if (!(err instanceof RevConflictError)) throw err
+    }
+  }
+  console.warn('[Annotask] design-session mutation gave up after rev conflicts')
+  return null
+}
+
+function isPendingEntry(e: SessionEntry): boolean {
+  return e.live.status === 'pending' || e.live.status === 'failed'
+}
+
+/** The agent-facing slice of an entry — envelope cruft (eids, collapse keys)
+ *  stripped; the change payload + anchor + evidence are the contract. */
+function entryForTask(e: SessionEntry): Record<string, unknown> {
+  return {
+    id: e.id,
+    change: e.change,
+    anchor: e.anchor,
+    ...(e.evidence ? { evidence: e.evidence } : {}),
+    ...(e.instanceId ? { instance_id: e.instanceId } : {}),
+  }
+}
+
+/**
+ * Close out a wireframe_apply task's hold on the wireframe doc.
+ *   'remove' (accept) — retire the implemented placements and clear the
+ *     route's canvas sketch (the real component is live now).
+ *   'revert' (abandon: delete / orphan / give-up) — return placements to
+ *     'placed' and unlock the canvas back to 'sketch' so it's editable again.
+ *
+ * Lives here (not in api.ts) so the HTTP PATCH path AND the server-side orphan
+ * reconcile / boot sweep call the SAME closure — a transition handled two
+ * different ways is exactly what stranded orphaned applies (canvas locked at
+ * 'building' forever). CAS-retried, best-effort.
+ */
+export async function closeWireframeLifecycle(
+  options: Pick<ApplySessionOptions, 'getWireframe' | 'setWireframe'>,
+  taskId: string,
+  mode: 'remove' | 'revert',
+): Promise<void> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const doc = await options.getWireframe()
+    let touched = false
+    const routes = doc.routes.map((route) => {
+      const canvasOwned = route.canvas?.taskId === taskId
+      if (!route.instances.some((i) => i.taskId === taskId) && !canvasOwned) return route
+      touched = true
+      const instances: WireframeInstance[] = mode === 'remove'
+        ? route.instances.filter((i) => i.taskId !== taskId)
+        : route.instances.map((i) => {
+            if (i.taskId !== taskId) return i
+            const { taskId: _cleared, ...rest } = i
+            return { ...rest, status: 'placed' as const, updatedAt: Date.now() }
+          })
+      // The snapshot-wireframe canvas rides the same lifecycle: accept removes
+      // the implemented sketch; abandon unlocks it for editing.
+      let canvas = route.canvas
+      if (canvasOwned) {
+        if (mode === 'remove') {
+          canvas = undefined
+        } else {
+          const { taskId: _t, ...rest } = route.canvas!
+          canvas = { ...rest, status: 'sketch' as const }
+        }
+      }
+      return { ...route, instances, canvas, updatedAt: Date.now() }
+    })
+    if (!touched) return
+    try {
+      await options.setWireframe({ ...doc, routes, updatedAt: Date.now() })
+      return
+    } catch (err) {
+      // A non-conflict failure (disk error) won't get better on retry.
+      if (!(err instanceof WireframeRevConflictError)) {
+        console.warn(`[Annotask] wireframe ${mode} for ${taskId} failed:`, err)
+        return
+      }
+    }
+  }
+  console.warn(`[Annotask] wireframe ${mode} for ${taskId} gave up after rev conflicts`)
+}
+
+export async function applyDesignSession(
+  options: ApplySessionOptions,
+  route: string,
+  extras?: { screenshot?: string },
+): Promise<{ taskId: string; batchId: string; entryIds: string[]; instanceIds: string[] } | { error: string }> {
+  const session = await options.getDesignSession()
+  const wireframe = await options.getWireframe()
+
+  // Element edits are session-wide (files aren't route-owned); placements are
+  // per-route, matching Build's contract. Wireframe directions are a per-route
+  // sketch diff — only the applied route's directions ride this task.
+  const entries = session.entries.filter((e) =>
+    isPendingEntry(e) && !e.instanceId
+    && (e.change.type !== 'wireframe_direction' || e.route === route))
+  const instances = (wireframe.routes.find((r) => r.route === route)?.instances ?? [])
+    .filter((i) => (i.status ?? 'placed') === 'placed')
+  if (entries.length === 0 && instances.length === 0) return { error: 'nothing to apply' }
+  const hasDirections = entries.some((e) => e.change.type === 'wireframe_direction')
+
+  // Dominant anchor file → the task-level anchor (buildWireframeRoute precedent).
+  // Empty anchors are honest "couldn't ground this block" (a captured element
+  // with no data-annotask-* ancestor, or an add with no donor neighbor) — they
+  // ride the task as screenshot-anchored directions but must never count toward
+  // the dominant file or, below, the snapshot set (snapshotting '' throws).
+  const hasFile = (f: unknown): f is string => typeof f === 'string' && f.length > 0
+  const fileCounts = new Map<string, number>()
+  for (const e of entries) if (hasFile(e.anchor.file)) fileCounts.set(e.anchor.file, (fileCounts.get(e.anchor.file) ?? 0) + 1)
+  for (const i of instances) if (hasFile(i.anchor.file)) fileCounts.set(i.anchor.file, (fileCounts.get(i.anchor.file) ?? 0) + 1)
+  let domFile = ''
+  let domCount = -1
+  for (const [f, c] of fileCounts) if (c > domCount) { domFile = f; domCount = c }
+  const domLine = entries.find((e) => e.anchor.file === domFile)?.anchor.line
+    ?? instances.find((i) => i.anchor.file === domFile)?.anchor.line ?? 0
+
+  // Number ONLY the direction entries (1..N in journal order — the order the
+  // shell recorded them, which is the composite's badge order). Instances and
+  // legacy session edits ride unnumbered so the badge mapping can't drift.
+  let directionNumber = 0
+  const summaryLines = [
+    ...instances.map((i) => `- place <${i.inserted.componentName ?? i.inserted.tag}> ${i.anchor.position} ${i.anchor.component || i.anchor.targetTag || 'target'}`),
+    ...entries.map((e) => e.change.type === 'wireframe_direction'
+      ? `${++directionNumber}. ${e.change.description}`
+      : `- ${e.change.description}`),
+  ]
+  // Directions get the intent frame; the composite sentence only when a
+  // composite actually rode along (the screenshot is best-effort by design).
+  const compositeNote = extras?.screenshot
+    ? " The task screenshot is a labeled before/after composite (left: captured render; right: the user's sketch — rearranged images, not real UI). Numbered badges on the right pane match the numbered directions below."
+    : ''
+  const description = hasDirections
+    ? `Implement the wireframe sketch on ${route}.${compositeNote} Pixel positions are hints — implement the INTENT with idiomatic layout.\n${summaryLines.join('\n')}`
+    : `Apply ${summaryLines.length} design-session edit${summaryLines.length === 1 ? '' : 's'} on ${route}:\n${summaryLines.join('\n')}`
+
+  const task = await options.addTask({
+    type: 'wireframe_apply',
+    description,
+    file: domFile,
+    line: domLine,
+    route,
+    ...(extras?.screenshot ? { screenshot: extras.screenshot } : {}),
+    context: {
+      ...(instances.length > 0 ? { wireframe: { route, instances } } : {}),
+      session: { session_id: session.sessionId, entries: entries.map(entryForTask) },
+    },
+  }) as { id?: string } | null
+  if (!task?.id) return { error: 'task creation failed' }
+  const taskId = task.id
+
+  // Snapshot BEFORE the agent can run — the journal is the crash-safety net.
+  // Filter empty anchors: an anchorless block (file '') would make snapshotFiles
+  // throw on resolveAbs('') — AFTER the task was already minted, stranding an
+  // orphan task with no batch. Those directions still ride the task and the
+  // agent grounds them from the screenshot; the git auto-extend captures any
+  // file the agent actually edits regardless.
+  const batchId = `ab-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`
+  const files = [...new Set([...entries.map((e) => e.anchor.file), ...instances.map((i) => i.anchor.file)])]
+    .filter(hasFile)
+  await options.snapshots.snapshotFiles(files, { id: batchId, taskId })
+
+  // Stamp instances 'building' (the existing Build semantics: a second apply
+  // won't collect them, and reapply won't re-mount them during review). A
+  // directions apply also locks the route's canvas sketch to the task —
+  // editing a sketch the agent is mid-implementing would lie about state.
+  if (instances.length > 0 || hasDirections) {
+    const ids = new Set(instances.map((i) => i.id))
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const wf = await options.getWireframe()
+      let touched = false
+      const routes = wf.routes.map((r) => {
+        if (r.route !== route) return r
+        let routeTouched = false
+        const next = r.instances.map((i) => {
+          if (!ids.has(i.id)) return i
+          routeTouched = true
+          return { ...i, status: 'building' as const, taskId, updatedAt: Date.now() }
+        })
+        let canvas = r.canvas
+        if (hasDirections && r.canvas && (r.canvas.status ?? 'sketch') === 'sketch') {
+          routeTouched = true
+          canvas = { ...r.canvas, status: 'building' as const, taskId }
+        }
+        if (!routeTouched) return r
+        touched = true
+        return { ...r, instances: next, canvas, updatedAt: Date.now() }
+      })
+      if (!touched) break
+      try {
+        await options.setWireframe({ ...wf, routes, updatedAt: Date.now() })
+        break
+      } catch (err) {
+        if (!(err instanceof WireframeRevConflictError)) {
+          console.warn('[Annotask] apply: stamping instances building failed:', err)
+          break
+        }
+      }
+    }
+  }
+
+  // Stamp entries 'applying' against the batch + task.
+  const entryIds = new Set(entries.map((e) => e.id))
+  await mutateSession(options, (doc) => {
+    let touched = false
+    for (const e of doc.entries) {
+      if (!entryIds.has(e.id) || !isPendingEntry(e)) continue
+      e.live = { status: 'applying', applyBatchId: batchId }
+      e.taskId = taskId
+      touched = true
+    }
+    return touched
+  })
+
+  return { taskId, batchId, entryIds: [...entryIds], instanceIds: instances.map((i) => i.id) }
+}
+
+/** Does the file's current content plausibly contain the applied edit? Used as
+ *  the verification fallback when the exact anchor drifted (the agent's own
+ *  edits shift lines). Conservative string checks — a miss marks the entry
+ *  'failed', never silently 'written'. */
+function contentContainsEdit(content: string, e: SessionEntry): boolean {
+  const c = e.change as unknown as Record<string, unknown>
+  if (c.type === 'text_update') {
+    const after = String(c.after ?? '').trim()
+    return after.length > 0 && content.includes(after)
+  }
+  if (c.type === 'component_prop_update') {
+    const after = c.after
+    if (after === undefined || after === null) return false
+    const v = typeof after === 'string' ? after : JSON.stringify(after)
+    return v.length > 0 && content.includes(v)
+  }
+  if (c.type === 'style_update') {
+    return typeof c.after === 'string' && c.after.length > 0 && content.includes(c.after)
+  }
+  if (c.type === 'class_update') {
+    const after = (c.after as { classes?: string } | undefined)?.classes ?? ''
+    return after.length > 0 && content.includes(after)
+  }
+  // Moves/annotations/inserts: trust the agent's review state — there is no
+  // cheap literal to look for.
+  return true
+}
+
+/**
+ * Verification pass — runs when the apply task transitions to 'review'.
+ * Precision over recall: an entry only flips to 'written' when its literal is
+ * verifiably in source (exact-anchor classification first, conservative
+ * content check as the drift fallback); everything else flips to 'failed'
+ * with a reason the panel can show.
+ */
+export async function verifyAppliedEntries(
+  options: ApplySessionOptions,
+  taskId: string,
+): Promise<void> {
+  const session = await options.getDesignSession()
+  const toVerify = session.entries.filter((e) => e.taskId === taskId && e.live.status === 'applying')
+
+  const verdicts = new Map<string, { ok: boolean; error?: string }>()
+  for (const e of toVerify) {
+    const c = e.change as unknown as Record<string, unknown>
+    // Spatial outcomes aren't literally verifiable in source — a direction
+    // flips on task review (trust the agent's resolution; the user verifies
+    // visually). Decided BEFORE any file read: the agent may legitimately
+    // have renamed/split the anchor file while implementing the sketch.
+    if (c.type === 'wireframe_direction') {
+      verdicts.set(e.id, { ok: true })
+      continue
+    }
+    let ok = false
+    try {
+      if (c.type === 'component_prop_update' || c.type === 'text_update') {
+        // Exact anchor first — proves the edit landed where it was recorded.
+        const cls = await classifyBindings(options.projectRoot, e.anchor.file, e.anchor.line, { tag: e.anchor.targetTag })
+        if (!cls.error) {
+          if (c.type === 'text_update') {
+            ok = cls.text.kind === 'literal' && (cls.text.source ?? '').trim() === String(c.after ?? '').trim()
+          } else {
+            const field = cls.props.find((p) => p.name === c.prop)
+            const after = c.after
+            const want = typeof after === 'string' ? after : String(after)
+            ok = !!field && field.kind === 'literal' && field.source.replace(/^['"`]|['"`]$/g, '') === want
+          }
+        }
+      }
+      if (!ok) {
+        // Drift fallback: the agent's other edits moved the anchor — verify by
+        // content. resolveProjectFile keeps the read inside the project.
+        const resolved = resolveProjectFile(options.projectRoot, e.anchor.file)
+        const abs = resolved?.absolutePath ?? (path.isAbsolute(e.anchor.file) ? e.anchor.file : null)
+        if (abs) {
+          const content = await fsp.readFile(abs, 'utf-8')
+          ok = contentContainsEdit(content, e)
+        }
+      }
+      verdicts.set(e.id, ok ? { ok } : { ok, error: 'agent run finished but this edit was not found in source — see the task' })
+    } catch (err) {
+      verdicts.set(e.id, { ok: false, error: `verification failed: ${(err as Error).message}` })
+    }
+  }
+
+  if (toVerify.length > 0) {
+    await mutateSession(options, (doc) => {
+      let touched = false
+      for (const e of doc.entries) {
+        const verdict = verdicts.get(e.id)
+        if (!verdict || e.live.status !== 'applying') continue
+        e.live = verdict.ok
+          ? { status: 'written', applyBatchId: e.live.applyBatchId, writtenAt: Date.now() }
+          : { status: 'failed', applyBatchId: e.live.applyBatchId, error: verdict.error }
+        touched = true
+      }
+      return touched
+    })
+  }
+
+  // (Re-)seal post-apply hashes — the baseline the undo/discard hash-guard
+  // trusts. Sealed by TASK, unconditionally on every review: re-apply after a
+  // deny leaves no entry in 'applying' (they're already written/failed) yet the
+  // agent wrote NEW bytes that must become the new undo baseline; and a
+  // pure-instances apply has no session entries to verify but still needs its
+  // hash. Re-sealing is safe — only lastAppliedHash + the created net change.
+  await options.snapshots.sealBatchByTask(taskId)
+}
+
+/** Undo the newest apply batch: restore its pre-apply bytes and return its
+ *  entries to 'pending' so they re-surface as work. */
+export async function revertApplyBatch(
+  options: ApplySessionOptions,
+  batchId: string,
+): Promise<{ reverted: string[]; skipped: string[] }> {
+  const result = await options.snapshots.revertBatch(batchId)
+  await mutateSession(options, (doc) => {
+    let touched = false
+    for (const e of doc.entries) {
+      if (e.live.applyBatchId !== batchId) continue
+      e.live = { status: 'pending' }
+      delete e.taskId
+      touched = true
+    }
+    return touched
+  })
+  return result
+}
+
+/**
+ * Accept: the user reviewed the agent's work and kept it. The bytes are now
+ * the project's baseline — drop the snapshot journal (no more undo into the
+ * accepted state), remove the task's session entries, and when that empties
+ * the journal, hand back `rotated: true` so the caller mints a fresh session.
+ */
+export async function acceptApplyTask(
+  options: Pick<ApplySessionOptions, 'getDesignSession' | 'setDesignSession' | 'snapshots'>,
+  taskId: string,
+): Promise<{ rotated: boolean }> {
+  await options.snapshots.commit()
+  const doc = await mutateSession(options, (d) => {
+    const before = d.entries.length
+    d.entries = d.entries.filter((e) => e.taskId !== taskId)
+    return d.entries.length !== before
+  })
+  return { rotated: !!doc && doc.entries.length === 0 }
+}
+
+/** Abandoned run (task deleted, a crashed/aborted/orphaned seed run flipped the
+ *  task back to pending/blocked, or the server-side orphan reconcile reclaimed
+ *  a stale in_progress lock): seal the possibly-half-written batch as 'failed'
+ *  so it carries a hash baseline and stays revertible (the undo/discard guard
+ *  refuses a still-'running' batch — leaving it 'running' is the wedge that
+ *  disabled undo+discard+re-apply at once), return its entries to 'pending' so
+ *  they re-surface as work, AND unlock the wireframe canvas back to 'sketch'
+ *  (otherwise it stays read-only at 'building' with no agent running). One
+ *  function for every abandon path so the HTTP and server-side paths agree. */
+export async function releaseApplyTask(
+  options: Pick<ApplySessionOptions, 'getDesignSession' | 'setDesignSession' | 'snapshots' | 'getWireframe' | 'setWireframe'>,
+  taskId: string,
+): Promise<void> {
+  await options.snapshots.sealBatchByTask(taskId, { failed: true })
+  await mutateSession(options, (doc) => {
+    let touched = false
+    for (const e of doc.entries) {
+      if (e.taskId !== taskId) continue
+      if (e.live.status === 'applying') e.live = { status: 'pending', applyBatchId: e.live.applyBatchId }
+      delete e.taskId
+      touched = true
+    }
+    return touched
+  })
+  // Unlock the route's canvas sketch (no-op when this task never owned one).
+  await closeWireframeLifecycle(options, taskId, 'revert')
+}
+
+/** Re-stamp a denied/blocked/needs_info task's session entries back to
+ *  'applying' when it re-enters 'in_progress' (retry / resume). Without this,
+ *  verifyAppliedEntries (which only re-reads entries still in 'applying') skips
+ *  them on the second review, so the apply panel keeps showing the FIRST run's
+ *  stale written/failed verdicts after a fix. Idempotent. */
+export async function restampApplyEntries(
+  options: Pick<ApplySessionOptions, 'getDesignSession' | 'setDesignSession'>,
+  taskId: string,
+  batchId?: string,
+): Promise<void> {
+  await mutateSession(options, (doc) => {
+    let touched = false
+    for (const e of doc.entries) {
+      if (e.taskId !== taskId) continue
+      if (e.live.status === 'written' || e.live.status === 'failed') {
+        e.live = { status: 'applying', applyBatchId: e.live.applyBatchId ?? batchId }
+        touched = true
+      }
+    }
+    return touched
+  })
+}
diff --git a/src/server/binding-classify.ts b/src/server/binding-classify.ts
new file mode 100644
index 0000000..63be8c0
--- /dev/null
+++ b/src/server/binding-classify.ts
@@ -0,0 +1,590 @@
+/**
+ * Round-trip honesty classifier — the gate that decides which fields of an
+ * element are EDITABLE in the properties panel and which are read-only.
+ *
+ * Given an element's durable anchor (file, line[, tag]), classify every
+ * attribute/prop written at that usage site as literal (editable — a write
+ * back to source is exact), bound expression (read-only — "this value comes
+ * from `planet.name`"), or unknown (read-only), plus the element's text
+ * content and any enclosing loop ("editing one edits all N").
+ *
+ * AST, not regex: real usage sites span multiple lines (`<PlanetCard
+ * v-for=… :planet=… :active=… />`) and `data-annotask-line` points at the
+ * opening tag only — a single-line regex can't see continuation-line attrs or
+ * the enclosing v-for, and misclassification means editing the wrong thing.
+ * The framework compilers are loaded lazily exactly like binding-analysis/
+ * (optional peers); when a parser is missing or parsing fails, everything
+ * degrades to read-only. PRECISION OVER RECALL — never guess editable.
+ */
+import fsp from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { resolveProjectFile } from './path-safety.js'
+
+export interface BindingFieldInfo {
+  name: string
+  kind: 'literal' | 'bound' | 'unknown'
+  /** Literal: the source value. Bound: the expression text, shown verbatim. */
+  source: string
+  /** Literal written through binding syntax (`:count="3"`, `count={3}`) —
+   *  a write back must keep the binding syntax. */
+  expression_literal?: boolean
+  /** Human-readable read-only reason ('bound expression', 'spread props', …). */
+  reason?: string
+}
+
+export interface BindingTextInfo {
+  /** 'literal' — text nodes only → editable, a textContent swap is exact.
+   *  'bound'   — interpolation/expression only → read-only.
+   *  'mixed'   — text plus elements/interpolations → read-only.
+   *  'none'    — no text children. 'unknown' — could not classify. */
+  kind: 'literal' | 'bound' | 'mixed' | 'none' | 'unknown'
+  source?: string
+  reason?: string
+}
+
+export interface BindingClassification {
+  file: string
+  line: number
+  tag?: string
+  analyzer: 'vue-sfc' | 'jsx' | 'svelte' | 'none'
+  /** Present when the element (or an ancestor) renders in a loop. */
+  loop?: { iterable: string; alias?: string }
+  props: BindingFieldInfo[]
+  text: BindingTextInfo
+  /** sha256-16 of the ±5-line excerpt around `line` — drift guard, same idea
+   *  as code-context.ts. */
+  excerpt_hash: string
+  /** Parse failed / element not found / ambiguous → everything read-only. */
+  error?: string
+}
+
+const EXPRESSION_LITERAL_RE = /^\s*(?:'[^']*'|"[^"]*"|`[^`$\\]*`|-?\d+(?:\.\d+)?|true|false)\s*$/
+
+// ── lazy optional-peer compiler loading (binding-analysis pattern) ──
+
+async function tryLoadVueSfc(): Promise<any | null> {
+  try {
+    // @ts-ignore optional peer dep
+    return await import('@vue/compiler-sfc')
+  } catch { return null }
+}
+
+async function tryLoadBabelParser(): Promise<any | null> {
+  try {
+    // @ts-ignore optional peer dep
+    return await import('@babel/parser')
+  } catch { return null }
+}
+
+async function tryLoadSvelte(): Promise<any | null> {
+  try {
+    // @ts-ignore optional peer dep
+    return await import('svelte/compiler')
+  } catch { return null }
+}
+
+// ── small shared helpers ──
+
+function excerptHash(lines: string[], line: number): string {
+  const idx = Math.max(0, Math.min(line - 1, lines.length - 1))
+  const start = Math.max(0, idx - 5)
+  const end = Math.min(lines.length - 1, idx + 5)
+  return createHash('sha256').update(lines.slice(start, end + 1).join('\n')).digest('hex').slice(0, 16)
+}
+
+function readOnlyResult(
+  base: Pick<BindingClassification, 'file' | 'line' | 'tag' | 'excerpt_hash'>,
+  analyzer: BindingClassification['analyzer'],
+  error: string,
+): BindingClassification {
+  return { ...base, analyzer, props: [], text: { kind: 'unknown', reason: error }, error }
+}
+
+/** Byte offset → 1-based line, for ASTs that only carry offsets (Svelte). */
+function buildOffsetToLine(content: string): (offset: number) => number {
+  const starts: number[] = [0]
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '\n') starts.push(i + 1)
+  }
+  return (offset: number) => {
+    let lo = 0
+    let hi = starts.length - 1
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1
+      if (starts[mid] <= offset) lo = mid
+      else hi = mid - 1
+    }
+    return lo + 1
+  }
+}
+
+function tagMatches(nodeTag: string | undefined, wanted: string | undefined): boolean {
+  if (!wanted || !nodeTag) return true
+  return nodeTag.toLowerCase() === wanted.toLowerCase()
+}
+
+// ── Vue (.vue) ──
+
+const VUE_NODE = { ELEMENT: 1, TEXT: 2, INTERPOLATION: 5, ATTRIBUTE: 6, DIRECTIVE: 7 } as const
+
+interface VueMatch { node: any; ancestors: any[] }
+
+function findVueElements(root: any, line: number, tag: string | undefined, lineOffset: number): VueMatch[] {
+  const matches: VueMatch[] = []
+  const stack: any[] = []
+  function walk(node: any): void {
+    if (!node || typeof node !== 'object') return
+    if (node.type === VUE_NODE.ELEMENT) {
+      const startLine = (node.loc?.start?.line ?? 0) + lineOffset
+      if (startLine === line && tagMatches(node.tag, tag)) {
+        matches.push({ node, ancestors: [...stack] })
+      }
+      stack.push(node)
+      for (const child of node.children ?? []) walk(child)
+      stack.pop()
+      return
+    }
+    for (const child of node.children ?? []) walk(child)
+  }
+  walk(root)
+  return matches
+}
+
+function parseVFor(exp: string): { iterable: string; alias?: string } {
+  // "planet in filtered" | "(planet, i) in filtered" | "item of list"
+  const m = /^\s*\(?\s*([^,)\s]+)[^)]*?\)?\s+(?:in|of)\s+(.+?)\s*$/.exec(exp)
+  if (m) return { iterable: m[2], alias: m[1] }
+  return { iterable: exp }
+}
+
+function classifyVueElement(match: VueMatch): Pick<BindingClassification, 'props' | 'text' | 'loop'> {
+  const { node, ancestors } = match
+  const props: BindingFieldInfo[] = []
+  let spread = false
+  let loop: BindingClassification['loop']
+
+  for (const holder of [...ancestors, node]) {
+    if (holder.type !== VUE_NODE.ELEMENT) continue
+    for (const p of holder.props ?? []) {
+      if (p.type === VUE_NODE.DIRECTIVE && p.name === 'for' && p.exp?.content) {
+        loop = parseVFor(String(p.exp.content))
+      }
+    }
+  }
+
+  for (const p of node.props ?? []) {
+    if (p.type === VUE_NODE.ATTRIBUTE) {
+      props.push({ name: p.name, kind: 'literal', source: p.value?.content ?? '' })
+    } else if (p.type === VUE_NODE.DIRECTIVE) {
+      if (p.name === 'for' || p.name === 'if' || p.name === 'else-if' || p.name === 'else' || p.name === 'on' || p.name === 'slot') continue
+      if (p.name === 'bind') {
+        if (!p.arg) { spread = true; continue } // v-bind="obj"
+        const name = p.arg.content ? String(p.arg.content) : ''
+        const exp = p.exp?.content ? String(p.exp.content) : ''
+        if (!name || !p.arg.isStatic) {
+          props.push({ name: name || '(dynamic)', kind: 'unknown', source: exp, reason: 'dynamic prop name' })
+        } else if (EXPRESSION_LITERAL_RE.test(exp)) {
+          props.push({ name, kind: 'literal', source: exp.trim(), expression_literal: true })
+        } else {
+          props.push({ name, kind: 'bound', source: exp, reason: 'bound expression' })
+        }
+      } else if (p.name === 'model') {
+        const name = p.arg?.content ? String(p.arg.content) : 'modelValue'
+        props.push({ name, kind: 'bound', source: p.exp?.content ? String(p.exp.content) : '', reason: 'v-model binding' })
+      }
+    }
+  }
+
+  if (spread) {
+    return {
+      props: props.map((f) => ({ ...f, kind: 'unknown' as const, expression_literal: undefined, reason: 'spread props (v-bind="…") may override' })),
+      text: classifyVueText(node),
+      loop,
+    }
+  }
+  return { props, text: classifyVueText(node), loop }
+}
+
+function classifyVueText(node: any): BindingTextInfo {
+  let textRuns = 0
+  let interpolations = 0
+  let elements = 0
+  let literal = ''
+  let expr = ''
+  for (const child of node.children ?? []) {
+    if (child.type === VUE_NODE.TEXT) {
+      if (String(child.content).trim() !== '') { textRuns++; literal += String(child.content) }
+    } else if (child.type === VUE_NODE.INTERPOLATION) {
+      interpolations++
+      expr = child.content?.content ? String(child.content.content) : ''
+    } else if (child.type === VUE_NODE.ELEMENT) {
+      elements++
+    }
+  }
+  if (elements > 0) return textRuns + interpolations > 0 ? { kind: 'mixed', reason: 'mixed content' } : { kind: 'none' }
+  if (textRuns > 0 && interpolations > 0) return { kind: 'mixed', reason: 'mixed content' }
+  if (interpolations > 0) return { kind: 'bound', source: expr, reason: 'bound expression' }
+  if (textRuns > 0) return { kind: 'literal', source: literal }
+  return { kind: 'none' }
+}
+
+async function classifyVue(content: string, base: Pick<BindingClassification, 'file' | 'line' | 'tag' | 'excerpt_hash'>): Promise<BindingClassification> {
+  const sfc = await tryLoadVueSfc()
+  if (!sfc) return readOnlyResult(base, 'none', 'Vue compiler not installed')
+  let descriptor: any
+  try { descriptor = sfc.parse(content).descriptor } catch { return readOnlyResult(base, 'vue-sfc', 'parse failed') }
+  const template = descriptor.template
+  if (!template?.ast) {
+    // compiler-sfc parses the template block AST itself in recent versions;
+    // fall back to compiler-dom when absent.
+    try {
+      // @ts-ignore optional peer dep
+      const dom = await import('@vue/compiler-dom')
+      const templateStartLine: number = template?.loc?.start?.line ?? 1
+      const ast = dom.parse(template?.content ?? '')
+      return finishVue(ast, templateStartLine, base)
+    } catch { return readOnlyResult(base, 'vue-sfc', 'template parse failed') }
+  }
+  const templateStartLine: number = template.loc?.start?.line ?? 1
+  return finishVue(template.ast, templateStartLine, base)
+}
+
+function firstElementLine(node: any): number | null {
+  if (!node || typeof node !== 'object') return null
+  if (node.type === VUE_NODE.ELEMENT) return node.loc?.start?.line ?? null
+  for (const child of node.children ?? []) {
+    const line = firstElementLine(child)
+    if (line !== null) return line
+  }
+  return null
+}
+
+function finishVue(ast: any, templateStartLine: number, base: Pick<BindingClassification, 'file' | 'line' | 'tag' | 'excerpt_hash'>): BindingClassification {
+  // Line-coordinate detection: compiler-sfc's template.ast carries
+  // FILE-ABSOLUTE element lines (parsed from the whole SFC — note the ROOT
+  // node's loc is unreliable, so probe the first element), while compiler-dom
+  // on the extracted block content is BLOCK-RELATIVE and needs the offset.
+  const probe = firstElementLine(ast)
+  const lineOffset = probe !== null && probe < templateStartLine ? templateStartLine - 1 : 0
+  const matches = findVueElements(ast, base.line, base.tag, lineOffset)
+  if (matches.length === 0) return readOnlyResult(base, 'vue-sfc', 'element not found at line')
+  if (matches.length > 1) return readOnlyResult(base, 'vue-sfc', 'ambiguous: multiple elements at line')
+  return { ...base, analyzer: 'vue-sfc', ...classifyVueElement(matches[0]) }
+}
+
+// ── JSX (.tsx / .jsx — React and Solid) ──
+
+interface JsxMatch { node: any; ancestors: any[] }
+
+function walkBabel(node: any, visit: (node: any, ancestors: any[]) => void, ancestors: any[] = []): void {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const item of node) walkBabel(item, visit, ancestors)
+    return
+  }
+  if (typeof node.type !== 'string') return
+  visit(node, ancestors)
+  ancestors.push(node)
+  for (const key of Object.keys(node)) {
+    if (key === 'loc' || key === 'leadingComments' || key === 'trailingComments') continue
+    const value = (node as Record<string, unknown>)[key]
+    if (value && typeof value === 'object') walkBabel(value, visit, ancestors)
+  }
+  ancestors.pop()
+}
+
+function jsxTagName(opening: any): string | undefined {
+  const name = opening?.name
+  if (!name) return undefined
+  if (name.type === 'JSXIdentifier') return name.name
+  if (name.type === 'JSXMemberExpression') return `${name.object?.name ?? ''}.${name.property?.name ?? ''}`
+  return undefined
+}
+
+function classifyJsxElement(content: string, match: JsxMatch): Pick<BindingClassification, 'props' | 'text' | 'loop'> {
+  const { node, ancestors } = match
+  const props: BindingFieldInfo[] = []
+  let spread = false
+  let loop: BindingClassification['loop']
+
+  for (const anc of ancestors) {
+    if (anc.type === 'CallExpression' && anc.callee?.type === 'MemberExpression'
+      && anc.callee.property?.type === 'Identifier' && anc.callee.property.name === 'map') {
+      const obj = anc.callee.object
+      const iterable = typeof obj?.start === 'number' && typeof obj?.end === 'number'
+        ? content.slice(obj.start, obj.end)
+        : 'list'
+      const cb = anc.arguments?.[0]
+      const alias = cb?.params?.[0]?.type === 'Identifier' ? cb.params[0].name : undefined
+      loop = { iterable, alias }
+    }
+  }
+
+  for (const attr of node.openingElement?.attributes ?? []) {
+    if (attr.type === 'JSXSpreadAttribute') { spread = true; continue }
+    if (attr.type !== 'JSXAttribute') continue
+    const name = attr.name?.name ? String(attr.name.name) : ''
+    if (!name) continue
+    // Event handlers are not editable props.
+    if (/^on[A-Z]/.test(name)) continue
+    const v = attr.value
+    if (v == null) {
+      props.push({ name, kind: 'literal', source: 'true', expression_literal: true })
+    } else if (v.type === 'StringLiteral') {
+      props.push({ name, kind: 'literal', source: v.value })
+    } else if (v.type === 'JSXExpressionContainer') {
+      const exp = v.expression
+      const raw = typeof exp?.start === 'number' && typeof exp?.end === 'number' ? content.slice(exp.start, exp.end) : ''
+      if (exp?.type === 'StringLiteral' || exp?.type === 'NumericLiteral' || exp?.type === 'BooleanLiteral'
+        || (exp?.type === 'TemplateLiteral' && (exp.expressions?.length ?? 0) === 0)
+        || (exp?.type === 'UnaryExpression' && exp.operator === '-' && exp.argument?.type === 'NumericLiteral')) {
+        props.push({ name, kind: 'literal', source: raw, expression_literal: true })
+      } else {
+        props.push({ name, kind: 'bound', source: raw, reason: 'bound expression' })
+      }
+    } else {
+      props.push({ name, kind: 'unknown', source: '', reason: 'unclassified attribute value' })
+    }
+  }
+
+  const text = classifyJsxText(content, node)
+  if (spread) {
+    return {
+      props: props.map((f) => ({ ...f, kind: 'unknown' as const, expression_literal: undefined, reason: 'spread props ({...props}) may override' })),
+      text,
+      loop,
+    }
+  }
+  return { props, text, loop }
+}
+
+function classifyJsxText(content: string, node: any): BindingTextInfo {
+  let textRuns = 0
+  let expressions = 0
+  let elements = 0
+  let literal = ''
+  let expr = ''
+  for (const child of node.children ?? []) {
+    if (child.type === 'JSXText') {
+      if (String(child.value).trim() !== '') { textRuns++; literal += String(child.value) }
+    } else if (child.type === 'JSXExpressionContainer') {
+      if (child.expression?.type === 'JSXEmptyExpression') continue
+      if (child.expression?.type === 'StringLiteral') {
+        textRuns++
+        literal += child.expression.value
+        continue
+      }
+      expressions++
+      expr = typeof child.expression?.start === 'number' ? content.slice(child.expression.start, child.expression.end) : ''
+    } else if (child.type === 'JSXElement' || child.type === 'JSXFragment') {
+      elements++
+    }
+  }
+  if (elements > 0) return textRuns + expressions > 0 ? { kind: 'mixed', reason: 'mixed content' } : { kind: 'none' }
+  if (textRuns > 0 && expressions > 0) return { kind: 'mixed', reason: 'mixed content' }
+  if (expressions > 0) return { kind: 'bound', source: expr, reason: 'bound expression' }
+  if (textRuns > 0) return { kind: 'literal', source: literal }
+  return { kind: 'none' }
+}
+
+async function classifyJsx(content: string, base: Pick<BindingClassification, 'file' | 'line' | 'tag' | 'excerpt_hash'>): Promise<BindingClassification> {
+  const babel = await tryLoadBabelParser()
+  if (!babel) return readOnlyResult(base, 'none', 'Babel parser not installed')
+  let ast: any
+  try {
+    ast = babel.parse(content, {
+      sourceType: 'module',
+      plugins: ['jsx', 'typescript', 'classProperties', 'decorators-legacy', 'importAssertions', 'topLevelAwait'],
+      errorRecovery: true,
+    })
+  } catch { return readOnlyResult(base, 'jsx', 'parse failed') }
+
+  const matches: JsxMatch[] = []
+  walkBabel(ast.program, (node, ancestors) => {
+    if (node.type !== 'JSXElement') return
+    const startLine = node.openingElement?.loc?.start?.line
+    if (startLine !== base.line) return
+    if (!tagMatches(jsxTagName(node.openingElement), base.tag)) return
+    matches.push({ node, ancestors: [...ancestors] })
+  })
+
+  if (matches.length === 0) return readOnlyResult(base, 'jsx', 'element not found at line')
+  if (matches.length > 1) return readOnlyResult(base, 'jsx', 'ambiguous: multiple elements at line')
+  return { ...base, analyzer: 'jsx', ...classifyJsxElement(content, matches[0]) }
+}
+
+// ── Svelte (.svelte) ──
+
+interface SvelteMatch { node: any; ancestors: any[] }
+
+function classifySvelteElement(content: string, match: SvelteMatch): Pick<BindingClassification, 'props' | 'text' | 'loop'> {
+  const { node, ancestors } = match
+  const props: BindingFieldInfo[] = []
+  let spread = false
+  let loop: BindingClassification['loop']
+
+  for (const anc of ancestors) {
+    if (anc.type === 'EachBlock') {
+      const iterable = typeof anc.expression?.start === 'number'
+        ? content.slice(anc.expression.start, anc.expression.end)
+        : 'list'
+      const alias = anc.context?.type === 'Identifier' ? anc.context.name : undefined
+      loop = { iterable, alias }
+    }
+  }
+
+  for (const attr of node.attributes ?? []) {
+    if (attr.type === 'Spread') { spread = true; continue }
+    if (attr.type === 'EventHandler' || attr.type === 'Binding') {
+      if (attr.type === 'Binding') {
+        props.push({ name: attr.name, kind: 'bound', source: `bind:${attr.name}`, reason: 'two-way binding' })
+      }
+      continue
+    }
+    if (attr.type !== 'Attribute') continue
+    const name = String(attr.name)
+    const value = attr.value
+    if (value === true) {
+      props.push({ name, kind: 'literal', source: 'true', expression_literal: true })
+      continue
+    }
+    const parts = Array.isArray(value) ? value : []
+    if (parts.length === 1 && parts[0].type === 'Text') {
+      props.push({ name, kind: 'literal', source: String(parts[0].data ?? parts[0].raw ?? '') })
+    } else if (parts.length === 1 && (parts[0].type === 'MustacheTag' || parts[0].type === 'ExpressionTag')) {
+      const exp = parts[0].expression
+      const raw = typeof exp?.start === 'number' ? content.slice(exp.start, exp.end) : ''
+      if (EXPRESSION_LITERAL_RE.test(raw)) {
+        props.push({ name, kind: 'literal', source: raw.trim(), expression_literal: true })
+      } else {
+        props.push({ name, kind: 'bound', source: raw, reason: 'bound expression' })
+      }
+    } else if (parts.length > 1) {
+      props.push({ name, kind: 'bound', source: '', reason: 'interpolated attribute' })
+    } else {
+      props.push({ name, kind: 'unknown', source: '', reason: 'unclassified attribute value' })
+    }
+  }
+
+  const text = classifySvelteText(content, node)
+  if (spread) {
+    return {
+      props: props.map((f) => ({ ...f, kind: 'unknown' as const, expression_literal: undefined, reason: 'spread props ({...props}) may override' })),
+      text,
+      loop,
+    }
+  }
+  return { props, text, loop }
+}
+
+function classifySvelteText(content: string, node: any): BindingTextInfo {
+  let textRuns = 0
+  let expressions = 0
+  let elements = 0
+  let literal = ''
+  let expr = ''
+  for (const child of node.children ?? node.fragment?.nodes ?? []) {
+    if (child.type === 'Text') {
+      if (String(child.data ?? '').trim() !== '') { textRuns++; literal += String(child.data ?? '') }
+    } else if (child.type === 'MustacheTag' || child.type === 'ExpressionTag') {
+      expressions++
+      expr = typeof child.expression?.start === 'number' ? content.slice(child.expression.start, child.expression.end) : ''
+    } else if (child.type === 'Element' || child.type === 'InlineComponent' || child.type === 'Component' || child.type === 'RegularElement') {
+      elements++
+    }
+  }
+  if (elements > 0) return textRuns + expressions > 0 ? { kind: 'mixed', reason: 'mixed content' } : { kind: 'none' }
+  if (textRuns > 0 && expressions > 0) return { kind: 'mixed', reason: 'mixed content' }
+  if (expressions > 0) return { kind: 'bound', source: expr, reason: 'bound expression' }
+  if (textRuns > 0) return { kind: 'literal', source: literal }
+  return { kind: 'none' }
+}
+
+async function classifySvelte(content: string, base: Pick<BindingClassification, 'file' | 'line' | 'tag' | 'excerpt_hash'>): Promise<BindingClassification> {
+  const sv = await tryLoadSvelte()
+  if (!sv?.parse) return readOnlyResult(base, 'none', 'Svelte compiler not installed')
+  let ast: any
+  try { ast = sv.parse(content) } catch { return readOnlyResult(base, 'svelte', 'parse failed') }
+
+  const offsetToLine = buildOffsetToLine(content)
+  const matches: SvelteMatch[] = []
+  const stack: any[] = []
+  function walk(node: any): void {
+    if (!node || typeof node !== 'object') return
+    const isElement = node.type === 'Element' || node.type === 'InlineComponent' || node.type === 'Component' || node.type === 'RegularElement'
+    if (isElement && typeof node.start === 'number') {
+      if (offsetToLine(node.start) === base.line && tagMatches(node.name, base.tag)) {
+        matches.push({ node, ancestors: [...stack] })
+      }
+    }
+    stack.push(node)
+    for (const child of node.children ?? node.fragment?.nodes ?? []) walk(child)
+    if (node.type === 'EachBlock' && node.else) walk(node.else)
+    stack.pop()
+  }
+  walk(ast.html ?? ast.fragment ?? ast)
+
+  if (matches.length === 0) return readOnlyResult(base, 'svelte', 'element not found at line')
+  if (matches.length > 1) return readOnlyResult(base, 'svelte', 'ambiguous: multiple elements at line')
+  return { ...base, analyzer: 'svelte', ...classifySvelteElement(content, matches[0]) }
+}
+
+// ── cache + entry point ──
+
+const CACHE_CAP = 500
+const cache = new Map<string, BindingClassification>()
+
+export async function classifyBindings(
+  projectRoot: string,
+  relFile: string,
+  line: number,
+  opts?: { tag?: string; workspaceRoot?: string },
+): Promise<BindingClassification> {
+  const resolved = resolveProjectFile(projectRoot, relFile, opts?.workspaceRoot)
+  if (!resolved) {
+    return {
+      file: String(relFile), line, tag: opts?.tag, analyzer: 'none',
+      props: [], text: { kind: 'unknown', reason: 'invalid path' },
+      excerpt_hash: '', error: 'Invalid or escaping file path',
+    }
+  }
+  const { absolutePath: absPath, relative: safeFile } = resolved
+
+  let stat: { mtimeMs: number }
+  let content: string
+  try {
+    stat = await fsp.stat(absPath)
+    content = await fsp.readFile(absPath, 'utf-8')
+  } catch (err: any) {
+    return {
+      file: safeFile, line, tag: opts?.tag, analyzer: 'none',
+      props: [], text: { kind: 'unknown', reason: 'unreadable file' },
+      excerpt_hash: '', error: `Could not read file: ${err?.message ?? 'unknown'}`,
+    }
+  }
+
+  const key = `${absPath}|${stat.mtimeMs}|${line}|${opts?.tag ?? ''}`
+  const hit = cache.get(key)
+  if (hit) return hit
+
+  const lines = content.split(/\r?\n/)
+  const base = { file: safeFile, line, tag: opts?.tag, excerpt_hash: excerptHash(lines, line) }
+
+  let result: BindingClassification
+  if (safeFile.endsWith('.vue')) result = await classifyVue(content, base)
+  else if (safeFile.endsWith('.tsx') || safeFile.endsWith('.jsx')) result = await classifyJsx(content, base)
+  else if (safeFile.endsWith('.svelte')) result = await classifySvelte(content, base)
+  else result = readOnlyResult(base, 'none', 'unsupported file type')
+
+  if (cache.size >= CACHE_CAP) {
+    const first = cache.keys().next().value
+    if (first !== undefined) cache.delete(first)
+  }
+  cache.set(key, result)
+  return result
+}
+
+/** Test hook — drop the (path, mtime, line, tag) cache. */
+export function clearBindingClassifyCache(): void {
+  cache.clear()
+}
diff --git a/src/server/component-scanner.ts b/src/server/component-scanner.ts
index 3bc25a1..7119a2d 100644
--- a/src/server/component-scanner.ts
+++ b/src/server/component-scanner.ts
@@ -3,7 +3,6 @@ import fsp from 'node:fs/promises'
 import path from 'node:path'
 import crypto from 'node:crypto'
 import { Worker } from 'node:worker_threads'
-import { resolveWorkspace } from './workspace.js'
 
 export interface ScannedProp {
   name: string
@@ -36,6 +35,15 @@ export interface ScannedComponent {
   slots: ScannedSlot[]
   events: ScannedEvent[]
   sourceFile: string | null   // absolute path — only populated for local components
+  /** Provider-dependence markers found in source (useContext/inject/useRouter/
+   *  useQuery/provide + router/query/store imports). Empty when none or when
+   *  source is unavailable (.d.ts-only libs). Lets the palette pre-mark a
+   *  component before attempting a throwing mount. */
+  providerSignals: string[]
+  /** Coarse render-fidelity hint for the palette: 'live' (should mount in
+   *  context), 'isolated-preview' (detached, provider-dependent), or 'unknown'
+   *  (source unavailable — the live mount itself confirms). */
+  fidelityHint: 'live' | 'isolated-preview' | 'placeholder' | 'unknown'
 }
 
 export interface ScannedLibrary {
@@ -98,26 +106,21 @@ function diskCachePath(projectRoot: string): string {
 }
 
 /**
- * Fingerprint of every workspace package.json plus its mtime. If any dep is
- * added, removed, or bumped, the key changes and the disk cache is ignored.
- * Cheap to compute (one stat + one read per package.json) relative to the
- * 20s+ scan it replaces.
+ * Fingerprint of the running package's package.json plus its mtime. If any dep
+ * is added, removed, or bumped, the key changes and the disk cache is ignored.
+ * Cheap (one stat + one read) relative to the 20s+ scan it replaces.
  */
 async function computeCacheKey(projectRoot: string): Promise<string | null> {
   try {
-    const ws = await resolveWorkspace(projectRoot)
-    const parts: string[] = []
-    for (const pkgDir of ws.packages) {
-      const p = path.join(pkgDir, 'package.json')
-      try {
-        const stat = await fsp.stat(p)
-        const content = await fsp.readFile(p, 'utf-8')
-        const pkg = JSON.parse(content)
-        const deps = { ...pkg.dependencies, ...pkg.devDependencies }
-        parts.push(`${pkgDir}|${stat.mtimeMs}|${JSON.stringify(deps)}`)
-      } catch { /* missing package.json — skip */ }
-    }
-    return crypto.createHash('sha1').update(parts.join('\n')).digest('hex')
+    // Scoped to the running package — the scan now reads only this package's
+    // deps, so the cache key must track exactly the same set.
+    const p = path.join(projectRoot, 'package.json')
+    const stat = await fsp.stat(p)
+    const content = await fsp.readFile(p, 'utf-8')
+    const pkg = JSON.parse(content)
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies }
+    const part = `${projectRoot}|${stat.mtimeMs}|${JSON.stringify(deps)}`
+    return crypto.createHash('sha1').update(part).digest('hex')
   } catch { return null }
 }
 
@@ -189,9 +192,68 @@ export function clearComponentCache() {
   cachedManifestAt = 0
   inflightCatalog = null
   refreshing = null
+  cachedProjectLibrary = null
+  cachedProjectLibraryAt = 0
+}
+
+// ── Project components (the user's own src/ components, as a palette group) ──
+
+let cachedProjectLibrary: ScannedLibrary | null = null
+let cachedProjectLibraryAt = 0
+const PROJECT_CACHE_TTL_MS = 60 * 1000
+
+/**
+ * Scan the project's own `src/` components into a `ScannedLibrary` shaped like
+ * a node_modules library — the palette renders it as a pinned "Project" group
+ * with zero new shell types, and the properties panel reads local components'
+ * prop metadata from it. `module` is the `./src/…` project-relative specifier
+ * that `ensureComponentLoaded` already resolves through
+ * `/__annotask/preview-module` (raw /@fs/ import, reload-free).
+ */
+export async function scanProjectComponents(projectRoot: string): Promise<ScannedLibrary> {
+  if (cachedProjectLibrary && (Date.now() - cachedProjectLibraryAt) < PROJECT_CACHE_TTL_MS) {
+    return cachedProjectLibrary
+  }
+  const components: ScannedComponent[] = []
+  const seen = new Set<string>()
+  const srcDir = path.join(projectRoot, 'src')
+  try {
+    const files = await findLocalComponentFilesRecursive(srcDir)
+    for (const filePath of files) {
+      const name = extractComponentName(filePath)
+      // PascalCase only — same rule as generateComponentManifest.
+      if (!name || name[0] !== name[0].toUpperCase() || name[0] === name[0].toLowerCase()) continue
+      if (seen.has(name)) continue
+      seen.add(name)
+      const details = await extractComponentDetails(filePath)
+      const relPath = './' + path.relative(projectRoot, filePath).replace(/\\/g, '/')
+      components.push(makeComponent({
+        name,
+        module: relPath,
+        props: details.props,
+        slots: details.slots,
+        events: details.events,
+        description: details.description,
+        sourceFile: filePath,
+        providerSignals: details.providerSignals,
+      }))
+    }
+  } catch { /* src/ may not exist */ }
+  components.sort((a, b) => a.name.localeCompare(b.name))
+  cachedProjectLibrary = { name: 'Project', version: '', components }
+  cachedProjectLibraryAt = Date.now()
+  return cachedProjectLibrary
 }
 
 /** Build a ScannedComponent with sensible empty defaults for optional enrichment fields. */
+// Barrel scanning of some libraries (notably PrimeVue, whose `*Style` modules
+// are ~half its exports) picks up internal style/service/directive objects that
+// aren't renderable components. Drop them so the catalog shows real components.
+const NON_COMPONENT_NAME_RE = /(Style|Service|Directive)$/
+function isLikelyComponentName(name: string): boolean {
+  return !NON_COMPONENT_NAME_RE.test(name)
+}
+
 function makeComponent(fields: {
   name: string
   module: string
@@ -203,7 +265,9 @@ function makeComponent(fields: {
   tags?: string[]
   deprecated?: boolean
   sourceFile?: string | null
+  providerSignals?: string[]
 }): ScannedComponent {
+  const providerSignals = fields.providerSignals ?? []
   return {
     name: fields.name,
     module: fields.module,
@@ -215,9 +279,57 @@ function makeComponent(fields: {
     slots: fields.slots ?? [],
     events: fields.events ?? [],
     sourceFile: fields.sourceFile ?? null,
+    providerSignals,
+    fidelityHint: deriveFidelityHint(fields.sourceFile ?? null, providerSignals),
   }
 }
 
+/** Coarse fidelity hint for the palette. We only assert when we actually read
+ *  the component's source (local components). Library components (.d.ts-only,
+ *  no recorded sourceFile) stay 'unknown' — the live mount confirms. Vue mounts
+ *  share the host app's provides/router/components by reference, so a
+ *  provider-dependent Vue component usually still renders in context ('live');
+ *  React/Svelte/Solid mount detached with no provider tree, so provider deps
+ *  degrade ('isolated-preview'). */
+function deriveFidelityHint(
+  sourceFile: string | null,
+  providerSignals: string[],
+): ScannedComponent['fidelityHint'] {
+  if (!sourceFile) return 'unknown'
+  if (providerSignals.length === 0) return 'live'
+  return path.extname(sourceFile) === '.vue' ? 'live' : 'isolated-preview'
+}
+
+const PROVIDER_SIGNAL_RULES: Array<[RegExp, string]> = [
+  // Call sites (provider/context/router/data consumers).
+  [/\binject\s*\(/, 'inject'],
+  [/\bprovide\s*\(/, 'provide'],
+  [/\buseContext\s*\(/, 'useContext'],
+  [/\buseRouter\s*\(/, 'useRouter'],
+  [/\buseRoute\s*\(/, 'useRoute'],
+  [/\buseParams\s*\(/, 'useParams'],
+  [/\buseSearchParams\s*\(/, 'useSearchParams'],
+  [/\buseStore\s*\(/, 'useStore'],
+  [/\buse(Query|Mutation|InfiniteQuery)\s*\(/, 'useQuery'],
+  // Provider-bearing imports (router/query/store libs).
+  [/from\s+['"]vue-router['"]/, 'vue-router'],
+  [/from\s+['"]react-router(?:-dom)?['"]/, 'react-router'],
+  [/from\s+['"]@tanstack\/[a-z-]*query[a-z-]*['"]/, '@tanstack/query'],
+  [/from\s+['"]pinia['"]/, 'pinia'],
+  [/from\s+['"](?:vuex|react-redux|@reduxjs\/toolkit)['"]/, 'store'],
+]
+
+/** Scan component source for provider-dependence markers. Heuristic by design:
+ *  false positives degrade gracefully (the now-honest 'threw'/'isolated-preview'
+ *  path), false negatives are caught by the mount itself. */
+function detectProviderSignals(content: string): string[] {
+  const found = new Set<string>()
+  for (const [re, label] of PROVIDER_SIGNAL_RULES) {
+    if (re.test(content)) found.add(label)
+  }
+  return Array.from(found)
+}
+
 /** Heuristic category from component name/module path. Returns null when nothing matches. */
 function categorizeComponent(name: string, module: string): string | null {
   const haystack = (name + ' ' + module).toLowerCase()
@@ -397,20 +509,19 @@ function runScanOffThread(projectRoot: string): Promise<ComponentCatalog> {
 export async function scanComponentLibrariesUncached(projectRoot: string): Promise<ComponentCatalog> {
   const libraries: ScannedLibrary[] = []
 
-  // Aggregate dependencies across every workspace package so the host's
-  // catalog includes libs that only sibling MFEs depend on (e.g. host has
-  // Radix, sibling MFE has Mantine — both should appear).
-  const ws = await resolveWorkspace(projectRoot)
+  // Scope to the RUNNING package's own dependencies. Aggregating every
+  // workspace package made a standalone app inherit unrelated sibling apps'
+  // UI kits — a plain Vue app showed React's Mantine, Solid's Kobalte, web-
+  // component Shoelace, etc.: libraries it can never actually render. Run an
+  // MFE/app directly to scan its own libraries.
   const deps: Record<string, { version: string; from: string }> = {}
-  for (const pkgDir of ws.packages) {
-    try {
-      const pkg = JSON.parse(await fsp.readFile(path.join(pkgDir, 'package.json'), 'utf-8'))
-      const merged = { ...pkg.dependencies, ...pkg.devDependencies }
-      for (const [name, version] of Object.entries(merged)) {
-        if (!deps[name]) deps[name] = { version: String(version), from: pkgDir }
-      }
-    } catch { /* missing or unreadable package.json — skip this package */ }
-  }
+  try {
+    const pkg = JSON.parse(await fsp.readFile(path.join(projectRoot, 'package.json'), 'utf-8'))
+    const merged = { ...pkg.dependencies, ...pkg.devDependencies }
+    for (const [name, version] of Object.entries(merged)) {
+      if (!deps[name]) deps[name] = { version: String(version), from: projectRoot }
+    }
+  } catch { /* missing or unreadable package.json */ }
   if (Object.keys(deps).length === 0) return { libraries: [], scannedAt: Date.now() }
 
   // Scan every dependency in parallel. Each `scanLibrary` is largely async
@@ -566,6 +677,7 @@ async function scanLibrary(name: string, pkgDir: string, sourceDir?: string): Pr
     let slots: ScannedSlot[] = []
     let events: ScannedEvent[] = []
     let description: string | null = null
+    let providerSignals: string[] = []
 
     // Try to extract props from .d.ts first (most reliable)
     let dtsDescription: string | null = null
@@ -588,6 +700,7 @@ async function scanLibrary(name: string, pkgDir: string, sourceDir?: string): Pr
         slots = vueDetails.slots
         events = vueDetails.events
         description = vueDetails.description ?? dtsDescription
+        providerSignals = vueDetails.providerSignals
       }
     }
     if (!description) description = dtsDescription
@@ -599,6 +712,7 @@ async function scanLibrary(name: string, pkgDir: string, sourceDir?: string): Pr
       slots,
       events,
       description,
+      providerSignals,
     }))
   }
 
@@ -624,8 +738,12 @@ async function scanLibrary(name: string, pkgDir: string, sourceDir?: string): Pr
 
   if (components.length === 0) return null
 
-  components.sort((a, b) => a.name.localeCompare(b.name))
-  return { name, version, components }
+  // Drop internal *Style/*Service/*Directive exports (keep the originals only if
+  // filtering would somehow remove everything, so we never hide a whole lib).
+  const real = components.filter(c => isLikelyComponentName(c.name))
+  const finalComponents = real.length > 0 ? real : components
+  finalComponents.sort((a, b) => a.name.localeCompare(b.name))
+  return { name, version, components: finalComponents }
 }
 
 /**
@@ -1064,6 +1182,7 @@ async function collectComponentExports(
         events: details.events,
         description: details.description,
         sourceFile: resolved,
+        providerSignals: details.providerSignals,
       }))
     } else {
       // JS/TS file — follow the chain. If the chain produces nothing AND the
@@ -1499,22 +1618,27 @@ export interface ExtractedComponentDetails {
   slots: ScannedSlot[]
   events: ScannedEvent[]
   description: string | null
+  providerSignals: string[]
 }
 
-/** Extract full component metadata (props + slots + events + description) from a source file. */
+/** Extract full component metadata (props + slots + events + description +
+ *  provider signals) from a source file. */
 async function extractComponentDetails(filePath: string): Promise<ExtractedComponentDetails> {
   const ext = path.extname(filePath)
-  const empty: ExtractedComponentDetails = { props: [], slots: [], events: [], description: null }
+  const empty: ExtractedComponentDetails = { props: [], slots: [], events: [], description: null, providerSignals: [] }
 
   let content: string
   try { content = await fsp.readFile(filePath, 'utf-8') } catch { return empty }
 
+  const providerSignals = detectProviderSignals(content)
+
   if (ext === '.vue') {
     return {
       props: await extractPropsFromVue(filePath),
       slots: extractSlotsFromVueContent(content),
       events: extractEventsFromVueContent(content),
       description: extractComponentJsDoc(content),
+      providerSignals,
     }
   }
   if (ext === '.tsx' || ext === '.jsx') {
@@ -1523,6 +1647,7 @@ async function extractComponentDetails(filePath: string): Promise<ExtractedCompo
       slots: [],
       events: [],
       description: extractComponentJsDoc(content),
+      providerSignals,
     }
   }
   if (ext === '.svelte') {
@@ -1531,6 +1656,7 @@ async function extractComponentDetails(filePath: string): Promise<ExtractedCompo
       slots: extractSlotsFromSvelteContent(content),
       events: [],
       description: extractComponentJsDoc(content),
+      providerSignals,
     }
   }
   return empty
@@ -1657,6 +1783,12 @@ async function extractPropsFromVue(vuePath: string): Promise<ScannedProp[]> {
   // Strategy A: defineProps<InterfaceName>() with TypeScript interface
   props = extractPropsFromTsInterface(content)
 
+  // Strategy A2: inline type literal — defineProps<{ planet: Planet; active?: boolean }>()
+  if (props.length === 0) {
+    const inline = content.match(/defineProps\s*<\s*\{([\s\S]*?)\}\s*>\s*\(/)
+    if (inline) props = parseTypeLiteralProps(inline[1])
+  }
+
   // Strategy B: defineProps({ prop: { type: String, ... } }) — object literal
   if (props.length === 0) {
     const definePropsObj = content.match(/defineProps\s*\(\s*\{([\s\S]*?)\}\s*\)/)
@@ -1743,6 +1875,36 @@ async function extractPropsFromSvelte(filePath: string): Promise<ScannedProp[]>
  * If `interfaceName` is given, look for that specific interface.
  * Otherwise, find the interface referenced by defineProps<X>() or $props<X>().
  */
+/** Parse the members of an inline TS type literal (`planet: Planet; active?: boolean`).
+ *  Splits on `;`/`,` at nesting depth 0 so object/generic/function member types
+ *  survive — single-line literals are the common `defineProps<{ … }>()` form. */
+function parseTypeLiteralProps(body: string): ScannedProp[] {
+  const members: string[] = []
+  let depth = 0
+  let current = ''
+  for (const ch of body) {
+    if (ch === '{' || ch === '(' || ch === '[' || ch === '<') depth++
+    else if (ch === '}' || ch === ')' || ch === ']' || ch === '>') depth--
+    if ((ch === ';' || ch === ',' || ch === '\n') && depth === 0) {
+      members.push(current)
+      current = ''
+      continue
+    }
+    current += ch
+  }
+  members.push(current)
+
+  const props: ScannedProp[] = []
+  for (const member of members) {
+    const m = /^\s*(\w+)(\??)\s*:\s*([\s\S]+?)\s*$/.exec(member)
+    if (!m) continue
+    let type = m[3].replace(/\/\/.*$/m, '').trim()
+    if (type.length > 400) type = type.slice(0, 397) + '...'
+    props.push({ name: m[1], type: type || null, required: m[2] !== '?', description: null, default: null })
+  }
+  return props
+}
+
 function extractPropsFromTsInterface(content: string, interfaceName?: string): ScannedProp[] {
   // Auto-detect interface name from defineProps<X>() or $props<X>()
   if (!interfaceName) {
diff --git a/src/server/component-usage.ts b/src/server/component-usage.ts
index 4734c53..4c4bac7 100644
--- a/src/server/component-usage.ts
+++ b/src/server/component-usage.ts
@@ -54,18 +54,18 @@ export async function scanComponentUsage(projectRoot: string): Promise<Component
 }
 
 async function scanUncached(projectRoot: string): Promise<ComponentUsageMap> {
-  // Walk every workspace package so the host's annotask sees imports from
-  // sibling MFEs. When not inside a workspace, this collapses to scanning
-  // projectRoot alone.
+  // Scope to the RUNNING package only. Walking every workspace package pulled
+  // in unrelated sibling apps' imports (a Vue app would show a sibling React
+  // app's component usages), polluting on-page detection. Paths stay
+  // workspace-relative (against `ws.root`) so the shell's currentDir
+  // translation still lines them up with the iframe's data-annotask-file.
   const ws = await resolveWorkspace(projectRoot)
   const relRoot = ws.root
   const files: string[] = []
-  for (const pkgDir of ws.packages) {
-    const srcDir = nodePath.join(pkgDir, 'src')
-    const scanRoot = fs.existsSync(srcDir) ? srcDir : pkgDir
-    await walk(scanRoot, files)
-    if (files.length >= MAX_FILES_SCANNED) break
-  }
+  const absRoot = nodePath.resolve(projectRoot)
+  const srcDir = nodePath.join(absRoot, 'src')
+  const scanRoot = fs.existsSync(srcDir) ? srcDir : absRoot
+  await walk(scanRoot, files)
 
   const usage: Record<string, Set<string>> = {}
   const imports: Record<string, Record<string, Set<string>>> = {}
diff --git a/src/server/data-source-scanner.ts b/src/server/data-source-scanner.ts
index a8e9c9c..e70126f 100644
--- a/src/server/data-source-scanner.ts
+++ b/src/server/data-source-scanner.ts
@@ -136,32 +136,28 @@ export async function scanDataSources(projectRoot: string): Promise<DataSourceCa
 }
 
 async function scanDataSourcesUncached(projectRoot: string): Promise<DataSourceCatalog> {
-  // 1. Read package.json deps across every workspace package
+  // 1. Read package.json deps for the RUNNING package only. Aggregating every
+  //    workspace package surfaced sibling apps' data libraries + entries (a Vue
+  //    app would show another app's hooks and endpoints), polluting the catalog
+  //    and the on-page data highlights — the same over-reach fixed in the
+  //    component scanner. Run an MFE/app directly to scan its own data sources.
   const ws = await resolveWorkspace(projectRoot)
-  const deps: Record<string, string> = {}
-  for (const pkgDir of ws.packages) {
-    const pkgDeps = await readDeps(pkgDir)
-    for (const [name, v] of Object.entries(pkgDeps)) {
-      if (!deps[name]) deps[name] = v
-    }
-  }
+  const deps: Record<string, string> = await readDeps(projectRoot)
   const libraryCandidates: Array<{ name: string; version?: string; patterns: string[] }> = []
   for (const depName of Object.keys(deps)) {
     const patterns = DATA_LIB_PATTERNS[depName]
     if (patterns) libraryCandidates.push({ name: depName, version: deps[depName], patterns })
   }
 
-  // 2. Walk src/ of every workspace package and read every candidate file
-  //    into memory once. Paths are relativized against the workspace root so
-  //    cross-MFE references resolve unambiguously.
+  // 2. Walk the running package's src/ once, reading every candidate file into
+  //    memory. Paths are relativized against the workspace root (`ws.root`) so
+  //    they stay workspace-relative for the shell's currentDir translation.
   const relRoot = ws.root
   const files: string[] = []
-  for (const pkgDir of ws.packages) {
-    const srcDir = nodePath.join(pkgDir, 'src')
-    const scanRoot = fs.existsSync(srcDir) ? srcDir : pkgDir
-    await walk(scanRoot, files)
-    if (files.length >= MAX_FILES_SCANNED) break
-  }
+  const absRoot = nodePath.resolve(projectRoot)
+  const srcDir = nodePath.join(absRoot, 'src')
+  const scanRoot = fs.existsSync(srcDir) ? srcDir : absRoot
+  await walk(scanRoot, files)
 
   const fileContents = new Map<string, string>()
   for (const fp of files) {
diff --git a/src/server/data-source-shape.ts b/src/server/data-source-shape.ts
new file mode 100644
index 0000000..a35edd6
--- /dev/null
+++ b/src/server/data-source-shape.ts
@@ -0,0 +1,180 @@
+/**
+ * Shape resolution for the wireframe data-binding picker. Given a data-source
+ * name from the scanner catalog, answer "what shape does this source yield?"
+ * down an honesty ladder:
+ *
+ *   1. 'api-schema'     — the entry's endpoint matches a discovered API
+ *                         operation (resolveEndpoint); walk its already-deref'd
+ *                         response_schema into a DataShapeNode tree.
+ *   2. 'source-details' — no schema match; surface the regex-inferred
+ *                         return-type hints verbatim. NO tree — expanding a
+ *                         type name into keys would fabricate shape.
+ *   3. 'none'           — nothing known. The picker shows free-text entry,
+ *                         visibly blind.
+ *
+ * Runtime-discovered entries are excluded up front: they have no code
+ * identity (`file: ''`) the agent could import, and runtime endpoints carry
+ * no response shapes (sample URLs only).
+ */
+import { scanDataSources } from './data-source-scanner.js'
+import { scanApiSchemas, type ScanOptions } from './api-schema-scanner.js'
+import { resolveEndpoint } from './api-schema-resolver.js'
+import { resolveDataSourceDetails } from './data-source-details.js'
+import type { DataShapeNode, DataSource, DataSourceShape, DataSourceShapeResult } from '../schema.js'
+
+const MAX_SHAPE_DEPTH = 8
+
+/**
+ * Walk a (deref'd) JSON-schema-ish object into a DataShapeNode tree. Residual
+ * `$ref` (cycle markers from resolveRefs) and GraphQL `$type` markers become
+ * named ref leaves. `allOf` merges object children; `oneOf`/`anyOf` take the
+ * first object-ish variant (minimal honest handling, unit-pinned).
+ */
+export function schemaToShape(schema: Record<string, unknown>, depth = 0): DataShapeNode {
+  if (depth > MAX_SHAPE_DEPTH) return { kind: 'unknown' }
+
+  const ref = schema.$ref
+  if (typeof ref === 'string') {
+    const tail = ref.split('/').pop()
+    return { kind: 'ref', ref: tail || ref }
+  }
+  const gqlType = schema.$type
+  if (typeof gqlType === 'string') return { kind: 'ref', ref: gqlType }
+
+  // REAL contract sample value at this node (OpenAPI `example`/`default`), used
+  // to preview bound props honestly. Spread onto each structural return below.
+  const ex = schema.example !== undefined ? schema.example : schema.default
+  const exField = ex !== undefined ? { example: ex } : {}
+
+  const type = schema.type
+  if (type === 'array' || (schema.items !== undefined && type === undefined)) {
+    const items = schema.items
+    const item = isPlainObject(items) ? schemaToShape(items, depth + 1) : { kind: 'unknown' as const }
+    return { kind: 'array', item, ...exField }
+  }
+
+  if (type === 'object' || isPlainObject(schema.properties)) {
+    const children: Record<string, DataShapeNode> = {}
+    // Composition first — `{ type:'object', allOf:[…] }` and
+    // `{ allOf:[…], properties:{…} }` are common OpenAPI inheritance forms;
+    // own properties extend/override the inherited keys.
+    if (Array.isArray(schema.allOf)) {
+      for (const member of schema.allOf) {
+        if (!isPlainObject(member)) continue
+        const walked = schemaToShape(member, depth + 1)
+        if (walked.kind === 'object' && walked.children) Object.assign(children, walked.children)
+      }
+    }
+    const props = schema.properties
+    if (isPlainObject(props)) {
+      for (const [key, value] of Object.entries(props)) {
+        children[key] = isPlainObject(value) ? schemaToShape(value, depth + 1) : { kind: 'unknown' }
+      }
+    }
+    return { kind: 'object', children, ...exField }
+  }
+
+  if (Array.isArray(schema.allOf)) {
+    const children: Record<string, DataShapeNode> = {}
+    let sawObject = false
+    for (const member of schema.allOf) {
+      if (!isPlainObject(member)) continue
+      const walked = schemaToShape(member, depth + 1)
+      if (walked.kind === 'object' && walked.children) {
+        sawObject = true
+        Object.assign(children, walked.children)
+      }
+    }
+    if (sawObject) return { kind: 'object', children, ...exField }
+    return { kind: 'unknown' }
+  }
+
+  const variants = Array.isArray(schema.oneOf) ? schema.oneOf : Array.isArray(schema.anyOf) ? schema.anyOf : null
+  if (variants) {
+    for (const member of variants) {
+      if (!isPlainObject(member)) continue
+      const walked = schemaToShape(member, depth + 1)
+      if (walked.kind === 'object' || walked.kind === 'array' || walked.kind === 'ref') return walked
+    }
+    return { kind: 'unknown' }
+  }
+
+  if (typeof type === 'string') return { kind: 'scalar', scalar: type, ...exField }
+  return { kind: 'unknown' }
+}
+
+export interface ShapeArgs {
+  projectRoot: string
+  name: string
+  kind?: DataSource['kind']
+  file?: string
+  workspaceRoot?: string
+  /** Schema-scan options (devServerUrl, explicit files/urls). Explicit
+   *  files/urls skip dev-server probes — tests stay offline. */
+  schemaScan?: ScanOptions
+}
+
+export async function resolveDataSourceShape(args: ShapeArgs): Promise<DataSourceShapeResult> {
+  const { projectRoot, name, kind, file, workspaceRoot } = args
+
+  const catalog = await scanDataSources(projectRoot)
+  // Runtime-promoted entries have no code identity to bind to — exclude.
+  let candidates = catalog.project_entries.filter(e => e.name === name && e.discovered_by !== 'runtime')
+  if (kind) candidates = candidates.filter(e => e.kind === kind)
+  if (file) candidates = candidates.filter(e => e.file === file)
+
+  if (candidates.length === 0) return { error: 'not_found', name }
+  if (candidates.length > 1) {
+    return {
+      error: 'ambiguous',
+      candidates: candidates.map(c => ({ name: c.name, kind: c.kind, file: c.file, line: c.line ?? 1 })),
+    }
+  }
+
+  const entry = candidates[0]
+  const base: DataSourceShape = {
+    name: entry.name,
+    kind: entry.kind,
+    file: entry.file,
+    ...(entry.endpoint ? { endpoint: entry.endpoint } : {}),
+    ...(entry.method ? { method: entry.method } : {}),
+    shape_source: 'none',
+  }
+
+  // Rung 1 — a real API contract behind the entry's endpoint.
+  const url = entry.resolved_endpoint ?? entry.endpoint
+  if (url) {
+    const schemas = await scanApiSchemas(projectRoot, args.schemaScan ?? {})
+    const match = resolveEndpoint(schemas, url, entry.method)
+    if (match?.operation.response_schema) {
+      return {
+        ...base,
+        shape_source: 'api-schema',
+        shape: schemaToShape(match.operation.response_schema),
+        ...(match.response_schema_ref ? { schema_ref: match.response_schema_ref } : {}),
+        schema_kind: match.schema_kind,
+        match_confidence: match.confidence,
+      }
+    }
+  }
+
+  // Rung 2 — regex-inferred hints, verbatim.
+  const details = await resolveDataSourceDetails({ projectRoot, name: entry.name, kind: entry.kind, file: entry.file, workspaceRoot })
+  if (!('error' in details) && (details.return_type || (details.referenced_types?.length ?? 0) > 0)) {
+    return {
+      ...base,
+      shape_source: 'source-details',
+      details_confidence: details.confidence,
+      ...(details.return_type ? { return_type: details.return_type } : {}),
+      ...(details.referenced_types?.length ? { referenced_types: details.referenced_types } : {}),
+      ...(details.signature ? { signature: details.signature } : {}),
+    }
+  }
+
+  // Rung 3 — honestly nothing.
+  return base
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
diff --git a/src/server/file-snapshots.ts b/src/server/file-snapshots.ts
new file mode 100644
index 0000000..cfc10e9
--- /dev/null
+++ b/src/server/file-snapshots.ts
@@ -0,0 +1,538 @@
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { resolveProjectFile } from './path-safety.js'
+import type { ApplyBatch } from '../shared/design-session-types.js'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * File-snapshot engine — the safety net under the agent-apply loop.
+ *
+ * The tool NEVER authors application source; the embedded agent does. What the
+ * tool guarantees is byte-exact reversibility: before an apply batch spawns
+ * the agent, every file the batch touches is snapshotted here, so "Undo last
+ * apply" restores that batch's pre-apply bytes and "Discard session" restores
+ * every touched file to its session-base bytes.
+ *
+ * Journal: `.annotask/file-snapshots.json` (atomic tmp+rename, written BEFORE
+ * the agent runs). Restart REHYDRATES the journal — agent-written edits are
+ * intentional user work and survive dev-server restarts; files revert only
+ * via explicit Undo/Discard. (The old render-in-place draft engine auto-
+ * reverted on boot; its legacy journal gets that treatment exactly once.)
+ *
+ * Hash guard: a restore only happens when the file on disk still matches the
+ * hash recorded when its batch sealed. A mismatch means the USER edited the
+ * file since — the file flips to 'diverged', restores skip it, and the only
+ * resolution is detachFile (keep the disk bytes, forget the file). Never
+ * clobber, never rebase silently.
+ *
+ * Byte-exact COVERAGE: the embedded agent edits freely — shared layouts,
+ * imported children, global CSS — not just the anchor files the apply
+ * predicted. In a git project we capture a baseline (`git stash create`, which
+ * snapshots the dirty working tree without touching it) BEFORE the agent runs,
+ * then at seal `git diff` the tree against it and fold EVERY touched tracked
+ * file into the batch (pre-apply bytes pulled from `git show`), so undo/discard
+ * restore the agent's whole footprint, not a partial subset. An agent-DELETED
+ * file is recreated from its held bytes on restore. Outside a git project (or a
+ * monorepo whose toplevel isn't the project root) coverage falls back to the
+ * predicted anchor files only — documented, never silent.
+ */
+
+function sha256(s: string): string {
+  return crypto.createHash('sha256').update(s).digest('hex')
+}
+
+interface SnapshotFileEntry {
+  absPath: string
+  /** Session-base bytes — captured ONCE, the first time any batch touches the file. */
+  base: string
+  baseHash: string
+  /** sha256 of the file when its latest batch sealed; the restore hash-guard. */
+  lastAppliedHash?: string
+  status: 'clean' | 'diverged'
+}
+
+interface SnapshotBatch extends ApplyBatch {
+  /** Pre-batch bytes per file — what "Undo last apply" restores. Seeded with
+   *  the predicted anchor files at snapshot time, then EXTENDED at seal with
+   *  every other tracked file the agent touched (bytes from `git show
+   *  gitBaseline:file`) so undo covers the agent's whole footprint. */
+  before: Record<string, string>
+  /** Untracked files at snapshot time (git projects only) — the baseline the
+   *  seal diffs against to net agent-CREATED files into undo. */
+  untrackedBefore?: string[]
+  /** `git stash create` SHA (or HEAD when the tree was clean) captured at
+   *  snapshot time — the pre-apply tree the seal diffs against to discover
+   *  agent-touched files and recover their pre-apply bytes. Absent outside a
+   *  git project / when the repo toplevel isn't the project root. */
+  gitBaseline?: string
+  /** Files the agent created during this batch (rel path → sha256 at seal).
+   *  Undo deletes them hash-guarded; a user-edited created file is kept. */
+  created?: Record<string, string>
+}
+
+interface SnapshotJournal {
+  version: 1
+  files: Record<string, SnapshotFileEntry>
+  batches: SnapshotBatch[]
+}
+
+export interface SnapshotState {
+  files: Record<string, { baseHash: string; lastAppliedHash?: string; status: 'clean' | 'diverged' }>
+  batches: Array<ApplyBatch & { created?: string[] }>
+}
+
+export interface SnapshotStore {
+  /** Capture pre-batch bytes for every file (and the session base on first touch).
+   *  Persisted BEFORE returning — the journal must exist before the agent runs. */
+  snapshotFiles(files: string[], batch: { id: string; taskId: string }): Promise<void>
+  /** Record post-apply hashes + finish the batch (the restore hash-guard baseline). */
+  sealBatch(batchId: string, opts?: { failed?: boolean }): Promise<void>
+  /** Seal the most-recent batch for a task — used by the review hook (which
+   *  knows the taskId, not the batchId) so re-apply-after-deny and
+   *  pure-instances applies still establish a hash baseline. No-op if no batch
+   *  matches; re-sealing is safe (only lastAppliedHash + the created net move). */
+  sealBatchByTask(taskId: string, opts?: { failed?: boolean }): Promise<void>
+  /** Restore the batch's pre-apply bytes. LIFO-only: only the newest batch can
+   *  be undone (out-of-order restores would resurrect older bytes). */
+  revertBatch(batchId: string): Promise<{ reverted: string[]; skipped: string[] }>
+  /** Discard: every touched file back to its session-base bytes (hash-guarded). */
+  revertAll(): Promise<{ reverted: string[]; skipped: string[] }>
+  /** Accept path: keep the bytes, drop the journal. */
+  commit(): Promise<void>
+  /** Diverged resolution: keep the disk bytes, forget the file entirely. */
+  detachFile(file: string): Promise<void>
+  /** Journal view with a fresh divergence hash-sweep. */
+  state(): Promise<SnapshotState>
+  flush(): Promise<void>
+}
+
+export function createSnapshotStore(projectRoot: string): SnapshotStore {
+  const journalPath = path.join(projectRoot, '.annotask', 'file-snapshots.json')
+  const legacyDraftJournalPath = path.join(projectRoot, '.annotask', 'draft-edits.json')
+
+  let journal: SnapshotJournal = { version: 1, files: {}, batches: [] }
+  // Serialize every mutation: rapid apply/undo clicks and lifecycle hooks must
+  // never interleave read-modify-write on the journal or the files.
+  let chain: Promise<unknown> = Promise.resolve()
+  function enqueue<T>(fn: () => Promise<T>): Promise<T> {
+    const run = chain.then(fn, fn)
+    chain = run.catch(() => { /* keep the chain alive */ })
+    return run
+  }
+
+  function resolveAbs(file: string): string {
+    // Containment: snapshot restores are the only tool-authored source writes,
+    // so targets must resolve inside projectRoot (same discipline as the old
+    // draft engine, via the shared resolveProjectFile guard).
+    if (file.includes('\0')) throw new Error(`Invalid snapshot target: ${file}`)
+    if (path.isAbsolute(file)) {
+      const rootAbs = path.resolve(projectRoot)
+      const abs = path.resolve(file)
+      const rootWithSep = rootAbs.endsWith(path.sep) ? rootAbs : rootAbs + path.sep
+      if (!abs.startsWith(rootWithSep)) {
+        throw new Error(`Snapshot target escapes the project root: ${file}`)
+      }
+      return abs
+    }
+    const resolved = resolveProjectFile(projectRoot, file)
+    if (!resolved) throw new Error(`Snapshot target escapes the project root: ${file}`)
+    return resolved.absolutePath
+  }
+
+  async function persist(): Promise<void> {
+    await fsp.mkdir(path.dirname(journalPath), { recursive: true })
+    const tmp = `${journalPath}.tmp.${process.pid}.${Date.now()}`
+    await fsp.writeFile(tmp, JSON.stringify(journal, null, 2), 'utf-8')
+    await fsp.rename(tmp, journalPath)
+  }
+
+  async function rehydrate(): Promise<void> {
+    try {
+      const raw = JSON.parse(await fsp.readFile(journalPath, 'utf-8'))
+      if (raw && typeof raw === 'object' && raw.version === 1 && raw.files && Array.isArray(raw.batches)) {
+        journal = raw as SnapshotJournal
+      }
+    } catch { /* no journal yet */ }
+    // Legacy v1 render-in-place journal: those drafts were preview artifacts,
+    // not user-intentional applies — give them the old restore-and-clear once.
+    try {
+      const legacy = JSON.parse(await fsp.readFile(legacyDraftJournalPath, 'utf-8')) as Record<string, { absPath: string; original: string; modifiedHash: string }>
+      let restored = 0
+      for (const entry of Object.values(legacy ?? {})) {
+        try {
+          const current = await fsp.readFile(entry.absPath, 'utf-8')
+          if (sha256(current) === entry.modifiedHash) {
+            await fsp.writeFile(entry.absPath, entry.original, 'utf-8')
+            restored++
+          }
+        } catch { /* file gone */ }
+      }
+      await fsp.rm(legacyDraftJournalPath, { force: true })
+      if (restored > 0) console.warn(`[Annotask] restored ${restored} legacy render-in-place draft(s)`)
+    } catch { /* no legacy journal */ }
+  }
+
+  const ready = rehydrate()
+
+  /** Untracked files per `git status --porcelain -uall` (gitignore-aware), or
+   *  null when this isn't a usable git project — the created-files net is then
+   *  silently off (snapshotted files still restore byte-exact). */
+  async function gitUntracked(): Promise<string[] | null> {
+    try {
+      const { stdout } = await execFileAsync(
+        'git', ['status', '--porcelain', '-uall', '--no-renames'],
+        { cwd: projectRoot, maxBuffer: 10 * 1024 * 1024 },
+      )
+      return stdout.split('\n')
+        .filter((l) => l.startsWith('?? '))
+        .map((l) => l.slice(3).trim())
+        // git quotes paths with special chars — those stay un-netted rather
+        // than risking a wrong unlink target.
+        .filter((f) => f && !f.startsWith('"') && !f.startsWith('.annotask/'))
+    } catch {
+      return null
+    }
+  }
+
+  /** Pre-apply baseline for the byte-exact auto-extend: `git stash create`
+   *  commits the dirty working tree + index to a dangling commit WITHOUT
+   *  touching the tree/index/refs, returning its SHA — exactly the pre-apply
+   *  snapshot we need. A clean tree produces no stash commit, so HEAD already
+   *  IS the baseline. Returns null when not a git project, or when the repo
+   *  toplevel isn't the project root (then `git show repo-rel:path` and our
+   *  project-relative paths would disagree — coverage falls back to anchors). */
+  async function gitBaselineRef(): Promise<string | null> {
+    try {
+      const { stdout: top } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd: projectRoot })
+      if (path.resolve(top.trim()) !== path.resolve(projectRoot)) return null
+      const { stdout: stash } = await execFileAsync('git', ['stash', 'create'], { cwd: projectRoot, maxBuffer: 1024 * 1024 })
+      const sha = stash.trim()
+      if (sha) return sha
+      const { stdout: head } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: projectRoot })
+      return head.trim() || null
+    } catch {
+      return null
+    }
+  }
+
+  /** Tracked files that differ between `baseline` and the current working tree
+   *  (added/modified/deleted) — the agent's footprint beyond the anchor set.
+   *  Created (still-untracked) files don't appear here; they ride the
+   *  untracked net. Project-relative, .annotask/ and quoted paths filtered. */
+  async function gitChangedSince(baseline: string): Promise<string[]> {
+    const { stdout } = await execFileAsync(
+      'git', ['diff', '--name-only', '--no-renames', '--relative', baseline, '--'],
+      { cwd: projectRoot, maxBuffer: 50 * 1024 * 1024 },
+    )
+    return stdout.split('\n').map((s) => s.trim())
+      .filter((f) => f && !f.startsWith('"') && !f.startsWith('.annotask/'))
+  }
+
+  /** Pre-apply content of one tracked file from the baseline tree. null when the
+   *  file didn't exist there (i.e. the agent CREATED it — handled by the
+   *  untracked net, not here). */
+  async function gitShow(baseline: string, file: string): Promise<string | null> {
+    try {
+      const { stdout } = await execFileAsync('git', ['show', `${baseline}:${file}`], { cwd: projectRoot, maxBuffer: 50 * 1024 * 1024 })
+      return stdout
+    } catch {
+      return null
+    }
+  }
+
+  /** Seal a found batch in place: fold in every other tracked file the agent
+   *  touched (byte-exact coverage), record each touched file's post-apply hash
+   *  (the restore guard baseline), and net agent-CREATED files into the batch.
+   *  Idempotent enough to re-run on a second review — pre-apply bytes are only
+   *  ever captured once per file (first touch wins). */
+  async function sealBatchInternal(batch: SnapshotBatch, opts?: { failed?: boolean }): Promise<void> {
+    // Auto-extend: fold every tracked file the agent changed beyond the
+    // predicted anchor set into the batch, recovering its pre-apply bytes from
+    // the baseline tree. Undo/discard then restore the agent's whole footprint.
+    if (batch.gitBaseline) {
+      try {
+        const known = new Set(batch.files)
+        for (const file of await gitChangedSince(batch.gitBaseline)) {
+          if (known.has(file)) continue
+          const pre = await gitShow(batch.gitBaseline, file)
+          if (pre === null) continue // created (not in baseline) — netted separately
+          let absPath: string
+          try { absPath = resolveAbs(file) } catch { continue } // escapes root — leave it
+          batch.before[file] = pre
+          batch.files.push(file)
+          known.add(file)
+          // Session base captured on first touch only (the pre-SESSION bytes);
+          // a file an earlier batch already snapshotted keeps that earlier base.
+          if (!journal.files[file]) {
+            journal.files[file] = { absPath, base: pre, baseHash: sha256(pre), status: 'clean' }
+          }
+        }
+      } catch { /* diff/show failed — anchor-only coverage stands, never crash the seal */ }
+    }
+    for (const file of batch.files) {
+      const entry = journal.files[file]
+      if (!entry) continue
+      try {
+        entry.lastAppliedHash = sha256(await fsp.readFile(entry.absPath, 'utf-8'))
+      } catch { /* file deleted by the agent — restore will recreate it */ }
+    }
+    // Net agent-CREATED files into the batch: anything newly untracked since
+    // the snapshot baseline (and not already a snapshotted target) belongs to
+    // this apply, hashed so undo only deletes pristine copies.
+    if (batch.untrackedBefore) {
+      const after = await gitUntracked()
+      if (after) {
+        const baseline = new Set(batch.untrackedBefore)
+        const snapshotted = new Set(batch.files)
+        const created: Record<string, string> = {}
+        for (const file of after) {
+          if (baseline.has(file) || snapshotted.has(file)) continue
+          try {
+            const abs = resolveAbs(file)
+            created[file] = sha256(await fsp.readFile(abs, 'utf-8'))
+          } catch { /* unreadable/escaping — leave it alone */ }
+        }
+        if (Object.keys(created).length > 0) batch.created = created
+      }
+    }
+    batch.finishedAt = Date.now()
+    batch.status = opts?.failed ? 'failed' : 'done'
+  }
+
+  /** Hash-guarded restore of one file to `bytes` (its pre-apply content).
+   *  Recreates an agent-DELETED file (mkdir -p + write) — that IS the byte-exact
+   *  undo, and the old code silently dropped it. Returns false (and marks
+   *  diverged) only when the disk state isn't the one our seal left behind:
+   *  the USER edited or deleted/created it since, so restoring would clobber
+   *  their work. `lastAppliedHash` is the seal fingerprint — undefined means the
+   *  file was ABSENT at seal (the agent deleted it during the apply). */
+  async function restoreFile(relFile: string, bytes: string): Promise<boolean> {
+    const entry = journal.files[relFile]
+    if (!entry) return false
+    const expected = entry.lastAppliedHash
+    let current: string | null = null
+    try {
+      current = await fsp.readFile(entry.absPath, 'utf-8')
+    } catch {
+      current = null // absent on disk now
+    }
+    if (current !== null) {
+      // Present now. Absent at seal (expected undefined) ⇒ the user re-created
+      // it after the agent deleted it — don't clobber. Otherwise it must still
+      // match the sealed bytes, or the user edited it since.
+      if (expected === undefined || sha256(current) !== expected) {
+        entry.status = 'diverged'
+        return false
+      }
+    } else {
+      // Absent now. Present at seal (expected set) ⇒ the user deleted it since —
+      // don't silently resurrect. Absent at seal too ⇒ agent-deleted, untouched
+      // by the user → recreate it from the held pre-apply bytes.
+      if (expected !== undefined) {
+        entry.status = 'diverged'
+        return false
+      }
+    }
+    await fsp.mkdir(path.dirname(entry.absPath), { recursive: true })
+    await fsp.writeFile(entry.absPath, bytes, 'utf-8')
+    entry.lastAppliedHash = sha256(bytes)
+    return true
+  }
+
+  return {
+    snapshotFiles(files, batch) {
+      return enqueue(async () => {
+        await ready
+        const before: Record<string, string> = {}
+        for (const file of files) {
+          // Defensive: an empty/falsy target can't resolve (resolveAbs('')
+          // throws). Callers should filter anchorless blocks, but never let one
+          // bad entry abort the whole snapshot and strand a task with no batch.
+          if (!file) continue
+          const absPath = resolveAbs(file)
+          let bytes = ''
+          try { bytes = await fsp.readFile(absPath, 'utf-8') } catch { bytes = '' }
+          before[file] = bytes
+          if (!journal.files[file]) {
+            // First apply wins: the session base is the pre-SESSION state.
+            journal.files[file] = { absPath, base: bytes, baseHash: sha256(bytes), status: 'clean' }
+          }
+        }
+        const untrackedBefore = await gitUntracked()
+        const gitBaseline = await gitBaselineRef()
+        journal.batches.push({
+          id: batch.id, taskId: batch.taskId, files: [...files], startedAt: Date.now(), status: 'running', before,
+          ...(untrackedBefore !== null ? { untrackedBefore } : {}),
+          ...(gitBaseline ? { gitBaseline } : {}),
+        })
+        await persist()
+      })
+    },
+
+    sealBatch(batchId, opts) {
+      return enqueue(async () => {
+        await ready
+        const batch = journal.batches.find((b) => b.id === batchId)
+        if (!batch) return
+        await sealBatchInternal(batch, opts)
+        await persist()
+      })
+    },
+
+    sealBatchByTask(taskId, opts) {
+      return enqueue(async () => {
+        await ready
+        // Newest batch for the task (one task → one batch today; reverse keeps
+        // this correct if that ever changes).
+        const batch = [...journal.batches].reverse().find((b) => b.taskId === taskId)
+        if (!batch) return
+        await sealBatchInternal(batch, opts)
+        await persist()
+      })
+    },
+
+    revertBatch(batchId) {
+      return enqueue(async () => {
+        await ready
+        const last = journal.batches[journal.batches.length - 1]
+        if (!last || last.id !== batchId) {
+          throw new Error('Only the most recent apply batch can be undone')
+        }
+        // A 'running' batch is unsealed — its files have no lastAppliedHash, so
+        // restoreFile would clobber the agent's in-progress bytes with no guard.
+        // Abandoned runs are sealed 'failed' first (releaseApplyTask), so this
+        // only ever refuses a batch whose agent is genuinely still writing.
+        if (last.status === 'running') {
+          throw new Error('This apply is still running — wait for it to finish before undoing')
+        }
+        const reverted: string[] = []
+        const skipped: string[] = []
+        for (const [file, bytes] of Object.entries(last.before)) {
+          if (await restoreFile(file, bytes)) reverted.push(file)
+          else skipped.push(file)
+        }
+        // Agent-created files: delete only pristine copies (seal-time hash).
+        // A user-edited created file is THEIR work now — keep it, report it.
+        for (const [file, hash] of Object.entries(last.created ?? {})) {
+          try {
+            const abs = resolveAbs(file)
+            if (sha256(await fsp.readFile(abs, 'utf-8')) === hash) {
+              await fsp.unlink(abs)
+              reverted.push(file)
+            } else {
+              skipped.push(file)
+            }
+          } catch { /* already gone — nothing to undo */ }
+        }
+        journal.batches.pop()
+        // Files whose only batch was this one and whose bytes are back at the
+        // session base carry no session state — drop them so a fully-undone
+        // session leaves an empty journal.
+        for (const file of Object.keys(last.before)) {
+          const stillReferenced = journal.batches.some((b) => file in b.before)
+          const entry = journal.files[file]
+          if (!stillReferenced && entry && entry.status === 'clean' && entry.lastAppliedHash === entry.baseHash) {
+            delete journal.files[file]
+          }
+        }
+        await persist()
+        return { reverted, skipped }
+      })
+    },
+
+    revertAll() {
+      return enqueue(async () => {
+        await ready
+        // Same guard as revertBatch: never discard over a live, unsealed run.
+        if (journal.batches.some((b) => b.status === 'running')) {
+          throw new Error('An apply is still running — wait for it to finish before discarding')
+        }
+        const reverted: string[] = []
+        const skipped: string[] = []
+        for (const [file, entry] of Object.entries(journal.files)) {
+          if (await restoreFile(file, entry.base)) {
+            reverted.push(file)
+            delete journal.files[file]
+          } else {
+            skipped.push(file)
+          }
+        }
+        // Discard removes every batch's pristine agent-created files too —
+        // newest batch first, so a file created then edited by a LATER batch
+        // is judged against the hash that sealed last.
+        const seen = new Set<string>()
+        for (const batch of [...journal.batches].reverse()) {
+          for (const [file, hash] of Object.entries(batch.created ?? {})) {
+            if (seen.has(file)) continue
+            seen.add(file)
+            try {
+              const abs = resolveAbs(file)
+              if (sha256(await fsp.readFile(abs, 'utf-8')) === hash) {
+                await fsp.unlink(abs)
+                reverted.push(file)
+              } else {
+                skipped.push(file)
+              }
+            } catch { /* already gone */ }
+          }
+        }
+        journal.batches = []
+        await persist()
+        return { reverted, skipped }
+      })
+    },
+
+    commit() {
+      return enqueue(async () => {
+        await ready
+        journal = { version: 1, files: {}, batches: [] }
+        try { await fsp.rm(journalPath, { force: true }) } catch { /* ignore */ }
+      })
+    },
+
+    detachFile(file) {
+      return enqueue(async () => {
+        await ready
+        delete journal.files[file]
+        for (const batch of journal.batches) {
+          delete batch.before[file]
+          batch.files = batch.files.filter((f) => f !== file)
+        }
+        journal.batches = journal.batches.filter((b) => b.files.length > 0)
+        await persist()
+      })
+    },
+
+    state() {
+      return enqueue(async () => {
+        await ready
+        // Divergence sweep: cheap (few files per session) and keeps the panel honest.
+        for (const entry of Object.values(journal.files)) {
+          if (entry.lastAppliedHash === undefined || entry.status === 'diverged') continue
+          try {
+            const current = await fsp.readFile(entry.absPath, 'utf-8')
+            if (sha256(current) !== entry.lastAppliedHash) entry.status = 'diverged'
+          } catch { entry.status = 'diverged' }
+        }
+        return {
+          files: Object.fromEntries(Object.entries(journal.files).map(([file, e]) => [
+            file,
+            { baseHash: e.baseHash, ...(e.lastAppliedHash !== undefined ? { lastAppliedHash: e.lastAppliedHash } : {}), status: e.status },
+          ])),
+          batches: journal.batches.map(({ before: _before, untrackedBefore: _ub, created, ...batch }) => ({
+            ...batch,
+            ...(created && Object.keys(created).length > 0 ? { created: Object.keys(created) } : {}),
+          })),
+        }
+      })
+    },
+
+    flush() {
+      return enqueue(async () => { await ready })
+    },
+  }
+}
diff --git a/src/server/index.ts b/src/server/index.ts
index 8234fcf..03d1751 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -6,6 +6,13 @@ import { createShellMiddleware } from './serve-shell.js'
 import { createProjectState, type ProjectState } from './state.js'
 import { createMcpMiddleware } from '../mcp/server.js'
 import { onCatalogRefreshed, scanComponentLibraries } from './component-scanner.js'
+import { createTaskThreadStore } from './task-thread.js'
+import { createAgentSpawnHandler } from './agent-spawn.js'
+import { createAgentDetector } from './agent-detect.js'
+import { createInitRunner } from './init.js'
+import { createUsageLedger } from './usage-ledger.js'
+import { createSnapshotStore } from './file-snapshots.js'
+import { releaseApplyTask, type ApplySessionOptions } from './apply-session.js'
 
 export interface AnnotaskServer {
   middleware: (req: IncomingMessage, res: ServerResponse, next: () => void) => void
@@ -23,22 +30,194 @@ export interface AnnotaskServerOptions {
   apiSchemaUrls?: string[]
   /** Extra project-relative schema file paths. */
   apiSchemaFiles?: string[]
+  /** Hostnames allowed in the Host header beyond localhost / IP literals —
+   *  the host the server announces plus any user-configured allowed hosts.
+   *  A function because the bind host is only known once listening starts. */
+  allowedHosts?: () => readonly string[]
 }
 
 export function createAnnotaskServer(options: AnnotaskServerOptions): AnnotaskServer {
   const wsServer = createWSServer()
-  const state = createProjectState(options.projectRoot, wsServer.broadcast)
+  // Forward-declared so state.ts can notify the init runner when its source
+  // of truth (design-spec.json) is unlinked, and the task-thread store when a
+  // task is removed for good. Both are built below; until then these are
+  // no-op callbacks.
+  let onSpecCleared: () => void = () => { /* set below */ }
+  let onTaskRemoved: (taskId: string) => void = () => { /* set below */ }
+  const state = createProjectState(options.projectRoot, wsServer.broadcast, {
+    onSpecCleared: () => onSpecCleared(),
+    onTaskRemoved: (taskId) => onTaskRemoved(taskId),
+  })
+  // Embedded-chat moving parts: per-task message log, subprocess streamer,
+  // CLI-detection probe. All scoped to this server instance so a single
+  // dispose() tears them down cleanly.
+  // Project-wide token usage ledger. Used by:
+  //   - task-thread onAppend (every assistant turn that carries usage)
+  //   - init runner (token totals reported by the local CLI on finish)
+  // It's an append-only JSONL so external tooling can `tail -f` and so the
+  // shell, CLI, and MCP all read the same canonical record.
+  const usageLedger = createUsageLedger({ projectRoot: options.projectRoot })
+  const taskThread = createTaskThreadStore({
+    projectRoot: options.projectRoot,
+    onAppend: (taskId, msg) => {
+      // Only assistant turns carry usage; user/tool messages are no-ops here.
+      const u = msg.usage
+      if (!u) return
+      // Fire-and-forget (must not block the SSE response) but surface failures:
+      // the usage ledger is the only audit trail for autonomous-agent spend, so
+      // a silent disk/permission error would let accounting drift unnoticed.
+      void state.addTaskUsage(taskId, {
+        inputTokens: u.inputTokens,
+        outputTokens: u.outputTokens,
+        cacheReadTokens: u.cacheReadTokens ?? 0,
+        cacheCreationTokens: u.cacheCreationTokens ?? 0,
+      }).catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn(`[annotask] addTaskUsage failed for task ${taskId}:`, err)
+      })
+      void usageLedger.append({
+        scope: 'task',
+        taskId,
+        ts: msg.ts,
+        providerId: msg.providerId,
+        model: msg.model,
+        inputTokens: u.inputTokens,
+        outputTokens: u.outputTokens,
+        cacheReadTokens: u.cacheReadTokens,
+        cacheCreationTokens: u.cacheCreationTokens,
+      }).catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn(`[annotask] usage ledger append failed for task ${taskId}:`, err)
+      })
+    },
+  })
+  // Transcript cleanup: accept/delete clean every other per-task sidecar
+  // (screenshot, interaction-history, rendered-html) inside state.ts, but the
+  // conversation transcript lives in the thread store — clear it here, the
+  // one layer that holds both. Fires after the task removal hits disk.
+  onTaskRemoved = (taskId) => {
+    void taskThread.clear(taskId)
+  }
+  // Orphaned-task reconcile. When an agent run ends (child exit) but the
+  // orchestrating client never transitioned the task — e.g. the tab closed
+  // mid-run, or the client crashed before its finalizing PATCH — the task is
+  // left locked in `in_progress` (the spawn registry kills the *process* but
+  // can't fix the *status*). We relinquish the lock back to `pending` so the
+  // task is retryable instead of stranded. The transition guard runs INSIDE
+  // the task lock, so a client transition that's merely slow still wins the
+  // race rather than being clobbered (guard rejects → we no-op).
+  function reconcileOrphanedTask(taskId: string, why: string): void {
+    // Capture the type BEFORE the update — a wireframe_apply orphan needs its
+    // apply batch sealed + entries released + canvas unlocked, exactly as the
+    // HTTP in_progress→pending hook does. This path bypasses the HTTP handler,
+    // so without the same closure the batch would stay 'running' and wedge
+    // undo/discard/re-apply.
+    const before = state.getTasks().tasks.find((t: { id?: string }) => t?.id === taskId) as { type?: string } | undefined
+    void state.updateTask(
+      taskId,
+      { status: 'pending' },
+      { guard: (t) => (t.status === 'in_progress' ? null : 'task already finalized') },
+    ).then(async (res) => {
+      // Guard rejected (client won the race) → nothing to report.
+      if (res && typeof res === 'object' && 'error' in res) return
+      // eslint-disable-next-line no-console
+      console.warn(`[annotask] reconciled orphaned task ${taskId} → pending (${why})`)
+      if (before?.type === 'wireframe_apply') {
+        try { await releaseApplyTask(applyOptions, taskId) }
+        catch (err) {
+          // eslint-disable-next-line no-console
+          console.warn(`[annotask] orphan apply-release failed for ${taskId}:`, err)
+        }
+      }
+    }).catch((err) => {
+      // eslint-disable-next-line no-console
+      console.warn(`[annotask] orphan reconcile failed for task ${taskId}:`, err)
+    })
+  }
+  // The registry reports every run end; we grace-check a moment later (a normal
+  // completion's client review/pending PATCH lands well within this window, so
+  // it no-ops) and, if the task is still `in_progress`, reconcile it. `killed`
+  // distinguishes an interrupted run (we terminated the child) from a child
+  // that exited on its own while the client failed to finalize — for honest
+  // logging; both reconcile to `pending`.
+  const ORPHAN_FINALIZE_GRACE_MS = 12_000
+  function scheduleOrphanFinalize(taskId: string, info: { killed: boolean }): void {
+    setTimeout(() => {
+      const task = state.getTasks().tasks.find((t: { id?: string; status?: string }) => t?.id === taskId)
+      if (!task || task.status !== 'in_progress') return
+      reconcileOrphanedTask(taskId, info.killed ? 'run interrupted' : 'client never finalized')
+    }, ORPHAN_FINALIZE_GRACE_MS).unref()
+  }
+  const agentSpawn = createAgentSpawnHandler({ onRunEnd: scheduleOrphanFinalize })
+
+  // Boot reconcile sweep. A task persisted as `in_progress` with no live run is
+  // an orphan from a previous process (server restarted mid-run, or a tab
+  // closed while the prior process's orphan-finalize timer — an in-memory
+  // unref'd setTimeout — was pending and never fired). The fresh run registry
+  // has no live runs at boot, so we can't tell an embedded orphan from a task
+  // an EXTERNAL MCP agent (e.g. /annotask-apply in another editor) locked and
+  // is still working across our restart. We therefore only reclaim tasks that
+  // have clearly been sitting (older than BOOT_RECLAIM_MIN_AGE_MS): a freshly
+  // killed embedded run is reverted to pending by its own still-open tab when
+  // the SSE dies, and a live external agent's recent lock is left untouched.
+  // Deferred a tick so it doesn't block boot; the task cache loads lazily.
+  const BOOT_RECLAIM_MIN_AGE_MS = 120_000
+  setImmediate(() => {
+    try {
+      const now = Date.now()
+      for (const t of state.getTasks().tasks as Array<{ id?: string; status?: string; updatedAt?: number }>) {
+        if (!t?.id || t.status !== 'in_progress') continue
+        if (agentSpawn.registry.taskRunning(t.id)) continue
+        const age = now - (typeof t.updatedAt === 'number' ? t.updatedAt : 0)
+        if (age < BOOT_RECLAIM_MIN_AGE_MS) continue
+        reconcileOrphanedTask(t.id, 'stale lock at boot')
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn('[annotask] boot orphan sweep failed:', err)
+    }
+  })
+  const agentDetect = createAgentDetector()
+  const initRunner = createInitRunner({
+    projectRoot: options.projectRoot,
+    broadcast: wsServer.broadcast,
+    agentDetect,
+    usageLedger,
+  })
+  onSpecCleared = () => { initRunner.reset() }
+
+  // File-snapshot engine — the agent-apply safety net. The tool never authors
+  // application source (the embedded agent does); snapshots make "Undo last
+  // apply" and "Discard session" byte-exact. Always on: every write it ever
+  // performs is an explicit, user-initiated restore.
+  const snapshotStore = createSnapshotStore(options.projectRoot)
+
+  // Shared apply-session options so the HTTP PATCH path AND the server-side
+  // orphan reconcile / boot sweep drive a wireframe_apply task's lifecycle the
+  // SAME way. Diverging here is exactly what stranded orphaned applies: an
+  // in_progress run reclaimed without sealing its batch left undo/discard/
+  // re-apply all dead and the canvas locked at 'building' forever.
+  const applyOptions: ApplySessionOptions = {
+    projectRoot: options.projectRoot,
+    getDesignSession: () => state.getDesignSession(),
+    setDesignSession: (doc) => state.setDesignSession(doc),
+    getWireframe: () => state.getWireframe(),
+    setWireframe: (doc) => state.setWireframe(doc),
+    addTask: (task) => state.addTask(task),
+    snapshots: snapshotStore,
+  }
 
   const apiMiddleware = createAPIMiddleware({
     projectRoot: options.projectRoot,
     apiSchemaUrls: options.apiSchemaUrls,
     apiSchemaFiles: options.apiSchemaFiles,
+    allowedHosts: options.allowedHosts,
     getReport: () => wsServer.getReport(),
     getConfig: () => state.getConfig(),
     getDesignSpec: () => state.getDesignSpec(),
     getTasks: () => state.getTasks(),
     addTask: (task) => state.addTask(task),
-    updateTask: (id, updates) => state.updateTask(id, updates),
+    updateTask: (id, updates, opts) => state.updateTask(id, updates, opts),
     deleteTask: (id) => state.deleteTask(id),
     saveInteractionHistory: (id, snapshot) => state.saveInteractionHistory(id, snapshot),
     readInteractionHistory: (id) => state.readInteractionHistory(id),
@@ -49,6 +228,20 @@ export function createAnnotaskServer(options: AnnotaskServerOptions): AnnotaskSe
     ingestNetworkCalls: (calls) => state.ingestNetworkCalls(calls),
     getRuntimeEndpointCatalog: () => state.getRuntimeEndpointCatalog(),
     clearRuntimeEndpoints: () => state.clearRuntimeEndpoints(),
+    taskThread,
+    agentSpawn,
+    agentDetect,
+    initRunner,
+    getAgentConfigs: () => state.getAgentConfigs(),
+    setAgentConfig: (id, entry) => state.setAgentConfig(id, entry),
+    getWireframe: () => state.getWireframe(),
+    setWireframe: (doc) => state.setWireframe(doc),
+    getDesignSession: () => state.getDesignSession(),
+    setDesignSession: (doc) => state.setDesignSession(doc),
+    clearDesignSession: () => state.clearDesignSession(),
+    snapshots: snapshotStore,
+    usageLedger,
+    getPersistenceHealth: () => state.getPersistenceHealth(),
   })
 
   const mcpMiddleware = createMcpMiddleware({
@@ -61,6 +254,7 @@ export function createAnnotaskServer(options: AnnotaskServerOptions): AnnotaskSe
     readInteractionHistory: (id) => state.readInteractionHistory(id),
     readRenderedHtml: (id) => state.readRenderedHtml(id),
     getRuntimeEndpointCatalog: () => state.getRuntimeEndpointCatalog(),
+    taskThread,
   })
 
   const shellMiddleware = createShellMiddleware()
@@ -100,7 +294,9 @@ export function createAnnotaskServer(options: AnnotaskServerOptions): AnnotaskSe
     broadcast: (event, data) => wsServer.broadcast(event, data),
     getReport: () => wsServer.getReport(),
     flush: () => state.flush(),
-    dispose: () => { offCatalog(); state.dispose(); wsServer.dispose() },
+    // flush, never revert: a live session is intentional user work and must
+    // survive dev-server restarts (rehydrate); discard is user-initiated only.
+    dispose: () => { void snapshotStore.flush(); agentSpawn.registry.killAll(); offCatalog(); state.dispose(); wsServer.dispose() },
   }
 }
 
diff --git a/src/server/init-templates/STYLE_GUIDE.md b/src/server/init-templates/STYLE_GUIDE.md
new file mode 100644
index 0000000..360d7cb
--- /dev/null
+++ b/src/server/init-templates/STYLE_GUIDE.md
@@ -0,0 +1,25 @@
+# Project style guide
+
+Annotask agents read this file before applying tasks. Fill in the sections
+below to teach them your project's conventions. Empty sections are fine —
+agents will fall back to inferring from the existing code.
+
+## Naming conventions
+
+<!-- e.g. PascalCase components, camelCase composables, kebab-case CSS classes -->
+
+## Spacing & layout
+
+<!-- e.g. 4px base unit; cards use --space-md padding; grid is 12-column -->
+
+## Component patterns
+
+<!-- e.g. wrap form inputs in <FormField label="…">; use <Button variant="primary"> -->
+
+## Things to avoid
+
+<!-- e.g. don't add new dependencies; don't refactor for cleanliness; preserve inline styles -->
+
+## Project context
+
+<!-- A sentence or two about what this project is for. Helps agents pick tone in copy edits. -->
diff --git a/src/server/init.ts b/src/server/init.ts
new file mode 100644
index 0000000..3caf773
--- /dev/null
+++ b/src/server/init.ts
@@ -0,0 +1,1496 @@
+/**
+ * Server-side init pipeline.
+ *
+ * Two-phase flow:
+ *   1. `start()` — runs scan steps, assembles a `draft` in memory.
+ *      Nothing is written to disk; the wizard moves to Review.
+ *   2. `commit(edits)` — writes design-spec.json + STYLE_GUIDE.md.
+ *
+ * How token extraction works:
+ *   If a local CLI (claude, codex, opencode) is installed and logged in, the
+ *   pipeline spawns it with the `annotask-init` skill as its system prompt.
+ *   The agent reads CSS files, Tailwind config, theme selectors, etc. and
+ *   writes `.annotask/design-spec.json` using its native file-edit tools —
+ *   exactly as if the user had run `/annotask-init` in Claude Code.
+ *
+ *   The pipeline watches for the file to land on disk (same watcher used by
+ *   state.ts for hot-reload) and reads it as the draft.
+ *
+ *   If no local CLI is available, the pipeline falls back to a lightweight
+ *   server-side scanner that extracts CSS custom properties and framework
+ *   info without LLM assistance.
+ */
+
+import fsp from 'node:fs/promises'
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import { spawn } from 'node:child_process'
+import { effectiveSpawnPath, hostUserSpawnOptions, exceedsPermissionCap } from './agent-spawn.js'
+import { scanComponentLibraries } from './component-scanner.js'
+import { scanDataSources } from './data-source-scanner.js'
+import { scanApiSchemas } from './api-schema-scanner.js'
+import type { AgentDetector } from './agent-detect.js'
+import type { UsageLedger } from './usage-ledger.js'
+import { loadSkill } from '../skills/index.js'
+import { atomicWrite } from './state.js'
+import { BUILT_IN_PERSONAS } from '../embedded/persona.js'
+import type { ProviderId, EffortLevel } from '../embedded/provider-config.js'
+import { EFFORTS_BY_PROVIDER, EFFORT_LEVELS } from '../embedded/provider-config.js'
+import { initPermissionFlagsFor, type InitCliBin } from '../embedded/permission-mode-flags.js'
+import type { AgentConfigEntry } from './agent-configs.js'
+
+/** Per-persona "what to investigate in the codebase" hint. The init CLI uses
+ *  these to know what kind of project context belongs in each agent's blob. */
+const PERSONA_GROUND_HINTS: Record<string, string> = {
+  general:    'What this app does + naming conventions + copy/tone guidelines + the framework/build system in use.',
+  designer:   'CSS approach (Tailwind/CSS variables/SCSS/etc), the component library if any, spacing scale + color tokens + typography patterns the project actually follows.',
+  a11y:       'Existing a11y patterns or libraries already in use (axe, eslint-plugin-jsx-a11y, focus-trap, etc.), target WCAG level, semantic HTML conventions in this codebase.',
+  'bug-hunter': 'Test setup (vitest/jest/playwright), error tracking libraries, logging conventions, how the project boots/builds so debugging hits root cause rather than symptoms.',
+}
+
+export type InitStepStatus = 'pending' | 'running' | 'success' | 'error' | 'skipped'
+
+export interface InitStep {
+  id: string
+  label: string
+  status: InitStepStatus
+  message?: string
+  startedAt?: number
+  finishedAt?: number
+}
+
+export interface InitDraft {
+  spec: Record<string, unknown>
+  styleGuide: string
+  styleGuideExists: boolean
+  designSpecExists: boolean
+}
+
+export interface InitState {
+  running: boolean
+  startedAt?: number
+  finishedAt?: number
+  result?: 'success' | 'error' | 'cancelled' | 'awaiting_review'
+  error?: string
+  steps: InitStep[]
+  draft?: InitDraft
+  committedAt?: number
+  /** Lines streamed from the local CLI agent during init. */
+  agentLines?: string[]
+  /** Which CLI the agent step used, for display. */
+  agentCli?: string
+  /**
+   * Running token usage tally for this init run. Accumulated across every
+   * agent CLI invocation (design-spec + agent-configs) so the wizard can
+   * surface a live counter. Reset on each `start()`.
+   */
+  tokenUsage?: {
+    inputTokens: number
+    outputTokens: number
+    cacheReadTokens: number
+    cacheCreationTokens: number
+    turns: number
+  }
+}
+
+export interface InitCommitBody {
+  spec?: Record<string, unknown>
+  styleGuide?: string
+  overwriteStyleGuide?: boolean
+}
+
+export interface ScanOptions {
+  /** Skip the LLM-driven design-spec / style-guide pass (framework + themes
+   *  + agent-scan + commit). Used by re-scan mode when the user only wants
+   *  to refresh agents.json or recompute components/data-sources/api-schemas
+   *  without rewriting the design-spec via the LLM. */
+  skipAgentScan?: boolean
+  /** Skip the separate agent-directions CLI invocation. */
+  skipAgentConfigs?: boolean
+  /** Skip the component library scan. */
+  skipComponents?: boolean
+  /** Skip the data-source scan. */
+  skipDataSources?: boolean
+  /** Skip the API schema scan. */
+  skipApiSchemas?: boolean
+  /** Provider selected in the init-agent step. Local CLIs use this exactly
+   *  when available so downstream agent defaults match the init agent. */
+  requestedProviderId?: ProviderId
+  /** Model selected for the init-agent provider. Passed to local CLIs that
+   *  support an explicit model flag (Claude, Codex, OpenCode). */
+  requestedModel?: string
+  requestedEffort?: EffortLevel
+}
+
+export interface InitRunner {
+  start: (opts?: ScanOptions) => InitState
+  cancel: () => void
+  commit: (body: InitCommitBody) => Promise<InitState>
+  /**
+   * Mark the project as initialized without committing any token data. Used
+   * when the user chooses to run the annotask-init skill in their editor
+   * agent instead of going through the wizard. Writes a minimal accepted
+   * spec so the wizard closes and the "not initialized" banner disappears.
+   */
+  skip: () => Promise<InitState>
+  /**
+   * Drop the in-memory step state and broadcast a fresh `init:progress`. Used
+   * when `design-spec.json` is wiped from disk so the wizard's last-run green
+   * checkmarks don't outlive the file. No-op while a scan is running — that
+   * path uses `cancel()` first.
+   */
+  reset: () => InitState
+  getState: () => InitState
+}
+
+interface Deps {
+  projectRoot: string
+  broadcast: (event: string, data: unknown) => void
+  agentDetect: AgentDetector
+  /** Optional — when provided, each init agent run logs its token totals here. */
+  usageLedger?: UsageLedger
+}
+
+const SCAN_STEPS: Array<{ id: string; label: string }> = [
+  { id: 'framework',     label: 'Detect framework and styling' },
+  { id: 'themes',        label: 'Detect theme variants' },
+  { id: 'agent-scan',    label: 'Extract design tokens with your agent' },
+  { id: 'agent-configs', label: 'Write agent directions' },
+  { id: 'components',    label: 'Scan component library' },
+  { id: 'data-sources',  label: 'Scan data sources' },
+  { id: 'api-schemas',   label: 'Scan API schemas' },
+]
+
+type InitLocalProviderId = Extract<ProviderId, 'claude-local' | 'codex-local' | 'opencode-local' | 'copilot-local'>
+
+interface InitCliOption {
+  id: InitLocalProviderId
+  bin: 'claude' | 'codex' | 'opencode' | 'copilot'
+  label: string
+}
+
+const INIT_CLI_OPTIONS: readonly InitCliOption[] = [
+  { id: 'claude-local',   bin: 'claude',   label: 'Claude' },
+  { id: 'codex-local',    bin: 'codex',    label: 'Codex' },
+  { id: 'opencode-local', bin: 'opencode', label: 'OpenCode' },
+  { id: 'copilot-local',  bin: 'copilot',  label: 'Copilot' },
+]
+
+function isInitLocalProviderId(id: ProviderId | undefined): id is InitLocalProviderId {
+  return id === 'claude-local' || id === 'codex-local' ||
+    id === 'opencode-local' || id === 'copilot-local'
+}
+
+function isFoundLocalCli(snap: Awaited<ReturnType<AgentDetector['detect']>>, id: InitLocalProviderId): boolean {
+  const status = snap[id]
+  return !!status?.found
+}
+
+function isReadyLocalCli(snap: Awaited<ReturnType<AgentDetector['detect']>>, id: InitLocalProviderId): boolean {
+  const status = snap[id]
+  return !!(status?.found && status?.loggedIn)
+}
+
+function selectInitCli(
+  snap: Awaited<ReturnType<AgentDetector['detect']>>,
+  requestedProviderId?: ProviderId,
+): InitCliOption | null {
+  if (isInitLocalProviderId(requestedProviderId)) {
+    if (!isReadyLocalCli(snap, requestedProviderId)) return null
+    return INIT_CLI_OPTIONS.find(c => c.id === requestedProviderId) ?? null
+  }
+  return INIT_CLI_OPTIONS.find(c => isReadyLocalCli(snap, c.id)) ?? null
+}
+
+/** Targeted error message when a requested CLI is found but not logged in. */
+function initCliNotReadyReason(
+  snap: Awaited<ReturnType<AgentDetector['detect']>>,
+  requestedProviderId?: ProviderId,
+): string | null {
+  if (!isInitLocalProviderId(requestedProviderId)) return null
+  if (!isFoundLocalCli(snap, requestedProviderId)) return null
+  if (isReadyLocalCli(snap, requestedProviderId)) return null
+  return `${requestedProviderId} is installed but not logged in — run its login command first`
+}
+
+/**
+ * Decide what model/effort to forward to the init CLI.
+ *
+ * The shell sends `requestedModel` + `requestedEffort` straight from the
+ * user's active provider config. Those identifiers are namespaced by
+ * provider — Copilot's `gpt-5.4-mini`, OpenRouter's `anthropic/...`, etc.
+ * If init had to substitute a different CLI than the user requested
+ * (e.g. user picked `copilot` but only `claude` is installed locally),
+ * forwarding the model is guaranteed to fail: the substituted CLI will
+ * reject the id with a "model may not exist" error. Drop the model and
+ * effort in that case so the substituted CLI uses its own default; the
+ * caller logs a note explaining the substitution.
+ */
+function narrowRuntimeToCli(
+  available: InitCliOption,
+  opts: { requestedProviderId?: ProviderId; requestedModel?: string; requestedEffort?: EffortLevel },
+): { model: string | undefined; effort: EffortLevel | undefined; substituted: boolean } {
+  const matches = opts.requestedProviderId === available.id
+  if (matches) return { model: opts.requestedModel, effort: opts.requestedEffort, substituted: false }
+  return { model: undefined, effort: undefined, substituted: opts.requestedProviderId != null }
+}
+
+/**
+ * Rewrite `.annotask/agents.json` so every built-in persona uses the exact
+ * provider/model/effort the user selected in the Init Wizard. Custom personas
+ * (ids that aren't built-ins) are preserved untouched.
+ *
+ * Called twice during init:
+ *   1. Before the CLI runs — seeds the file so the CLI sees the target shape.
+ *      `fallbackRoleText: false` keeps `projectDirections` empty so the CLI is
+ *      forced to write fresh content (otherwise it tends to keep the built-in
+ *      role text verbatim).
+ *   2. After the CLI runs — re-opens the file and forcibly restores the
+ *      selected provider/model/effort in case the CLI rewrote them.
+ *      `fallbackRoleText: true` so any persona the CLI left blank ends up with
+ *      at least its built-in role identity.
+ *
+ * The selected `providerId`/`model`/`effort` always wins. Prior values for
+ * built-in personas are never preserved — re-init with a different provider
+ * must overwrite previous Claude defaults.
+ */
+async function enforceSelectedRuntime(opts: {
+  filePath: string
+  providerId: ProviderId
+  model: string
+  effort: EffortLevel
+  fallbackRoleText: boolean
+}): Promise<{ backfilled: number; filled: number; totalBuiltIns: number }> {
+  let existing: Record<string, any> = {}
+  try {
+    const raw = JSON.parse(await fsp.readFile(opts.filePath, 'utf-8'))
+    if (raw && typeof raw.agents === 'object' && raw.agents !== null) existing = raw.agents
+  } catch { /* missing or unreadable — treat as empty */ }
+
+  const agents: Record<string, AgentConfigEntry> = {}
+  let backfilled = 0
+  for (const persona of BUILT_IN_PERSONAS) {
+    const prior = existing[persona.id] ?? {}
+    const priorDirections = typeof prior.projectDirections === 'string' ? prior.projectDirections : ''
+    const hasDirections = priorDirections.trim().length > 0
+    let directions: string
+    if (hasDirections) {
+      directions = priorDirections
+    } else if (opts.fallbackRoleText) {
+      directions = persona.roleDirections
+      backfilled += 1
+    } else {
+      directions = ''
+    }
+    agents[persona.id] = {
+      projectDirections: directions,
+      providerId: opts.providerId,
+      model: opts.model,
+      effort: opts.effort,
+    }
+  }
+  for (const [id, value] of Object.entries(existing)) {
+    if (agents[id]) continue
+    const v = value as Partial<AgentConfigEntry>
+    agents[id] = {
+      projectDirections: typeof v?.projectDirections === 'string' ? v.projectDirections : '',
+      ...(v?.providerId ? { providerId: v.providerId } : {}),
+      ...(typeof v?.model === 'string' ? { model: v.model } : {}),
+      ...(v?.effort ? { effort: v.effort } : {}),
+    }
+  }
+
+  await fsp.mkdir(path.dirname(opts.filePath), { recursive: true })
+  const tmp = `${opts.filePath}.tmp.${process.pid}.${Date.now()}`
+  await fsp.writeFile(tmp, JSON.stringify({ version: 1, agents }, null, 2), 'utf-8')
+  await fsp.rename(tmp, opts.filePath)
+
+  const filled = Object.values(agents).filter(
+    (a) => typeof a?.projectDirections === 'string' && a.projectDirections.trim(),
+  ).length
+  return { backfilled, filled, totalBuiltIns: BUILT_IN_PERSONAS.length }
+}
+
+/**
+ * Build the prompt sent to the init CLI to fill `projectDirections`. Exported
+ * for tests so we can assert the CLI is never asked to pick a model/effort per
+ * persona.
+ */
+function buildAgentConfigsPrompt(opts: {
+  projectRoot: string
+  framework?: FrameworkInfo | null
+  totalPersonas: number
+}): string {
+  const { projectRoot, framework, totalPersonas } = opts
+  return [
+    `Your task: edit \`.annotask/agents.json\` and fill in \`projectDirections\` for every agent. Use your file-editing tool (Edit / Write / patch) — do NOT just describe what you would write; actually modify the file on disk.`,
+    ``,
+    `You may ONLY edit the \`projectDirections\` field. The \`providerId\`, \`model\`, and \`effort\` fields are owned by Annotask — do not invent values, do not copy values from other personas, do not change them. Annotask rewrites those fields after you finish, regardless of what you write.`,
+    ``,
+    `Step 1 — read these files to ground the directions in the real codebase:`,
+    `  - .annotask/agents.json  (you'll edit this; every \`projectDirections\` is currently "")`,
+    `  - package.json           (framework, deps, scripts)`,
+    `  - README.md              (if present — what this app is for)`,
+    `  - 2-3 representative source files in src/ or app/ to confirm conventions`,
+    ``,
+    `Step 2 — for each of the ${totalPersonas} personas listed below, write ONE cohesive markdown blob (4-8 sentences, prose not bullets) that combines:`,
+    `  • The agent's identity and tone, rephrased in your own words to fit this project (do NOT paste the example sentence verbatim).`,
+    `  • Concrete project facts you confirmed by reading files: framework + version, styling system, component library, naming conventions, things to prefer or avoid.`,
+    ``,
+    `Personas to fill (id → tone example to draw from, then what to ground each in):`,
+    ...BUILT_IN_PERSONAS.flatMap(p => [
+      `  ${p.id} (${p.name}):`,
+      `    tone example: ${p.roleDirections}`,
+      `    must cover: ${PERSONA_GROUND_HINTS[p.id] ?? 'identity + project-specific guidance'}`,
+    ]),
+    ``,
+    `Step 3 — write the file using your Edit/Write tool. Preserve the JSON shape exactly. Only \`projectDirections\` is yours to edit:`,
+    `  { "version": 1, "agents": { "<id>": { "projectDirections": "<your blob>", "providerId": "<leave as-is>", "model": "<leave as-is>", "effort": "<leave as-is>" }, ... } }`,
+    `Do NOT add or remove personas. Do NOT leave any \`projectDirections\` empty.`,
+    ``,
+    `Step 4 — re-read \`.annotask/agents.json\` to confirm every \`projectDirections\` is a non-empty string with project-specific content.`,
+    ``,
+    `Project: ${projectRoot}`,
+    `Framework: ${framework?.name ?? 'unknown'}${framework?.version ? ` ${framework.version}` : ''}`,
+    `Styling: ${(framework?.styling ?? []).join(', ') || 'standard CSS'}`,
+  ].join('\n')
+}
+
+export const __test = {
+  selectInitCli,
+  initCliNotReadyReason,
+  enforceSelectedRuntime,
+  buildAgentConfigsPrompt,
+  // Exposed for spawn-error tests; defined below after spawnCliWithSkill.
+  detectFatalStderrLine: (bin: string, line: string) => detectFatalStderrLine(bin, line),
+  extractTextFromLine: (bin: string, line: string) => extractTextFromLine(bin, line),
+  extractUsageFromLine: (bin: string, line: string) => extractUsageFromLine(bin, line),
+}
+
+export function createInitRunner(deps: Deps): InitRunner {
+  let state: InitState = freshState()
+  let cancelRequested = false
+  let agentAbortController: AbortController | null = null
+  // One id per `start()` run so all CLI invocations within a single init
+  // (design-spec, agent-configs) cluster together in the ledger.
+  let currentRunId: string | null = null
+
+  function recordInitUsage(label: string, providerId: string, usage: SpawnUsage): void {
+    // Accumulate into the wizard's live counter regardless of whether the
+    // ledger is wired — the user-facing tally should still update during
+    // tests / dev that don't provide a ledger.
+    const prev = state.tokenUsage ?? {
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheCreationTokens: 0,
+      turns: 0,
+    }
+    state.tokenUsage = {
+      inputTokens: prev.inputTokens + Math.max(0, usage.inputTokens || 0),
+      outputTokens: prev.outputTokens + Math.max(0, usage.outputTokens || 0),
+      cacheReadTokens: prev.cacheReadTokens + Math.max(0, usage.cacheReadTokens || 0),
+      cacheCreationTokens: prev.cacheCreationTokens + Math.max(0, usage.cacheCreationTokens || 0),
+      turns: prev.turns + 1,
+    }
+    broadcastProgress()
+    if (!deps.usageLedger) return
+    void deps.usageLedger.append({
+      scope: 'init',
+      runId: currentRunId ?? undefined,
+      providerId,
+      model: usage.model,
+      label,
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      cacheReadTokens: usage.cacheReadTokens,
+      cacheCreationTokens: usage.cacheCreationTokens,
+    })
+  }
+
+  function freshState(): InitState {
+    return {
+      running: false,
+      steps: SCAN_STEPS.map(d => ({ id: d.id, label: d.label, status: 'pending' as const })),
+      agentLines: [],
+    }
+  }
+
+  function broadcastProgress() {
+    deps.broadcast('init:progress', {
+      ...state,
+      steps: state.steps.map(s => ({ ...s })),
+      draft: state.draft,
+      agentLines: state.agentLines ?? [],
+      tokenUsage: state.tokenUsage,
+    })
+  }
+
+  function setStep(id: string, patch: Partial<InitStep>) {
+    state.steps = state.steps.map(s => s.id === id ? { ...s, ...patch } : s)
+    broadcastProgress()
+  }
+
+  function appendAgentLine(line: string) {
+    state.agentLines = [...(state.agentLines ?? []).slice(-499), line]
+    broadcastProgress()
+  }
+
+  async function runStep<T>(id: string, fn: () => Promise<T>, skip = false): Promise<T | undefined> {
+    if (skip) {
+      setStep(id, { status: 'skipped', message: 'Skipped', finishedAt: Date.now() })
+      return undefined
+    }
+    if (cancelRequested) {
+      setStep(id, { status: 'skipped', message: 'Cancelled' })
+      return undefined
+    }
+    setStep(id, { status: 'running', startedAt: Date.now() })
+    try {
+      const result = await fn()
+      setStep(id, { status: 'success', finishedAt: Date.now() })
+      return result
+    } catch (err) {
+      const message = (err as Error)?.message ?? String(err)
+      setStep(id, { status: 'error', finishedAt: Date.now(), message })
+      throw err
+    }
+  }
+
+  function start(opts: ScanOptions = {}): InitState {
+    if (state.running) return state
+    cancelRequested = false
+    currentRunId = `init-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`
+    state = { ...freshState(), running: true, startedAt: Date.now() }
+    broadcastProgress()
+
+    runPipeline(opts).catch(err => {
+      state.result = 'error'
+      state.error = (err as Error)?.message ?? String(err)
+      state.finishedAt = Date.now()
+      state.running = false
+      broadcastProgress()
+    })
+
+    return state
+  }
+
+  function cancel() {
+    if (!state.running) return
+    cancelRequested = true
+    agentAbortController?.abort()
+  }
+
+  function getState(): InitState {
+    return {
+      ...state,
+      steps: state.steps.map(s => ({ ...s })),
+      draft: state.draft,
+      agentLines: state.agentLines ?? [],
+      tokenUsage: state.tokenUsage,
+    }
+  }
+
+  async function runPipeline(opts: ScanOptions = {}) {
+    // When `skipAgentScan` is set we always need framework + theme detection
+    // for downstream context, but they're cheap deterministic scans, so just
+    // run them as usual. The LLM-driven `agent-scan` step is the one that's
+    // actually skipped — see runStep below.
+    const cssFiles = await collectCssFiles(deps.projectRoot)
+
+    const framework = await runStep('framework', () => detectFramework(deps.projectRoot), opts.skipAgentScan)
+    if (cancelRequested) return finishCancelled()
+
+    const themes = await runStep('themes', () => detectThemeVariants(cssFiles), opts.skipAgentScan)
+    if (cancelRequested) return finishCancelled()
+
+    const themeList = themes?.themes ?? [{ id: 'default', name: 'Default', selector: { kind: 'default' } }]
+    const defaultTheme = themes?.defaultTheme ?? 'default'
+
+    // ── Agent-driven token extraction ────────────────────────────────────────
+    let agentUsed = false
+    let initCliUsed: InitCliOption | null = null
+    // Re-scan mode may skip the heavy agent-scan step entirely. When skipped,
+    // we still set `agentUsed` to true so the downstream draft-assembly path
+    // reads the existing design-spec.json from disk instead of falling back
+    // to the empty scaffold.
+    if (opts.skipAgentScan) {
+      agentUsed = true
+    }
+    await runStep('agent-scan', async () => {
+      const snap = await deps.agentDetect.detect()
+      const detected = selectInitCli(snap, opts.requestedProviderId)
+      // Honor the ANNOTASK_MAX_PERMISSION floor here too: the init agent must
+      // write to `.annotask/`, which on claude/opencode requires bypass. If the
+      // cap forbids the flags this CLI needs, don't run the agent — degrade to
+      // the static scanner exactly as if no CLI were available.
+      const capBlock = detected ? exceedsPermissionCap(initPermissionFlagsFor(detected.bin)) : null
+      const available = capBlock ? null : detected
+
+      if (!available) {
+        const notReadyMsg = capBlock && detected
+          ? `${detected.label} would need '${capBlock.level}' permission but ANNOTASK_MAX_PERMISSION caps at '${capBlock.cap}' — running lightweight scanner instead.`
+          : (initCliNotReadyReason(snap, opts.requestedProviderId)
+            ?? 'No local CLI logged in — running lightweight scanner (colors and layout only)')
+        setStep('agent-scan', { message: notReadyMsg })
+        await runFallbackScan(cssFiles, themeList)
+        return
+      }
+
+      state.agentCli = available.label
+      initCliUsed = available
+      const runtime = narrowRuntimeToCli(available, opts)
+      if (runtime.substituted) {
+        appendAgentLine(
+          `Init substituted ${available.label} for requested provider "${opts.requestedProviderId}". ` +
+          `Dropping requested model "${opts.requestedModel ?? ''}" — that id is in the wrong namespace ` +
+          `for ${available.bin}. ${available.label} will use its CLI default.`,
+        )
+      }
+      const modelSuffix = runtime.model?.trim() ? ` (${runtime.model.trim()})` : ''
+      setStep('agent-scan', { message: `Running annotask-init with ${available.label}${modelSuffix}…` })
+
+      let skillBody = ''
+      try {
+        const skill = loadSkill('annotask-init')
+        skillBody = skill.body
+      } catch {
+        skillBody = 'Initialize Annotask for this project. Write `.annotask/design-spec.json` following the annotask design-spec schema.'
+      }
+
+      const styleGuidePath2 = path.join(deps.projectRoot, '.annotask', 'STYLE_GUIDE.md')
+      let preexistingGuide: string | null = null
+      try { preexistingGuide = await fsp.readFile(styleGuidePath2, 'utf-8') } catch { /* not present */ }
+
+      const userMessage = [
+        `Initialize Annotask for this project. Do both of the following:`,
+        ``,
+        `1. Write the complete \`.annotask/design-spec.json\` file with all detected design tokens.`,
+        ``,
+        `2. Write \`.annotask/STYLE_GUIDE.md\` — a project style guide agents read before every task.`,
+        `   Use the existing one if present (path: .annotask/STYLE_GUIDE.md) and update it,`,
+        `   otherwise create it from scratch with sections: Naming conventions, Spacing & layout,`,
+        `   Component patterns, Things to avoid, Project context.`,
+        `   Fill in what you can infer from the codebase; leave sections blank rather than guessing.`,
+        preexistingGuide ? `   Existing STYLE_GUIDE.md content:\n${preexistingGuide.slice(0, 2000)}` : '',
+        ``,
+        `Project context:`,
+        `  Root: ${deps.projectRoot}`,
+        `  Framework: ${framework?.name ?? 'unknown'}${framework?.version ? ` ${framework.version}` : ''}`,
+        `  Styling: ${(framework?.styling ?? []).join(', ') || 'standard CSS'}`,
+        `  Detected theme variants: ${themeList.map(t => t.id).join(', ')}`,
+      ].filter(l => l !== null).join('\n')
+
+      const specPath = path.join(deps.projectRoot, '.annotask', 'design-spec.json')
+
+      await spawnCliWithSkill({
+        bin: available.bin,
+        model: runtime.model,
+        effort: runtime.effort,
+        skillBody,
+        userMessage,
+        projectRoot: deps.projectRoot,
+        onLine: (line) => { appendAgentLine(line) },
+        onUsage: (u) => recordInitUsage('annotask-init', `${available.bin}-local`, u),
+        signal: (agentAbortController = new AbortController()).signal,
+      })
+
+      agentUsed = true
+
+      // Verify the agent wrote the spec file
+      try {
+        await fsp.access(specPath)
+        const guideWritten = await fsp.access(styleGuidePath2).then(() => true).catch(() => false)
+        setStep('agent-scan', {
+          message: `${available.label} wrote design-spec.json${guideWritten ? ' + STYLE_GUIDE.md' : ''}`,
+        })
+      } catch {
+        setStep('agent-scan', {
+          status: 'error',
+          message: `${available.label} exited but design-spec.json was not found — running fallback`,
+        })
+        await runFallbackScan(cssFiles, themeList)
+        agentUsed = false
+      }
+    }, opts.skipAgentScan)
+    if (cancelRequested) return finishCancelled()
+
+    // ── Agent directions — separate CLI invocation ───────────────────────────
+    await runStep('agent-configs', async () => {
+      const agentConfigsPath = path.join(deps.projectRoot, '.annotask', 'agents.json')
+
+      // Use the exact provider/model/effort selected in the init-agent step
+      // for every built-in runtime agent. The local CLI below is only the
+      // writer used to fill projectDirections; it does not get to choose each
+      // persona's runtime model.
+      const detectedForConfigs = initCliUsed ?? selectInitCli(await deps.agentDetect.detect(), opts.requestedProviderId)
+      // Same ANNOTASK_MAX_PERMISSION floor as the agent-scan step: if the cap
+      // forbids the flags this CLI needs, don't run the directions agent — fall
+      // through to the seeded-defaults path below (the `!available` branch).
+      const configsCapBlock = detectedForConfigs ? exceedsPermissionCap(initPermissionFlagsFor(detectedForConfigs.bin)) : null
+      if (configsCapBlock && detectedForConfigs) {
+        appendAgentLine(`${detectedForConfigs.label} would need '${configsCapBlock.level}' permission but ANNOTASK_MAX_PERMISSION caps at '${configsCapBlock.cap}' — seeding default agent roles instead.`)
+      }
+      const available = configsCapBlock ? null : detectedForConfigs
+      // Resolution priority for the per-built-in runtime: explicit request →
+      // detected CLI → persona's own default. We deliberately never fall back
+      // to whatever value is currently sitting in agents.json — re-init with a
+      // different provider must overwrite prior Claude defaults.
+      const resolvedProviderId: ProviderId = opts.requestedProviderId
+        ?? available?.id
+        ?? BUILT_IN_PERSONAS[0].providerId
+      const allowedEfforts = EFFORTS_BY_PROVIDER[resolvedProviderId] ?? EFFORT_LEVELS
+      const allowedEffortSet = new Set<EffortLevel>(allowedEfforts)
+      const selectedModel = opts.requestedModel?.trim() ?? ''
+      const selectedEffort: EffortLevel = opts.requestedEffort && allowedEffortSet.has(opts.requestedEffort)
+        ? opts.requestedEffort
+        : 'auto'
+
+      if (!agentUsed) {
+        await enforceSelectedRuntime({
+          filePath: agentConfigsPath,
+          providerId: resolvedProviderId,
+          model: selectedModel,
+          effort: selectedEffort,
+          fallbackRoleText: true,
+        })
+        setStep('agent-configs', { message: 'Seeded default agent roles — edit in Settings → Agents.' })
+        return
+      }
+
+      if (!available) {
+        await enforceSelectedRuntime({
+          filePath: agentConfigsPath,
+          providerId: resolvedProviderId,
+          model: selectedModel,
+          effort: selectedEffort,
+          fallbackRoleText: true,
+        })
+        setStep('agent-configs', { message: 'No CLI available — seeded default roles. Edit in Settings → Agents.' })
+        return
+      }
+
+      // Seed runtime config only. projectDirections stays empty so the CLI
+      // is forced to write fresh project-tailored content rather than copy
+      // the built-in role text it sees in the file.
+      await enforceSelectedRuntime({
+        filePath: agentConfigsPath,
+        providerId: resolvedProviderId,
+        model: selectedModel,
+        effort: selectedEffort,
+        fallbackRoleText: false,
+      })
+
+      const runtime = narrowRuntimeToCli(available, opts)
+      if (runtime.substituted) {
+        appendAgentLine(
+          `Init substituted ${available.label} for requested provider "${opts.requestedProviderId}". ` +
+          `Dropping requested model "${opts.requestedModel ?? ''}" — that id is in the wrong namespace ` +
+          `for ${available.bin}. ${available.label} will use its CLI default.`,
+        )
+      }
+      const modelSuffix = runtime.model?.trim() ? ` (${runtime.model.trim()})` : ''
+      setStep('agent-configs', { message: `Writing agent directions with ${available.label}${modelSuffix}…` })
+
+      const agentConfigsMessage = buildAgentConfigsPrompt({
+        projectRoot: deps.projectRoot,
+        framework,
+        totalPersonas: BUILT_IN_PERSONAS.length,
+      })
+
+      // Run the CLI inside its own try/catch so a failure (timeout, non-zero
+      // exit, network error) doesn't bypass the backfill. Without this, a
+      // failed CLI leaves every projectDirections as the empty string we
+      // seeded — the user sees totally blank agent settings.
+      let cliError: Error | null = null
+      try {
+        await spawnCliWithSkill({
+          bin: available.bin,
+          model: runtime.model,
+          effort: runtime.effort,
+          skillBody: '',
+          userMessage: agentConfigsMessage,
+          projectRoot: deps.projectRoot,
+          onLine: (line) => { appendAgentLine(line) },
+          onUsage: (u) => recordInitUsage('agent-configs', `${available.bin}-local`, u),
+          signal: (agentAbortController = new AbortController()).signal,
+        })
+      } catch (err) {
+        cliError = err as Error
+        appendAgentLine(`[error] ${cliError.message}`)
+      }
+
+      // Re-open the file and forcibly restore the selected provider/model/effort
+      // in case the CLI rewrote them. Backfills empty projectDirections with
+      // the built-in role text so the user never sees a totally blank entry.
+      try {
+        const { backfilled, filled, totalBuiltIns } = await enforceSelectedRuntime({
+          filePath: agentConfigsPath,
+          providerId: resolvedProviderId,
+          model: selectedModel,
+          effort: selectedEffort,
+          fallbackRoleText: true,
+        })
+        const snapNotes: string[] = []
+        if (backfilled > 0) snapNotes.push(`${backfilled} fell back to role default`)
+        const baseMsg = snapNotes.length > 0
+          ? `${filled} of ${totalBuiltIns} agent personas configured (${snapNotes.join(', ')})`
+          : `${filled} of ${totalBuiltIns} agent personas configured`
+        const msg = cliError ? `${baseMsg}. ${available.label} errored: ${cliError.message.slice(0, 120)}` : baseMsg
+        setStep('agent-configs', { message: msg })
+      } catch {
+        // CLI munged the file beyond JSON-readability — restore role text
+        // as a safety net so the user has something to edit in Settings.
+        await enforceSelectedRuntime({
+          filePath: agentConfigsPath,
+          providerId: resolvedProviderId,
+          model: selectedModel,
+          effort: selectedEffort,
+          fallbackRoleText: true,
+        })
+        setStep('agent-configs', { message: 'agents.json was unreadable — restored default roles. Edit in Settings → Agents.' })
+      }
+    }, opts.skipAgentConfigs)
+    if (cancelRequested) return finishCancelled()
+
+    const components = await runStep('components', async () => {
+      const catalog = await scanComponentLibraries(deps.projectRoot)
+      return summarizeComponents(catalog, framework?.name)
+    }, opts.skipComponents)
+    if (cancelRequested) return finishCancelled()
+
+    await runStep('data-sources', async () => {
+      const catalog = await scanDataSources(deps.projectRoot)
+      return catalog.project_entries.length
+    }, opts.skipDataSources)
+    if (cancelRequested) return finishCancelled()
+
+    await runStep('api-schemas', async () => {
+      const catalog = await scanApiSchemas(deps.projectRoot)
+      return catalog.schemas.length
+    }, opts.skipApiSchemas)
+    if (cancelRequested) return finishCancelled()
+
+    // ── Assemble draft ──────────────────────────────────────────────────────
+    const specPath = path.join(deps.projectRoot, '.annotask', 'design-spec.json')
+    let draftSpec: Record<string, unknown>
+
+    if (agentUsed) {
+      // Agent wrote the file — read it as the draft
+      try {
+        const raw = await fsp.readFile(specPath, 'utf-8')
+        const parsed = JSON.parse(raw)
+        // Merge scanner-detected components into the agent-written spec when missing
+        if (!parsed.components && components) parsed.components = components
+        draftSpec = parsed
+      } catch {
+        draftSpec = baseDraftSpec(framework, themeList, defaultTheme, components)
+      }
+    } else {
+      // Fallback: read what the fallback scanner wrote, or build from scratch
+      draftSpec = state.draft?.spec ?? baseDraftSpec(framework, themeList, defaultTheme, components)
+    }
+
+    const styleGuidePath = path.join(deps.projectRoot, '.annotask', 'STYLE_GUIDE.md')
+    let existingGuide: string | null = null
+    try { existingGuide = await fsp.readFile(styleGuidePath, 'utf-8') } catch { /* not present */ }
+
+    let designSpecExists = false
+    try { await fsp.access(specPath); designSpecExists = true } catch { /* fine */ }
+
+    // If the run only touched agent-configs (everything else explicitly
+    // skipped), there's no draft for the user to review — skip the Review
+    // step entirely and let the wizard show a plain "done" state. We still
+    // populate state.draft for consistency with the read endpoints, but the
+    // result below will be 'success' rather than 'awaiting_review'.
+    const onlyAgentConfigsRan = !!(opts.skipAgentScan && opts.skipComponents && opts.skipDataSources && opts.skipApiSchemas) && !opts.skipAgentConfigs
+
+    state.draft = {
+      spec: draftSpec,
+      styleGuide: existingGuide ?? STYLE_GUIDE_TEMPLATE,
+      styleGuideExists: existingGuide != null,
+      designSpecExists,
+    }
+    state.result = onlyAgentConfigsRan ? 'success' : 'awaiting_review'
+    state.finishedAt = Date.now()
+    state.running = false
+    broadcastProgress()
+  }
+
+  async function runFallbackScan(
+    cssFiles: string[],
+    themes: Array<{ id: string; selector: Record<string, unknown> }>,
+  ) {
+    // Lightweight CSS scanner for when no CLI is available.
+    // Extracts CSS custom properties and uses them to build a minimal spec.
+    // The design-spec.json is NOT written to disk during fallback scan —
+    // only the draft state is populated so the user can still review.
+    const fallbackSpec = baseDraftSpec(null, themes, themes[0]?.id ?? 'default', null)
+    state.draft = {
+      spec: fallbackSpec,
+      styleGuide: STYLE_GUIDE_TEMPLATE,
+      styleGuideExists: false,
+      designSpecExists: false,
+    }
+    broadcastProgress()
+  }
+
+  async function commit(body: InitCommitBody): Promise<InitState> {
+    if (!state.draft) {
+      state = { ...state, result: 'error', error: 'No draft to commit — run start() first.', finishedAt: Date.now(), running: false }
+      broadcastProgress()
+      return getState()
+    }
+
+    // Mark the spec as user-accepted. `state.ts` only treats the spec as
+    // "initialized" when this field is explicitly `true` — an agent-written
+    // spec without it keeps the wizard open until the user commits here.
+    const rawSpec = body.spec ?? state.draft.spec
+    const spec = { ...rawSpec, initialized: true }
+    const styleGuide = body.styleGuide ?? state.draft.styleGuide
+    const overwriteStyleGuide = body.overwriteStyleGuide === true
+
+    const specPath = path.join(deps.projectRoot, '.annotask', 'design-spec.json')
+    const stylePath = path.join(deps.projectRoot, '.annotask', 'STYLE_GUIDE.md')
+
+    try {
+      // Atomic temp+rename (atomicWrite mkdirs the parent): state.ts reads
+      // design-spec.json with a sync readFileSync on cache miss, so a plain
+      // writeFile could hand it a half-written file mid-commit.
+      await atomicWrite(specPath, JSON.stringify(spec, null, 2))
+      if (state.draft.styleGuideExists && !overwriteStyleGuide) {
+        // preserve existing
+      } else {
+        await atomicWrite(stylePath, styleGuide)
+      }
+      state = { ...state, result: 'success', committedAt: Date.now(), draft: { ...state.draft, spec, styleGuide } }
+      broadcastProgress()
+    } catch (err) {
+      state = { ...state, result: 'error', error: (err as Error)?.message ?? String(err) }
+      broadcastProgress()
+    }
+    return getState()
+  }
+
+  async function skip(): Promise<InitState> {
+    // Write the minimal accepted spec and close. The user will run the
+    // annotask-init skill in their editor agent to populate tokens.
+    const existing = state.draft?.spec
+    const specPath = path.join(deps.projectRoot, '.annotask', 'design-spec.json')
+    let baseSpec: Record<string, unknown>
+    if (existing) {
+      baseSpec = { ...existing, initialized: true }
+    } else {
+      // Read the on-disk spec if present, else build a blank one.
+      try {
+        const raw = JSON.parse(await fsp.readFile(specPath, 'utf-8'))
+        baseSpec = { ...raw, initialized: true }
+      } catch {
+        baseSpec = { version: '1.0', initialized: true, colors: [], typography: { families: [], scale: [], weights: [] }, spacing: [], borders: { radius: [] } }
+      }
+    }
+    try {
+      // Same atomic temp+rename as commit() — see the comment there.
+      await atomicWrite(specPath, JSON.stringify(baseSpec, null, 2))
+      state = { ...state, result: 'success', committedAt: Date.now() }
+      broadcastProgress()
+    } catch (err) {
+      state = { ...state, result: 'error', error: (err as Error)?.message ?? String(err) }
+      broadcastProgress()
+    }
+    return getState()
+  }
+
+  function finishCancelled() {
+    agentAbortController?.abort()
+    state.result = 'cancelled'
+    state.finishedAt = Date.now()
+    state.running = false
+    broadcastProgress()
+  }
+
+  function reset(): InitState {
+    // A running scan owns currentRunId, the abort controller, and the live
+    // CLI subprocess. Refuse to wipe state under its feet — callers (the spec
+    // watcher) should be no-op'ing in that case anyway, since an in-flight
+    // init is the one thing that writes the spec.
+    if (state.running) return getState()
+    state = freshState()
+    currentRunId = null
+    broadcastProgress()
+    return getState()
+  }
+
+  return { start, cancel, commit, skip, reset, getState }
+}
+
+// ─── CLI agent spawn ──────────────────────────────────────────────────────────
+
+interface SpawnUsage {
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens?: number
+  cacheCreationTokens?: number
+  model?: string
+}
+
+interface SpawnCliOpts {
+  bin: InitCliBin
+  model?: string
+  effort?: EffortLevel
+  skillBody: string
+  userMessage: string
+  projectRoot: string
+  onLine: (line: string) => void
+  /**
+   * Fires once per usage-bearing line emitted by the CLI. Most CLIs report
+   * usage on completion (claude `result`, codex `turn.completed`); some emit
+   * incremental updates. Each call carries the delta or final total reported
+   * on that line — the caller decides whether to sum or replace.
+   */
+  onUsage?: (usage: SpawnUsage) => void
+  signal: AbortSignal
+}
+
+const AGENT_TIMEOUT_MS = 5 * 60_000  // 5 minutes — annotask-init can take a while on large projects
+
+/**
+ * Build the argv + stdin for an init CLI invocation. Pure (no spawning) so the
+ * per-CLI flags — including the easy-to-drop ones like codex's
+ * `--skip-git-repo-check` — can be unit-tested without a live CLI. Mirrors the
+ * per-task `*LocalProvider.buildSpawn` flag choices.
+ */
+export function buildInitCliInvocation(
+  opts: Pick<SpawnCliOpts, 'bin' | 'model' | 'effort' | 'skillBody' | 'userMessage'>,
+): { args: string[]; stdin?: string } {
+  const { bin, effort, skillBody, userMessage } = opts
+  const modelArg = opts.model?.trim()
+  const args: string[] = []
+  let stdin: string | undefined
+
+  // Each CLI gets the least-permissive headless mode that can still write
+  // inside `.annotask/` — see `initPermissionModeFor` in permission-mode-flags.ts
+  // for the per-CLI rationale (codex/copilot stay sandboxed; claude/opencode
+  // have no native less-permissive headless mode that allows writes).
+  const permissionFlags = initPermissionFlagsFor(bin)
+
+  if (bin === 'claude') {
+    // Claude Code CLI: --print reads from stdin, flattened System:/User: format.
+    args.push('--print', '--output-format', 'stream-json', '--verbose', ...permissionFlags)
+    if (modelArg) args.push('--model', modelArg)
+    stdin = `${skillBody}\n\nUser: ${userMessage}`
+  } else if (bin === 'codex') {
+    // Codex: positional prompt with skill prepended.
+    // `--skip-git-repo-check` matches the per-task CodexLocalProvider: without
+    // it codex refuses to start ("Not inside a trusted directory") in any
+    // project that isn't a git repo, producing zero output.
+    args.push('exec', '--json', ...permissionFlags, '--skip-git-repo-check')
+    if (modelArg) args.push('--model', modelArg)
+    if (effort && effort !== 'auto' && effort !== 'minimal') {
+      args.push('-c', `model_reasoning_effort=${effort}`)
+    }
+    // `--` is required: the skill body starts with YAML frontmatter (`---`),
+    // and without the separator clap parses the leading `--` as an unknown flag.
+    args.push('--', `${skillBody}\n\n---\n\n${userMessage}`)
+  } else if (bin === 'copilot') {
+    // GitHub Copilot CLI: `-p <prompt>` for non-interactive, JSON event stream.
+    args.push('--output-format', 'json', ...permissionFlags)
+    if (modelArg) args.push('--model', modelArg)
+    if (effort && effort !== 'auto' && effort !== 'minimal') {
+      args.push('--reasoning-effort', effort)
+    }
+    args.push('-p', `${skillBody}\n\n---\n\n${userMessage}`)
+  } else {
+    // opencode: run with positional prompt.
+    args.push('run', '--print-logs', '--format=json', ...permissionFlags)
+    if (modelArg) args.push('--model', modelArg)
+    // `--` is required: the skill body starts with YAML frontmatter (`---`),
+    // and without the separator the CLI parses the leading `--` as an unknown flag.
+    args.push('--', `${skillBody}\n\n---\n\n${userMessage}`)
+  }
+
+  return { args, stdin }
+}
+
+async function spawnCliWithSkill(opts: SpawnCliOpts): Promise<void> {
+  const { bin, projectRoot, onLine, onUsage, signal } = opts
+  const isAborted = () => signal.aborted
+  const { args, stdin } = buildInitCliInvocation(opts)
+
+  return new Promise<void>((resolve, reject) => {
+    if (isAborted()) { reject(new Error('Cancelled')); return }
+
+    const hostUser = hostUserSpawnOptions()
+    const child = spawn(bin, args, {
+      cwd: projectRoot,
+      shell: false,
+      uid: hostUser.uid,
+      gid: hostUser.gid,
+      env: { ...process.env, PATH: effectiveSpawnPath(), ...(hostUser.env ?? {}) },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+
+    if (stdin) {
+      child.stdin.write(stdin)
+      child.stdin.end()
+    } else {
+      child.stdin.end()
+    }
+
+    // Track whether the CLI actually produced any usable stdout. A run that
+    // exits 0 with zero stdout chunks is a silent failure — the most common
+    // case is opencode's configured model provider being unreachable; the
+    // failure lands on stderr as an `ERROR ... service=llm` line while
+    // stdout stays empty.
+    let stdoutSeen = false
+    let textOrUsageSeen = false
+    let fatalError: Error | null = null
+
+    function failFast(err: Error) {
+      if (fatalError) return
+      fatalError = err
+      try { child.kill('SIGTERM') } catch { /* ignore */ }
+      setTimeout(() => { try { child.kill('SIGKILL') } catch { /* ignore */ } }, 1_000).unref()
+    }
+
+    let stdoutBuf = ''
+    child.stdout.setEncoding('utf-8')
+    child.stdout.on('data', (chunk: string) => {
+      stdoutSeen = true
+      stdoutBuf += chunk
+      let nl: number
+      while ((nl = stdoutBuf.indexOf('\n')) >= 0) {
+        const line = stdoutBuf.slice(0, nl)
+        stdoutBuf = stdoutBuf.slice(nl + 1)
+        const trimmed = line.trim()
+        const text = extractTextFromLine(bin, trimmed)
+        if (text) { onLine(text); textOrUsageSeen = true }
+        if (onUsage) {
+          const u = extractUsageFromLine(bin, trimmed)
+          if (u) { onUsage(u); textOrUsageSeen = true }
+        }
+      }
+    })
+
+    let stderrBuf = ''
+    let stderrLineBuf = ''
+    child.stderr.setEncoding('utf-8')
+    child.stderr.on('data', (chunk: string) => {
+      stderrBuf += chunk
+      // Cap stderr buffer to prevent OOM on long-running stuck CLIs that
+      // spam log lines (opencode emits ~50 INFO lines per second on startup).
+      if (stderrBuf.length > 64_000) stderrBuf = stderrBuf.slice(-64_000)
+      stderrLineBuf += chunk
+      let nl: number
+      while ((nl = stderrLineBuf.indexOf('\n')) >= 0) {
+        const line = stderrLineBuf.slice(0, nl)
+        stderrLineBuf = stderrLineBuf.slice(nl + 1)
+        const fatal = detectFatalStderrLine(bin, line)
+        if (fatal) {
+          onLine(`[${bin}] ${fatal}`)
+          failFast(new Error(`${bin} ${fatal}`))
+        }
+      }
+    })
+
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM')
+      setTimeout(() => { try { child.kill('SIGKILL') } catch { /* ignore */ } }, 2_000).unref()
+      const tail = lastNonEmptyStderrLine(stderrBuf)
+      const detail = tail ? ` — last stderr: ${tail.slice(0, 300)}` : ''
+      reject(new Error(`Agent timed out after ${AGENT_TIMEOUT_MS / 1000}s${detail}`))
+    }, AGENT_TIMEOUT_MS)
+    timer.unref()
+
+    signal.addEventListener('abort', () => {
+      clearTimeout(timer)
+      try { child.kill('SIGTERM') } catch { /* ignore */ }
+    }, { once: true })
+
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      if (isAborted()) { reject(new Error('Cancelled')); return }
+      if (fatalError) {
+        reject(fatalError)
+        return
+      }
+      if (code !== 0 && code !== null) {
+        reject(new Error(`Agent exited with code ${code}. stderr: ${stderrBuf.slice(-500)}`))
+        return
+      }
+      // Exit 0 (or null) — but did the CLI actually do anything?
+      if (!stdoutSeen) {
+        const tail = lastNonEmptyStderrLine(stderrBuf)
+        const detail = tail ? ` Last stderr: ${tail.slice(0, 300)}` : ''
+        reject(new Error(
+          `${bin} exited cleanly but produced no output — check that the CLI is logged in and its configured model provider is reachable.${detail}`,
+        ))
+        return
+      }
+      if (!textOrUsageSeen) {
+        const tail = lastNonEmptyStderrLine(stderrBuf)
+        const detail = tail ? ` Last stderr: ${tail.slice(0, 300)}` : ''
+        reject(new Error(
+          `${bin} emitted output but no assistant text or token usage was parsed — the CLI may have failed mid-run.${detail}`,
+        ))
+        return
+      }
+      resolve()
+    })
+
+    child.on('error', (err) => {
+      clearTimeout(timer)
+      reject(err)
+    })
+  })
+}
+
+/**
+ * Detect fatal error lines on stderr that the CLI itself will never recover
+ * from (LLM provider unreachable, auth failure). Returns a short human
+ * description when a fatal pattern matches; null otherwise.
+ *
+ * opencode emits structured log lines like:
+ *   ERROR 2026-... service=llm ... error={"error":{"name":"AI_APICallError",
+ *     "cause":{"code":"ConnectionRefused", "path":"http://..."},...}}
+ * The CLI then retries silently. Without this short-circuit, the init pipeline
+ * waits the full 5-minute timeout with no visible feedback.
+ */
+function detectFatalStderrLine(bin: string, line: string): string | null {
+  if (!line) return null
+  if (bin === 'opencode') {
+    if (!line.startsWith('ERROR')) return null
+    // Only treat LLM-service errors as fatal — file-watcher / formatter
+    // warnings sometimes surface as ERROR but don't block the run.
+    if (!line.includes('service=llm')) return null
+    // Try to extract the most specific cause we can: ConnectionRefused is
+    // the canonical "your provider isn't running" signal; AI_APICallError
+    // covers the broader bucket (auth, 5xx, etc.).
+    const causeCode = line.match(/"code":"([^"]+)"/)?.[1]
+    const causePath = line.match(/"path":"([^"]+)"/)?.[1]
+    const errName   = line.match(/"name":"([^"]+)"/)?.[1]
+    if (causeCode && causePath) {
+      return `LLM provider unreachable (${causeCode} at ${causePath})`
+    }
+    if (errName) return `LLM call failed: ${errName}`
+    return 'LLM call failed (see logs)'
+  }
+  return null
+}
+
+function lastNonEmptyStderrLine(buf: string): string | null {
+  const lines = buf.split('\n')
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim()
+    if (line.length > 0) return line
+  }
+  return null
+}
+
+/**
+ * Extract displayable text from a CLI output line.
+ * Claude outputs stream-json events; codex/opencode also output JSON.
+ * If we can't parse it, return the raw line (truncated).
+ */
+function extractTextFromLine(bin: string, line: string): string | null {
+  if (!line) return null
+  try {
+    const ev = JSON.parse(line) as any
+    // Claude stream-json
+    if (ev.type === 'assistant' && ev.message?.content) {
+      const texts = (ev.message.content as any[]).filter(b => b.type === 'text').map(b => b.text)
+      return texts.join('') || null
+    }
+    // Codex item_completed with text
+    if (ev.type === 'item.completed' && ev.item?.text) return String(ev.item.text)
+    // opencode v1.14+: { type: 'text', part: { type: 'text', text: '...' } }
+    if (ev.type === 'text' && typeof ev.part?.text === 'string' && ev.part.text.length > 0) {
+      return ev.part.text
+    }
+    // opencode (legacy / fallback shapes)
+    if (ev.type === 'text' && typeof ev.text === 'string' && ev.text.length > 0) return ev.text
+    if (ev.type === 'assistant' && typeof ev.text === 'string') return ev.text
+    if (ev.type === 'message' && ev.content) return String(ev.content)
+    // Copilot CLI: stream events from `copilot --output-format json`.
+    //   • assistant.message_delta carries per-chunk text in data.deltaContent
+    //     (a few chars at a time, sometimes splitting mid-word)
+    //   • assistant.message carries the cumulative text in data.content
+    //
+    // The streaming chat provider uses deltas because it paints text
+    // incrementally and skipping deltas would freeze the UI. The init wizard
+    // is the opposite shape: it appends each emitted string as its own entry
+    // in the agent-output panel, so per-chunk deltas turn one message into
+    // ~50 newline-separated word fragments. Read the cumulative
+    // `assistant.message.content` here and ignore deltas — one message in,
+    // one paragraph out.
+    if (bin === 'copilot' && ev.type === 'assistant.message'
+        && typeof ev.data?.content === 'string'
+        && ev.data.content.length > 0) {
+      return ev.data.content
+    }
+    return null
+  } catch {
+    // Not JSON — surface non-trivial plaintext lines
+    return line.length > 5 && !line.startsWith('{') ? line : null
+  }
+}
+
+/**
+ * Extract token usage from a CLI output line. Mirrors the per-CLI shapes the
+ * embedded providers parse (claude-local-provider, codex-local-provider,
+ * opencode-local-provider) so the init pipeline reports usage with the same
+ * fidelity as a live chat turn.
+ */
+function extractUsageFromLine(bin: string, line: string): SpawnUsage | null {
+  if (!line || !line.startsWith('{')) return null
+  let ev: any
+  try { ev = JSON.parse(line) } catch { return null }
+  if (!ev || typeof ev !== 'object') return null
+  if (bin === 'claude') {
+    // The `result` line carries the final cumulative totals; `message_start`
+    // and intermediate `message` events also carry running totals. We only
+    // emit on `result` to avoid double-counting — init runs are one-shot.
+    if (ev.type === 'result' && ev.usage) {
+      const u = ev.usage
+      return {
+        inputTokens: numberOr(u.input_tokens, 0),
+        outputTokens: numberOr(u.output_tokens, 0),
+        cacheReadTokens: numberOr(u.cache_read_input_tokens, undefined),
+        cacheCreationTokens: numberOr(u.cache_creation_input_tokens, undefined),
+        model: typeof ev.model === 'string' ? ev.model : undefined,
+      }
+    }
+    return null
+  }
+  if (bin === 'codex') {
+    if (ev.type === 'turn.completed' && ev.usage) {
+      const u = ev.usage
+      return {
+        inputTokens: numberOr(u.input_tokens, 0),
+        outputTokens: numberOr(u.output_tokens, 0),
+        cacheReadTokens: numberOr(u.cached_input_tokens, undefined),
+        model: typeof ev.model === 'string' ? ev.model : undefined,
+      }
+    }
+    return null
+  }
+  if (bin === 'copilot') {
+    // Copilot CLI surfaces only outputTokens per assistant message; no
+    // input-token count is exposed. The terminal `result` event carries
+    // timing/premiumRequests but no token totals — see
+    // src/embedded/copilot-local-provider.ts for the same contract.
+    if (ev.type === 'assistant.message' && typeof ev.data?.outputTokens === 'number') {
+      return {
+        inputTokens: 0,
+        outputTokens: numberOr(ev.data.outputTokens, 0),
+        model: typeof ev.data?.model === 'string' ? ev.data.model : undefined,
+      }
+    }
+    return null
+  }
+  // opencode v1.14+: token totals ride on `step_finish` events under
+  // `part.tokens.{input,output,cache.{read,write}}`. Mirrors
+  // src/embedded/opencode-local-provider.ts:179-190.
+  if (ev.type === 'step_finish' && ev.part?.tokens) {
+    const t = ev.part.tokens
+    if (typeof t.input === 'number' || typeof t.output === 'number') {
+      return {
+        inputTokens: numberOr(t.input, 0),
+        outputTokens: numberOr(t.output, 0),
+        cacheReadTokens: numberOr(t.cache?.read, undefined),
+        cacheCreationTokens: numberOr(t.cache?.write, undefined),
+        model: typeof ev.model === 'string' ? ev.model : undefined,
+      }
+    }
+  }
+  // Legacy / OpenAI-compatible shape that older opencode releases emitted
+  // on the closing event of each turn.
+  if (ev.usage && (ev.usage.input_tokens || ev.usage.output_tokens)) {
+    const u = ev.usage
+    return {
+      inputTokens: numberOr(u.input_tokens, 0),
+      outputTokens: numberOr(u.output_tokens, 0),
+      model: typeof ev.model === 'string' ? ev.model : undefined,
+    }
+  }
+  return null
+}
+
+function numberOr<T>(v: unknown, fallback: T): number | T {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback
+}
+
+// ─── Framework detection ──────────────────────────────────────────────────────
+
+interface FrameworkInfo { name: string; version?: string; styling: string[] }
+
+async function detectFramework(projectRoot: string): Promise<FrameworkInfo> {
+  let pkg: any = {}
+  try { pkg = JSON.parse(await fsp.readFile(path.join(projectRoot, 'package.json'), 'utf-8')) } catch { return { name: 'unknown', styling: [] } }
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
+
+  let name = 'unknown'
+  let version: string | undefined
+  if (deps.vue)             { name = 'vue';    version = String(deps.vue).replace(/^\^|~/, '') }
+  else if (deps.react)      { name = 'react';  version = String(deps.react).replace(/^\^|~/, '') }
+  else if (deps.svelte)     { name = 'svelte'; version = String(deps.svelte).replace(/^\^|~/, '') }
+  else if (deps['solid-js'])  { name = 'solid';  version = String(deps['solid-js']).replace(/^\^|~/, '') }
+  else if (deps.astro)      { name = 'astro';  version = String(deps.astro).replace(/^\^|~/, '') }
+
+  const styling: string[] = []
+  if (deps.tailwindcss || deps['@tailwindcss/vite']) styling.push('tailwind')
+  if (name === 'vue') styling.push('scoped-css')
+  if (Object.keys(deps).some(d => /css-modules?/.test(d))) styling.push('css-modules')
+  return { name, version, styling }
+}
+
+// ─── Theme variant detection ──────────────────────────────────────────────────
+
+interface ThemeVariantDetection {
+  themes: Array<{ id: string; name: string; scheme?: string; selector: Record<string, unknown> }>
+  defaultTheme: string
+}
+
+async function detectThemeVariants(cssFiles: string[]): Promise<ThemeVariantDetection> {
+  let combined = ''
+  for (const file of cssFiles.slice(0, 60)) {
+    try { combined += '\n' + await fsp.readFile(file, 'utf-8') } catch { /* skip */ }
+  }
+
+  const hasDarkClass = /(?::root|html|body)\.dark\b/.test(combined) || /(?:html|body)\.dark\s*\{/.test(combined)
+  const dataThemeMatch = combined.match(/\[data-theme="([^"]+)"\]/g)
+  const hasMediaDark = /@media\s*\(prefers-color-scheme:\s*dark\)/.test(combined)
+
+  if (hasDarkClass) return {
+    themes: [
+      { id: 'light', name: 'Light', scheme: 'light', selector: { kind: 'default' } },
+      { id: 'dark',  name: 'Dark',  scheme: 'dark',  selector: { kind: 'class', host: 'html', name: 'dark' } },
+    ], defaultTheme: 'light',
+  }
+
+  if (dataThemeMatch?.length) {
+    const values = new Set<string>()
+    for (const m of dataThemeMatch) {
+      const v = m.match(/\[data-theme="([^"]+)"\]/)?.[1]
+      if (v) values.add(v)
+    }
+    const themes = Array.from(values).map(v => ({
+      id: v, name: v.charAt(0).toUpperCase() + v.slice(1),
+      selector: { kind: 'attribute', host: 'html', name: 'data-theme', value: v },
+    }))
+    if (themes.length) return { themes, defaultTheme: themes[0].id }
+  }
+
+  if (hasMediaDark) return {
+    themes: [
+      { id: 'light', name: 'Light', scheme: 'light', selector: { kind: 'default' } },
+      { id: 'dark',  name: 'Dark',  scheme: 'dark',  selector: { kind: 'media', media: '(prefers-color-scheme: dark)' } },
+    ], defaultTheme: 'light',
+  }
+
+  return { themes: [{ id: 'default', name: 'Default', selector: { kind: 'default' } }], defaultTheme: 'default' }
+}
+
+// ─── File collection ──────────────────────────────────────────────────────────
+
+async function collectCssFiles(projectRoot: string): Promise<string[]> {
+  const out: string[] = []
+  for (const root of ['src', 'app', 'styles', 'assets', 'public']) {
+    await walk(path.join(projectRoot, root), out, ['.css', '.scss', '.sass', '.vue', '.svelte', '.astro'])
+  }
+  return out
+}
+
+async function walk(dir: string, out: string[], exts: string[], depth = 0): Promise<void> {
+  if (depth > 6) return
+  let entries: import('node:fs').Dirent[]
+  try { entries = await fsp.readdir(dir, { withFileTypes: true }) } catch { return }
+  for (const ent of entries) {
+    if (ent.name.startsWith('.') || ent.name === 'node_modules' || ent.name === 'dist') continue
+    const full = path.join(dir, ent.name)
+    if (ent.isDirectory()) await walk(full, out, exts, depth + 1)
+    else if (exts.some(e => ent.name.endsWith(e))) out.push(full)
+  }
+}
+
+// ─── Component library ────────────────────────────────────────────────────────
+
+const FRAMEWORK_LIBRARY_PATTERNS: Record<string, RegExp> = {
+  vue:    /vue|primevue|quasar|nuxt|naive-ui|radix-vue|vueuse|headlessui|oruga|varlet|element-plus|ant-design-vue|vant/i,
+  react:  /react|mantine|chakra|radix-ui|shadcn|antd|material-ui|@mui|headlessui|nextui|tremor|ark-ui/i,
+  svelte: /svelte|bits-ui|shadcn-svelte/i,
+  solid:  /solid|kobalte/i,
+  astro:  /astro/i,
+}
+
+function summarizeComponents(catalog: any, frameworkName?: string): Record<string, unknown> | null {
+  const libs: any[] = Array.isArray(catalog?.libraries) ? catalog.libraries : []
+  if (libs.length === 0) return null
+
+  let candidates = libs
+  if (frameworkName) {
+    const pattern = FRAMEWORK_LIBRARY_PATTERNS[frameworkName]
+    if (pattern) {
+      const matching = libs.filter(l => pattern.test(l.name))
+      if (matching.length > 0) candidates = matching
+    }
+  }
+
+  const primary = candidates.slice().sort((a, b) => (b.components?.length ?? 0) - (a.components?.length ?? 0))[0]
+  if (!primary) return null
+  if (!primary.name) return null
+  return { library: primary.name, version: primary.version, used: [] }
+}
+
+// ─── Draft helpers ────────────────────────────────────────────────────────────
+
+function baseDraftSpec(
+  framework: FrameworkInfo | null | undefined,
+  themes: Array<{ id: string; selector: Record<string, unknown> }>,
+  defaultTheme: string,
+  components: Record<string, unknown> | null | undefined,
+): Record<string, unknown> {
+  return {
+    version: '1.0',
+    framework: framework ?? { name: 'unknown', version: '', styling: [] },
+    themes,
+    defaultTheme,
+    colors: [],
+    typography: { families: [], scale: [], weights: [] },
+    spacing: [],
+    borders: { radius: [] },
+    breakpoints: {},
+    icons: null,
+    components: components ?? null,
+  }
+}
+
+// ─── Style guide template ────────────────────────────────────────────────────
+
+const STYLE_GUIDE_TEMPLATE = `# Project style guide
+
+Annotask agents read this file before applying tasks. Fill in the sections
+below to teach them your project's conventions. Empty sections are fine —
+agents will fall back to inferring from the existing code.
+
+## Naming conventions
+
+<!-- e.g. PascalCase components, camelCase composables, kebab-case CSS classes -->
+
+## Spacing & layout
+
+<!-- e.g. 4px base unit; cards use --space-md padding; grid is 12-column -->
+
+## Component patterns
+
+<!-- e.g. wrap form inputs in <FormField label="…">; use <Button variant="primary"> -->
+
+## Things to avoid
+
+<!-- e.g. don't add new dependencies; don't refactor for cleanliness; preserve inline styles -->
+
+## Project context
+
+<!-- A sentence or two about what this project is for. Helps agents pick tone in copy edits. -->
+`
diff --git a/src/server/json-cas-store.ts b/src/server/json-cas-store.ts
new file mode 100644
index 0000000..649bc85
--- /dev/null
+++ b/src/server/json-cas-store.ts
@@ -0,0 +1,72 @@
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+
+/**
+ * Thrown when a `set()` carries a stale (or missing) `rev` against a doc that
+ * already has one. The HTTP layer maps this to a 409 `conflict` so the losing
+ * tab reloads instead of last-writer-wins clobbering the other writer.
+ */
+export class RevConflictError extends Error {
+  constructor(public readonly currentRev: number, incomingRev: unknown, what = 'document') {
+    super(`${what} rev conflict: document is at rev ${currentRev}, write carried rev ${String(incomingRev)}`)
+    this.name = 'RevConflictError'
+  }
+}
+
+/**
+ * Generic compare-and-set JSON document store — the wireframe-store pattern
+ * (no in-memory cache: the file is small and may be edited externally, so
+ * always read fresh; atomic tmp+rename writes; CAS on `rev`) lifted so new
+ * documents (design session, …) don't re-implement it. `wireframe-store.ts`
+ * itself is left untouched — consolidating it onto this is a separate chore.
+ */
+export function createJsonCasStore<T extends { rev?: number }>(
+  filePath: string,
+  opts: {
+    /** Shape guard — malformed disk content falls back to `empty()`. */
+    validate: (v: unknown) => v is T
+    empty: () => T
+    /** Used in conflict error messages (e.g. 'Design session'). */
+    label?: string
+  },
+) {
+  async function load(): Promise<T> {
+    try {
+      const raw = JSON.parse(await fsp.readFile(filePath, 'utf-8'))
+      return opts.validate(raw) ? raw : opts.empty()
+    } catch {
+      return opts.empty()
+    }
+  }
+
+  async function persist(doc: T): Promise<void> {
+    const dir = path.dirname(filePath)
+    await fsp.mkdir(dir, { recursive: true })
+    const tmp = `${filePath}.tmp.${process.pid}.${Date.now()}`
+    await fsp.writeFile(tmp, JSON.stringify(doc, null, 2), 'utf-8')
+    await fsp.rename(tmp, filePath)
+  }
+
+  return {
+    get: load,
+    /** CAS write: enforced once the on-disk doc carries a rev; a fresh/legacy
+     *  doc accepts any write, which stamps rev 1. Returns the stamped doc. */
+    set: async (doc: T): Promise<T> => {
+      const current = await load()
+      if (typeof current.rev === 'number' && doc.rev !== current.rev) {
+        throw new RevConflictError(current.rev, doc.rev, opts.label ?? 'Document')
+      }
+      const stamped: T = { ...doc, rev: (current.rev ?? 0) + 1 }
+      await persist(stamped)
+      return stamped
+    },
+    /** Unconditional replace (server-owned mutations like discard) — still
+     *  bumps the rev so concurrent CAS writers lose cleanly. */
+    replace: async (doc: T): Promise<T> => {
+      const current = await load()
+      const stamped: T = { ...doc, rev: (current.rev ?? 0) + 1 }
+      await persist(stamped)
+      return stamped
+    },
+  }
+}
diff --git a/src/server/origin.ts b/src/server/origin.ts
index a62d493..98a8669 100644
--- a/src/server/origin.ts
+++ b/src/server/origin.ts
@@ -1,3 +1,5 @@
+import net from 'node:net'
+
 /**
  * Origin validation for mutating requests.
  *
@@ -37,3 +39,67 @@ export function originMatchesPort(origin: string | undefined, port: number | und
 function isLocalHostname(host: string): boolean {
   return host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1'
 }
+
+/**
+ * Host-header gate against DNS rebinding.
+ *
+ * Annotask's middleware registers ahead of Vite's own host-check middleware,
+ * so Vite's `allowedHosts` never protects `/__annotask/*`. Without a Host
+ * check, a page on `evil.example` whose DNS re-resolves to 127.0.0.1 can read
+ * every GET endpoint (read-file, tasks, screenshots, transcripts) — the
+ * browser sends the request straight to the dev server with
+ * `Host: evil.example` and same-origin rules don't apply.
+ *
+ * Accepts when:
+ *   - there is no Host header at all (HTTP/1.0 / non-browser clients — a
+ *     browser-driven rebinding attack always carries the attacker hostname);
+ *   - the hostname part is localhost / 127.0.0.1 / [::1] / ::1;
+ *   - the hostname is an IP literal (a typed-in LAN address like
+ *     192.168.1.5:5173 — an IP in Host can't be a rebound DNS name, which is
+ *     also why Vite allows IPs by default);
+ *   - it matches an entry in `extraAllowed` (the host the server announces in
+ *     server.json plus any Vite `server.allowedHosts` entries — `'*'` allows
+ *     everything, a leading-dot entry like `.example.com` allows the domain
+ *     and all subdomains, mirroring Vite's semantics);
+ *   - it is listed in the env var `ANNOTASK_ALLOWED_HOSTS` (comma-separated
+ *     hostnames, e.g. `ANNOTASK_ALLOWED_HOSTS=dev.tunnel.example,myhost.local`).
+ */
+export function isAllowedHost(hostHeader: string | undefined, extraAllowed: readonly string[] = []): boolean {
+  if (!hostHeader) return true
+  const hostname = hostnameOf(hostHeader)
+  if (!hostname) return false
+  if (isLocalHostname(hostname)) return true
+  if (isIpLiteral(hostname)) return true
+  const envList = (process.env.ANNOTASK_ALLOWED_HOSTS ?? '').split(',').map(s => s.trim()).filter(Boolean)
+  for (const entry of [...extraAllowed, ...envList]) {
+    if (entry === '*') return true
+    const allowed = hostnameOf(entry)
+    if (!allowed) continue
+    if (allowed.startsWith('.')) {
+      // Vite-style suffix entry: `.example.com` allows example.com and any subdomain.
+      if (hostname === allowed.slice(1) || hostname.endsWith(allowed)) return true
+    } else if (hostname === allowed) {
+      return true
+    }
+  }
+  return false
+}
+
+/** Lowercased hostname part of a Host header value (port stripped, IPv6 kept bracketed). */
+function hostnameOf(raw: string): string | null {
+  const trimmed = raw.trim()
+  if (!trimmed) return null
+  // Leading-dot suffix entries (`.example.com`) aren't URL-parseable — keep verbatim.
+  if (trimmed.startsWith('.')) return trimmed.toLowerCase()
+  try {
+    return new URL(`http://${trimmed}`).hostname.toLowerCase()
+  } catch {
+    return null
+  }
+}
+
+/** True for bare IPv4/IPv6 literals (IPv6 arrives bracketed from `hostnameOf`). */
+function isIpLiteral(hostname: string): boolean {
+  const bare = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname
+  return net.isIP(bare) !== 0
+}
diff --git a/src/server/runtime-endpoints.ts b/src/server/runtime-endpoints.ts
index a6d9e5a..de9c1b8 100644
--- a/src/server/runtime-endpoints.ts
+++ b/src/server/runtime-endpoints.ts
@@ -315,7 +315,13 @@ export function findMatchingStaticEntries<T extends { name: string; method?: str
   for (const entry of staticEntries) {
     if (!entry.endpoint) continue
     if (entry.method && entry.method.toUpperCase() !== ep.method) continue
-    const decomp = decomposeEndpoint(entry.resolved_endpoint || entry.endpoint)
+    // Match on the ORIGINAL endpoint, not the proxy-resolved one. A relative
+    // endpoint (`/api/...`) is a same-origin call from the browser — its origin
+    // is '' and matches the same-origin '' the iframe reports for Vite-proxied
+    // fetches. resolved_endpoint's proxy-target host (e.g. :8888) is a
+    // server-side detail; gating on it makes every proxied same-origin call
+    // miss its static entry (so the Network tab showed only orphans).
+    const decomp = decomposeEndpoint(entry.endpoint)
     if (!decomp.path) continue
     // Path must match either as normalized pattern or as a literal.
     if (decomp.pattern !== ep.pattern && decomp.path !== ep.path) continue
@@ -366,7 +372,12 @@ export function mergeRuntimeOrphansIntoEntries(
   for (const entry of staticEntries) {
     if (!entry.endpoint) continue
     const method = (entry.method || 'GET').toUpperCase()
-    const decomp = decomposeEndpoint(entry.resolved_endpoint || entry.endpoint)
+    // Original endpoint, not proxy-resolved (see findMatchingStaticEntries):
+    // a relative entry's origin is '' so it covers same-origin '' runtime calls
+    // via `relKey` — which is how the iframe reports Vite-proxied fetches. Using
+    // the resolved :PORT host here would orphan every proxied call (duplicate
+    // synthetic rows alongside the real static entry).
+    const decomp = decomposeEndpoint(entry.endpoint)
     if (!decomp.path) continue
     covered.add(`${method}|${decomp.origin}|${decomp.pattern}`)
   }
diff --git a/src/server/schemas.ts b/src/server/schemas.ts
index f863ec6..7533868 100644
--- a/src/server/schemas.ts
+++ b/src/server/schemas.ts
@@ -7,9 +7,12 @@
  * in one place instead of spread across hand-rolled checks.
  */
 import { z } from 'zod'
-import { TASK_TYPES } from '../schema.js'
+import { TASK_TYPES, PERMISSION_MODES } from '../schema.js'
 import { SAFE_SCREENSHOT_RE, VALID_TASK_STATUSES, VALID_TRANSITIONS } from './validation.js'
 
+const permissionModeValues = [...PERMISSION_MODES] as [typeof PERMISSION_MODES[number], ...typeof PERMISSION_MODES[number][]]
+const permissionModeError = `Invalid permissionMode. Must be one of: ${permissionModeValues.join(', ')}`
+
 const statusValues = [...VALID_TASK_STATUSES] as [string, ...string[]]
 const statusError = `Invalid status. Must be one of: ${statusValues.join(', ')}`
 
@@ -99,6 +102,7 @@ export const CreateTaskBody = z.object({
   screenshot: ScreenshotName.optional(),
   screenshot_meta: z.unknown().optional(),
   visual: z.unknown().optional(),
+  permissionMode: z.enum(permissionModeValues, { message: permissionModeError }).optional(),
 })
 
 // ── HTTP: PATCH /tasks/:id ───────────────────────────────
@@ -121,6 +125,10 @@ export const UpdateTaskBody = z.object({
   agent_feedback: AgentFeedbackSchema.optional(),
   blocked_reason: z.string().optional(),
   resolution: z.string().optional(),
+  // `null` clears the per-task override so the task inherits from the persona
+  // tier (or global). Resolution uses `??`, which treats null and undefined
+  // identically — both fall through to the next tier.
+  permissionMode: z.enum(permissionModeValues, { message: permissionModeError }).nullable().optional(),
 })
 
 // ── HTTP: POST /screenshots ──────────────────────────────
@@ -129,6 +137,14 @@ export const UploadScreenshotBody = z.object({
   data: z.string().regex(/^data:image\/png;base64,/, 'Invalid PNG data URL'),
 })
 
+// ── HTTP: POST /wireframe-snapshots ──────────────────────
+
+export const UploadWireframeSnapshotBody = z.object({
+  /** Shell-minted block id — becomes the filename ({id}.png). */
+  id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/, 'Invalid snapshot id'),
+  data: z.string().regex(/^data:image\/png;base64,/, 'Invalid PNG data URL'),
+})
+
 // ── HTTP: POST /performance ──────────────────────────────
 
 export const PerformanceSnapshotBody = z.unknown() // shape owned by the shell; validated there
diff --git a/src/server/session-store.ts b/src/server/session-store.ts
new file mode 100644
index 0000000..92280f4
--- /dev/null
+++ b/src/server/session-store.ts
@@ -0,0 +1,33 @@
+import path from 'node:path'
+import { createJsonCasStore, RevConflictError } from './json-cas-store.js'
+import {
+  emptyDesignSessionDocument,
+  isDesignSessionDocument,
+  type DesignSessionDocument,
+} from '../shared/design-session-types.js'
+
+export { RevConflictError }
+
+/**
+ * Persists the design-session journal to `.annotask/design-session.json` —
+ * the ordered record of what the user did in the design tool (element edits +
+ * placement cross-references). The shell owns the in-memory journal and PUTs
+ * the whole document (small, single-writer file, CAS on `rev`); the server
+ * owns discard and the task-lifecycle mutations.
+ */
+export function createSessionStore(projectRoot: string) {
+  // The empty doc needs a session id; mint one per store so repeated GETs of a
+  // missing file agree with each other until the first write adopts the
+  // shell's id.
+  const fallbackId = `ds-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`
+  return createJsonCasStore<DesignSessionDocument>(
+    path.join(projectRoot, '.annotask', 'design-session.json'),
+    {
+      validate: isDesignSessionDocument,
+      empty: () => emptyDesignSessionDocument(fallbackId),
+      label: 'Design session',
+    },
+  )
+}
+
+export type SessionStore = ReturnType<typeof createSessionStore>
diff --git a/src/server/standalone.ts b/src/server/standalone.ts
index 24a2492..4ffca18 100644
--- a/src/server/standalone.ts
+++ b/src/server/standalone.ts
@@ -12,9 +12,28 @@ export async function startStandaloneServer(options: StandaloneServerOptions): P
   close: () => Promise<void>
 }> {
   const port = options.port || 24678
-  const uiServer = createAnnotaskServer({ projectRoot: options.projectRoot })
+  // The standalone server binds 127.0.0.1 only, so the API middleware's Host
+  // gate (DNS rebinding) passes on the IP literal already — the array exists
+  // so the announced host stays allowed if the bind logic ever changes.
+  const extraAllowedHosts: string[] = []
+  const uiServer = createAnnotaskServer({
+    projectRoot: options.projectRoot,
+    allowedHosts: () => extraAllowedHosts,
+  })
 
   const httpServer = http.createServer((req, res) => {
+    // Vite serves /__annotask/preview-module through its on-demand /@fs/
+    // transform pipeline; webpack has no equivalent (a raw .vue/.svelte URL
+    // would be untransformable in the browser). Answer honestly and FAST so
+    // ensureComponentLoaded falls into the labeled 'not-registered'
+    // placeholder — off-route palette mounts are a documented Vite-only
+    // capability; on-route components work the same under both bundlers.
+    if (req.url?.startsWith('/__annotask/preview-module')) {
+      res.statusCode = 404
+      res.setHeader('Content-Type', 'application/json')
+      res.end(JSON.stringify({ error: 'preview-module unavailable under webpack: components must be loaded by a visited route' }))
+      return
+    }
     uiServer.middleware(req, res, () => {
       res.statusCode = 404
       res.end('Not found')
@@ -41,6 +60,7 @@ export async function startStandaloneServer(options: StandaloneServerOptions): P
         httpServer.listen(0, '127.0.0.1', () => {
           const addr = httpServer.address() as { port: number; address: string }
           writeServerInfo(options.projectRoot, addr.port, addr.address)
+          extraAllowedHosts.push(addr.address)
           resolve({ port: addr.port, close: shutdown })
         })
       } else {
@@ -50,6 +70,7 @@ export async function startStandaloneServer(options: StandaloneServerOptions): P
 
     httpServer.listen(port, '127.0.0.1', () => {
       writeServerInfo(options.projectRoot, port, '127.0.0.1')
+      extraAllowedHosts.push('127.0.0.1')
       resolve({ port, close: shutdown })
     })
   })
diff --git a/src/server/state.ts b/src/server/state.ts
index ccf03a9..6f3075e 100644
--- a/src/server/state.ts
+++ b/src/server/state.ts
@@ -3,7 +3,13 @@ import fsp from 'node:fs/promises'
 import path from 'node:path'
 import { isSafeScreenshot } from './validation.js'
 import { createRuntimeEndpointStore, type RuntimeEndpointStore } from './runtime-endpoints.js'
-import type { NetworkCall, RuntimeEndpointCatalog } from '../schema.js'
+import { createAgentConfigStore } from './agent-configs.js'
+import type { AgentConfigs, AgentConfigEntry } from './agent-configs.js'
+import { createWireframeStore } from './wireframe-store.js'
+import { createSessionStore } from './session-store.js'
+import type { NetworkCall, RuntimeEndpointCatalog, TokenUsage } from '../schema.js'
+import { isWireframeDocument, type WireframeDocument } from '../shared/wireframe-types.js'
+import { emptyDesignSessionDocument, type DesignSessionDocument } from '../shared/design-session-types.js'
 
 const DEFAULT_DESIGN_SPEC = {
   initialized: false,
@@ -72,7 +78,26 @@ export interface ProjectState {
   getConfig: () => unknown
   getTasks: () => { version: string; tasks: any[] }
   addTask: (task: Record<string, unknown>) => Promise<unknown>
-  updateTask: (id: string, updates: Record<string, unknown>) => Promise<unknown>
+  /**
+   * Update a task. `opts.guard` runs INSIDE the task lock against the task as
+   * it exists at update time — the HTTP layer passes its status-transition
+   * assert here so two concurrent PATCHes can't both pass a pre-lock check
+   * (TOCTOU). A non-null guard return aborts the update and surfaces as
+   * `{ error: 'Invalid transition', reason }`.
+   */
+  updateTask: (
+    id: string,
+    updates: Record<string, unknown>,
+    opts?: { guard?: (task: Record<string, unknown>) => string | null },
+  ) => Promise<unknown>
+  /**
+   * Increment a task's `tokenUsage` rollup. Called from the task-thread store's
+   * onAppend hook when an assistant turn lands with usage. Silently no-ops on
+   * unknown task ids — the conversation log can outlive the task record
+   * (e.g. an accepted task is removed while a late-arriving usage event is
+   * still in flight).
+   */
+  addTaskUsage: (id: string, usage: Partial<TokenUsage>) => Promise<TokenUsage | null>
   deleteTask: (id: string) => Promise<unknown>
   /** Persist per-task interaction history alongside tasks.json so agents can
    *  fetch it on demand even when the user didn't embed it in the task payload. */
@@ -89,13 +114,46 @@ export interface ProjectState {
   getRuntimeEndpointCatalog: () => RuntimeEndpointCatalog
   /** Drop the runtime endpoint catalog (in-memory + on-disk). */
   clearRuntimeEndpoints: () => void
+  /** Read per-persona project directions from `.annotask/agents.json`. */
+  getAgentConfigs: () => Promise<AgentConfigs>
+  /** Write one persona's project directions and return the updated file. */
+  setAgentConfig: (personaId: string, entry: Partial<AgentConfigEntry>) => Promise<AgentConfigs>
+  /** Read the persisted multi-route wireframe document (`.annotask/wireframe.json`). */
+  getWireframe: () => Promise<WireframeDocument>
+  /** Replace the wireframe document, persist atomically, broadcast, and return it. */
+  setWireframe: (doc: WireframeDocument) => Promise<WireframeDocument>
+  /** Read the persisted design-session journal (`.annotask/design-session.json`). */
+  getDesignSession: () => Promise<DesignSessionDocument>
+  /** Replace the design-session journal (CAS on rev), broadcast, and return it. */
+  setDesignSession: (doc: DesignSessionDocument) => Promise<DesignSessionDocument>
+  /** Server-owned reset to an empty session (discard / accept-all) — not CAS-gated. */
+  clearDesignSession: () => Promise<DesignSessionDocument>
   /** Wait for any pending writes to complete. Use before process shutdown. */
   flush: () => Promise<void>
+  /**
+   * Health of the tasks.json disk-write path. Mutations reply 200 before the
+   * fire-and-forget flush lands, so a failing disk write would otherwise lose
+   * data silently — this lets `/api/status` report `persistence: 'degraded'`.
+   */
+  getPersistenceHealth: () => PersistenceHealth
   dispose: () => void
 }
 
-/** Atomic write: write to tmp file then rename into place */
-async function atomicWrite(filePath: string, data: string) {
+export interface PersistenceHealth {
+  ok: boolean
+  consecutiveFailures: number
+  lastError: string | null
+}
+
+function clampNonNeg(n: number | undefined): number {
+  if (n == null || !Number.isFinite(n) || n < 0) return 0
+  return n
+}
+
+/** Atomic write: write to tmp file then rename into place. Exported so other
+ *  `.annotask/` writers (init commit/skip) share the same crash-safe pattern
+ *  instead of racing the sync readers here with a plain writeFile. */
+export async function atomicWrite(filePath: string, data: string) {
   const dir = path.dirname(filePath)
   await fsp.mkdir(dir, { recursive: true })
   const tmpPath = filePath + `.tmp.${process.pid}.${Date.now()}`
@@ -103,9 +161,57 @@ async function atomicWrite(filePath: string, data: string) {
   await fsp.rename(tmpPath, filePath)
 }
 
-export function createProjectState(projectRoot: string, broadcast: (event: string, data: unknown) => void): ProjectState {
+/**
+ * Best-effort: make sure `.annotask/` is gitignored. Transcripts
+ * (conversations/*.jsonl), screenshots, and sidecars accumulate under
+ * `.annotask/` — before this helper the only thing keeping them out of
+ * commits was an instruction inside the LLM skill text. Only touches
+ * projects that have a `.git` (dir or worktree file), appends exactly once,
+ * and never throws — a read-only checkout must not break server boot.
+ */
+export function ensureAnnotaskIgnored(projectRoot: string): void {
+  try {
+    if (!fs.existsSync(path.join(projectRoot, '.git'))) return
+    const gitignorePath = path.join(projectRoot, '.gitignore')
+    let existing = ''
+    try { existing = fs.readFileSync(gitignorePath, 'utf-8') } catch { /* no .gitignore yet */ }
+    // Already covered when any line is `.annotask` / `.annotask/` / `/.annotask/`.
+    if (/^\/?\.annotask\/?\s*$/m.test(existing)) return
+    const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : ''
+    fs.appendFileSync(gitignorePath, `${prefix}# Annotask local data (tasks, screenshots, conversation transcripts)\n.annotask/\n`, 'utf-8')
+  } catch { /* best-effort — never block boot */ }
+}
+
+export interface ProjectStateOptions {
+  /**
+   * Fired when `design-spec.json` disappears from disk (the file is unlinked
+   * outside the normal init write flow). Used by the init runner to drop its
+   * in-memory step state — the wizard's "all green checkmarks from last run"
+   * survives a `rm -rf .annotask/*` until something tells it the world has
+   * changed.
+   */
+  onSpecCleared?: () => void
+  /**
+   * Fired after a task leaves the store for good (accepted or deleted) and
+   * the removal has been flushed to disk. Lets the server clean per-task
+   * sidecars state.ts doesn't own — today the conversation transcript
+   * (`.annotask/conversations/<id>.jsonl`, owned by the task-thread store).
+   * Screenshot / interaction-history / rendered-html cleanup stays in here.
+   */
+  onTaskRemoved?: (taskId: string) => void
+}
+
+export function createProjectState(
+  projectRoot: string,
+  broadcast: (event: string, data: unknown) => void,
+  options: ProjectStateOptions = {},
+): ProjectState {
   let cachedDesignSpec: unknown = null
   let specWatcher: fs.FSWatcher | null = null
+  // Canonical boot-time spot for keeping `.annotask/` out of version control —
+  // every server entry (Vite plugin, Webpack plugin, standalone) constructs a
+  // project state exactly once.
+  ensureAnnotaskIgnored(projectRoot)
   const tasksPath = path.join(projectRoot, '.annotask', 'tasks.json')
   const screenshotsDir = path.join(projectRoot, '.annotask', 'screenshots')
   const interactionHistoryDir = path.join(projectRoot, '.annotask', 'interaction-history')
@@ -183,11 +289,32 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
   let taskFlushChain: Promise<unknown> = Promise.resolve()
   // Watcher fires on our own rename; skip events within this window after a self-write.
   let selfWriteUntil = 0
+  // Flush-failure tracking — see getPersistenceHealth.
+  let flushFailureCount = 0
+  let lastFlushError: string | null = null
 
   function loadTasksFromDisk(): { version: string; tasks: any[] } {
     try {
-      return JSON.parse(fs.readFileSync(tasksPath, 'utf-8'))
-    } catch {
+      const parsed = JSON.parse(fs.readFileSync(tasksPath, 'utf-8'))
+      // Tolerate a bare-array file (hand-written resets, older tooling) and
+      // a missing `tasks` key — a wrong-shape parse would otherwise crash
+      // the first addTask() and take the whole dev server down with it.
+      if (Array.isArray(parsed)) return { version: '1.0', tasks: parsed }
+      if (!Array.isArray(parsed?.tasks)) return { version: parsed?.version ?? '1.0', tasks: [] }
+      return parsed
+    } catch (err) {
+      // Distinguish "no file yet" (normal first boot) from a corrupt-but-
+      // recoverable file. Falling back to empty is fine in memory, but the
+      // next mutation's atomic flush would overwrite the corrupt file with
+      // `[]` — quarantine a copy first so the user (or an agent) can hand-
+      // recover the tasks. Best-effort: a failed copy never blocks boot.
+      if (fs.existsSync(tasksPath)) {
+        const quarantinePath = `${tasksPath}.corrupt-${new Date().toISOString().replace(/[:.]/g, '-')}`
+        try {
+          fs.copyFileSync(tasksPath, quarantinePath)
+          console.warn(`[Annotask] tasks.json is unreadable (${(err as Error).message}) — quarantined a copy at ${quarantinePath}`)
+        } catch { /* best-effort */ }
+      }
       return { version: '1.0', tasks: [] }
     }
   }
@@ -224,8 +351,14 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
       selfWriteUntil = Date.now() + 500
       await atomicWrite(tasksPath, payload)
       selfWriteUntil = Date.now() + 500
+      flushFailureCount = 0
+      lastFlushError = null
     }).catch(err => {
-      console.warn('[Annotask] task flush failed:', err)
+      // The HTTP response already went out before this write ran, so a failure
+      // here is silent data loss across restarts — track it for /api/status.
+      flushFailureCount += 1
+      lastFlushError = err instanceof Error ? err.message : String(err)
+      console.error(`[Annotask] task flush failed (${flushFailureCount} consecutive) — task changes are NOT being persisted to ${tasksPath}:`, err)
     })
     taskFlushChain = run
     return run
@@ -247,7 +380,12 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
     const specPath = path.join(projectRoot, '.annotask', 'design-spec.json')
     try {
       const parsed = JSON.parse(fs.readFileSync(specPath, 'utf-8'))
-      cachedDesignSpec = { initialized: true, ...normalizeDesignSpec(parsed) }
+      // Honor the file's own `initialized` field. The init wizard sets it
+      // to `true` only when the user explicitly commits — an agent-written
+      // spec that hasn't been accepted yet has no `initialized` key and
+      // should keep the wizard open (defaults to false, not true).
+      const normalized = normalizeDesignSpec(parsed)
+      cachedDesignSpec = { initialized: parsed.initialized === true, ...normalized }
     } catch {
       cachedDesignSpec = DEFAULT_DESIGN_SPEC
     }
@@ -259,6 +397,15 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
           if (filename === 'design-spec.json') {
             cachedDesignSpec = null
             broadcast('designspec:updated', null)
+            // If the file is gone entirely (user wiped .annotask/), tell the
+            // init runner to drop its remembered "all steps done" state so the
+            // wizard reopens cleanly without checkmarks from the last run.
+            // fs.watch fires before/around the write, so check synchronously.
+            try {
+              fs.statSync(specPath)
+            } catch {
+              options.onSpecCleared?.()
+            }
           }
           if (filename === 'tasks.json') {
             // Ignore events caused by our own atomic writes.
@@ -266,6 +413,16 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
             // External edit — drop cache so the next read picks up the disk version.
             taskCache = null
           }
+          if (filename === 'wireframe.json') {
+            // Ignore our own atomic writes; on a genuine external edit tell live
+            // listeners to re-load (the store reads fresh, so no cache to clear).
+            if (Date.now() < wireframeSelfWriteUntil) return
+            broadcast('wireframe:updated', null)
+          }
+          if (filename === 'design-session.json') {
+            if (Date.now() < sessionSelfWriteUntil) return
+            broadcast('session:updated', null)
+          }
         })
       } catch { cachedDesignSpec = null }
     }
@@ -291,11 +448,22 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
     })
   }
 
-  async function updateTask(id: string, updates: Record<string, unknown>) {
+  async function updateTask(
+    id: string,
+    updates: Record<string, unknown>,
+    opts: { guard?: (task: Record<string, unknown>) => string | null } = {},
+  ) {
     return withTaskLock(async () => {
       const data = getTasksSnapshot()
       const task = data.tasks.find((t: any) => t.id === id)
       if (!task) return { error: 'Task not found' }
+      // Run the caller's guard against the task as it exists NOW, under the
+      // lock. The HTTP/MCP boundaries validate transitions before queuing,
+      // but that check races concurrent updates — this one can't.
+      if (opts.guard) {
+        const reason = opts.guard(task)
+        if (reason) return { error: 'Invalid transition', reason }
+      }
       Object.assign(task, updates, { updatedAt: Date.now() })
       let screenshotToUnlink: unknown = null
       let sidecarsToClean: string | null = null
@@ -306,15 +474,52 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
       }
       const flushed = queueFlushTasks(data)
       // Unlink after the write succeeds so the screenshot isn't deleted if
-      // the write fails. Chained off the flush, but not awaited — response
-      // goes out as soon as the in-memory state is consistent.
-      if (screenshotToUnlink) void flushed.then(() => unlinkScreenshot(screenshotToUnlink))
-      if (sidecarsToClean) void flushed.then(() => cleanTaskSidecars(sidecarsToClean!))
+      // the write fails. Appended to the flush chain (not awaited here) — the
+      // response goes out as soon as the in-memory state is consistent, but
+      // flush() still covers the cleanup's disk work.
+      if (screenshotToUnlink || sidecarsToClean) {
+        taskFlushChain = flushed.then(async () => {
+          if (screenshotToUnlink) await unlinkScreenshot(screenshotToUnlink)
+          if (sidecarsToClean) {
+            await cleanTaskSidecars(sidecarsToClean)
+            options.onTaskRemoved?.(sidecarsToClean)
+          }
+        }).catch(() => { /* cleanup is best-effort */ })
+      }
       broadcast('tasks:updated', data)
       return task
     })
   }
 
+  async function addTaskUsage(id: string, usage: Partial<TokenUsage>): Promise<TokenUsage | null> {
+    return withTaskLock(async () => {
+      const data = getTasksSnapshot()
+      const task = data.tasks.find((t: any) => t.id === id)
+      if (!task) return null
+      const prev: TokenUsage = task.tokenUsage ?? {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        turns: 0,
+        lastUpdated: 0,
+      }
+      const next: TokenUsage = {
+        inputTokens: prev.inputTokens + clampNonNeg(usage.inputTokens),
+        outputTokens: prev.outputTokens + clampNonNeg(usage.outputTokens),
+        cacheReadTokens: prev.cacheReadTokens + clampNonNeg(usage.cacheReadTokens),
+        cacheCreationTokens: prev.cacheCreationTokens + clampNonNeg(usage.cacheCreationTokens),
+        turns: prev.turns + 1,
+        lastUpdated: Date.now(),
+      }
+      task.tokenUsage = next
+      task.updatedAt = Date.now()
+      void queueFlushTasks(data)
+      broadcast('tasks:updated', data)
+      return next
+    })
+  }
+
   async function deleteTask(id: string) {
     return withTaskLock(async () => {
       const data = getTasksSnapshot()
@@ -323,8 +528,11 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
       const screenshotToUnlink = task.screenshot
       data.tasks = data.tasks.filter((t: any) => t.id !== id)
       const flushed = queueFlushTasks(data)
-      if (screenshotToUnlink) void flushed.then(() => unlinkScreenshot(screenshotToUnlink))
-      void flushed.then(() => cleanTaskSidecars(id))
+      taskFlushChain = flushed.then(async () => {
+        if (screenshotToUnlink) await unlinkScreenshot(screenshotToUnlink)
+        await cleanTaskSidecars(id)
+        options.onTaskRemoved?.(id)
+      }).catch(() => { /* cleanup is best-effort */ })
       broadcast('tasks:updated', data)
       return { deleted: id }
     })
@@ -347,6 +555,90 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
     perfLock = run.catch(() => {})
   }
 
+  // ── Agent configs (.annotask/agents.json) ──
+  const agentConfigStore = createAgentConfigStore(projectRoot)
+
+  // ── Wireframe document (.annotask/wireframe.json) ──
+  const wireframeStore = createWireframeStore(projectRoot)
+  // Watcher fires on our own rename; skip events within this window after a self-write.
+  let wireframeSelfWriteUntil = 0
+
+  // Boot-time GC for canvas snapshot PNGs: failed uploads, crashed sessions,
+  // and recapture races strand files no doc references. Boot is the only safe
+  // moment (no in-flight upload can race a fresh process); the mtime guard
+  // keeps anything recent enough to plausibly belong to a just-written doc.
+  void (async () => {
+    const dir = path.join(projectRoot, '.annotask', 'wireframe-snapshots')
+    let names: string[]
+    try { names = await fsp.readdir(dir) } catch { return }
+    if (names.length === 0) return
+    // Read the doc RAW: the store's get() falls back to an EMPTY document on
+    // a malformed file, and "empty references" would let the sweep nuke every
+    // legitimately-referenced PNG. A doc that exists but doesn't validate
+    // aborts the GC; a doc that doesn't exist leaves only true orphans.
+    const referenced = new Set<string>()
+    try {
+      const raw = await fsp.readFile(path.join(projectRoot, '.annotask', 'wireframe.json'), 'utf-8')
+      let doc: unknown
+      try { doc = JSON.parse(raw) } catch { return }
+      if (!isWireframeDocument(doc)) return
+      for (const route of doc.routes) {
+        if (!route.canvas) continue
+        for (const b of route.canvas.blocks) if (b.image) referenced.add(b.image)
+        if (route.canvas.fullImage) referenced.add(route.canvas.fullImage)
+      }
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') return
+      // No doc at all → every PNG is an orphan; the mtime guard still applies.
+    }
+    const cutoff = Date.now() - 60 * 60 * 1000
+    let removed = 0
+    for (const name of names) {
+      if (referenced.has(name) || !name.endsWith('.png')) continue
+      const p = path.join(dir, name)
+      try {
+        const st = await fsp.stat(p)
+        if (st.mtimeMs >= cutoff) continue
+        await fsp.unlink(p)
+        removed++
+      } catch { /* best effort */ }
+    }
+    if (removed > 0) console.warn(`[Annotask] wireframe-snapshot GC removed ${removed} orphaned file(s)`)
+  })()
+
+  async function setWireframe(doc: WireframeDocument): Promise<WireframeDocument> {
+    wireframeSelfWriteUntil = Date.now() + 500
+    const saved = await wireframeStore.set(doc)
+    wireframeSelfWriteUntil = Date.now() + 500
+    // Notify live listeners (other shells/tabs) so they re-load without polling.
+    broadcast('wireframe:updated', saved)
+    return saved
+  }
+
+  // ── Design-session journal (.annotask/design-session.json) ──
+  const sessionStore = createSessionStore(projectRoot)
+  let sessionSelfWriteUntil = 0
+
+  async function setDesignSession(doc: DesignSessionDocument): Promise<DesignSessionDocument> {
+    sessionSelfWriteUntil = Date.now() + 500
+    const saved = await sessionStore.set(doc)
+    sessionSelfWriteUntil = Date.now() + 500
+    broadcast('session:updated', saved)
+    return saved
+  }
+
+  async function clearDesignSession(): Promise<DesignSessionDocument> {
+    sessionSelfWriteUntil = Date.now() + 500
+    const fresh = emptyDesignSessionDocument(`ds-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`)
+    fresh.startedAt = Date.now()
+    fresh.updatedAt = Date.now()
+    // Server-owned reset — bypasses CAS so discard works from any tab state.
+    const saved = await sessionStore.replace(fresh)
+    sessionSelfWriteUntil = Date.now() + 500
+    broadcast('session:updated', saved)
+    return saved
+  }
+
   // ── Runtime endpoint catalog ──
   const runtimeEndpoints: RuntimeEndpointStore = createRuntimeEndpointStore(projectRoot)
 
@@ -380,6 +672,7 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
     getTasks: getTasksSnapshot,
     addTask,
     updateTask,
+    addTaskUsage,
     deleteTask,
     saveInteractionHistory,
     readInteractionHistory,
@@ -390,7 +683,19 @@ export function createProjectState(projectRoot: string, broadcast: (event: strin
     ingestNetworkCalls,
     getRuntimeEndpointCatalog,
     clearRuntimeEndpoints,
+    getAgentConfigs: agentConfigStore.get,
+    setAgentConfig: agentConfigStore.set,
+    getWireframe: wireframeStore.get,
+    setWireframe,
+    getDesignSession: sessionStore.get,
+    setDesignSession,
+    clearDesignSession,
     flush,
+    getPersistenceHealth: () => ({
+      ok: flushFailureCount === 0,
+      consecutiveFailures: flushFailureCount,
+      lastError: lastFlushError,
+    }),
     dispose,
   }
 }
diff --git a/src/server/task-thread.ts b/src/server/task-thread.ts
new file mode 100644
index 0000000..31be847
--- /dev/null
+++ b/src/server/task-thread.ts
@@ -0,0 +1,347 @@
+/**
+ * Per-task conversation thread store.
+ *
+ * Each task gets an append-only JSONL log at `.annotask/conversations/<taskId>.jsonl`.
+ * One line per message: `{ id, ts, role, content, providerId?, model?, usage?, toolCalls? }`.
+ *
+ * Why JSONL on disk rather than an in-memory ring or sqlite:
+ *   - The same file is read by external agents through the MCP
+ *     `annotask_conversation_*` tools, so persistence is a feature not an
+ *     accident. Users can run `tail -f` on a conversation while it streams.
+ *   - Append-only means no consistency questions across browser tab,
+ *     external CLI, and MCP simultaneously.
+ *   - Replay from disk on reconnect is trivial — we don't need a stream
+ *     backplane beyond "stat the file."
+ *
+ * Live updates: each task has a `Set<Listener>` of in-process subscribers
+ * (browser SSE clients, MCP long-polls). Append fans out synchronously.
+ */
+
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import type { WorkStreamBlock } from '../shared/work-stream.js'
+
+const SAFE_TASK_ID = /^task-[A-Za-z0-9_-]+$/
+const MAX_CONTENT_BYTES = 1_000_000 // 1 MB per message — chat replies don't reasonably exceed this
+
+export type ThreadRole = 'system' | 'user' | 'assistant' | 'tool'
+
+export interface ThreadMessage {
+  id: string
+  ts: number
+  role: ThreadRole
+  content: string
+  /** Provider id the assistant turn ran against. Undefined for user/system. */
+  providerId?: string
+  /** Model id reported by the provider. */
+  model?: string
+  /** Optional usage counters (mirrors ProviderEvent shape). */
+  usage?: {
+    inputTokens: number
+    outputTokens: number
+    cacheReadTokens?: number
+    cacheCreationTokens?: number
+  }
+  /**
+   * For assistant turns that called tools. Stored alongside content so a
+   * future tool-bridge pass can reconstruct the turn without inferring
+   * structure from prose.
+   */
+  toolCalls?: Array<{ id: string; name: string; input: unknown }>
+  /** For tool-role messages: which tool_use this is a result for. */
+  toolUseId?: string
+  /**
+   * Ordered work-stream blocks for the turn — text deltas interleaved with
+   * tool_call / tool_result blocks. The Conversation tab renders these as
+   * the rich timeline; `content` stays for MCP/CLI tail-readers as a flat
+   * text rollup. Optional so legacy turns (pre work-stream) still parse.
+   */
+  blocks?: WorkStreamBlock[]
+  /**
+   * True while an assistant turn is still streaming. The embedded agent
+   * appends one assistant message with `isPartial: true` at the start of a
+   * turn, then `update()`s it in place as events arrive (throttled), clearing
+   * the flag on the final flush. Lets *any* subscriber (a Conversation tab
+   * that attached mid-run, an MCP tail-reader) observe progress instead of
+   * waiting for the whole turn to land at once.
+   */
+  isPartial?: boolean
+  /**
+   * Wall-clock of the last streamed event for a partial turn. The stall
+   * watchdog / "stalled?" UI compares it to `now` to detect a run that
+   * stopped producing output.
+   */
+  lastEventAt?: number
+}
+
+export interface TaskThreadOptions {
+  projectRoot: string
+  /**
+   * Fires after a message is appended to disk. Used to feed token-usage
+   * rollups: when `msg.usage` is set, the server wires this to update the
+   * task's `tokenUsage` field and write a ledger entry. Optional so tests
+   * and CLI usage of the store don't need to wire anything.
+   */
+  onAppend?: (taskId: string, msg: ThreadMessage) => void
+}
+
+export interface AppendInput {
+  role: ThreadRole
+  content: string
+  providerId?: string
+  model?: string
+  usage?: ThreadMessage['usage']
+  toolCalls?: ThreadMessage['toolCalls']
+  toolUseId?: string
+  blocks?: WorkStreamBlock[]
+  isPartial?: boolean
+  lastEventAt?: number
+}
+
+/** Mutable fields an `update()` may patch on an existing message. */
+export type UpdateInput = Partial<
+  Pick<ThreadMessage, 'content' | 'blocks' | 'usage' | 'isPartial' | 'lastEventAt' | 'model' | 'providerId'>
+>
+
+type Listener = (msg: ThreadMessage) => void
+
+export interface TaskThreadStore {
+  /** Read the full thread snapshot, optionally filtered to messages after `afterId`. */
+  read(taskId: string, opts?: { afterId?: string }): Promise<ThreadMessage[]>
+  /** Append a message; returns the stored record (with id+ts assigned). */
+  append(taskId: string, input: AppendInput): Promise<ThreadMessage>
+  /**
+   * Patch an existing message in place (by id). Used to stream a partial
+   * assistant turn: append once, then update the same line as events arrive.
+   * Returns the merged record, or `null` if no message with that id exists.
+   */
+  update(taskId: string, id: string, patch: UpdateInput): Promise<ThreadMessage | null>
+  /** Subscribe to live appends. Returns an unsubscribe fn. */
+  subscribe(taskId: string, listener: Listener): () => void
+  /** Drop the on-disk log for a task — called when the task is deleted. */
+  clear(taskId: string): Promise<void>
+}
+
+export function createTaskThreadStore(opts: TaskThreadOptions): TaskThreadStore {
+  const dir = path.join(opts.projectRoot, '.annotask', 'conversations')
+  const listeners = new Map<string, Set<Listener>>()
+  // Serialize writes per task so two simultaneous append() calls can't
+  // interleave their JSONL lines.
+  const writeLocks = new Map<string, Promise<unknown>>()
+
+  // In-memory mirror of each task's thread. This store is the SOLE writer of
+  // the conversation JSONL (external agents only read / tail it), so the mirror
+  // is authoritative. It lets update() skip re-reading+parsing the whole file
+  // on every throttled partial-turn flush, and lets the common "update the
+  // last (streaming) message" case rewrite only the tail instead of the whole
+  // file — turning the old O(n) per-flush (O(n^2) over a turn) into O(1)
+  // amortized. `bytes` tracks the file's byte length so the tail offset is known
+  // without a stat.
+  interface TaskCache { messages: ThreadMessage[]; bytes: number }
+  const caches = new Map<string, TaskCache>()
+  const loading = new Map<string, Promise<TaskCache>>()
+
+  function lineBytes(msg: ThreadMessage): number {
+    return Buffer.byteLength(JSON.stringify(msg) + '\n', 'utf-8')
+  }
+
+  async function ensureCache(taskId: string): Promise<TaskCache> {
+    const have = caches.get(taskId)
+    if (have) return have
+    let load = loading.get(taskId)
+    if (!load) {
+      load = (async (): Promise<TaskCache> => {
+        const p = safePath(taskId)
+        let raw = ''
+        if (p) {
+          try { raw = await fsp.readFile(p, 'utf-8') }
+          catch (err: unknown) {
+            if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
+          }
+        }
+        const messages: ThreadMessage[] = []
+        for (const line of raw.split('\n')) {
+          const t = line.trim()
+          if (!t) continue
+          try { messages.push(JSON.parse(t) as ThreadMessage) } catch { /* skip malformed */ }
+        }
+        // Sole-writer invariant ⇒ a well-formed JSONL file, so byte length is
+        // the sum of serialized message lines.
+        const entry: TaskCache = { messages, bytes: messages.reduce((n, m) => n + lineBytes(m), 0) }
+        caches.set(taskId, entry)
+        loading.delete(taskId)
+        return entry
+      })()
+      loading.set(taskId, load)
+    }
+    return load
+  }
+
+  function safePath(taskId: string): string | null {
+    if (!SAFE_TASK_ID.test(taskId)) return null
+    return path.join(dir, `${taskId}.jsonl`)
+  }
+
+  async function appendInternal(taskId: string, msg: ThreadMessage): Promise<void> {
+    const p = safePath(taskId)
+    if (!p) throw new Error(`Invalid taskId: ${taskId}`)
+    await fsp.mkdir(dir, { recursive: true })
+    const line = JSON.stringify(msg) + '\n'
+    await fsp.appendFile(p, line, 'utf-8')
+  }
+
+  async function read(
+    taskId: string,
+    o: { afterId?: string } = {},
+  ): Promise<ThreadMessage[]> {
+    const { messages } = await ensureCache(taskId)
+    if (o.afterId) {
+      const idx = messages.findIndex((m) => m.id === o.afterId)
+      if (idx >= 0) return messages.slice(idx + 1)
+    }
+    // Return a copy so callers can't splice the cache; message objects are
+    // shared but update() replaces them immutably, so that's safe.
+    return messages.slice()
+  }
+
+  async function append(taskId: string, input: AppendInput): Promise<ThreadMessage> {
+    if (input.content.length > MAX_CONTENT_BYTES) {
+      throw new Error(`message content exceeds ${MAX_CONTENT_BYTES} bytes`)
+    }
+    const msg: ThreadMessage = {
+      id: `msg-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`,
+      ts: Date.now(),
+      role: input.role,
+      content: input.content,
+      providerId: input.providerId,
+      model: input.model,
+      usage: input.usage,
+      toolCalls: input.toolCalls,
+      toolUseId: input.toolUseId,
+      blocks: input.blocks,
+      isPartial: input.isPartial,
+      lastEventAt: input.lastEventAt,
+    }
+    const entry = await ensureCache(taskId)
+    const prev = writeLocks.get(taskId) ?? Promise.resolve()
+    const next = prev
+      .catch(() => undefined)
+      .then(async () => {
+        await appendInternal(taskId, msg)
+        entry.messages.push(msg)
+        entry.bytes += lineBytes(msg)
+      })
+    writeLocks.set(taskId, next)
+    await next
+    fanOut(taskId, msg)
+    return msg
+  }
+
+  /**
+   * Rewrite the whole JSONL file with `lines` via a temp file + atomic
+   * rename, so a reader never sees a half-written log. Runs inside the
+   * per-task write lock (callers chain it through `writeLocks`).
+   */
+  async function rewriteInternal(taskId: string, lines: ThreadMessage[]): Promise<void> {
+    const p = safePath(taskId)
+    if (!p) throw new Error(`Invalid taskId: ${taskId}`)
+    await fsp.mkdir(dir, { recursive: true })
+    const body = lines.map((m) => JSON.stringify(m)).join('\n') + (lines.length > 0 ? '\n' : '')
+    const tmp = `${p}.${crypto.randomBytes(4).toString('hex')}.tmp`
+    await fsp.writeFile(tmp, body, 'utf-8')
+    await fsp.rename(tmp, p)
+  }
+
+  /** Fan a (new or updated) message out to subscribers + the onAppend sink. */
+  function fanOut(taskId: string, msg: ThreadMessage): void {
+    const set = listeners.get(taskId)
+    if (set) {
+      for (const fn of set) {
+        try { fn(msg) } catch { /* one bad listener mustn't block others */ }
+      }
+    }
+    if (opts.onAppend) {
+      try { opts.onAppend(taskId, msg) } catch { /* never block the response on a downstream sink */ }
+    }
+  }
+
+  async function update(taskId: string, id: string, patch: UpdateInput): Promise<ThreadMessage | null> {
+    if (typeof patch.content === 'string' && patch.content.length > MAX_CONTENT_BYTES) {
+      throw new Error(`message content exceeds ${MAX_CONTENT_BYTES} bytes`)
+    }
+    // Serialize against append/update on the same task. The lock value is a
+    // promise resolving to the merged message (or null when the id is gone)
+    // so the awaited result below reflects this update specifically.
+    const prev = writeLocks.get(taskId) ?? Promise.resolve()
+    const next = prev
+      .catch(() => undefined)
+      .then(async (): Promise<ThreadMessage | null> => {
+        const entry = await ensureCache(taskId)
+        const idx = entry.messages.findIndex((m) => m.id === id)
+        if (idx < 0) return null
+        const merged: ThreadMessage = { ...entry.messages[idx], ...patch }
+        const p = safePath(taskId)
+        if (idx === entry.messages.length - 1 && p) {
+          // Common case — updating the in-flight (last) message. Rewrite only
+          // the tail line. Non-atomic (truncate then append), but the dropped
+          // line is the streaming partial and in-process readers serve from the
+          // cache, so they never observe the gap.
+          const lineStart = entry.bytes - lineBytes(entry.messages[idx])
+          const newLine = JSON.stringify(merged) + '\n'
+          await fsp.truncate(p, lineStart)
+          await fsp.appendFile(p, newLine, 'utf-8')
+          entry.bytes = lineStart + Buffer.byteLength(newLine, 'utf-8')
+        } else {
+          // Updating an earlier message (rare) — atomic full rewrite.
+          const tentative = entry.messages.slice()
+          tentative[idx] = merged
+          await rewriteInternal(taskId, tentative)
+          entry.bytes = tentative.reduce((n, m) => n + lineBytes(m), 0)
+        }
+        entry.messages[idx] = merged
+        return merged
+      })
+    writeLocks.set(taskId, next)
+    const merged = await next
+    if (merged) fanOut(taskId, merged)
+    return merged
+  }
+
+  function subscribe(taskId: string, listener: Listener): () => void {
+    let set = listeners.get(taskId)
+    if (!set) { set = new Set(); listeners.set(taskId, set) }
+    set.add(listener)
+    return () => {
+      const s = listeners.get(taskId)
+      if (!s) return
+      s.delete(listener)
+      if (s.size === 0) listeners.delete(taskId)
+    }
+  }
+
+  async function clear(taskId: string): Promise<void> {
+    caches.delete(taskId)
+    loading.delete(taskId)
+    const p = safePath(taskId)
+    if (!p) return
+    try { await fsp.unlink(p) } catch { /* already gone */ }
+  }
+
+  return { read, append, update, subscribe, clear }
+}
+
+/** Async wait used by SSE handlers when there's nothing new to send. */
+export function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) return reject(new Error('aborted'))
+    const t = setTimeout(resolve, ms)
+    signal?.addEventListener('abort', () => { clearTimeout(t); reject(new Error('aborted')) }, { once: true })
+  })
+}
+
+/** Filesystem helpers exposed for tests. */
+export const __test = { SAFE_TASK_ID }
+// Suppress unused-import warning for `fs` since we may reference it in tests later.
+void fs
diff --git a/src/server/usage-ledger.ts b/src/server/usage-ledger.ts
new file mode 100644
index 0000000..b76eee6
--- /dev/null
+++ b/src/server/usage-ledger.ts
@@ -0,0 +1,191 @@
+/**
+ * Project-wide token usage ledger.
+ *
+ * One append-only JSONL file at `.annotask/usage.jsonl`. Every provider turn
+ * (chat against a task, init agent run, ad-hoc apply) lands as one line:
+ *
+ *   { ts, scope, taskId?, runId?, providerId?, model?, label?,
+ *     inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens }
+ *
+ * Append-only mirrors the conversation log on disk so external tooling can
+ * `tail -f` the spend, and there's no consistency dance between the shell,
+ * the CLI, and MCP — they all read the same file. Summarization is computed
+ * on demand by scanning the file; the ledger is small enough that this stays
+ * fast for the lifetime of a typical project.
+ */
+
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+
+export type UsageScope = 'task' | 'init' | 'apply' | 'chat'
+
+export interface UsageEntry {
+  ts: number
+  scope: UsageScope
+  /** Set when the entry belongs to a specific task (chat / apply turn). */
+  taskId?: string
+  /** Set for init runs and other non-task agent invocations. */
+  runId?: string
+  /** Provider id reported by the embedded chat (e.g. `claude-local`). */
+  providerId?: string
+  /** Model id reported by the provider. */
+  model?: string
+  /** Free-form label for UI display (e.g. `'annotask-init'`). */
+  label?: string
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens?: number
+  cacheCreationTokens?: number
+}
+
+export interface UsageTotals {
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheCreationTokens: number
+  /** Number of ledger entries folded in. */
+  turns: number
+}
+
+export interface UsageSummary {
+  totals: UsageTotals
+  byScope: Record<UsageScope, UsageTotals>
+  byProvider: Record<string, UsageTotals>
+  /** Epoch ms of the oldest entry, or null when the ledger is empty. */
+  firstAt: number | null
+  /** Epoch ms of the newest entry, or null when the ledger is empty. */
+  lastAt: number | null
+}
+
+export interface UsageLedgerOptions {
+  projectRoot: string
+}
+
+export interface UsageLedger {
+  /** Append one entry. Resolves once the line is flushed to disk. */
+  append(entry: Omit<UsageEntry, 'ts'> & { ts?: number }): Promise<UsageEntry>
+  /** Read every entry from disk. Used by summary() and tests. */
+  readAll(): Promise<UsageEntry[]>
+  /** Compute aggregate totals + per-scope + per-provider tallies. */
+  summary(): Promise<UsageSummary>
+  /** Most recent N entries (newest first). */
+  recent(limit?: number): Promise<UsageEntry[]>
+}
+
+function emptyTotals(): UsageTotals {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheCreationTokens: 0,
+    turns: 0,
+  }
+}
+
+function addInto(target: UsageTotals, e: UsageEntry): void {
+  target.inputTokens += clamp(e.inputTokens)
+  target.outputTokens += clamp(e.outputTokens)
+  target.cacheReadTokens += clamp(e.cacheReadTokens)
+  target.cacheCreationTokens += clamp(e.cacheCreationTokens)
+  target.turns += 1
+}
+
+function clamp(n: number | undefined): number {
+  if (n == null || !Number.isFinite(n) || n < 0) return 0
+  return n
+}
+
+export function createUsageLedger(opts: UsageLedgerOptions): UsageLedger {
+  const filePath = path.join(opts.projectRoot, '.annotask', 'usage.jsonl')
+  // Serialize writes so two callers can't interleave their JSONL lines.
+  let writeChain: Promise<unknown> = Promise.resolve()
+
+  async function appendLine(line: string): Promise<void> {
+    await fsp.mkdir(path.dirname(filePath), { recursive: true })
+    await fsp.appendFile(filePath, line, 'utf-8')
+  }
+
+  async function append(input: Omit<UsageEntry, 'ts'> & { ts?: number }): Promise<UsageEntry> {
+    const entry: UsageEntry = {
+      ts: input.ts ?? Date.now(),
+      scope: input.scope,
+      taskId: input.taskId,
+      runId: input.runId,
+      providerId: input.providerId,
+      model: input.model,
+      label: input.label,
+      inputTokens: clamp(input.inputTokens),
+      outputTokens: clamp(input.outputTokens),
+      cacheReadTokens: clamp(input.cacheReadTokens),
+      cacheCreationTokens: clamp(input.cacheCreationTokens),
+    }
+    // Skip purely-empty turns — they add noise without adding signal.
+    if (
+      entry.inputTokens === 0 &&
+      entry.outputTokens === 0 &&
+      entry.cacheReadTokens === 0 &&
+      entry.cacheCreationTokens === 0
+    ) {
+      return entry
+    }
+    const line = JSON.stringify(entry) + '\n'
+    const run = writeChain.then(() => appendLine(line))
+    writeChain = run.catch(() => { /* isolate: next op should still run */ })
+    await run
+    return entry
+  }
+
+  async function readAll(): Promise<UsageEntry[]> {
+    let raw: string
+    try { raw = await fsp.readFile(filePath, 'utf-8') }
+    catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
+      throw err
+    }
+    const out: UsageEntry[] = []
+    for (const line of raw.split('\n')) {
+      const t = line.trim()
+      if (!t) continue
+      try {
+        const parsed = JSON.parse(t) as UsageEntry
+        if (parsed && typeof parsed.ts === 'number' && typeof parsed.scope === 'string') {
+          out.push(parsed)
+        }
+      } catch {
+        // Skip malformed lines silently — better to serve a partial summary
+        // than to 500 because one byte got corrupted.
+      }
+    }
+    return out
+  }
+
+  async function summary(): Promise<UsageSummary> {
+    const entries = await readAll()
+    const totals = emptyTotals()
+    const byScope: Record<UsageScope, UsageTotals> = {
+      task: emptyTotals(),
+      init: emptyTotals(),
+      apply: emptyTotals(),
+      chat: emptyTotals(),
+    }
+    const byProvider: Record<string, UsageTotals> = {}
+    let firstAt: number | null = null
+    let lastAt: number | null = null
+    for (const e of entries) {
+      addInto(totals, e)
+      addInto(byScope[e.scope] ?? (byScope[e.scope] = emptyTotals()), e)
+      const key = e.providerId ?? 'unknown'
+      addInto(byProvider[key] ?? (byProvider[key] = emptyTotals()), e)
+      if (firstAt === null || e.ts < firstAt) firstAt = e.ts
+      if (lastAt === null || e.ts > lastAt) lastAt = e.ts
+    }
+    return { totals, byScope, byProvider, firstAt, lastAt }
+  }
+
+  async function recent(limit = 50): Promise<UsageEntry[]> {
+    const entries = await readAll()
+    return entries.slice(-Math.max(0, limit)).reverse()
+  }
+
+  return { append, readAll, summary, recent }
+}
diff --git a/src/server/validation.ts b/src/server/validation.ts
index d1d98c8..c8223a7 100644
--- a/src/server/validation.ts
+++ b/src/server/validation.ts
@@ -18,7 +18,11 @@ export const VALID_TASK_STATUSES = new Set([
 /** From `current` → allowed `next`. Rejects silent-overwrite transitions. */
 export const VALID_TRANSITIONS: Record<string, ReadonlySet<string>> = {
   pending:     new Set(['in_progress', 'denied']),
-  in_progress: new Set(['applied', 'review', 'needs_info', 'blocked', 'denied']),
+  // `pending` = relinquish the lock back to the queue without finishing: the
+  // agent gave up, the stream errored, or the user/observer cancelled the run.
+  // Without this, the client's revert-to-pending recovery (and the server's
+  // orphan reconcile) would be rejected and the task stranded in_progress.
+  in_progress: new Set(['applied', 'review', 'needs_info', 'blocked', 'denied', 'pending']),
   applied:     new Set(['review', 'in_progress']),
   review:      new Set(['accepted', 'denied', 'in_progress']),
   needs_info:  new Set(['in_progress', 'denied']),
diff --git a/src/server/wireframe-store.ts b/src/server/wireframe-store.ts
new file mode 100644
index 0000000..e3af943
--- /dev/null
+++ b/src/server/wireframe-store.ts
@@ -0,0 +1,79 @@
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import {
+  emptyWireframeDocument,
+  migrateWireframeDocument,
+  type WireframeDocument,
+} from '../shared/wireframe-types.js'
+
+/**
+ * Thrown when a `set()` carries a stale (or missing) `rev` against a doc that
+ * already has one. The HTTP layer maps this to a 409 `conflict` so the losing
+ * tab reloads instead of last-writer-wins clobbering the other tab's
+ * placements.
+ */
+export class WireframeRevConflictError extends Error {
+  constructor(public readonly currentRev: number, incomingRev: unknown) {
+    super(`Wireframe rev conflict: document is at rev ${currentRev}, write carried rev ${String(incomingRev)}`)
+    this.name = 'WireframeRevConflictError'
+  }
+}
+
+/**
+ * Persists the multi-route wireframe document to `.annotask/wireframe.json`.
+ * Modeled on createAgentConfigStore: no in-memory cache (the file is small and
+ * may be edited or cleared externally — always read fresh so external edits and
+ * the `.annotask/` watcher stay coherent), atomic tmp+rename writes.
+ *
+ * Writes are compare-and-set on `rev`: the caller must send back the rev it
+ * last read; the store rejects a stale rev (WireframeRevConflictError) and
+ * stamps `rev + 1` on success. Legacy docs without a rev accept one write
+ * unconditionally — that write stamps the first rev.
+ */
+export function createWireframeStore(projectRoot: string) {
+  const filePath = path.join(projectRoot, '.annotask', 'wireframe.json')
+
+  async function load(): Promise<WireframeDocument> {
+    try {
+      const raw = JSON.parse(await fsp.readFile(filePath, 'utf-8'))
+      const migrated = migrateWireframeDocument(raw)
+      if (migrated) return migrated
+      // Recognizably a wireframe doc (has routes) but unmigratable — a newer/
+      // unknown version, or a malformed shape. Don't pretend it never existed:
+      // warn so the loss isn't silent (the next write will overwrite it).
+      if (raw && typeof raw === 'object' && Array.isArray((raw as { routes?: unknown }).routes)) {
+        console.warn(`[Annotask] wireframe.json could not be migrated (version ${String((raw as { version?: unknown }).version)}) — starting empty; the file will be overwritten on the next save.`)
+      }
+      return emptyWireframeDocument()
+    } catch {
+      return emptyWireframeDocument()
+    }
+  }
+
+  async function persist(doc: WireframeDocument): Promise<void> {
+    const dir = path.dirname(filePath)
+    await fsp.mkdir(dir, { recursive: true })
+    const tmp = `${filePath}.tmp.${process.pid}.${Date.now()}`
+    await fsp.writeFile(tmp, JSON.stringify(doc, null, 2), 'utf-8')
+    await fsp.rename(tmp, filePath)
+  }
+
+  return {
+    get: load,
+    set: async (doc: WireframeDocument): Promise<WireframeDocument> => {
+      const current = await load()
+      // CAS: only enforced once the on-disk doc carries a rev. A fresh/legacy
+      // doc (no rev) accepts any write — including one without a rev — so old
+      // shells aren't bricked; the write below stamps rev 1 and from then on
+      // every writer must round-trip it.
+      if (typeof current.rev === 'number' && doc.rev !== current.rev) {
+        throw new WireframeRevConflictError(current.rev, doc.rev)
+      }
+      const stamped: WireframeDocument = { ...doc, rev: (current.rev ?? 0) + 1 }
+      await persist(stamped)
+      return stamped
+    },
+  }
+}
+
+export type WireframeStore = ReturnType<typeof createWireframeStore>
diff --git a/src/shared/__tests__/design-session-types.test.ts b/src/shared/__tests__/design-session-types.test.ts
new file mode 100644
index 0000000..629f662
--- /dev/null
+++ b/src/shared/__tests__/design-session-types.test.ts
@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest'
+import {
+  emptyDesignSessionDocument,
+  isDesignSessionDocument,
+  isSessionEntry,
+  type DesignSessionDocument,
+  type SessionEntry,
+} from '../design-session-types'
+
+function entry(id: string, extra: Partial<SessionEntry> = {}): SessionEntry {
+  return {
+    id,
+    ordinal: 1,
+    ts: 1,
+    route: '/planets',
+    change: {
+      id: `c-${id}`,
+      type: 'style_update',
+      description: 'color change',
+      file: 'src/pages/PlanetsPage.vue',
+      section: 'template',
+      line: 9,
+      element: 'h1',
+      property: 'color',
+      before: 'red',
+      after: 'blue',
+    },
+    anchor: { file: 'src/pages/PlanetsPage.vue', line: 9 },
+    live: { status: 'pending' },
+    ...extra,
+  }
+}
+
+function docWith(entries: unknown[]): unknown {
+  return { version: '1.0', sessionId: 'ds-1', startedAt: 1, updatedAt: 1, entries }
+}
+
+describe('emptyDesignSessionDocument', () => {
+  it('produces a valid empty document', () => {
+    expect(isDesignSessionDocument(emptyDesignSessionDocument('ds-1'))).toBe(true)
+  })
+})
+
+describe('isSessionEntry', () => {
+  it('accepts a minimal pending entry', () => {
+    expect(isSessionEntry(entry('se-1'))).toBe(true)
+  })
+
+  it('accepts the full envelope (evidence, live states, cross-refs, breakpoint)', () => {
+    expect(isSessionEntry(entry('se-1', {
+      evidence: { classification: 'literal', excerptHash: 'abc123', loopCount: 4 },
+      live: { status: 'written', applyBatchId: 'ab-1', writtenAt: 5 },
+      instanceId: 'wfi-1',
+      eid: 'eid-9',
+      taskId: 'task-1',
+      breakpointId: 'iphone-se',
+    }))).toBe(true)
+    // bound evidence names the binding; breakpointId null means base viewport
+    expect(isSessionEntry(entry('se-2', {
+      evidence: { classification: 'bound', binding: 'planet.name' },
+      breakpointId: null,
+    }))).toBe(true)
+    expect(isSessionEntry(entry('se-3', {
+      live: { status: 'failed', error: 'edit not found in source' },
+    }))).toBe(true)
+  })
+
+  it('rejects missing/malformed envelope fields', () => {
+    expect(isSessionEntry({ ...entry('se-1'), id: '' })).toBe(false)
+    expect(isSessionEntry({ ...entry('se-1'), ordinal: '1' })).toBe(false)
+    expect(isSessionEntry({ ...entry('se-1'), route: undefined })).toBe(false)
+    expect(isSessionEntry({ ...entry('se-1'), change: null })).toBe(false)
+    expect(isSessionEntry({ ...entry('se-1'), change: { description: 'no type' } })).toBe(false)
+    expect(isSessionEntry({ ...entry('se-1'), anchor: { file: 'a.vue' } })).toBe(false)
+    expect(isSessionEntry({ ...entry('se-1'), anchor: { file: 'a.vue', line: '9' } })).toBe(false)
+    expect(isSessionEntry({ ...entry('se-1'), live: undefined })).toBe(false)
+    expect(isSessionEntry({ ...entry('se-1'), live: { status: 'done' } })).toBe(false)
+  })
+
+  it('rejects malformed optional fields', () => {
+    expect(isSessionEntry(entry('se-1', { evidence: { classification: 'maybe' } as never }))).toBe(false)
+    expect(isSessionEntry(entry('se-1', { evidence: { classification: 'literal', loopCount: '4' } as never }))).toBe(false)
+    expect(isSessionEntry(entry('se-1', { live: { status: 'written', writtenAt: 'now' } as never }))).toBe(false)
+    expect(isSessionEntry(entry('se-1', { anchor: { file: 'a.vue', line: 9, position: 'inside' } as never }))).toBe(false)
+    expect(isSessionEntry(entry('se-1', { instanceId: 42 as never }))).toBe(false)
+    expect(isSessionEntry(entry('se-1', { taskId: 42 as never }))).toBe(false)
+    expect(isSessionEntry(entry('se-1', { breakpointId: 7 as never }))).toBe(false)
+  })
+})
+
+describe('isDesignSessionDocument', () => {
+  it('accepts a well-formed document', () => {
+    expect(isDesignSessionDocument(docWith([entry('se-1'), entry('se-2', { instanceId: 'wfi-1' })]))).toBe(true)
+    expect(isDesignSessionDocument({ ...docWith([]) as Record<string, unknown>, rev: 3 })).toBe(true)
+  })
+
+  it('rejects malformed top-level fields', () => {
+    expect(isDesignSessionDocument(null)).toBe(false)
+    expect(isDesignSessionDocument({ ...docWith([]) as Record<string, unknown>, version: '0.9' })).toBe(false)
+    expect(isDesignSessionDocument({ ...docWith([]) as Record<string, unknown>, sessionId: '' })).toBe(false)
+    expect(isDesignSessionDocument({ ...docWith([]) as Record<string, unknown>, startedAt: 'yesterday' })).toBe(false)
+    expect(isDesignSessionDocument({ ...docWith([]) as Record<string, unknown>, rev: '3' })).toBe(false)
+    expect(isDesignSessionDocument({ ...docWith([]) as Record<string, unknown>, entries: 'nope' })).toBe(false)
+  })
+
+  it('one bad entry rejects the whole document (PUT boundary)', () => {
+    expect(isDesignSessionDocument(docWith([entry('se-good'), { id: 'se-bad' }]))).toBe(false)
+  })
+})
diff --git a/src/shared/__tests__/wireframe-types.test.ts b/src/shared/__tests__/wireframe-types.test.ts
new file mode 100644
index 0000000..b613956
--- /dev/null
+++ b/src/shared/__tests__/wireframe-types.test.ts
@@ -0,0 +1,143 @@
+import { describe, it, expect } from 'vitest'
+import {
+  isWireframeDataBinding,
+  isWireframeBlock,
+  isWireframeDocument,
+  migrateWireframeDocument,
+  type WireframeBlock,
+  type WireframeDataBinding,
+  type WireframeDocument,
+} from '../wireframe-types'
+
+function binding(extra: Partial<WireframeDataBinding> = {}): WireframeDataBinding {
+  return {
+    kind: 'composable',
+    name: 'usePlanets',
+    module: 'src/composables/usePlanets.ts',
+    path: 'planets[]',
+    fields: ['name', 'type'],
+    shape_source: 'api-schema',
+    ...extra,
+  }
+}
+
+function paletteBlock(extra: Partial<WireframeBlock> = {}): WireframeBlock {
+  return {
+    id: 'wfb-1',
+    kind: 'palette',
+    rect: { x: 0, y: 0, width: 100, height: 40 },
+    z: 1,
+    createdAt: 1,
+    component: { tag: 'planetcard', componentName: 'PlanetCard' },
+    ...extra,
+  }
+}
+
+function placeholderBlock(extra: Partial<WireframeBlock> = {}): WireframeBlock {
+  return {
+    id: 'wfb-2',
+    kind: 'placeholder',
+    rect: { x: 0, y: 60, width: 200, height: 80 },
+    z: 2,
+    createdAt: 1,
+    label: 'related planets',
+    ...extra,
+  }
+}
+
+function docWith(blocks: WireframeBlock[]): WireframeDocument {
+  return {
+    version: '1.0',
+    updatedAt: 0,
+    rev: 1,
+    routes: [{
+      route: '/planets',
+      instances: [],
+      canvas: {
+        capturedAt: 1,
+        viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2000, scale: 1 },
+        blocks,
+      },
+    }],
+  }
+}
+
+describe('migrateWireframeDocument (version-bump safety — never silently wipe)', () => {
+  it('passes a valid current-version doc through unchanged', () => {
+    const doc = docWith([paletteBlock()])
+    expect(migrateWireframeDocument(doc)).toEqual(doc)
+  })
+
+  it('stamps the current version onto a pre-versioned (early-format) doc instead of wiping it', () => {
+    const legacy = { updatedAt: 1, rev: 2, routes: [{ route: '/', instances: [] }] } // no `version`
+    const migrated = migrateWireframeDocument(legacy)
+    expect(migrated).not.toBeNull()
+    expect(migrated!.version).toBe('1.0')
+    expect(migrated!.routes).toEqual([{ route: '/', instances: [] }])
+  })
+
+  it('returns null for a newer/unknown version (caller leaves the file alone, not overwrites)', () => {
+    expect(migrateWireframeDocument({ version: '99.0', updatedAt: 1, routes: [] })).toBeNull()
+  })
+
+  it('returns null for genuinely malformed input (preserves same-version strictness)', () => {
+    expect(migrateWireframeDocument(null)).toBeNull()
+    expect(migrateWireframeDocument({ version: '1.0', updatedAt: 1, routes: 'nope' })).toBeNull()
+    // One bad instance still fails — the PUT-boundary contract is unchanged.
+    expect(migrateWireframeDocument({ version: '1.0', updatedAt: 1, routes: [{ route: '/', instances: [{ id: 'x' }] }] })).toBeNull()
+  })
+})
+
+describe('isWireframeDataBinding', () => {
+  it('accepts the full contract and a minimal one', () => {
+    expect(isWireframeDataBinding(binding())).toBe(true)
+    expect(isWireframeDataBinding({ kind: 'fetch', name: 'loadCats', shape_source: 'none' })).toBe(true)
+  })
+
+  it('rejects malformed bindings', () => {
+    expect(isWireframeDataBinding(null)).toBe(false)
+    expect(isWireframeDataBinding('usePlanets')).toBe(false)
+    expect(isWireframeDataBinding([])).toBe(false)
+    expect(isWireframeDataBinding(binding({ kind: 'webhook' as never }))).toBe(false)
+    expect(isWireframeDataBinding(binding({ name: '' }))).toBe(false)
+    expect(isWireframeDataBinding(binding({ shape_source: 'guessed' as never }))).toBe(false)
+    expect(isWireframeDataBinding({ kind: 'fetch', name: 'x' })).toBe(false) // missing shape_source
+    expect(isWireframeDataBinding(binding({ module: '' }))).toBe(false)
+    expect(isWireframeDataBinding(binding({ path: 42 as never }))).toBe(false)
+    expect(isWireframeDataBinding(binding({ fields: 'name,type' as never }))).toBe(false)
+    expect(isWireframeDataBinding(binding({ fields: ['name', 7] as never }))).toBe(false)
+    expect(isWireframeDataBinding(binding({ fields: [''] }))).toBe(false)
+  })
+})
+
+describe('WireframeBlock.data + .md validation', () => {
+  it('accepts bindings on palette AND placeholder blocks (kind-agnostic)', () => {
+    expect(isWireframeBlock(paletteBlock({ data: binding() }))).toBe(true)
+    expect(isWireframeBlock(placeholderBlock({ data: binding({ shape_source: 'source-details' }) }))).toBe(true)
+  })
+
+  it('accepts a markdown body on a drawn section and rejects non-strings', () => {
+    expect(isWireframeBlock(placeholderBlock({ md: '## Related planets\n- name and type' }))).toBe(true)
+    expect(isWireframeBlock(placeholderBlock({ md: 42 as never }))).toBe(false)
+    // md + data round-trip through the document validator together.
+    expect(isWireframeDocument(docWith([placeholderBlock({ md: 'spec', data: binding() })]))).toBe(true)
+  })
+
+  it('accepts legacy blocks without data', () => {
+    expect(isWireframeBlock(paletteBlock())).toBe(true)
+    expect(isWireframeBlock(placeholderBlock())).toBe(true)
+  })
+
+  it('rejects malformed data at block depth', () => {
+    expect(isWireframeBlock(paletteBlock({ data: { name: 'usePlanets' } as never }))).toBe(false)
+    expect(isWireframeBlock(placeholderBlock({ data: binding({ kind: 'nope' as never }) }))).toBe(false)
+  })
+
+  it('one bad binding rejects the whole document (PUT boundary)', () => {
+    expect(isWireframeDocument(docWith([paletteBlock({ data: binding() })]))).toBe(true)
+    expect(isWireframeDocument(docWith([
+      paletteBlock({ data: binding() }),
+      placeholderBlock({ data: { kind: 'composable' } as never }),
+    ]))).toBe(false)
+  })
+})
diff --git a/src/shared/bridge-types.ts b/src/shared/bridge-types.ts
index 2e44cf2..d934a57 100644
--- a/src/shared/bridge-types.ts
+++ b/src/shared/bridge-types.ts
@@ -53,6 +53,11 @@ export interface ResolvedElement {
   classes: string
   /** Visible label text (aria-label/title/textContent, normalized, <=200 chars). */
   text?: string
+  /** Set when the point sits inside an annotask-mounted wireframe placement
+   *  ([data-annotask-instance]). The eid is the placement CONTAINER's eid and
+   *  any file/line describe the mounted component's internals — selection must
+   *  treat this as "the placement", not a source element. */
+  instance_id?: string
 }
 
 export interface ResolveTemplateGroupPayload {
@@ -329,6 +334,56 @@ export interface ClassUndoPayload {
   classes: string
 }
 
+// ── Wireframe Capture ────────────────────────────────────
+
+export interface WireframeCapturePayload {
+  /** Capture children of this element instead of the page (W4 explode). */
+  rootEid?: string
+  /** Rasterization scale; default min(devicePixelRatio, 2), capped at 3. */
+  scale?: number
+}
+
+export interface WireframeCaptureBlock {
+  eid: string
+  /** Source anchor from data-annotask-* — '' when unstamped (honest no-chip). */
+  file: string
+  line: string
+  component: string
+  source_tag: string
+  tag: string
+  /** First class name — the human-distinct label ('toolbar', 'layout'). */
+  cls: string
+  /** 'header' | 'nav' | 'footer' | 'aside' | 'content' from block discovery. */
+  role: string
+  /** Document CSS px (captured at scroll 0,0). */
+  rect: BridgeRect
+  /** PNG dataUrl at `scale`x; null when this block's capture failed. */
+  dataUrl: string | null
+  error?: string
+  /** Block was taller than the 4000px cap — only the top is in the image. */
+  clipped?: boolean
+}
+
+export interface WireframeCaptureResult {
+  viewport?: { width: number; height: number; docWidth: number; docHeight: number; scale: number }
+  /** Block discovery hit the 24-block cap. */
+  truncated?: boolean
+  /** Full-document capture at scale 1 — the "before" composite source. */
+  fullDataUrl?: string
+  /** Explode (rootEid) only: the root's own pixels with the captured child
+   *  blocks hidden — the container's surface, no ghost children. */
+  shellDataUrl?: string
+  blocks?: WireframeCaptureBlock[]
+  error?: string
+}
+
+/** Pushed per block during a capture (then once for the full-page pass). */
+export interface WireframeCaptureProgress {
+  index: number
+  total: number
+  label: string
+}
+
 // ── Layout ──────────────────────────────────────────────
 
 export interface LayoutContainerData {
@@ -400,6 +455,9 @@ export interface ClickElementEvent {
   clientY: number
   /** Visible label text (aria-label/title/textContent, normalized, <=200 chars). */
   text?: string
+  /** Set when the click landed inside an annotask-mounted wireframe placement —
+   *  see ResolvedElement.instance_id. The eid is the placement container's eid. */
+  instance_id?: string
 }
 
 export interface RouteChangedEvent {
@@ -428,7 +486,7 @@ export interface KeyDownEvent {
 
 // ── Mode ────────────────────────────────────────────────
 
-export type InteractionMode = 'select' | 'interact' | 'pin' | 'arrow' | 'draw' | 'highlight'
+export type InteractionMode = 'select' | 'interact' | 'pin' | 'arrow' | 'highlight'
 
 export interface ModeSetPayload {
   mode: InteractionMode
@@ -498,28 +556,49 @@ export interface InsertPlaceholderPayload {
   category?: string
   library?: string
   defaultProps?: Record<string, unknown>
+  /** Wireframe instance id — stamped on the placeholder as
+   *  `data-annotask-instance` for placement identity (click/selection,
+   *  drop-target refusal, capture exclusion, reapply idempotency). */
+  instanceId?: string
 }
 
 export interface InsertPlaceholderResult {
   placeholderEid: string
 }
 
-export interface MoveElementPayload {
-  eid: string
-  targetEid: string
-  position: 'before' | 'after' | 'append' | 'prepend'
-}
-
 export interface InsertComponentPayload {
   targetEid: string
   position: 'before' | 'after' | 'append' | 'prepend'
   componentName: string
   props?: Record<string, unknown>
-}
+  /** Import specifier for on-demand loading when the component isn't already
+   *  registered on the current route (e.g. "primevue/button"). */
+  module?: string
+  /** Wireframe instance id — stamped on the mounted container as
+   *  `data-annotask-instance` for placement identity (click/selection,
+   *  drop-target refusal, capture exclusion, reapply idempotency). */
+  instanceId?: string
+}
+
+/** Why a component mount did not produce a real, in-context render. */
+export type MountReason =
+  | 'not-registered'
+  | 'threw'
+  | 'rendered-empty'
+  | 'no-runtime'
+  | 'async-pending'
+
+/** How faithfully the dropped component is rendered on the canvas. */
+export type MountFidelity = 'live' | 'isolated-preview' | 'placeholder'
 
 export interface InsertComponentResult {
   eid: string
   mounted: boolean
+  /** Present whenever the mount was not a clean in-context render. */
+  reason?: MountReason | null
+  /** `live` = Vue in real app context, `isolated-preview` = detached
+   *  React/Svelte/Solid (no provider tree), `placeholder` = could not render. */
+  fidelity?: MountFidelity
 }
 
 /** @deprecated Use InsertComponentPayload */
@@ -527,6 +606,35 @@ export type InsertVueComponentPayload = InsertComponentPayload
 /** @deprecated Use InsertComponentResult */
 export type InsertVueComponentResult = InsertComponentResult
 
+export interface PreviewComponentPayload {
+  componentName: string
+  props?: Record<string, unknown>
+  /** Import specifier for on-demand loading (e.g. "primevue/button"). */
+  module?: string
+  /** Render width for the offscreen snapshot (px). */
+  width?: number
+  /** Mount this many copies (a list/loop binding) into one snapshot. Default 1. */
+  repeat?: number
+  /** Per-instance prop overlays for a repeated render — instance i merges
+   *  `{ ...props, ...instanceProps[i] }` (falls back to instanceProps[0]). Used
+   *  to show bound data values per row. */
+  instanceProps?: Record<string, unknown>[]
+}
+
+export interface PreviewComponentResult {
+  mounted: boolean
+  fidelity?: MountFidelity
+  reason?: MountReason | null
+  /** The actual render error message when reason === 'threw'. */
+  detail?: string | null
+  /** PNG data URL of the rendered component, when it rendered + snapshotted. */
+  dataUrl?: string
+  width?: number
+  height?: number
+  /** Set when the mount succeeded but the snapshot itself failed. */
+  error?: string
+}
+
 // ── Component Library ──────────────────────────────────
 
 export interface ComponentPropInfo {
diff --git a/src/shared/design-session-types.ts b/src/shared/design-session-types.ts
new file mode 100644
index 0000000..99dc855
--- /dev/null
+++ b/src/shared/design-session-types.ts
@@ -0,0 +1,186 @@
+/**
+ * Design-session document — the persisted, ordered journal of what the user
+ * did in a design session. One `.annotask/design-session.json` per project,
+ * shared by the server GET/PUT validator, the shell `useDesignSession`
+ * composable, and the agent-facing `wireframe_apply` task context
+ * (`context.session`) — so the persisted shape, the shell, and the apply
+ * playbook never drift. Mirrors the wireframe-types.ts discipline: runtime
+ * shape guards validate to entry depth at the HTTP boundary.
+ *
+ * The journal is the truth of "what the user did", in order. Placement
+ * entries cross-reference their `WireframeInstance` by id (wireframe.json
+ * stays the canonical placement artifact — payloads are never copied).
+ * Element edits carry the `AnnotaskChange` payload plus anchor + classifier
+ * evidence. Source writes are always agent-authored; the `live` state tracks
+ * whether an entry is still pending, riding an apply batch, verified written
+ * in source, or failed verification.
+ */
+
+import type { AnnotaskChange } from '../schema'
+
+/**
+ * Where an entry is in the agent-apply lifecycle.
+ *  'pending'  — recorded (and optimistically previewed where honest); not in source.
+ *  'applying' — part of an in-flight apply batch (agent running).
+ *  'written'  — verified present in source after an apply batch sealed.
+ *  'failed'   — apply batch finished but verification couldn't find the edit.
+ */
+export type LiveWriteStatus = 'pending' | 'applying' | 'written' | 'failed'
+
+export interface LiveWriteState {
+  status: LiveWriteStatus
+  /** The apply batch that wrote (or tried to write) this entry. */
+  applyBatchId?: string
+  /** Human-readable failure reason when status === 'failed'. */
+  error?: string
+  writtenAt?: number
+}
+
+/**
+ * Round-trip-honesty evidence captured at record time by the binding
+ * classifier. The agent re-grounds at apply time (code-context /
+ * binding-classify); this is the record of what the shell verified before
+ * allowing the edit.
+ */
+export interface EditEvidence {
+  classification: 'literal' | 'bound' | 'loop-literal' | 'unknown'
+  /** sha256-16 of the excerpt around the anchor at classify time — drift guard. */
+  excerptHash?: string
+  /** The bound expression when read-only (e.g. 'planet.name'). */
+  binding?: string
+  /** When loop-rendered: how many instances the edit visibly affects. */
+  loopCount?: number
+}
+
+/** Durable element anchor, from data-annotask-file/-line (+ re-resolution aids). */
+export interface SessionAnchor {
+  file: string
+  line: number
+  /** Re-resolution aid for findTemplateGroup after reload/HMR. */
+  targetTag?: string
+  component?: string
+  /** Inserts/moves only. */
+  position?: 'before' | 'after' | 'append' | 'prepend'
+  mfe?: string
+}
+
+export interface SessionEntry {
+  id: string
+  /** Monotonic within the session — the undo order. */
+  ordinal: number
+  ts: number
+  /** Normalized iframe route at record time. */
+  route: string
+  /** The change payload — the ONLY part report/task consumers see. */
+  change: AnnotaskChange
+  anchor: SessionAnchor
+  evidence?: EditEvidence
+  live: LiveWriteState
+  /** Cross-reference to a WireframeInstance for placement entries. */
+  instanceId?: string
+  /** Volatile bridge element id — never trusted across HMR; re-resolved by anchor. */
+  eid?: string
+  /** Set when the entry was snapshotted into a wireframe_apply task. */
+  taskId?: string
+  /** Viewport preset scope for the edit (M6); null/absent = base. Ships now so
+   *  collapse keys are breakpoint-aware from day one. */
+  breakpointId?: string | null
+}
+
+export interface DesignSessionDocument {
+  version: '1.0'
+  sessionId: string
+  startedAt: number
+  updatedAt: number
+  /** Server-managed write revision — same CAS scheme as wireframe.json. */
+  rev?: number
+  entries: SessionEntry[]
+}
+
+/** One agent-apply run: which task it rode and which files it touched. */
+export interface ApplyBatch {
+  id: string
+  taskId: string
+  files: string[]
+  startedAt: number
+  finishedAt?: number
+  status: 'running' | 'done' | 'failed'
+}
+
+export const DESIGN_SESSION_DOC_VERSION = '1.0' as const
+
+const LIVE_WRITE_STATUSES: readonly string[] = ['pending', 'applying', 'written', 'failed']
+const EVIDENCE_CLASSIFICATIONS: readonly string[] = ['literal', 'bound', 'loop-literal', 'unknown']
+const ANCHOR_POSITIONS: readonly string[] = ['before', 'after', 'append', 'prepend']
+
+export function emptyDesignSessionDocument(sessionId: string): DesignSessionDocument {
+  return { version: DESIGN_SESSION_DOC_VERSION, sessionId, startedAt: 0, updatedAt: 0, entries: [] }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isLiveWriteState(value: unknown): value is LiveWriteState {
+  if (!isPlainObject(value)) return false
+  if (!LIVE_WRITE_STATUSES.includes(value.status as string)) return false
+  if (value.applyBatchId !== undefined && typeof value.applyBatchId !== 'string') return false
+  if (value.error !== undefined && typeof value.error !== 'string') return false
+  if (value.writtenAt !== undefined && typeof value.writtenAt !== 'number') return false
+  return true
+}
+
+function isEditEvidence(value: unknown): value is EditEvidence {
+  if (!isPlainObject(value)) return false
+  if (!EVIDENCE_CLASSIFICATIONS.includes(value.classification as string)) return false
+  if (value.excerptHash !== undefined && typeof value.excerptHash !== 'string') return false
+  if (value.binding !== undefined && typeof value.binding !== 'string') return false
+  if (value.loopCount !== undefined && typeof value.loopCount !== 'number') return false
+  return true
+}
+
+function isSessionAnchor(value: unknown): value is SessionAnchor {
+  if (!isPlainObject(value)) return false
+  if (typeof value.file !== 'string') return false
+  if (typeof value.line !== 'number') return false
+  if (value.targetTag !== undefined && typeof value.targetTag !== 'string') return false
+  if (value.component !== undefined && typeof value.component !== 'string') return false
+  if (value.position !== undefined && !ANCHOR_POSITIONS.includes(value.position as string)) return false
+  if (value.mfe !== undefined && typeof value.mfe !== 'string') return false
+  return true
+}
+
+/** Entry-depth shape guard. The PUT boundary must reject a single malformed
+ *  entry — once persisted it would poison reapply, undo ordering, and the
+ *  agent's `context.session` payload. */
+export function isSessionEntry(value: unknown): value is SessionEntry {
+  if (!isPlainObject(value)) return false
+  if (typeof value.id !== 'string' || !value.id) return false
+  if (typeof value.ordinal !== 'number') return false
+  if (typeof value.ts !== 'number') return false
+  if (typeof value.route !== 'string') return false
+  // The change payload is the open AnnotaskChange union — validate the shared
+  // envelope only (id/type/description discipline lives with the producers).
+  if (!isPlainObject(value.change) || typeof (value.change as Record<string, unknown>).type !== 'string') return false
+  if (!isSessionAnchor(value.anchor)) return false
+  if (value.evidence !== undefined && !isEditEvidence(value.evidence)) return false
+  if (!isLiveWriteState(value.live)) return false
+  if (value.instanceId !== undefined && typeof value.instanceId !== 'string') return false
+  if (value.eid !== undefined && typeof value.eid !== 'string') return false
+  if (value.taskId !== undefined && typeof value.taskId !== 'string') return false
+  if (value.breakpointId !== undefined && value.breakpointId !== null && typeof value.breakpointId !== 'string') return false
+  return true
+}
+
+/** Structural validation for the GET/PUT boundary — entry depth, one bad entry
+ *  rejects the whole document (the wireframe PUT discipline). */
+export function isDesignSessionDocument(value: unknown): value is DesignSessionDocument {
+  if (!isPlainObject(value)) return false
+  if (value.version !== DESIGN_SESSION_DOC_VERSION) return false
+  if (typeof value.sessionId !== 'string' || !value.sessionId) return false
+  if (typeof value.startedAt !== 'number') return false
+  if (typeof value.updatedAt !== 'number') return false
+  if (value.rev !== undefined && typeof value.rev !== 'number') return false
+  if (!Array.isArray(value.entries)) return false
+  return (value.entries as unknown[]).every(isSessionEntry)
+}
diff --git a/src/shared/task-summary.ts b/src/shared/task-summary.ts
index 47ee653..11e6db8 100644
--- a/src/shared/task-summary.ts
+++ b/src/shared/task-summary.ts
@@ -21,7 +21,6 @@ const CONTEXT_FIELDS_BY_TYPE: Partial<Record<TaskType, readonly string[]>> = {
   error_fix:    ['level', 'occurrences', 'errorId'],
   theme_update: ['category', 'role', 'before', 'after', 'cssVar'],
   style_update: [],
-  api_update:   ['data_source_name', 'data_source_kind', 'schema_location', 'schema_kind', 'endpoint', 'desired_change'],
 }
 
 /**
@@ -133,19 +132,6 @@ export function buildTaskSummary(task: Record<string, unknown>): Record<string,
     if ((typeKey === 'style_update' || typeKey === 'class_update') && Array.isArray(ctxRecord.changes)) {
       summary.change_count = (ctxRecord.changes as unknown[]).length
     }
-    // api_update tasks: lift the nested operation pointer so triage sees
-    // method + path without a detail fetch.
-    if (typeKey === 'api_update' && ctxRecord.operation && typeof ctxRecord.operation === 'object' && !Array.isArray(ctxRecord.operation)) {
-      const op = ctxRecord.operation as Record<string, unknown>
-      if (typeof op.method === 'string' && op.method) summary.operation_method = op.method
-      if (typeof op.path === 'string' && op.path) summary.operation_path = op.path
-    }
-    // Any task that recorded cross-boundary API edits (commonly annotations
-    // that the user approved into backend territory) — surface the count so
-    // triage sees that this task crossed the frontend/backend line.
-    if (Array.isArray(ctxRecord.api_edits) && ctxRecord.api_edits.length > 0) {
-      summary.api_edits_count = ctxRecord.api_edits.length
-    }
   }
 
   return summary
@@ -177,6 +163,27 @@ export function stripTaskVisual(task: unknown): Record<string, unknown> {
   return rest
 }
 
+/**
+ * List-mode variant of `stripTaskVisual` for `detail=true` task *lists*
+ * (MCP `annotask_get_tasks` and CLI `tasks --detail --mcp`). On top of the
+ * visual/timestamp stripping it drops the two per-task payloads that can be
+ * huge and each have a dedicated retrieval tool:
+ * - `interaction_history` → `annotask_get_interaction_history`
+ * - `context.rendered` (embedded outerHTML, up to 200 KB per task) →
+ *   `annotask_get_rendered_html`
+ * Single-task fetches (`annotask_get_task`) keep both fields — only bulk
+ * listings strip them, since N tasks × 200 KB would swamp an agent's context.
+ */
+export function stripTaskForList(task: unknown): Record<string, unknown> {
+  const rest = stripTaskVisual(task)
+  delete rest.interaction_history
+  if (rest.context && typeof rest.context === 'object' && !Array.isArray(rest.context)) {
+    const { rendered, ...ctx } = rest.context as Record<string, unknown>
+    if (rendered !== undefined) rest.context = ctx
+  }
+  return rest
+}
+
 /**
  * Trim `agent_feedback` to the latest resolved exchange plus every unresolved
  * one. Keeps the thread agent-friendly without re-sending old answered
diff --git a/src/shared/wireframe-types.ts b/src/shared/wireframe-types.ts
new file mode 100644
index 0000000..7f0d675
--- /dev/null
+++ b/src/shared/wireframe-types.ts
@@ -0,0 +1,437 @@
+/**
+ * Wireframe document — the persisted, multi-route artifact behind the
+ * drag-and-drop wireframe tool. One `.annotask/wireframe.json` per project,
+ * keyed by iframe route (like RuntimeEndpoint.routes[]). This single definition
+ * is shared by the server GET/PUT validator, the shell `useWireframeDoc`
+ * composable, and the agent-facing `wireframe_apply` task context — so the
+ * persisted shape, the shell, and codegen never drift.
+ *
+ * `inserted` deliberately mirrors `InsertChangeRecord.inserted`
+ * (useStyleEditor) and `ComponentInsertChange.component` (schema.ts) so the
+ * `wireframe_apply` playbook can lift an instance straight into the existing
+ * component-insert codegen shape.
+ */
+
+import type { DataSource } from '../schema'
+
+/** How faithfully a dropped component renders on the canvas. */
+export type WireframeFidelity = 'live' | 'isolated-preview' | 'placeholder'
+
+/**
+ * Binding from a wireframe block (palette component or drawn section) to a
+ * REAL project data source — scanner-catalog identity, never invented. The
+ * agent re-grounds it via `annotask_get_data_source_details` /
+ * `annotask_get_api_operation` before wiring; `shape_source` is the honesty
+ * tag for where the drill-down shape came from.
+ */
+export interface WireframeDataBinding {
+  /** REAL catalog identity — scanner names, never invented. */
+  kind: DataSource['kind']
+  /** e.g. "useUserQuery" */
+  name: string
+  module?: string
+  endpoint?: string
+  /** Drill-down into the resolved shape, user-selected.
+   *  e.g. "items[]" (the list), "data.user" (an object). */
+  path?: string
+  /** Keys the element should display, when the user narrowed them.
+   *  e.g. ["name", "price"]. */
+  fields?: string[]
+  /** Where the shape came from — the honesty tag the agent sees.
+   *  'api-schema' (real contract) | 'source-details' (regex inference) |
+   *  'none' (user typed the path blind). NOTE: a numeric confidence is NOT
+   *  currently carried on the binding — the tag is the only signal. Reworking
+   *  this ladder (a real confidence floor, threaded to the agent) is why data
+   *  binding is gated off for this release (see shell/wireframeFeatures.ts). */
+  shape_source: 'api-schema' | 'source-details' | 'none'
+  /** Maps a component PROP name → a data FIELD within the bound item
+   *  (e.g. { label: 'name', value: 'type' }). Drives the preview's bound
+   *  values; the agent wires the real binding from it at apply. Components
+   *  only — drawn sections describe content via `md`, not props. */
+  propMap?: Record<string, string>
+  /** For a LIST binding (`path` ends '[]'): how many instances to SKETCH on the
+   *  canvas (the repeated v-for elements). A hint only — at apply the agent
+   *  renders a real loop over the whole `path`, not literally N copies. */
+  repeat?: number
+  /** Up to a few REAL example rows pulled from the API contract at pick time
+   *  (api-schema tier only) — drives the preview's bound values and gives the
+   *  agent honest sample context. NEVER fabricated; absent for lower tiers. */
+  sample?: Record<string, unknown>[]
+}
+
+/** Runtime mirror of DataSource['kind'] — typed against the union so schema
+ *  drift breaks typecheck instead of silently accepting unknown kinds. */
+export const DATA_SOURCE_KINDS: readonly DataSource['kind'][] =
+  ['composable', 'signal', 'store', 'fetch', 'graphql', 'loader', 'rpc']
+
+const SHAPE_SOURCES: readonly string[] = ['api-schema', 'source-details', 'none']
+
+export function isWireframeDataBinding(value: unknown): value is WireframeDataBinding {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
+  const b = value as Record<string, unknown>
+  if (!DATA_SOURCE_KINDS.includes(b.kind as DataSource['kind'])) return false
+  if (typeof b.name !== 'string' || !b.name) return false
+  if (!SHAPE_SOURCES.includes(b.shape_source as string)) return false
+  for (const k of ['module', 'endpoint', 'path'] as const) {
+    if (b[k] !== undefined && (typeof b[k] !== 'string' || !b[k])) return false
+  }
+  if (b.fields !== undefined) {
+    if (!Array.isArray(b.fields)) return false
+    if (!(b.fields as unknown[]).every((f) => typeof f === 'string' && !!f)) return false
+  }
+  if (b.propMap !== undefined) {
+    if (!b.propMap || typeof b.propMap !== 'object' || Array.isArray(b.propMap)) return false
+    for (const v of Object.values(b.propMap as Record<string, unknown>)) {
+      if (typeof v !== 'string' || !v) return false
+    }
+  }
+  if (b.repeat !== undefined && (typeof b.repeat !== 'number' || !Number.isFinite(b.repeat) || b.repeat < 1)) return false
+  if (b.sample !== undefined) {
+    if (!Array.isArray(b.sample)) return false
+    if (!(b.sample as unknown[]).every((r) => !!r && typeof r === 'object' && !Array.isArray(r))) return false
+  }
+  return true
+}
+
+/** What was dropped: a real project/library component, a raw HTML element, or a
+ *  styled layout preset (flex row, grid, container, …). */
+export type WireframeKind = 'component' | 'html' | 'layout-preset'
+
+/** Where the new node sits relative to the drop target. */
+export type WireframePosition = 'before' | 'after' | 'append' | 'prepend'
+
+/**
+ * Lifecycle of one placement. Absent means 'placed' (legacy docs predate the
+ * field). 'building' = batched into a wireframe_apply task that is still in
+ * flight; 'applied' is reserved for instances whose source edit landed but
+ * whose doc entry hasn't been cleared yet. Only 'placed' instances re-mount
+ * on reload and only 'placed' instances are collected by Build — that pair of
+ * rules is what stops a placement from rendering NEXT TO the agent's freshly
+ * applied component during review, and stops a double-click from emitting a
+ * duplicate task.
+ */
+export type WireframeInstanceStatus = 'placed' | 'building' | 'applied'
+
+export interface WireframeAnchor {
+  /** Source file of the drop target, as emitted by `data-annotask-file`
+   *  (package-local). The durable half of the anchor. */
+  file: string
+  /** Opening-tag line of the drop target (`data-annotask-line`). */
+  line: number
+  /** Placement relative to the target element. */
+  position: WireframePosition
+  /** The drop target's owning component — context for the codegen agent. */
+  component?: string
+  /** The drop target's tag — helps re-resolve the anchor after reload/HMR. */
+  targetTag?: string
+  /** Volatile same-session element id of the target. NOT durable across reload;
+   *  re-resolved from (file, line, targetTag) via `resolve:template-group`. */
+  targetEid?: string
+}
+
+export interface WireframeInserted {
+  /** HTML tag, or the lowercased component tag. */
+  tag: string
+  /** Component constructor name when `kind === 'component'`. */
+  componentName?: string
+  library?: string
+  /** Import specifier (e.g. "primevue/button") for on-demand re-mount. */
+  module?: string
+  props?: Record<string, unknown>
+  classes?: string
+  text_content?: string
+}
+
+export interface WireframeInstance {
+  id: string
+  kind: WireframeKind
+  anchor: WireframeAnchor
+  inserted: WireframeInserted
+  fidelity: WireframeFidelity
+  /** Whether the live mount actually rendered (components only; always true for
+   *  html/layout-preset placeholders, which render deterministically). */
+  mounted: boolean
+  /** Lifecycle state. Optional so legacy docs stay valid; absent == 'placed'. */
+  status?: WireframeInstanceStatus
+  /** The wireframe_apply task this instance was batched into (status
+   *  'building'/'applied'). Cleared when the task is deleted (revert) and the
+   *  whole instance is removed when the task is accepted. */
+  taskId?: string
+  /** Display-only sample props the user actually previewed on the canvas.
+   *  Kept SEPARATE from `inserted.props` (the real props): the agent uses
+   *  these as hints for sensible labels/values, and reapply mounts with them
+   *  so a reload doesn't degrade to an empty 'rendered-empty' placeholder. */
+  previewProps?: Record<string, unknown>
+  createdAt: number
+  updatedAt?: number
+}
+
+// ── Snapshot-wireframe canvas ────────────────────────────
+// The frozen-image canvas behind Wireframe mode: per-block html2canvas
+// captures of the live route, manipulated as positioned images. Block PNGs
+// live on disk (.annotask/wireframe-snapshots/) — the doc stores FILENAMES,
+// never dataUrls, so the CAS round-trip stays small.
+
+/** 'captured' — rasterized from the live route (carries a source anchor).
+ *  'palette'  — a component snapshot dropped from the palette.
+ *  'placeholder' — a user-drawn labeled box; stays visibly a placeholder. */
+export type WireframeBlockKind = 'captured' | 'palette' | 'placeholder'
+
+/** Iframe-document CSS px at capture time — the canvas coordinate space. */
+export interface WireframeBlockRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+/** Source identity of a captured block (data-annotask-* at capture time).
+ *  `file` may be '' when the element carried no stamp — honest, no chip. */
+export interface WireframeBlockAnchor {
+  file: string
+  line: number
+  component?: string
+  sourceTag?: string
+  tag?: string
+  /** First class name at capture time — the human-distinct direction label
+   *  ('toolbar', 'layout'); component names repeat across a page's blocks. */
+  cssClass?: string
+  /** 'header' | 'nav' | 'footer' | 'aside' | 'content' from block discovery. */
+  role?: string
+}
+
+/** What a palette block stands for — REAL scanner names, mirrors
+ *  WireframeInserted so apply-time codegen can lift it directly. */
+export interface WireframePaletteRef {
+  tag: string
+  componentName?: string
+  library?: string
+  module?: string
+  props?: Record<string, unknown>
+  previewProps?: Record<string, unknown>
+  /** Owning MFE id, stamped at place time so apply-time codegen imports from
+   *  the correct package in a multi-MFE workspace. Absent in single-MFE/legacy
+   *  docs — codegen then falls back to library/module exactly as before. */
+  mfe?: string
+}
+
+export interface WireframeBlock {
+  id: string
+  kind: WireframeBlockKind
+  /** Current rect on the canvas (the user's transform). */
+  rect: WireframeBlockRect
+  z: number
+  /** USER-SAID, verbatim — never mixed with tool-measured facts. */
+  note?: string
+  /** Snapshot filename under .annotask/wireframe-snapshots/. */
+  image?: string
+  createdAt: number
+  updatedAt?: number
+  // captured blocks
+  anchor?: WireframeBlockAnchor
+  /** Rect as captured — the diff baseline for move/resize directions. */
+  originalRect?: WireframeBlockRect
+  /** Soft delete: hidden on the canvas but kept so the diff sees it. */
+  deleted?: boolean
+  captureError?: string
+  clipped?: boolean
+  /** Exploded container: this block is now the SHELL backdrop (its image has
+   *  the children hidden); its children exist as separate blocks. Not
+   *  explodable again. */
+  shell?: boolean
+  /** Set on duplicates; the original block's id (image file is shared). */
+  duplicateOf?: string
+  // palette blocks
+  component?: WireframePaletteRef
+  fidelity?: WireframeFidelity
+  // placeholder blocks
+  label?: string
+  /** USER-WRITTEN markdown spec for a drawn section — verbatim, never blended
+   *  with tool-measured facts. A placeholder with `md` (or `data`) renders
+   *  with the "section" affordance; the body rides `added.md` verbatim. */
+  md?: string
+  /** Data-source binding (any kind — palette components and drawn sections).
+   *  REAL catalog identity; carried into the add direction's `added.data`. */
+  data?: WireframeDataBinding
+}
+
+export interface WireframeCanvasState {
+  capturedAt: number
+  viewport: { width: number; height: number; docWidth: number; docHeight: number; scale: number }
+  /** Full-document capture filename — the honest "before" for composites. */
+  fullImage?: string
+  /** Block discovery hit the cap; some page regions have no block. */
+  truncated?: boolean
+  blocks: WireframeBlock[]
+  /** Apply lifecycle, mirroring WireframeInstanceStatus semantics:
+   *  absent/'sketch' = editable; 'building' = batched into a task in flight. */
+  status?: 'sketch' | 'building'
+  taskId?: string
+}
+
+export interface WireframeRoute {
+  route: string
+  instances: WireframeInstance[]
+  /** Snapshot-wireframe canvas for this route (absent until first capture). */
+  canvas?: WireframeCanvasState
+  updatedAt?: number
+}
+
+export interface WireframeDocument {
+  version: '1.0'
+  updatedAt: number
+  /** Server-managed write revision. Stamped/incremented by the store on every
+   *  successful PUT; a PUT whose `rev` doesn't match the current doc is
+   *  rejected with 409 so two tabs can't last-writer-wins each other. Absent
+   *  only on legacy docs that predate the field (first PUT stamps it). */
+  rev?: number
+  routes: WireframeRoute[]
+}
+
+export const WIREFRAME_DOC_VERSION = '1.0' as const
+
+const WIREFRAME_KINDS: readonly string[] = ['component', 'html', 'layout-preset']
+const WIREFRAME_POSITIONS: readonly string[] = ['before', 'after', 'append', 'prepend']
+const WIREFRAME_STATUSES: readonly string[] = ['placed', 'building', 'applied']
+const BLOCK_KINDS: readonly string[] = ['captured', 'palette', 'placeholder']
+const CANVAS_STATUSES: readonly string[] = ['sketch', 'building']
+/** Snapshot filenames are shell-minted ids + .png — reject anything else at
+ *  the PUT boundary so a poisoned doc can't traverse on the serve path. The
+ *  server's upload/serve/delete routes enforce the same shape. */
+export const WIREFRAME_SNAPSHOT_FILENAME_RE = /^[a-z0-9][a-z0-9-]{0,63}\.png$/
+
+export function emptyWireframeDocument(): WireframeDocument {
+  return { version: WIREFRAME_DOC_VERSION, updatedAt: 0, routes: [] }
+}
+
+/**
+ * Forward migrations, keyed by the version they upgrade FROM. Each returns the
+ * doc one schema version newer. Empty today — `1.0` is current — but the frame
+ * MUST exist before the version is ever bumped: without a registered migration,
+ * `isWireframeDocument` rejects the old-version doc and the store wipes every
+ * persisted wireframe (silent data loss). When you bump WIREFRAME_DOC_VERSION,
+ * add the `'1.0': (doc) => ({ ...doc, version: '1.1', ...transform })` entry here.
+ */
+const WIREFRAME_MIGRATIONS: Record<string, (doc: Record<string, unknown>) => Record<string, unknown>> = {}
+
+/**
+ * Reconcile a persisted doc with the current schema instead of silently wiping
+ * it. A fully-valid current doc passes through; a recognized older version is
+ * migrated forward step by step; a pre-versioned (early-format) doc that
+ * otherwise matches the shape is stamped with the current version. Returns null
+ * only when the result still isn't a valid document (genuinely malformed, or a
+ * NEWER/unknown version we can't safely interpret) — the caller then leaves the
+ * file alone rather than overwriting it. Same-version strictness is unchanged:
+ * one bad instance/block still fails validation (the PUT-boundary contract).
+ */
+export function migrateWireframeDocument(raw: unknown): WireframeDocument | null {
+  if (!isPlainObject(raw)) return null
+  let doc: Record<string, unknown> = raw
+  // Pre-versioned early-format doc: shares 1.0's shape, just lacks the field.
+  if (doc.version === undefined) doc = { ...doc, version: WIREFRAME_DOC_VERSION }
+  let guard = 0
+  while (typeof doc.version === 'string' && doc.version !== WIREFRAME_DOC_VERSION
+    && WIREFRAME_MIGRATIONS[doc.version] && guard++ < 20) {
+    doc = WIREFRAME_MIGRATIONS[doc.version](doc)
+  }
+  return isWireframeDocument(doc) ? doc : null
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** Instance-depth shape guard. The PUT boundary must reject a single malformed
+ *  instance — once persisted it would poison every subsequent reapply pass and
+ *  the agent's wireframe_apply context. */
+export function isWireframeInstance(value: unknown): value is WireframeInstance {
+  if (!isPlainObject(value)) return false
+  if (typeof value.id !== 'string' || !value.id) return false
+  if (!WIREFRAME_KINDS.includes(value.kind as string)) return false
+  if (!isPlainObject(value.anchor)) return false
+  const anchor = value.anchor as Record<string, unknown>
+  if (typeof anchor.file !== 'string') return false
+  if (typeof anchor.line !== 'number') return false
+  if (!WIREFRAME_POSITIONS.includes(anchor.position as string)) return false
+  if (!isPlainObject(value.inserted)) return false
+  if (typeof (value.inserted as Record<string, unknown>).tag !== 'string') return false
+  // Optional lifecycle fields — when present they must be well-formed, or the
+  // accept/delete hooks and the Build collector would misread them.
+  if (value.status !== undefined && !WIREFRAME_STATUSES.includes(value.status as string)) return false
+  if (value.taskId !== undefined && typeof value.taskId !== 'string') return false
+  if (value.previewProps !== undefined && !isPlainObject(value.previewProps)) return false
+  return true
+}
+
+function isBlockRect(value: unknown): value is WireframeBlockRect {
+  if (!isPlainObject(value)) return false
+  return typeof value.x === 'number' && typeof value.y === 'number'
+    && typeof value.width === 'number' && typeof value.height === 'number'
+}
+
+/** Block-depth shape guard with per-kind requirements: a captured block must
+ *  carry its anchor + original rect (the diff baseline), a palette block its
+ *  component ref, a placeholder its label — a block missing its kind's
+ *  substance could only fabricate. */
+export function isWireframeBlock(value: unknown): value is WireframeBlock {
+  if (!isPlainObject(value)) return false
+  if (typeof value.id !== 'string' || !value.id) return false
+  if (!BLOCK_KINDS.includes(value.kind as string)) return false
+  if (!isBlockRect(value.rect)) return false
+  if (typeof value.z !== 'number') return false
+  if (typeof value.createdAt !== 'number') return false
+  if (value.note !== undefined && typeof value.note !== 'string') return false
+  if (value.image !== undefined && !WIREFRAME_SNAPSHOT_FILENAME_RE.test(value.image as string)) return false
+  if (value.deleted !== undefined && typeof value.deleted !== 'boolean') return false
+  if (value.shell !== undefined && typeof value.shell !== 'boolean') return false
+  if (value.duplicateOf !== undefined && typeof value.duplicateOf !== 'string') return false
+  if (value.md !== undefined && typeof value.md !== 'string') return false
+  if (value.data !== undefined && !isWireframeDataBinding(value.data)) return false
+  if (value.kind === 'captured') {
+    const anchor = value.anchor as Record<string, unknown> | undefined
+    if (!isPlainObject(anchor) || typeof anchor.file !== 'string' || typeof anchor.line !== 'number') return false
+    if (!isBlockRect(value.originalRect)) return false
+  }
+  if (value.kind === 'palette') {
+    const component = value.component as Record<string, unknown> | undefined
+    if (!isPlainObject(component) || typeof component.tag !== 'string' || !component.tag) return false
+  }
+  if (value.kind === 'placeholder') {
+    if (typeof value.label !== 'string' || !value.label) return false
+  }
+  return true
+}
+
+export function isWireframeCanvasState(value: unknown): value is WireframeCanvasState {
+  if (!isPlainObject(value)) return false
+  if (typeof value.capturedAt !== 'number') return false
+  const vp = value.viewport as Record<string, unknown> | undefined
+  if (!isPlainObject(vp)) return false
+  for (const k of ['width', 'height', 'docWidth', 'docHeight', 'scale']) {
+    if (typeof vp[k] !== 'number') return false
+  }
+  if (value.fullImage !== undefined && !WIREFRAME_SNAPSHOT_FILENAME_RE.test(value.fullImage as string)) return false
+  if (value.status !== undefined && !CANVAS_STATUSES.includes(value.status as string)) return false
+  if (value.taskId !== undefined && typeof value.taskId !== 'string') return false
+  if (!Array.isArray(value.blocks)) return false
+  return (value.blocks as unknown[]).every(isWireframeBlock)
+}
+
+/** Structural validation for the GET/PUT boundary. Mirrors the agent-configs
+ *  PATCH validation discipline: shape-guard before persisting. Validates down
+ *  to instance/block depth so one bad instance or block can't be persisted. */
+export function isWireframeDocument(value: unknown): value is WireframeDocument {
+  if (!isPlainObject(value)) return false
+  const doc = value as Record<string, unknown>
+  if (doc.version !== WIREFRAME_DOC_VERSION) return false
+  if (typeof doc.updatedAt !== 'number') return false
+  if (doc.rev !== undefined && typeof doc.rev !== 'number') return false
+  if (!Array.isArray(doc.routes)) return false
+  return doc.routes.every((r) => {
+    if (!isPlainObject(r)) return false
+    const route = r as Record<string, unknown>
+    if (typeof route.route !== 'string' || !Array.isArray(route.instances)) return false
+    if (route.canvas !== undefined && !isWireframeCanvasState(route.canvas)) return false
+    return (route.instances as unknown[]).every(isWireframeInstance)
+  })
+}
diff --git a/src/shared/work-stream.ts b/src/shared/work-stream.ts
new file mode 100644
index 0000000..e5de3ab
--- /dev/null
+++ b/src/shared/work-stream.ts
@@ -0,0 +1,51 @@
+/**
+ * Work-stream blocks — the timeline view the Conversation tab renders.
+ *
+ * One `ThreadMessage` per assistant turn carries an ordered array of these
+ * blocks. The legacy `content: string` field is kept alongside as a flat
+ * text rollup so MCP / CLI tail-readers (e.g. `annotask_conversation_read`)
+ * still get a sensible plaintext shape; rich UIs read `blocks` instead.
+ *
+ * Block kinds:
+ * - `text`     — assistant prose (markdown). Multiple texts are allowed in
+ *                one turn because tool calls split the timeline.
+ * - `tool_call`  — agent invoked a tool. `summary` is a one-liner produced
+ *                by the toolSummary helper; `input` is the raw arguments.
+ * - `tool_result` — paired with a prior `tool_call.id`. `summary` is a
+ *                  short preview ("128 lines returned"); `raw` is the
+ *                  full content for the expandable panel.
+ * - `agent_question` — synthetic block emitted by the shell when the task
+ *                     transitions to `needs_info`. Renders read-only with
+ *                     a link to the inline answer composer.
+ *
+ * This file is shared by both the server task-thread store and the shell
+ * UI so the wire format has a single source of truth.
+ */
+
+export type WorkStreamBlock =
+  | { kind: 'text'; text: string }
+  | {
+      kind: 'tool_call'
+      id: string
+      name: string
+      input: unknown
+      /** Human-friendly one-liner (`"Reading App.vue:42-89"`). */
+      summary: string
+    }
+  | {
+      kind: 'tool_result'
+      /** Pairs with a prior tool_call.id. */
+      toolUseId: string
+      /** One-line preview, e.g. "128 lines returned" or "Error: …". */
+      summary: string
+      /** Full raw output. UI shows in an expandable panel. */
+      raw: string
+      isError?: boolean
+    }
+  | {
+      kind: 'agent_question'
+      /** Index into task.agent_feedback for the entry this block represents. */
+      entryIndex: number
+      /** Short message extracted from the entry (or first question text). */
+      label: string
+    }
diff --git a/src/shell/App.vue b/src/shell/App.vue
index ff7e5ea..23602e7 100644
--- a/src/shell/App.vue
+++ b/src/shell/App.vue
@@ -1,7 +1,12 @@
 <script setup lang="ts">
-import { ref, computed, watch } from 'vue'
+import { ref, computed, watch, nextTick } from 'vue'
 import { useStyleEditor } from './composables/useStyleEditor'
+import { useDesignSession } from './composables/useDesignSession'
 import { useInteractionMode } from './composables/useInteractionMode'
+import { useWireframeMode } from './composables/useWireframeMode'
+import { useComponentGenerator } from './composables/useComponentGenerator'
+import { useWorkspace } from './composables/useWorkspace'
+import type { PaletteDragItem } from './composables/usePaletteDrag'
 import { useDesignSpec, setActiveColorScheme } from './composables/useDesignSpec'
 import { useLayoutOverlay } from './composables/useLayoutOverlay'
 import { useAnnotations } from './composables/useAnnotations'
@@ -17,9 +22,9 @@ import type { A11yViolation } from './composables/useA11yScanner'
 // Annotation overlays (still used inline in canvas area)
 import PinOverlay from './components/PinOverlay.vue'
 import ArrowOverlay from './components/ArrowOverlay.vue'
-import DrawnSectionOverlay from './components/DrawnSectionOverlay.vue'
 import TextHighlightOverlay from './components/TextHighlightOverlay.vue'
 import LayoutOverlay from './components/LayoutOverlay.vue'
+import WireframeCanvas from './components/WireframeCanvas.vue'
 // Panels + Overlays + Modals (extracted components)
 import AppToolbar from './components/AppToolbar.vue'
 import AppBanners from './components/AppBanners.vue'
@@ -31,8 +36,16 @@ import A11yPanel from './components/A11yPanel.vue'
 import AuditPanel from './components/AuditPanel.vue'
 import DataSourcesPage from './components/DataSourcesPage.vue'
 import ComponentsPage from './components/ComponentsPage.vue'
+import OverlayLegend from './components/OverlayLegend.vue'
 import HelpOverlay from './components/HelpOverlay.vue'
 import SettingsOverlay from './components/SettingsOverlay.vue'
+import InitWizard from './components/InitWizard.vue'
+import { useInitFlow } from './composables/useInitFlow'
+import { useProviderSettings } from './composables/useProviderSettings'
+import { useAgentModels } from './composables/useAgentModels'
+import { useAgentMode } from './composables/useAgentMode'
+import { startAutoRunDriver } from './composables/useAutoRunDriver'
+import { useAgentDetect, fetchAgentDetect } from './composables/useTaskThread'
 import A11yDetailDrawer from './components/A11yDetailDrawer.vue'
 import ContextMenu from './components/ContextMenu.vue'
 import ReportViewer from './components/ReportViewer.vue'
@@ -61,6 +74,7 @@ import { useBridgeEventHandlers } from './composables/useBridgeEventHandlers'
 import { useShellLifecycle } from './composables/useShellLifecycle'
 import { useInteractionModeSync } from './composables/useInteractionModeSync'
 import { normalizeRoute } from './utils/routes'
+import { useWireframeCanvas } from './composables/useWireframeCanvas'
 import { navigateIframe as navigateIframeUtil, useAppUrl, useIframeStyle } from './utils/iframeNavigation'
 
 const shellTheme = useShellTheme()
@@ -104,6 +118,7 @@ const { shellView, designSection, developSection, activePanel } = useShellNaviga
 const layoutOverlay = useLayoutOverlay(iframeRef)
 const iframe = useIframeManager(iframeRef)
 const { currentRoute } = iframe
+
 // Keep the shared active-theme signal in sync with the iframe so views that
 // don't see iframe.colorScheme directly (e.g. the token palette popover) can
 // still resolve the iframe's current design-spec variant.
@@ -111,13 +126,13 @@ watch(iframe.colorScheme, (cs) => setActiveColorScheme(cs), { immediate: true })
 const arrowColor = useLocalStorageRef('annotask:arrowColor', '#ef4444')
 const highlightColor = useLocalStorageRef('annotask:highlightColor', '#f59e0b')
 const canvas = useCanvasDrawing(annotations, (x: number, y: number) => iframe.resolveElementAt(x, y), () => interactionMode.value, (arrowId, fromCtx, toCtx) => onArrowCreated(arrowId, fromCtx, toCtx), () => arrowColor.value, () => discardUncommittedAnnotations())
-const { drawingArrow, drawingRect, hoverElement: arrowHoverElement, onCanvasPointerDown, onCanvasPointerMove, onCanvasPointerUp } = canvas
+const { drawingArrow, hoverElement: arrowHoverElement, onCanvasPointerDown, onCanvasPointerMove, onCanvasPointerUp } = canvas
 
 const showWarning = ref(false)
 const showReportPanel = ref(false)
 const annotaskVersion = typeof __ANNOTASK_VERSION__ !== 'undefined' ? __ANNOTASK_VERSION__ : 'dev'
 // Markup visibility toggles
-const showMarkup = ref({ pins: true, arrows: true, sections: true, highlights: true, inspector: true })
+const showMarkup = ref({ pins: true, arrows: true, highlights: true, inspector: true })
 const includeHistory = useLocalStorageBool('annotask:includeHistory', false)
 // Intentionally non-persistent: every session starts with rendered HTML off so
 // tasks don't accidentally carry a large outerHTML blob from a prior opt-in.
@@ -130,12 +145,66 @@ const includeDataContext = ref(false)
 const screenshots = useScreenshots(iframe)
 const { snipActive, snipRect, pendingScreenshot, startSnip, onSnipDown, onSnipMove, onSnipUp, cancelSnip, removeScreenshot } = screenshots
 const showThemeEditor = ref(false)
+const initFlow = useInitFlow()
 const helpSection = ref<'overview' | 'annotate' | 'design' | 'audit' | 'context' | 'tasks' | 'agent' | 'skills' | 'apply-skill' | 'init-skill' | 'settings'>('overview')
 const {
   showShortcuts, showSettings,
   toggleShortcuts, toggleSettings,
 } = useOverlayToggles()
 
+// Kick off the local-CLI probe at shell mount and mirror the result into
+// the provider-settings singleton. The probe used to live inside the
+// Settings panel, which meant `providerSettings.ready` was false for every
+// local-CLI provider until the user opened Settings — masking auto-run
+// and Run-with-agent. App.vue is always mounted, so the probe always fires.
+const providerSettings = useProviderSettings()
+const agentDetect = useAgentDetect()
+fetchAgentDetect()
+
+// Dev-side session reset. The playground justfile's `clear-init` target
+// writes `.annotask/.session-reset` on disk so the shell can self-clear
+// browser-side state (localStorage) the next time it loads — no DevTools
+// paste required. The server includes `sessionReset: true` in the status
+// payload until we DELETE the sentinel below.
+async function consumeSessionResetIfAny() {
+  try {
+    const r = await fetch('/__annotask/api/status')
+    if (!r.ok) return
+    const { sessionReset } = await r.json()
+    if (!sessionReset) return
+    for (const k of Object.keys(localStorage)) {
+      if (k.startsWith('annotask:')) localStorage.removeItem(k)
+    }
+    await fetch('/__annotask/api/session-reset', { method: 'DELETE' })
+    location.reload()
+  } catch { /* server offline — nothing to do */ }
+}
+void consumeSessionResetIfAny()
+
+// Warm the model-catalog cache for the primary providers at shell load so
+// every dropdown (Settings → Providers, InitWizard, AgentDirectionsPanel)
+// shows the live list immediately when opened. The composable honors a
+// 5-min localStorage TTL, so refreshes are free when warm.
+void useAgentModels().preload(['claude-local', 'codex-local', 'opencode-local', 'copilot-local'])
+watch(
+  () => agentDetect.snapshot.value,
+  (snap) => {
+    if (!snap) return
+    providerSettings.setLocalCliProbe({
+      'claude-local': !!(snap['claude-local'].found && snap['claude-local'].loggedIn),
+      'codex-local': !!(snap['codex-local'].found && snap['codex-local'].loggedIn),
+      'opencode-local': !!(snap['opencode-local'].found && snap['opencode-local'].loggedIn),
+      'copilot-local': !!(snap['copilot-local']?.found && snap['copilot-local']?.loggedIn),
+    })
+  },
+  { immediate: true },
+)
+
+// Agent-mode auto-run queue lives at module scope (singleton); the watcher
+// that routes a queued id into the detail modal is set up further down,
+// once `detailTaskId` is in scope.
+const agentMode = useAgentMode()
+
 
 
 // ── Selection Model ────────────────────────────────────
@@ -368,7 +437,7 @@ const dataHighlightActive = computed(() =>
   (shellView.value === 'design' && designSection.value === 'components'))
 const dataHighlights = useDataHighlights({ iframe, active: dataHighlightActive })
 
-function rectClass(h: { eid: string; sourceName: string; ownerSources?: string[]; confidence?: 'precise' | 'fallback' | 'runtime-only' }) {
+function rectClass(h: { eid: string; sourceName: string; ownerSources?: string[]; confidence?: 'precise' | 'fallback' | 'runtime-only'; encoding?: 'identity' | 'latency' }) {
   const fEid = dataHighlights.focusedEid.value
   const fName = dataHighlights.focusedName.value
   const owners = h.ownerSources ?? [h.sourceName]
@@ -381,6 +450,8 @@ function rectClass(h: { eid: string; sourceName: string; ownerSources?: string[]
     dimmed: hasFocus && !isFocused,
     'hover-only': shellView.value === 'design' && designSection.value === 'components',
     fallback: h.confidence === 'fallback',
+    'runtime-only': h.confidence === 'runtime-only',
+    latency: h.encoding === 'latency',
     multi: owners.length > 1,
   }
 }
@@ -451,9 +522,18 @@ iframe.onBridgeEvent('data:hover', (payload: DataHoverPayload) => {
   const iframeRect = iframeEl?.getBoundingClientRect()
   const offX = iframeRect?.left ?? 0
   const offY = iframeRect?.top ?? 0
+  // Clamp/flip the fixed-position tooltip to the viewport so it never renders
+  // off-screen at the iframe's right/bottom edges (where dense overlays cluster).
+  const ttW = Math.min(280, 34 + hit.label.length * 7) // estimate before paint
+  const ttH = 26
+  let ttX = offX + payload.clientX + 12
+  let ttY = offY + payload.clientY + 14
+  if (ttX + ttW > window.innerWidth - 8) ttX = offX + payload.clientX - ttW - 12 // flip left
+  ttX = Math.max(8, Math.min(ttX, window.innerWidth - ttW - 8))
+  ttY = Math.max(8, Math.min(ttY, window.innerHeight - ttH - 8))
   dataTooltip.value = {
-    x: offX + payload.clientX + 12,
-    y: offY + payload.clientY + 14,
+    x: ttX,
+    y: ttY,
     label: hit.label,
     color: hit.color,
   }
@@ -498,18 +578,137 @@ const {
   denyingTaskId, denyFeedbackText,
   detailTaskId, detailTask,
   confirmDeleteTaskId,
-  sectionTaskMap, arrowDragTargetRect,
+  arrowDragTargetRect,
   restoredTaskIds,
   discardUncommittedAnnotations, removeTaskAnnotations, executeDeleteTask,
   acceptTask, submitDeny, submitNewTask,
   createRouteTask,
-  onSectionSubmit,
   onArrowDragMove, onArrowDragEnd,
   describeElement, onArrowCreated,
   submitPendingTask, cancelPendingTask,
   restoreAnnotationsFromTasks, resolveSelectTaskEids,
 } = taskWorkflows
 
+// ── Wireframe canvas (palette drop pipeline + Build) ──
+// Initialized after taskWorkflows because Build creates its task through
+// createRouteTask (route/viewport/color-scheme enrichment).
+const {
+  paletteDrag, wireframeDoc,
+  dropIndicator,
+  onPaletteDragOver, onPaletteDragLeave, onPaletteDrop,
+  wireframePlacements,
+  buildWireframeRoute, deletePlacement,
+} = useWireframeCanvas({ iframe, createRouteTask })
+
+// Keep the design-session journal stamped with the current iframe route so
+// entries recorded by the style-editor façade carry the route they happened on.
+const designSession = useDesignSession()
+watch(iframe.currentRoute, (r) => { designSession.sessionRoute.value = normalizeRoute(r) }, { immediate: true })
+
+// ── Wireframe mode (snapshot canvas over the live iframe) ──
+const wireframeMode = useWireframeMode({ iframe, interactionMode, shellView })
+
+// Place-first component flow: a drop/click mints the block immediately and the
+// snapshot fills in the background; the user configures it in place via the
+// inline popover. surfaceMfe stamps placed blocks so apply-time codegen imports
+// from the right package in a multi-MFE workspace.
+const workspace = useWorkspace()
+void workspace.load()
+const componentGenerator = useComponentGenerator({
+  iframe,
+  wireframe: wireframeMode,
+  surfaceMfe: () => workspace.currentMfe.value,
+})
+
+// Palette drops land on the canvas natively (no iframe shield in the way);
+// the drag item rides usePaletteDrag, not the DataTransfer.
+// Place-first goes through selection.select directly (not the canvas's select()
+// wrapper that focuses on click), so neither drop nor click focuses the canvas —
+// focus it after the block lands so Delete/Escape/arrow-nudge work right away.
+const wireframeCanvasRef = ref<InstanceType<typeof WireframeCanvas> | null>(null)
+function focusWireframeCanvasSoon() {
+  void nextTick(() => wireframeCanvasRef.value?.focusStage())
+}
+
+function onWireframePaletteDrop(at: { x: number; y: number }) {
+  const item = paletteDrag.draggingItem.value
+  paletteDrag.endDrag()
+  if (!item) return
+  if (item.kind === 'component' && item.componentName) {
+    // Place-first: the block lands now and configures in place on the canvas.
+    componentGenerator.placeComponent(item, at)
+    focusWireframeCanvasSoon()
+  } else {
+    void wireframeMode.dropPaletteItem(item, at)
+  }
+}
+
+// Palette CLICK path (wireframe mode only): place at a small cascade so repeated
+// clicks don't stack exactly on top of each other. Drag is the primary path.
+const clickCascade = ref(0)
+function onWireframeGenerateComponent(item: PaletteDragItem) {
+  if (!item.componentName) return
+  const vp = wireframeMode.canvas.value?.viewport
+  const baseX = vp ? Math.max(20, Math.round(vp.width / 2 - 160)) : 40
+  const step = clickCascade.value
+  clickCascade.value = (clickCascade.value + 1) % 6
+  componentGenerator.placeComponent(item, { x: baseX + step * 24, y: 80 + step * 24 })
+  focusWireframeCanvasSoon()
+}
+
+// "Implement this wireframe" mints the task through the existing apply loop,
+// then rides the same auto-run path as Apply now / Build. Any open generate
+// session is cancelled first — the sketch is about to lock, and a pending
+// ghost placement must not mutate it mid-implement.
+async function onImplementWireframe() {
+  componentGenerator.cancel()
+  const result = await wireframeMode.implementWireframe()
+  if (result?.taskId) onApplyRunAgent(result.taskId)
+}
+
+// Auto-mode runs silently: no modal hijack, no forced switch to the
+// Conversation tab. The dedicated driver claims queued ids and runs the
+// embedded agent headlessly; the task card surfaces status (in_progress)
+// and a live-activity dot. Users open the modal only if they want to
+// watch the work-stream.
+startAutoRunDriver()
+
+// Batch-run handler — surfaced by the Tasks panel header when agentMode
+// is auto or manual AND a provider is ready AND there's at least one
+// pending task. Enqueues every pending task; the watcher above opens the
+// most-recent one and the Conversation tab drains the queue on mount.
+const pendingTasksCount = computed(
+  () => routeTasks.value.filter((t) => t.status === 'pending' || t.status === 'denied').length,
+)
+const canBatchRunAgent = computed(
+  () =>
+    providerSettings.settings.value.embeddedAgentEnabled === true
+    && providerSettings.ready.value
+    && providerSettings.settings.value.agentMode !== 'off'
+    && pendingTasksCount.value > 0,
+)
+// "Apply now" minted a wireframe_apply task — run the embedded agent on it
+// when a provider is configured; otherwise it waits in Tasks for an external
+// agent (same contract as Build).
+function onApplyRunAgent(taskId: string) {
+  if (
+    providerSettings.settings.value.embeddedAgentEnabled === true
+    && providerSettings.ready.value
+    && providerSettings.settings.value.agentMode !== 'off'
+  ) {
+    agentMode.requestAutoRun(taskId)
+  }
+}
+
+function runPendingAgentBatch() {
+  if (!canBatchRunAgent.value) return
+  for (const t of routeTasks.value) {
+    if (t.status === 'pending' || t.status === 'denied') {
+      agentMode.requestAutoRun(t.id)
+    }
+  }
+}
+
 // ── Change history (undo / clear / commit-as-task) ──
 // Needs createRouteTask from taskWorkflows, so initialized after it.
 const { selectionChanges, doUndo, doClearChanges, commitChangesAsTask } = useChangeHistory({
@@ -522,8 +721,20 @@ const { selectionChanges, doUndo, doClearChanges, commitChangesAsTask } = useCha
   shellView,
   readLiveStyles,
   createRouteTask,
+  deletePlacement,
 })
 
+// Undo/redo dispatch: the wireframe canvas owns its own history while active
+// (no-op while building); everywhere else falls back to the design-session
+// style/class/placement undo. Redo only exists for the wireframe canvas today.
+function onUndo(): void {
+  if (wireframeMode.active.value) { wireframeMode.undo(); return }
+  void doUndo()
+}
+function onRedo(): void {
+  if (wireframeMode.active.value) { wireframeMode.redo(); return }
+}
+
 // ── Bridge event handlers (needs doUndo from useChangeHistory) ──
 const { setup: setupBridgeEvents } = useBridgeEventHandlers({
   iframe, iframeRef, annotations, interactionHistory, errorMonitor, networkMonitor,
@@ -535,7 +746,7 @@ const { setup: setupBridgeEvents } = useBridgeEventHandlers({
   describeElement, discardUncommittedAnnotations,
   restoreAnnotationsFromTasks, resolveSelectTaskEids,
   contextMenu, currentRoute,
-  doUndo, scheduleAutoScan,
+  doUndo: onUndo, scheduleAutoScan,
 })
 
 // ── Keyboard Shortcuts (composable handles mount/unmount) ──
@@ -551,7 +762,8 @@ useKeyboardShortcuts({
   selectionRects,
   groupRects,
   activePanel,
-  doUndo,
+  doUndo: onUndo,
+  doRedo: onRedo,
   cancelSnip,
   cancelPendingTask,
   layoutOverlayToggle: () => layoutOverlay.toggle(),
@@ -592,6 +804,8 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
       :develop-section="developSection"
       :current-route="currentRoute"
       :layout-overlay-active="layoutOverlay.showOverlay.value"
+      :wireframe-active="wireframeMode.active.value"
+      :wireframe-capturing="wireframeMode.capturing.value"
       :a11y-loading="a11yLoading"
       :a11y-violations-count="a11yViolations.length"
       :tab-order-enabled="tabOrder.enabled.value"
@@ -613,6 +827,7 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
       @switch-design-section="designSection = $event; activePanel = 'inspector'"
       @switch-develop-section="developSection = $event; activePanel = 'inspector'"
       @toggle-layout-overlay="layoutOverlay.toggle()"
+      @toggle-wireframe="wireframeMode.active.value ? wireframeMode.exit() : wireframeMode.enter()"
       @scan-a11y="activePanel = 'inspector'; scanA11y('page')"
       @toggle-tab-order="tabOrder.toggle()"
       @start-perf-recording="startPerfRecording"
@@ -624,7 +839,9 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
     />
 
     <!-- Banners -->
-    <AppBanners :show-warning="showWarning" :config-initialized="configInitialized" />
+    <AppBanners :show-warning="showWarning" :config-initialized="configInitialized"
+      :wireframe-error="(!wireframeMode.active.value && !wireframeMode.capturing.value) ? wireframeMode.error.value : null"
+      @dismiss-wireframe-error="wireframeMode.error.value = null" />
 
     <!-- Snipping overlay -->
     <SnippingOverlay v-if="snipActive" :snip-rect="snipRect"
@@ -639,6 +856,55 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
         @pointerup="shellView === 'editor' ? onCanvasPointerUp($event) : undefined">
         <iframe ref="iframeRef" :src="appUrl" class="app-iframe" :style="iframeStyle" />
 
+        <!-- Wireframe palette drop catcher. HTML5 drag events don't reach the
+             parent document while the cursor is over the iframe, so a
+             transparent shield over the iframe receives dragover/drop. It is
+             always present but pointer-events:none until a palette drag starts
+             (toggling a class avoids a mid-drag mount race; v-if would miss the
+             first dragover). dragover MUST preventDefault or drop never fires;
+             resolveElementAt still hit-tests through it. -->
+        <div class="palette-drop-shield" :class="{ active: !!paletteDrag.draggingItem.value && !wireframeMode.active.value }"
+          @dragenter.prevent
+          @dragover.prevent="onPaletteDragOver"
+          @drop.prevent="onPaletteDrop"
+          @dragleave="onPaletteDragLeave" />
+
+        <!-- Wireframe mode: an opaque sketch canvas OVER the live iframe. The
+             iframe stays mounted (bridge alive for component snapshots), so
+             exiting is lossless — remove the overlay, the app is still there. -->
+        <WireframeCanvas v-if="wireframeMode.active.value || wireframeMode.capturing.value"
+          ref="wireframeCanvasRef"
+          :canvas="wireframeMode.canvas.value"
+          :capturing="wireframeMode.capturing.value"
+          :progress="wireframeMode.progress.value"
+          :error="wireframeMode.error.value"
+          :image-src="wireframeMode.imageSrc"
+          :deleted-blocks="wireframeMode.deletedBlocks.value"
+          :building="wireframeMode.building.value"
+          :implementing="wireframeMode.implementing.value"
+          :selection="wireframeMode.selection"
+          :history="wireframeMode.history"
+          :generator="componentGenerator"
+          :generating-ids="wireframeMode.generatingIds.value"
+          @exit="wireframeMode.exit()"
+          @recapture="wireframeMode.recapture()"
+          @implement="onImplementWireframe"
+          @undo-implementation="wireframeMode.undoImplementation()"
+          @explode-block="wireframeMode.explodeBlock"
+          @update-rect="wireframeMode.updateBlockRect"
+          @bring-to-front="wireframeMode.bringToFront"
+          @send-to-back="wireframeMode.sendToBack"
+          @bring-forward="wireframeMode.bringForward"
+          @send-backward="wireframeMode.sendBackward"
+          @delete-block="wireframeMode.deleteBlock"
+          @undelete-block="wireframeMode.undeleteBlock"
+          @duplicate-block="wireframeMode.duplicateBlock"
+          @set-note="wireframeMode.setNote"
+          @set-md="wireframeMode.setBlockMd"
+          @set-data="wireframeMode.setBlockData"
+          @add-placeholder="wireframeMode.addPlaceholderBlock"
+          @palette-drop="onWireframePaletteDrop" />
+
         <!-- Hover + selection overlays (editor, design tokens/inspector) -->
         <template v-if="shellView === 'editor' ? showMarkup.inspector : (shellView === 'design' && designSection !== 'components')">
           <div v-if="hoverRect" class="highlight hover"
@@ -687,15 +953,31 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
               :data-impact="h.impact"
               :style="overlayStyle(h.rect)" />
           </template>
+
+          <!-- Live wireframe drop indicator (where a dragged palette item will land). -->
+          <div v-if="dropIndicator" class="drop-indicator" :class="dropIndicator.position"
+            :style="overlayStyle(dropIndicator)" />
         </div>
 
+        <!-- On-canvas legend: decode rect colors without looking at the sidebar.
+             Hovering an identity row focuses that source's rects; the Network
+             tab switches it to a latency-bucket key. -->
+        <OverlayLegend
+          v-if="dataHighlightActive && dataHighlights.sources.value.length"
+          :sources="dataHighlights.sources.value"
+          :focused-name="dataHighlights.focusedName.value"
+          :truncated="dataHighlights.truncated.value"
+          :shown="dataHighlights.rects.value.length"
+          :total="dataHighlights.totalResolved.value"
+          @focus="dataHighlights.setFocus($event)" />
+
         <!-- Tab/focus order overlay — numbered badges. Only rendered while
              the user has opted in via the panel toggle. -->
         <TabOrderOverlay v-if="a11yHighlightActive && tabOrder.enabled.value" :badges="tabOrder.badges.value" />
 
         <!-- Editor-only overlays -->
         <template v-if="shellView === 'editor'">
-          <div v-if="interactionMode === 'arrow' || interactionMode === 'draw'" class="drawing-shield" :class="interactionMode" />
+          <div v-if="interactionMode === 'arrow'" class="drawing-shield" :class="interactionMode" />
           <template v-if="interactionMode !== 'interact'">
             <div v-for="te in taskElementRects" :key="'te-' + te.taskId" class="highlight task-element"
               :style="{ left: te.rect.x + 'px', top: te.rect.y + 'px', width: te.rect.width + 'px', height: te.rect.height + 'px' }" />
@@ -719,17 +1001,6 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
               @drag-move="onArrowDragMove"
               @drag-end="onArrowDragEnd"
             />
-            <DrawnSectionOverlay v-if="showMarkup.sections"
-              :sections="annotations.routeSections.value"
-              :selectedId="annotations.selectedSectionId.value"
-              :drawingRect="drawingRect"
-              :sectionTaskMap="sectionTaskMap"
-              @select="annotations.selectedSectionId.value = $event"
-              @remove="annotations.removeDrawnSection"
-              @update-prompt="(id, prompt) => annotations.updateDrawnSection(id, { prompt })"
-              @update-rect="(id, rect) => annotations.updateDrawnSection(id, { x: rect.x, y: rect.y, width: rect.width, height: rect.height })"
-              @submit="onSectionSubmit"
-            />
             <TextHighlightOverlay v-if="showMarkup.highlights"
               :highlights="annotations.routeHighlights.value"
               :selectedId="annotations.selectedHighlightId.value"
@@ -744,7 +1015,7 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
       </div>
 
       <!-- Design panel (tokens/inspector sub-sections of the Design view) -->
-      <aside v-if="shellView === 'design' && designSection !== 'components' && activePanel !== 'tasks'" class="theme-panel">
+      <aside v-if="shellView === 'design' && (designSection === 'tokens' || designSection === 'inspector') && activePanel !== 'tasks'" class="theme-panel">
         <DesignPanel
           :section="designSection"
           :iframeRef="iframeRef"
@@ -804,6 +1075,9 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
         :include-rendered-html="includeRenderedHtml"
         :include-data-context="includeDataContext"
         :data-context-probe="dataContextProbe"
+        :can-batch-run="canBatchRunAgent"
+        :pending-count="pendingTasksCount"
+        @run-pending="runPendingAgentBatch"
         @update:showReportPanel="showReportPanel = $event"
         @update:newTaskText="newTaskText = $event"
         @update:denyFeedbackText="denyFeedbackText = $event"
@@ -823,7 +1097,7 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
         @remove-screenshot="removeScreenshot"
       />
 
-      <!-- Audit > Data: sources + API schemas + api_update task creation -->
+      <!-- Audit > Data: data-source + API-schema browser (read-only — creates no tasks) -->
       <DataSourcesPage v-else-if="shellView === 'develop' && developSection === 'data'"
         key="data-sources-data"
         variant="data"
@@ -831,19 +1105,19 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
         :currentRoute="currentRoute"
       />
 
-      <!-- Audit > Libraries: data-fetching and state libraries detected in package.json -->
-      <DataSourcesPage v-else-if="shellView === 'develop' && developSection === 'libraries'"
-        key="data-sources-libraries"
-        variant="libraries"
-        :highlightRects="dataHighlights.rects.value"
-        :currentRoute="currentRoute"
-      />
-
-      <!-- Design > Components: library components catalog -->
+      <!-- Design > Components: catalog browser + drag-to-place palette + preview -->
       <ComponentsPage v-else-if="shellView === 'design' && designSection === 'components'"
         :iframe="iframe"
         :highlightRects="dataHighlights.rects.value"
         :focusedName="dataHighlights.focusedName.value"
+        :placements="wireframePlacements"
+        :stale-ids="wireframeDoc.staleIds.value"
+        :failed-ids="wireframeDoc.failedIds.value"
+        :wireframe-active="wireframeMode.active.value"
+        @build="buildWireframeRoute"
+        @delete-placement="deletePlacement"
+        @run-agent="onApplyRunAgent"
+        @generate-component="onWireframeGenerateComponent"
       />
 
       <!-- Audit > A11y panel -->
@@ -897,6 +1171,8 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
         @close="showSettings = false"
         @update:showThemeEditor="showThemeEditor = $event"
       />
+
+      <InitWizard v-if="initFlow.open.value" />
     </div>
 
     <!-- Context menu -->
@@ -918,12 +1194,27 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
     <TaskDetailModal
       v-if="detailTask"
       :task="detailTask"
+      :initial-tab="'details'"
       @close="detailTaskId = null"
       @accept="(id) => { acceptTask(id); detailTaskId = null }"
       @deny="(id) => { denyingTaskId = id; denyFeedbackText = ''; detailTaskId = null }"
       @delete="(id) => { removeTaskAnnotations(id); restoredTaskIds.delete(id); taskSystem.deleteTask(id); detailTaskId = null }"
       @update="(id, fields) => { taskSystem.updateTaskStatus(id, detailTask!.status, undefined, fields) }"
-      @reply="(id, answers) => { taskSystem.respondToAgent(id, answers) }"
+      @reply="async (id, answers) => {
+        await taskSystem.respondToAgent(id, answers)
+        // Same auto-retry as deny: hand the now-in_progress task back to
+        // the auto-run driver so the agent picks up the user's answer
+        // without anyone clicking Run. Driver short-circuits if embedded
+        // mode is off or no provider is ready.
+        if (
+          providerSettings.settings.value.embeddedAgentEnabled === true
+          && providerSettings.settings.value.agentMode === 'auto'
+          && providerSettings.ready.value
+        ) {
+          agentMode.requestAutoRun(id)
+        }
+      }"
+      @open-settings="() => { showSettings = true }"
     />
 
     <ConfirmDialog
@@ -962,7 +1253,7 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
   /* Severity */
   --severity-critical: #ef4444; --severity-serious: #ef4444; --severity-moderate: #f59e0b; --severity-minor: #71717a;
   /* Modes */
-  --mode-interact: #6366f1; --mode-arrow: #ef4444; --mode-draw: #71717a; --mode-highlight: #f59e0b;
+  --mode-interact: #6366f1; --mode-arrow: #ef4444; --mode-highlight: #f59e0b;
   /* Layout viz */
   --layout-flex: #a855f7; --layout-grid: #22c55e;
   /* Roles */
@@ -990,7 +1281,7 @@ const navigateIframe = (route: string) => navigateIframeUtil(iframeRef, currentR
   --status-pending: #6b7280; --status-in-progress: #2563eb; --status-review: #d97706;
   --status-denied: #dc2626; --status-accepted: #16a34a; --status-needs-info: #9333ea; --status-blocked: #ea580c;
   --severity-critical: #dc2626; --severity-serious: #dc2626; --severity-moderate: #d97706; --severity-minor: #6b7280;
-  --mode-interact: #4f46e5; --mode-arrow: #dc2626; --mode-draw: #6b7280; --mode-highlight: #d97706;
+  --mode-interact: #4f46e5; --mode-arrow: #dc2626; --mode-highlight: #d97706;
   --layout-flex: #9333ea; --layout-grid: #16a34a;
   --role-container: #16a34a; --role-content: #2563eb; --role-component: #9333ea;
   --syntax-property: #0369a1; --syntax-string: #15803d; --syntax-number: #b45309;
@@ -1048,4 +1339,14 @@ html, body, #app { height: 100%; overflow: hidden; background: var(--bg); color:
   text-overflow: ellipsis;
   color: var(--tt-color, var(--text));
 }
+
+/* Native <option> elements don't inherit Vue scoped styles. Browsers render
+   the dropdown list in OS chrome, which on dark themes ends up white-on-
+   white-ish (Chrome especially). Force theme-aware bg/text globally so any
+   <select> in the shell reads correctly without each component having to
+   repeat the rule. */
+option {
+  background: var(--surface);
+  color: var(--text);
+}
 </style>
diff --git a/src/shell/components/AgentDirectionsPanel.vue b/src/shell/components/AgentDirectionsPanel.vue
new file mode 100644
index 0000000..99c910d
--- /dev/null
+++ b/src/shell/components/AgentDirectionsPanel.vue
@@ -0,0 +1,670 @@
+<template>
+  <div class="adp">
+    <!-- Left: persona list -->
+    <ul class="adp-list" role="listbox" aria-label="Agents">
+      <li
+        v-for="p in allPersonas"
+        :key="p.id"
+        role="option"
+        :aria-selected="selectedId === p.id"
+        class="adp-item"
+        :class="{ selected: selectedId === p.id, custom: p.isCustom }"
+        @click="select(p.id)"
+      >
+        <span class="adp-item-name">{{ p.name }}</span>
+        <span v-if="p.isCustom" class="adp-item-badge">custom</span>
+        <p class="adp-item-desc">{{ p.description }}</p>
+        <div class="adp-item-runtime">
+          <span class="adp-item-runtime-provider">{{ providerLabel(p.id) }}</span>
+          <span v-if="modelFor(p.id)" class="adp-item-runtime-model">{{ modelFor(p.id) }}</span>
+          <span class="adp-item-runtime-effort">{{ effortFor(p.id) }}</span>
+        </div>
+        <div class="adp-item-types">
+          <span v-for="t in p.taskTypes" :key="t" class="adp-chip">{{ t }}</span>
+        </div>
+      </li>
+    </ul>
+
+    <!-- Right: content -->
+    <div v-if="selected" class="adp-content">
+      <div class="adp-content-header">
+        <div class="adp-content-meta">
+          <h3 class="adp-content-title">{{ selected.name }}</h3>
+          <p class="adp-content-desc">{{ selected.description }}</p>
+        </div>
+        <div class="adp-toggle" role="group" aria-label="View mode">
+          <button :class="['adp-mode', { active: mode === 'preview' }]" @click="mode = 'preview'">
+            Preview
+          </button>
+          <button :class="['adp-mode', { active: mode === 'edit' }]" @click="mode = 'edit'">
+            Edit
+          </button>
+        </div>
+      </div>
+
+      <!-- Per-agent runtime config: provider, model, effort. Auto-saves on change. -->
+
+      <!-- Blocked-state warning. Hoisted above the row so users see WHY
+           the picker is degraded (or replaced with a text input) before
+           they try to interact with it. Same diagnosis as the wizard's
+           AgentQuickSetup banner, kept in sync deliberately. -->
+      <div
+        v-if="modelsBlocked"
+        class="adp-runtime-warning"
+        role="alert"
+        data-testid="adp-engine-model-blocked"
+      >
+        <strong>Cannot fetch models.</strong>
+        {{ modelCatalog.error || 'The live probe returned nothing.' }}
+        Defaulting to Auto — enter a custom id in the Model field if you'd rather override.
+      </div>
+
+      <div class="adp-runtime">
+        <label class="adp-field">
+          <span class="adp-field-label">Provider</span>
+          <select
+            class="adp-select"
+            :value="effectiveProvider"
+            :disabled="runtimeSaving"
+            @change="onProviderChange(($event.target as HTMLSelectElement).value)"
+          >
+            <option v-for="p in CLI_PROVIDER_OPTIONS" :key="p.id" :value="p.id">{{ p.label }}</option>
+          </select>
+        </label>
+        <label class="adp-field">
+          <span class="adp-field-label">Model</span>
+          <!-- When the catalog has a real list (or a static catalog), pick
+               from it. When it doesn't — Copilot CLI is the canonical case;
+               its `/model` picker is interactive only — fall back to a
+               plain text input. Empty = Auto (CLI default). -->
+          <select
+            v-if="!modelsBlocked"
+            class="adp-select"
+            :value="effectiveModel"
+            :disabled="runtimeSaving || modelsLoading"
+            data-testid="adp-engine-model"
+            @change="onModelChange(($event.target as HTMLSelectElement).value)"
+          >
+            <option v-for="m in modelOptions" :key="m.id" :value="m.id">{{ m.label }}</option>
+            <!-- Persist a previously-saved model id that isn't in the
+                 discovered list so we don't silently lose the user's choice. -->
+            <option v-if="effectiveModel && !modelOptions.some(m => m.id === effectiveModel)" :value="effectiveModel">
+              {{ effectiveModel }} (custom)
+            </option>
+          </select>
+          <!-- Visually clear the field when blocked so the user sees the
+               default (Auto) instead of whatever stale id the persona had
+               for a different provider. They can still type a custom id to
+               override, which persists via the same onModelChange path. -->
+          <input
+            v-else
+            type="text"
+            class="adp-input"
+            :value="modelsBlocked ? '' : effectiveModel"
+            :disabled="runtimeSaving"
+            placeholder="Auto (CLI default)"
+            data-testid="adp-engine-model-manual"
+            @change="onModelChange(($event.target as HTMLInputElement).value.trim())"
+          />
+        </label>
+        <label class="adp-field">
+          <span class="adp-field-label">Effort</span>
+          <select
+            class="adp-select"
+            :value="effectiveEffort"
+            :disabled="runtimeSaving"
+            @change="onEffortChange(($event.target as HTMLSelectElement).value)"
+          >
+            <option v-for="e in effortOptionsForProvider" :key="e" :value="e">{{ e }}</option>
+          </select>
+        </label>
+      </div>
+
+      <!-- Preview -->
+      <div
+        v-if="mode === 'preview'"
+        class="adp-preview markdown-body"
+        v-html="renderedContent || emptyHint"
+      />
+
+      <!-- Edit -->
+      <template v-else>
+        <MarkdownEditor
+          v-model="draftContent"
+          :placeholder="`Project-specific context for the ${selected.name} agent.\n\nWritten in markdown. Appended to the base prompt before applying any ${selected.taskTypes.join(', ')} task.`"
+          :aria-label="`Project directions for ${selected.name}`"
+          class="adp-editor"
+        />
+        <div class="adp-save-row">
+          <span v-if="saveStatus === 'saved'" class="adp-save-ok">✓ Saved</span>
+          <button class="adp-save-btn" :disabled="saving" @click="save">
+            {{ saving ? 'Saving…' : 'Save' }}
+          </button>
+        </div>
+      </template>
+    </div>
+
+    <div v-else class="adp-empty">
+      <p>Select an agent on the left to view and edit its directions.</p>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, watch } from 'vue'
+import MarkdownEditor from './MarkdownEditor.vue'
+import { safeMd } from '../utils/safeMd'
+import { useAgentConfigs } from '../composables/useAgentConfigs'
+import { useProviderSettings } from '../composables/useProviderSettings'
+import { useAgentModels } from '../composables/useAgentModels'
+import { BUILT_IN_PERSONAS } from '../../embedded/persona'
+import type { PersonaConfig } from '../../embedded/persona'
+import {
+  EFFORT_LEVELS,
+  EFFORTS_BY_PROVIDER,
+  type ProviderId,
+  type EffortLevel,
+} from '../../embedded/provider-config'
+
+// Per the product decision: agent settings panel only exposes the four
+// CLI-style providers for now. Direct-API providers will be folded in when
+// the apply path supports them.
+const CLI_PROVIDER_OPTIONS: Array<{ id: ProviderId; label: string }> = [
+  { id: 'claude-local',   label: 'Claude (local CLI)' },
+  { id: 'codex-local',    label: 'Codex (local CLI)' },
+  { id: 'opencode-local', label: 'OpenCode (local CLI)' },
+  { id: 'copilot-local',  label: 'Copilot (local CLI)' },
+]
+const emptyHint = '<p class="adp-empty-hint">No directions written yet. Switch to Edit to add some.</p>'
+
+const agentConfigs = useAgentConfigs()
+const settings = useProviderSettings()
+
+// Merge built-ins (with server directions) + custom personas
+const allPersonas = computed<PersonaConfig[]>(() => settings.personas.value)
+
+const selectedId = ref<string | null>(BUILT_IN_PERSONAS[0]?.id ?? null)
+const mode = ref<'preview' | 'edit'>('preview')
+const draftContent = ref('')
+const saving = ref(false)
+const saveStatus = ref<'idle' | 'saved'>('idle')
+let saveStatusTimer: ReturnType<typeof setTimeout> | null = null
+
+const selected = computed(() => allPersonas.value.find(p => p.id === selectedId.value) ?? null)
+
+// The canonical content for the selected persona
+const currentContent = computed(() => {
+  if (!selected.value) return ''
+  if (!selected.value.isCustom) {
+    return agentConfigs.configs.value[selected.value.id]?.projectDirections ?? ''
+  }
+  return selected.value.systemPromptExtras ?? ''
+})
+
+// Sync draft whenever selection or server data changes (but don't clobber in-flight edits)
+watch([selected, currentContent], ([, content]) => {
+  draftContent.value = content
+  mode.value = 'preview'
+  saveStatus.value = 'idle'
+}, { immediate: true })
+
+const renderedContent = computed(() => {
+  const md = draftContent.value.trim()
+  if (!md) return ''
+  try { return safeMd(md) } catch { return safeMd(md) }
+})
+
+function providerLabel(personaId: string): string {
+  const persona = allPersonas.value.find(p => p.id === personaId)
+  if (!persona) return ''
+  const providerId = persona.isCustom
+    ? persona.providerId
+    : (agentConfigs.configs.value[personaId]?.providerId ?? persona.providerId)
+  return CLI_PROVIDER_OPTIONS.find(p => p.id === providerId)?.label ?? providerId
+}
+function modelFor(personaId: string): string {
+  const persona = allPersonas.value.find(p => p.id === personaId)
+  if (!persona) return ''
+  if (persona.isCustom) return persona.model
+  const override = agentConfigs.configs.value[personaId]?.model
+  return typeof override === 'string' ? override : persona.model
+}
+function effortFor(personaId: string): EffortLevel {
+  const persona = allPersonas.value.find(p => p.id === personaId)
+  if (!persona) return 'auto'
+  if (persona.isCustom) return persona.effort
+  return agentConfigs.configs.value[personaId]?.effort ?? persona.effort
+}
+
+function select(id: string) {
+  if (selectedId.value === id) return
+  selectedId.value = id
+}
+
+async function save() {
+  if (!selected.value) return
+  saving.value = true
+  if (!selected.value.isCustom) {
+    await agentConfigs.save(selected.value.id, { projectDirections: draftContent.value })
+  } else {
+    settings.upsertPersona({ ...selected.value, systemPromptExtras: draftContent.value })
+  }
+  saving.value = false
+  saveStatus.value = 'saved'
+  mode.value = 'preview'
+  if (saveStatusTimer) clearTimeout(saveStatusTimer)
+  saveStatusTimer = setTimeout(() => { saveStatus.value = 'idle' }, 3000)
+}
+
+// ── Per-agent runtime config (provider / model / effort) ────────────────────
+// For built-in personas: persisted to .annotask/agents.json via the API.
+// For custom personas: persisted to localStorage via upsertPersona.
+
+const runtimeSaving = ref(false)
+
+const effectiveProvider = computed<ProviderId>(() => {
+  if (!selected.value) return 'claude-local'
+  if (selected.value.isCustom) return selected.value.providerId
+  const override = agentConfigs.configs.value[selected.value.id]?.providerId
+  return override ?? selected.value.providerId
+})
+
+const effectiveModel = computed<string>(() => {
+  if (!selected.value) return ''
+  if (selected.value.isCustom) return selected.value.model
+  const override = agentConfigs.configs.value[selected.value.id]?.model
+  return typeof override === 'string' ? override : selected.value.model
+})
+
+const effectiveEffort = computed<EffortLevel>(() => {
+  if (!selected.value) return 'auto'
+  if (selected.value.isCustom) return selected.value.effort
+  const override = agentConfigs.configs.value[selected.value.id]?.effort
+  return override ?? selected.value.effort
+})
+
+// Provider-driven dropdown options. Effort filters to the provider's
+// supported set so users can't pick one the provider drops.
+const effortOptionsForProvider = computed<readonly EffortLevel[]>(() =>
+  EFFORTS_BY_PROVIDER[effectiveProvider.value] ?? EFFORT_LEVELS,
+)
+
+// Models: sourced from the singleton useAgentModels cache so the picker
+// stays in sync with Settings → Providers and the InitWizard. The composable
+// dedupes fetches and persists to localStorage. There is no curated fallback —
+// when the live probe returns nothing the dropdown is blocked and a warning
+// directs the user back to Settings → Providers to enter a model id manually.
+const agentModels = useAgentModels()
+const modelCatalog = computed(() => agentModels.catalogFor(effectiveProvider.value).value)
+const modelOptions = computed(() => modelCatalog.value.models)
+const modelsLoading = computed(() => agentModels.state.loading[effectiveProvider.value] === true)
+const modelsBlocked = computed(
+  () => !modelsLoading.value && modelOptions.value.length <= 1 && !modelCatalog.value.discovered,
+)
+
+// Kick off a fetch whenever the effective provider changes (initial mount
+// included via immediate).
+watch(effectiveProvider, (id) => { void agentModels.ensure(id) }, { immediate: true })
+
+// When the picker enters the "Cannot fetch models" state and the persona
+// has a stale model id saved, reset it to Auto (empty) so the input starts
+// clean instead of pre-filling a value the live probe couldn't confirm.
+watch(modelsBlocked, (blocked) => {
+  if (!blocked) return
+  if (!selected.value) return
+  if (!effectiveModel.value) return
+  void persistRuntime({ model: '' })
+})
+
+async function persistRuntime(patch: { providerId?: ProviderId; model?: string; effort?: EffortLevel }) {
+  if (!selected.value) return
+  runtimeSaving.value = true
+  if (selected.value.isCustom) {
+    settings.upsertPersona({ ...selected.value, ...patch })
+  } else {
+    await agentConfigs.save(selected.value.id, patch)
+  }
+  runtimeSaving.value = false
+  saveStatus.value = 'saved'
+  if (saveStatusTimer) clearTimeout(saveStatusTimer)
+  saveStatusTimer = setTimeout(() => { saveStatus.value = 'idle' }, 2000)
+}
+
+function onProviderChange(value: string) {
+  if (!CLI_PROVIDER_OPTIONS.some(p => p.id === value)) return
+  const nextProvider = value as ProviderId
+  // If the current effort isn't in the new provider's supported set, snap
+  // to its first option (usually 'auto') so the select doesn't sit on a
+  // value the dropdown can't render.
+  const supportedEfforts = EFFORTS_BY_PROVIDER[nextProvider] ?? EFFORT_LEVELS
+  const patch: { providerId: ProviderId; effort?: EffortLevel } = { providerId: nextProvider }
+  if (!supportedEfforts.includes(effectiveEffort.value)) {
+    patch.effort = supportedEfforts[0] ?? 'auto'
+  }
+  void persistRuntime(patch)
+}
+
+function onModelChange(value: string) {
+  void persistRuntime({ model: value })
+}
+
+function onEffortChange(value: string) {
+  if (!(EFFORT_LEVELS as readonly string[]).includes(value)) return
+  void persistRuntime({ effort: value as EffortLevel })
+}
+
+</script>
+
+<style scoped>
+.adp {
+  display: flex;
+  height: 100%;
+  min-height: 0;
+  overflow: hidden;
+}
+
+/* ── Left list ── */
+.adp-list {
+  width: 220px;
+  flex-shrink: 0;
+  border-right: 1px solid var(--border);
+  overflow-y: auto;
+  list-style: none;
+  margin: 0;
+  padding: 6px;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.adp-item {
+  border-radius: 6px;
+  padding: 10px 12px;
+  cursor: pointer;
+  border: 1px solid transparent;
+  transition: background 100ms, border-color 100ms;
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+.adp-item:hover { background: var(--surface-2); }
+.adp-item.selected {
+  background: color-mix(in srgb, var(--accent) 10%, transparent);
+  border-color: color-mix(in srgb, var(--accent) 35%, transparent);
+}
+.adp-item.custom { border-color: color-mix(in srgb, var(--accent) 25%, var(--border)); }
+
+.adp-item-name {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text);
+}
+
+.adp-item-badge {
+  font-size: 10px;
+  font-weight: 600;
+  padding: 1px 6px;
+  border-radius: 3px;
+  background: color-mix(in srgb, var(--accent) 15%, transparent);
+  border: 1px solid var(--accent);
+  color: var(--accent);
+  align-self: flex-start;
+}
+
+.adp-item-desc {
+  font-size: 11px;
+  color: var(--text-muted);
+  margin: 0;
+  line-height: 1.4;
+  overflow: hidden;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+
+.adp-item-runtime {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  margin-top: 4px;
+  font-size: 10px;
+  color: var(--text-muted);
+}
+.adp-item-runtime > span {
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 100%;
+}
+.adp-item-runtime-provider {
+  color: var(--text);
+  font-weight: 500;
+}
+.adp-item-runtime-effort {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  font-weight: 600;
+}
+
+.adp-item-types {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 3px;
+  margin-top: 2px;
+}
+
+.adp-chip {
+  font-size: 10px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  color: var(--text-muted);
+  white-space: nowrap;
+}
+.adp-item.selected .adp-chip {
+  background: color-mix(in srgb, var(--accent) 8%, transparent);
+  border-color: color-mix(in srgb, var(--accent) 30%, transparent);
+  color: var(--accent);
+}
+
+/* ── Right content ── */
+.adp-content {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.adp-content-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+.adp-content-meta { flex: 1; min-width: 0; }
+
+.adp-content-title {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text);
+  margin: 0 0 3px;
+}
+
+.adp-content-desc {
+  font-size: 12px;
+  color: var(--text-muted);
+  margin: 0;
+  line-height: 1.4;
+}
+
+.adp-toggle {
+  display: inline-flex;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 2px;
+  gap: 2px;
+  flex-shrink: 0;
+}
+
+.adp-mode {
+  font: inherit;
+  font-size: 11px;
+  font-weight: 500;
+  padding: 4px 10px;
+  border: none;
+  background: transparent;
+  color: var(--text-muted);
+  border-radius: 4px;
+  cursor: pointer;
+  transition: background 100ms, color 100ms;
+}
+.adp-mode:hover { color: var(--text); }
+.adp-mode.active {
+  background: var(--surface);
+  color: var(--text);
+  box-shadow: 0 1px 3px var(--shadow);
+}
+
+.adp-runtime {
+  flex-shrink: 0;
+  display: flex;
+  gap: 10px;
+  padding: 10px 16px;
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+  align-items: flex-end;
+}
+.adp-runtime-warning {
+  flex-shrink: 0;
+  margin: 10px 16px 0;
+  padding: 8px 12px;
+  border-radius: 6px;
+  background: color-mix(in srgb, var(--warning) 12%, var(--surface-2));
+  border: 1px solid color-mix(in srgb, var(--warning) 45%, var(--border));
+  color: var(--text);
+  font-size: 12px;
+  line-height: 1.45;
+}
+.adp-runtime-warning strong { color: var(--warning); }
+.adp-field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  flex: 1;
+  min-width: 0;
+}
+.adp-field-label {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+.adp-field-warning {
+  font-size: 11px;
+  line-height: 1.4;
+  color: var(--warning);
+}
+.adp-select,
+.adp-input {
+  font: inherit;
+  font-size: 12px;
+  padding: 5px 8px;
+  border: 1px solid var(--border);
+  background: var(--surface-2);
+  color: var(--text);
+  border-radius: 4px;
+  min-width: 0;
+  width: 100%;
+}
+.adp-select:focus,
+.adp-input:focus {
+  outline: none;
+  border-color: var(--accent);
+}
+.adp-select:disabled,
+.adp-input:disabled {
+  opacity: 0.6;
+}
+
+.adp-preview {
+  flex: 1;
+  overflow-y: auto;
+  padding: 16px 20px;
+  font-size: 13px;
+  line-height: 1.65;
+  color: var(--text);
+}
+.adp-preview :deep(h1),
+.adp-preview :deep(h2),
+.adp-preview :deep(h3) { font-weight: 600; margin: 1em 0 0.4em; color: var(--text); }
+.adp-preview :deep(h2) { font-size: 13px; padding-bottom: 4px; border-bottom: 1px solid var(--border); }
+.adp-preview :deep(p) { margin: 0 0 0.75em; }
+.adp-preview :deep(ul), .adp-preview :deep(ol) { margin: 0 0 0.75em; padding-left: 20px; }
+.adp-preview :deep(li) { margin-bottom: 2px; }
+.adp-preview :deep(code) { background: var(--surface-2); padding: 1px 5px; border-radius: 3px; font-size: 12px; }
+.adp-preview :deep(pre) { background: var(--surface-2); padding: 10px 12px; border-radius: 6px; overflow-x: auto; }
+.adp-preview :deep(pre code) { background: none; padding: 0; }
+.adp-preview :deep(strong) { font-weight: 600; }
+.adp-preview :deep(.adp-empty-hint) { color: var(--text-muted); font-style: italic; }
+
+.adp-editor {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+}
+
+.adp-save-row {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 10px;
+  padding: 10px 16px;
+  border-top: 1px solid var(--border);
+  background: var(--surface-2);
+  flex-shrink: 0;
+}
+
+.adp-save-ok {
+  font-size: 12px;
+  color: var(--success);
+  font-weight: 500;
+}
+
+.adp-save-btn {
+  font: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  padding: 6px 16px;
+  border-radius: 5px;
+  background: var(--accent);
+  color: var(--text-on-accent);
+  border: 1px solid var(--accent);
+  cursor: pointer;
+  transition: background 120ms;
+}
+.adp-save-btn:hover:not(:disabled) { background: var(--accent-hover); }
+.adp-save-btn:disabled { opacity: 0.6; cursor: default; }
+
+.adp-empty {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 13px;
+  color: var(--text-muted);
+  padding: 24px;
+  text-align: center;
+}
+</style>
diff --git a/src/shell/components/AgentModePanel.vue b/src/shell/components/AgentModePanel.vue
new file mode 100644
index 0000000..65b643b
--- /dev/null
+++ b/src/shell/components/AgentModePanel.vue
@@ -0,0 +1,117 @@
+<script setup lang="ts">
+/**
+ * Agent-mode panel — extracted from ProviderSettingsPanel to live on the
+ * General settings tab. Three-state global toggle controlling how
+ * aggressively the in-shell agent fires:
+ *   - `auto`   — every new task auto-opens its Conversation tab and runs
+ *   - `manual` — Conversation tab available; agent runs on user click
+ *   - `off`    — no in-shell chat surface; drive via terminal/MCP
+ */
+import { computed } from 'vue'
+import { useProviderSettings } from '../composables/useProviderSettings'
+import { useAgentDetect } from '../composables/useTaskThread'
+import { AGENT_MODES, isActiveProviderReady, type AgentMode, type LocalCliReadiness } from '../../embedded/provider-config'
+
+const store = useProviderSettings()
+const settings = store.settings
+const detect = useAgentDetect()
+
+const localReadiness = computed<LocalCliReadiness>(() => {
+  const snap = detect.snapshot.value
+  if (!snap) return {}
+  return {
+    'claude-local': snap['claude-local']?.found === true && snap['claude-local']?.loggedIn === true,
+    'codex-local': snap['codex-local']?.found === true && snap['codex-local']?.loggedIn === true,
+    'opencode-local': snap['opencode-local']?.found === true && snap['opencode-local']?.loggedIn === true,
+    'copilot-local': snap['copilot-local']?.found === true && snap['copilot-local']?.loggedIn === true,
+  }
+})
+const activeReady = computed(() => isActiveProviderReady(settings.value, localReadiness.value))
+
+const AGENT_MODE_DESCRIPTIONS: Record<AgentMode, string> = {
+  auto: 'Tasks auto-run on create. The agent opens the Conversation tab and starts immediately.',
+  manual: 'Conversation tab is available, but the agent only runs when you click Run-with-agent on a task.',
+  off: 'No in-shell chat surface. Drive agents from the terminal via MCP, the annotask CLI, or the /annotask-apply skill.',
+}
+
+function setAgentMode(mode: AgentMode) {
+  store.setAgentMode(mode)
+}
+</script>
+
+<template>
+  <div class="agent-mode-panel">
+    <p class="agent-mode-desc">
+      Controls how aggressive the in-shell agent is when you create a task.
+    </p>
+    <div class="agent-mode-strip" role="radiogroup" aria-label="Agent mode">
+      <button
+        v-for="mode in AGENT_MODES"
+        :key="mode"
+        type="button"
+        role="radio"
+        :aria-checked="settings.agentMode === mode"
+        :class="['agent-mode-btn', { active: settings.agentMode === mode }]"
+        :data-testid="`agent-mode-${mode}`"
+        :disabled="mode !== 'off' && !activeReady"
+        @click="setAgentMode(mode)"
+      >
+        {{ mode }}
+      </button>
+    </div>
+    <p class="agent-mode-hint">{{ AGENT_MODE_DESCRIPTIONS[settings.agentMode] }}</p>
+    <p v-if="!activeReady && settings.agentMode !== 'off'" class="agent-mode-hint tone-warning">
+      Configure a CLI provider in LLM Providers to use auto or manual mode.
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.agent-mode-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.agent-mode-desc {
+  margin: 0 0 4px;
+  font-size: 12px;
+  color: var(--text-muted);
+  line-height: 1.5;
+}
+.agent-mode-strip {
+  display: inline-flex;
+  gap: 2px;
+  padding: 3px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 7px;
+  align-self: flex-start;
+}
+.agent-mode-btn {
+  font: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  padding: 5px 14px;
+  border: none;
+  background: transparent;
+  color: var(--text-muted);
+  border-radius: 5px;
+  cursor: pointer;
+  text-transform: lowercase;
+}
+.agent-mode-btn:hover:not(.active):not(:disabled) { color: var(--text); }
+.agent-mode-btn:disabled { opacity: 0.45; cursor: not-allowed; }
+.agent-mode-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+.agent-mode-btn.active {
+  background: var(--surface);
+  color: var(--text);
+  box-shadow: 0 1px 3px var(--shadow);
+}
+.agent-mode-hint {
+  margin: 0;
+  font-size: 11.5px;
+  color: var(--text-muted);
+  line-height: 1.45;
+}
+.agent-mode-hint.tone-warning { color: var(--warning); }
+</style>
diff --git a/src/shell/components/AgentQuickSetup.vue b/src/shell/components/AgentQuickSetup.vue
new file mode 100644
index 0000000..84d5aaf
--- /dev/null
+++ b/src/shell/components/AgentQuickSetup.vue
@@ -0,0 +1,479 @@
+<template>
+  <div class="aqs">
+    <div class="aqs-row">
+      <label class="aqs-field">
+        <span>Agent</span>
+        <select :value="activeProvider" @change="onProviderChange(($event.target as HTMLSelectElement).value)">
+          <option v-for="p in primaryProviders" :key="p.id" :value="p.id">{{ p.label }}</option>
+        </select>
+      </label>
+
+      <label class="aqs-field">
+        <span>Model</span>
+        <!-- When the live probe returns a real list (or a static catalog
+             exists), show the dropdown. When it doesn't — Copilot CLI is
+             the canonical case; the CLI's `/model` picker is interactive
+             only — drop to a plain text input so the user can type any id
+             their account supports. Empty = Auto (CLI default). -->
+        <select
+          v-if="!modelsBlocked"
+          :value="currentModel"
+          :disabled="modelsLoading"
+          data-testid="aqs-engine-model"
+          @change="onModelChange(($event.target as HTMLSelectElement).value)"
+        >
+          <option v-for="m in models" :key="m.id" :value="m.id">{{ m.label }}</option>
+          <option v-if="currentModel && !models.some(m => m.id === currentModel)" :value="currentModel">
+            {{ currentModel }} (custom)
+          </option>
+        </select>
+        <input
+          v-else
+          type="text"
+          :value="currentModel"
+          placeholder="Auto (CLI default)"
+          data-testid="aqs-engine-model-manual"
+          @change="onModelChange(($event.target as HTMLInputElement).value.trim())"
+        />
+        <span
+          v-if="modelsBlocked"
+          class="aqs-field-warning"
+          role="alert"
+          data-testid="aqs-engine-model-blocked"
+        >
+          <strong>Cannot fetch models.</strong>
+          {{ modelCatalog.error || 'The live probe returned nothing.' }}
+          Defaulting to Auto — type a custom id above to override.
+        </span>
+      </label>
+
+      <label class="aqs-field">
+        <span>Effort</span>
+        <select :value="currentEffort" @change="onEffortChange(($event.target as HTMLSelectElement).value)">
+          <option v-for="e in effortOptions" :key="e" :value="e">{{ e }}</option>
+        </select>
+      </label>
+    </div>
+
+    <div class="aqs-row aqs-mode-row">
+      <span class="aqs-field-label">Mode</span>
+      <div class="aqs-mode-group" role="radiogroup" aria-label="Agent mode">
+        <button
+          v-for="m in modeOptions"
+          :key="m.id"
+          type="button"
+          role="radio"
+          :aria-checked="agentMode === m.id"
+          :class="['aqs-mode-btn', { active: agentMode === m.id }]"
+          @click="setAgentMode(m.id)">
+          {{ m.label }}
+        </button>
+      </div>
+      <span class="aqs-mode-hint">{{ modeHints[agentMode] }}</span>
+    </div>
+
+    <div v-if="!hidePermissionMode" class="aqs-row aqs-mode-row">
+      <span class="aqs-field-label">Permissions</span>
+      <div class="aqs-mode-group" role="radiogroup" aria-label="Permission mode">
+        <button
+          v-for="m in visiblePermissionModes"
+          :key="m.id"
+          type="button"
+          role="radio"
+          :aria-checked="permissionMode === m.id"
+          :class="['aqs-mode-btn', { active: permissionMode === m.id }]"
+          @click="setPermissionMode(m.id)">
+          {{ m.label }}
+        </button>
+      </div>
+      <span class="aqs-mode-hint">{{ permissionModeHints[permissionMode] }}</span>
+    </div>
+
+    <!-- Wizard context: the permission picker is hidden because init's
+         permission mode is forced server-side (`init.ts` spawnCliWithSkill +
+         initPermissionModeFor) to the least-permissive headless mode that
+         can still write inside `.annotask/` — which varies per CLI. Show the
+         exact flags so the user can audit what's actually being run. The
+         Review & Save step still has a picker for per-task agents. -->
+    <p v-if="hidePermissionMode && initFlagsForActive" class="aqs-init-note">
+      The initial scan runs with <code>{{ initFlagsForActive.flags }}</code>
+      — {{ initFlagsForActive.rationale }} It writes inside
+      <code>.annotask/</code> only. Per-task agent permissions are set on
+      the Review &amp; Save step.
+    </p>
+
+    <p :class="['aqs-status', readiness.tone]" v-if="readiness.message">
+      <span class="aqs-status-dot" aria-hidden="true" />
+      {{ readiness.message }}
+    </p>
+
+    <details class="aqs-advanced">
+      <summary>Advanced settings</summary>
+      <p class="aqs-advanced-lead">
+        API keys for HTTP providers, reasoning effort, redaction toggles, and
+        extra CLI args live here. The defaults above cover most setups.
+      </p>
+      <ProviderSettingsPanel />
+    </details>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, onMounted, watch } from 'vue'
+import ProviderSettingsPanel from './ProviderSettingsPanel.vue'
+import { useProviderSettings } from '../composables/useProviderSettings'
+import { useAgentDetect, fetchAgentDetect } from '../composables/useTaskThread'
+import { useAgentModels } from '../composables/useAgentModels'
+import {
+  EFFORTS_BY_PROVIDER,
+  EFFORT_LEVELS,
+  type AgentMode,
+  type EffortLevel,
+  type ProviderConfig,
+  type ProviderId,
+} from '../../embedded/provider-config'
+import { type PermissionMode } from '../../schema'
+import { initPermissionFlagsFor, type InitCliBin } from '../../embedded/permission-mode-flags'
+
+const props = defineProps<{
+  /**
+   * Hide the "Plan" permission option. Plan is a plan-then-execute mode
+   * that only makes sense on tasks. Kept around for callers that still want
+   * the picker visible with Default + Bypass only.
+   */
+  hidePlanMode?: boolean
+  /**
+   * Hide the entire permission-mode picker. Used by the init wizard, where
+   * init's permission mode is decided server-side per-CLI (see
+   * `initPermissionModeFor` in permission-mode-flags.ts). Headless `--print`
+   * mode can't answer permission prompts, so each CLI gets the least-
+   * permissive mode that still allows writes inside `.annotask/`. The
+   * Review & Save step exposes a separate picker that sets the global
+   * default for per-task agents that run after init.
+   */
+  hidePermissionMode?: boolean
+}>()
+
+/**
+ * Per-CLI rationale shown alongside the actual flags in the wizard's init
+ * note. Read alongside `initPermissionModeFor` — these mirror its
+ * per-CLI reasoning in user-facing prose.
+ */
+const INIT_RATIONALE: Record<InitCliBin, string> = {
+  claude:   "Claude's headless --print mode has no workspace-write equivalent, so bypass is the only mode that lets the agent run grep/Bash and write the design spec.",
+  codex:    'this puts Codex in an OS-enforced workspace-write sandbox — strictly less permissive than full bypass.',
+  opencode: "OpenCode's headless run only exposes this single boolean — there's no native less-permissive mode that allows writes.",
+  copilot:  "Copilot's -p headless mode requires --allow-all-tools to run at all; this skips the broader --allow-all that bypass would add.",
+}
+
+const PROVIDER_BIN: Record<string, InitCliBin> = {
+  'claude-local':   'claude',
+  'codex-local':    'codex',
+  'opencode-local': 'opencode',
+  'copilot-local':  'copilot',
+}
+
+// Primary providers — the visible CLI surface. Anthropic / OpenAI /
+// OpenRouter / Compatible / Paperclip stay reachable via Advanced below.
+// Copilot is wired to the `copilot-local` CLI subprocess only — the prior
+// HTTP/OAuth `'copilot'` provider was removed because its
+// `/copilot_internal/v2/token` endpoint is gated on the IDE-extension OAuth
+// app and rejects every other token shape.
+const PRIMARY: Array<{ id: ProviderId; label: string }> = [
+  { id: 'claude-local', label: 'Claude' },
+  { id: 'codex-local', label: 'Codex' },
+  { id: 'opencode-local', label: 'OpenCode' },
+  { id: 'copilot-local', label: 'Copilot' },
+]
+
+const primaryProviders = PRIMARY
+
+const store = useProviderSettings()
+const detect = useAgentDetect()
+const agentModels = useAgentModels()
+
+const activeProvider = computed(() => store.activeProvider.value)
+const agentMode = computed<AgentMode>(() => store.settings.value.agentMode)
+const currentModel = computed(() => store.settings.value.providers[activeProvider.value].model ?? '')
+const currentEffort = computed(() => store.settings.value.providers[activeProvider.value].effort ?? 'auto')
+const effortOptions = computed<readonly EffortLevel[]>(() => EFFORTS_BY_PROVIDER[activeProvider.value] ?? EFFORT_LEVELS)
+
+/** The flags + rationale string the wizard's init-mode note renders. */
+const initFlagsForActive = computed<{ flags: string; rationale: string } | null>(() => {
+  const bin = PROVIDER_BIN[activeProvider.value as string]
+  if (!bin) return null
+  return {
+    flags: initPermissionFlagsFor(bin).join(' '),
+    rationale: INIT_RATIONALE[bin],
+  }
+})
+
+// Model dropdown — sourced from the singleton catalog. There is no curated
+// fallback: when the live probe returns nothing the dropdown reduces to
+// "Auto (CLI default)" and a warning links users to the Advanced panel where
+// they can enter a custom model id explicitly.
+const modelCatalog = computed(() => agentModels.catalogFor(activeProvider.value).value)
+const models = computed(() => modelCatalog.value.models)
+const modelsLoading = computed(() => agentModels.state.loading[activeProvider.value] === true)
+const modelsBlocked = computed(
+  () => !modelsLoading.value && models.value.length <= 1 && !modelCatalog.value.discovered,
+)
+
+const modeOptions: Array<{ id: AgentMode; label: string }> = [
+  { id: 'auto', label: 'Auto' },
+  { id: 'manual', label: 'Manual' },
+  { id: 'off', label: 'Off' },
+]
+
+const modeHints: Record<AgentMode, string> = {
+  auto: 'Tasks auto-run on create — hands-free.',
+  manual: 'Conversation tab available; agent runs when you click Run.',
+  off: 'No in-shell chat; drive agents from the terminal instead.',
+}
+
+const permissionMode = computed<PermissionMode>(() => store.settings.value.permissionMode)
+// `default` is "Auto": each CLI runs the least-permissive mode that still works
+// headlessly (normalizeHeadlessMode) — codex/copilot stay sandboxed/minimal,
+// claude/opencode escalate to bypass since they have no headless ask-mode. It's
+// the safe, recommended default. `bypass` (all sandboxes off) is the explicit
+// opt-in. See InitWizard.vue's INIT_PERMISSION_MODE_OPTIONS for the mirror.
+const permissionModeOptions: Array<{ id: PermissionMode; label: string }> = [
+  { id: 'default', label: 'Auto' },
+  { id: 'bypass',  label: 'Bypass' },
+  { id: 'plan',    label: 'Plan' },
+]
+const visiblePermissionModes = computed(() =>
+  props.hidePlanMode
+    ? permissionModeOptions.filter(m => m.id !== 'plan')
+    : permissionModeOptions,
+)
+const permissionModeHints: Record<PermissionMode, string> = {
+  default: 'Auto (recommended) — safest mode that still applies tasks: codex/copilot run sandboxed/minimal; claude/opencode run as bypass (no headless ask-mode).',
+  plan: 'Read-only — agent investigates but cannot write (CLI/sandbox-enforced on Claude/Codex; model-directive only on Copilot/OpenCode).',
+  bypass: 'Auto-approve everything, all sandboxes off. Fastest, riskiest — opt-in.',
+}
+
+const readiness = computed<{ message: string; tone: 'success' | 'muted' | 'danger' }>(() => {
+  const id = activeProvider.value
+  const snap = detect.snapshot.value
+  if (id === 'claude-local' || id === 'codex-local' || id === 'opencode-local' || id === 'copilot-local') {
+    if (!snap) return { message: 'Detecting local CLI…', tone: 'muted' }
+    const probe = snap[id]
+    if (!probe?.found) return { message: `${PRIMARY.find(p => p.id === id)?.label} CLI not installed.`, tone: 'danger' }
+    if (!probe?.loggedIn) return { message: `${PRIMARY.find(p => p.id === id)?.label} CLI installed but not logged in. Run \`${id.replace('-local', '')} login\` in a terminal.`, tone: 'danger' }
+    return { message: `${PRIMARY.find(p => p.id === id)?.label} (local CLI) ready.`, tone: 'success' }
+  }
+  return { message: '', tone: 'muted' }
+})
+
+function onProviderChange(value: string) {
+  store.setActiveProvider(value as ProviderId)
+}
+
+function onModelChange(value: string) {
+  store.setModel(activeProvider.value, value)
+}
+
+function onEffortChange(value: string) {
+  store.setEffort(activeProvider.value, value as EffortLevel)
+}
+
+function setAgentMode(mode: AgentMode) {
+  store.setAgentMode(mode)
+}
+
+function setPermissionMode(mode: PermissionMode) {
+  store.setPermissionMode(mode)
+}
+
+onMounted(() => {
+  fetchAgentDetect()
+  void agentModels.ensure(activeProvider.value)
+  // Ensure the model field starts at Auto ('') for the initial provider.
+  // If the user previously saved a specific model it stays; if not set,
+  // the empty string matches the "Auto (CLI default)" option.
+  const initial = store.settings.value.providers[activeProvider.value] as ProviderConfig
+  if (!initial.model) store.setModel(activeProvider.value, '')
+})
+
+watch(activeProvider, (id) => {
+  void agentModels.ensure(id)
+  // Always reset to Auto when the user switches provider — the model
+  // from the previous provider is meaningless for the new one.
+  store.setModel(id, '')
+})
+
+// When the picker enters the "Cannot fetch models" state and the user has
+// a stale model id saved, default that input back to Auto (empty) so the
+// blocked-state UI starts clean instead of pre-filling a value the live
+// probe couldn't confirm.
+watch(modelsBlocked, (blocked) => {
+  if (!blocked) return
+  if (!currentModel.value) return
+  store.setModel(activeProvider.value, '')
+})
+</script>
+
+<style scoped>
+.aqs {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.aqs-row {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+}
+
+.aqs-field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  font-size: 14px;
+  color: color-mix(in srgb, var(--text) 78%, var(--surface));
+}
+.aqs-field > span:first-child { font-weight: 700; color: var(--text); font-size: 13px; }
+
+.aqs-field-label {
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--text);
+  align-self: center;
+}
+
+.aqs-field select,
+.aqs-field input[type="text"] {
+  font: inherit;
+  font-size: 13px;
+  padding: 8px 10px;
+  border-radius: 6px;
+  border: 1px solid var(--border);
+  background: var(--surface);
+  color: var(--text);
+}
+.aqs-field select:disabled { opacity: 0.6; cursor: progress; }
+.aqs-field input[type="text"]:focus { outline: 2px solid var(--accent); outline-offset: -1px; border-color: transparent; }
+
+.aqs-field-warning {
+  font-size: 13px;
+  line-height: 1.45;
+  color: color-mix(in srgb, var(--text) 78%, var(--surface));
+  background: color-mix(in srgb, var(--warning) 22%, transparent);
+  border-left: 3px solid var(--warning);
+  padding: 6px 10px;
+  border-radius: 4px;
+  margin-top: 2px;
+}
+
+.aqs-mode-row {
+  grid-template-columns: auto 1fr auto;
+  align-items: center;
+  gap: 12px;
+}
+
+.aqs-mode-group {
+  display: inline-flex;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 2px;
+  gap: 2px;
+}
+
+.aqs-mode-btn {
+  font: inherit;
+  font-size: 13px;
+  font-weight: 600;
+  padding: 6px 14px;
+  border: none;
+  background: transparent;
+  color: color-mix(in srgb, var(--text) 78%, var(--surface));
+  border-radius: 4px;
+  cursor: pointer;
+}
+.aqs-mode-btn:hover:not(.active) { color: var(--text); }
+.aqs-mode-btn.active {
+  background: var(--accent);
+  color: var(--text-on-accent);
+}
+
+.aqs-mode-hint {
+  font-size: 13px;
+  color: color-mix(in srgb, var(--text) 78%, var(--surface));
+  text-align: right;
+  flex-basis: 100%;
+}
+
+.aqs-init-note {
+  margin: 0;
+  padding: 10px 14px;
+  font-size: 14px;
+  line-height: 1.55;
+  color: color-mix(in srgb, var(--text) 78%, var(--surface));
+  background: color-mix(in srgb, var(--warning) 22%, transparent);
+  border-left: 3px solid var(--warning);
+  border-radius: 4px;
+}
+.aqs-init-note code {
+  font-size: 13px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: var(--surface-2);
+  color: var(--text);
+}
+
+
+.aqs-status {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 14px;
+  font-weight: 500;
+  margin: 0;
+  padding: 10px 14px;
+  border-radius: 4px;
+  background: var(--surface-2);
+  border-left: 3px solid var(--border);
+  color: color-mix(in srgb, var(--text) 78%, var(--surface));
+}
+.aqs-status.success {
+  background: color-mix(in srgb, var(--success) 22%, transparent);
+  border-left-color: var(--success);
+}
+.aqs-status.danger {
+  background: color-mix(in srgb, var(--danger) 22%, transparent);
+  border-left-color: var(--danger);
+}
+.aqs-status.muted {
+  color: color-mix(in srgb, var(--text) 78%, var(--surface));
+}
+
+.aqs-status-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: currentColor;
+}
+
+.aqs-advanced {
+  margin-top: 4px;
+  border-top: 1px solid var(--border);
+  padding-top: 12px;
+}
+.aqs-advanced summary {
+  font-size: 14px;
+  font-weight: 700;
+  color: color-mix(in srgb, var(--text) 78%, var(--surface));
+  cursor: pointer;
+  padding: 4px 0;
+}
+.aqs-advanced summary:hover { color: var(--text); }
+.aqs-advanced[open] summary { color: var(--text); margin-bottom: 8px; }
+.aqs-advanced-lead {
+  font-size: 14px;
+  color: color-mix(in srgb, var(--text) 78%, var(--surface));
+  margin: 0 0 10px;
+}
+</style>
diff --git a/src/shell/components/AgentsPanel.vue b/src/shell/components/AgentsPanel.vue
new file mode 100644
index 0000000..1a86fd3
--- /dev/null
+++ b/src/shell/components/AgentsPanel.vue
@@ -0,0 +1,28 @@
+<template>
+  <div class="agents-panel">
+    <AgentDirectionsPanel class="agents-panel-inner" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import AgentDirectionsPanel from './AgentDirectionsPanel.vue'
+</script>
+
+<style scoped>
+.agents-panel {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  /* Let the panel fill the settings content area */
+  height: 100%;
+}
+
+.agents-panel-inner {
+  flex: 1;
+  min-height: 400px;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  overflow: hidden;
+}
+</style>
diff --git a/src/shell/components/AppBanners.vue b/src/shell/components/AppBanners.vue
index 82cb2b0..1b7d2e5 100644
--- a/src/shell/components/AppBanners.vue
+++ b/src/shell/components/AppBanners.vue
@@ -6,6 +6,13 @@
     <div v-if="!configInitialized" class="setup-banner">
       Annotask not initialized — run <code>/annotask-init</code> in your AI assistant to set up project tokens and component detection.
     </div>
+    <!-- Wireframe capture/enter failure. The canvas (which normally renders this
+         error) unmounts when entry fails, so without this the message flashes
+         and vanishes. Surface it here, dismissibly, instead. -->
+    <div v-if="wireframeError" class="warning-banner" data-testid="wireframe-error-banner">
+      Wireframe: {{ wireframeError }}
+      <button class="banner-dismiss" type="button" @click="$emit('dismiss-wireframe-error')">Dismiss</button>
+    </div>
   </div>
 </template>
 
@@ -13,7 +20,25 @@
 interface Props {
   showWarning: boolean
   configInitialized: boolean
+  /** Wireframe capture/enter error to surface when the canvas isn't mounted. */
+  wireframeError?: string | null
 }
 
 defineProps<Props>()
+defineEmits<{ 'dismiss-wireframe-error': [] }>()
 </script>
+
+<style scoped>
+.banner-dismiss {
+  margin-left: 8px;
+  padding: 1px 8px;
+  font-size: 11px;
+  background: transparent;
+  border: 1px solid currentColor;
+  border-radius: 4px;
+  color: inherit;
+  cursor: pointer;
+  opacity: 0.8;
+}
+.banner-dismiss:hover { opacity: 1; }
+</style>
diff --git a/src/shell/components/AppToolbar.vue b/src/shell/components/AppToolbar.vue
index 5469561..438423b 100644
--- a/src/shell/components/AppToolbar.vue
+++ b/src/shell/components/AppToolbar.vue
@@ -35,9 +35,15 @@
             @click="onInspectClick" title="Inspect (V)">
             <Icon name="search" />
           </button>
+          <button data-testid="tool-wireframe" :class="['mode-btn mode-wireframe', { active: wireframeActive }]"
+            :disabled="wireframeCapturing"
+            @click="$emit('toggle-wireframe')" title="Wireframe — freeze the route into a manipulable sketch">
+            <Icon name="frame" />
+          </button>
         </div>
         <button v-if="designSection !== 'components'"
-          :class="['tool-btn', { active: layoutOverlayActive }]" @click="$emit('toggle-layout-overlay')" title="Show Layout (L)">
+          :class="['tool-btn', { active: layoutOverlayActive }]" :disabled="wireframeActive"
+          @click="$emit('toggle-layout-overlay')" title="Show Layout (L)">
           <Icon name="layout-dashboard" />
         </button>
       </template>
@@ -114,7 +120,7 @@
             Inspector
           </button>
           <button data-testid="design-components" :class="['toggle-btn', { active: designSection === 'components' && activePanel !== 'tasks' }]"
-            @click="$emit('switch-design-section', 'components')" title="Browse project components">
+            @click="$emit('switch-design-section', 'components')" title="Browse + drag components onto the live app">
             <Icon name="grid-2x2" :size="12" />
             Components
           </button>
@@ -127,7 +133,7 @@
         </div>
       </template>
 
-      <!-- Audit sub-section: Accessibility / Data / Libraries / Performance / Errors + Tasks -->
+      <!-- Audit sub-section: Accessibility / Data / Performance / Errors + Tasks -->
       <template v-else-if="shellView === 'develop'">
         <div class="panel-toggle">
           <button data-testid="audit-a11y" :class="['toggle-btn', { active: developSection === 'a11y' && activePanel !== 'tasks' }]"
@@ -141,11 +147,6 @@
             <Icon name="database" :size="12" />
             Data
           </button>
-          <button data-testid="audit-libraries" :class="['toggle-btn', { active: developSection === 'libraries' && activePanel !== 'tasks' }]"
-            @click="$emit('switch-develop-section', 'libraries')" title="Browse detected data-fetching and state libraries">
-            <Icon name="library" :size="12" />
-            Libraries
-          </button>
           <button data-testid="audit-perf" :class="['toggle-btn', { active: developSection === 'perf' && activePanel !== 'tasks' }]"
             @click="$emit('switch-develop-section', 'perf')" title="Web Vitals and page performance">
             <Icon name="activity" :size="12" />
@@ -198,6 +199,8 @@ interface Props {
   developSection: DevelopSection
   currentRoute: string
   layoutOverlayActive: boolean
+  wireframeActive: boolean
+  wireframeCapturing: boolean
   a11yLoading: boolean
   a11yViolationsCount: number
   tabOrderEnabled: boolean
@@ -223,6 +226,7 @@ const emit = defineEmits<{
   (e: 'switch-design-section', value: DesignSection): void
   (e: 'switch-develop-section', value: DevelopSection): void
   (e: 'toggle-layout-overlay'): void
+  (e: 'toggle-wireframe'): void
   (e: 'scan-a11y'): void
   (e: 'toggle-tab-order'): void
   (e: 'start-perf-recording'): void
diff --git a/src/shell/components/ArrowOverlay.vue b/src/shell/components/ArrowOverlay.vue
index b867d7f..59fd1a2 100644
--- a/src/shell/components/ArrowOverlay.vue
+++ b/src/shell/components/ArrowOverlay.vue
@@ -210,11 +210,10 @@ function onEndpointUp(e: PointerEvent) {
     </g>
 
     <!-- Element outline during endpoint drag -->
-    <rect v-if="endpointDrag && dragTargetRect"
+    <rect v-if="endpointDrag && dragTargetRect" class="drag-target-outline"
       :x="dragTargetRect.x - 4" :y="dragTargetRect.y - 4"
       :width="dragTargetRect.width + 8" :height="dragTargetRect.height + 8"
-      fill="rgba(59,130,246,0.06)" stroke="#3b82f6" stroke-width="2"
-      stroke-dasharray="4 2" rx="3" opacity="0.7"
+      stroke-width="2" stroke-dasharray="4 2" rx="3" opacity="0.7"
     />
 
     <!-- Hover preview (before drawing starts) -->
@@ -284,6 +283,12 @@ function onEndpointUp(e: PointerEvent) {
   pointer-events: none;
 }
 .arrow-path { pointer-events: stroke; cursor: pointer; }
+/* var() is unreliable in SVG presentation attributes, so the drag-target
+   outline is themed here instead of inline on the <rect>. */
+.drag-target-outline {
+  fill: color-mix(in srgb, var(--accent) 6%, transparent);
+  stroke: var(--accent);
+}
 .arrow-delete { cursor: pointer; pointer-events: auto; }
 .endpoint-handle { cursor: grab; pointer-events: auto; }
 .endpoint-handle:active { cursor: grabbing; }
diff --git a/src/shell/components/ColorPalettePicker.vue b/src/shell/components/ColorPalettePicker.vue
index 1cd047d..115ecf6 100644
--- a/src/shell/components/ColorPalettePicker.vue
+++ b/src/shell/components/ColorPalettePicker.vue
@@ -334,7 +334,7 @@ onUnmounted(() => {
 }
 .var-swatch:hover { background: var(--surface-2); border-color: var(--border); }
 .var-swatch.selected { border-color: var(--accent); }
-.var-color { width: 18px; height: 18px; border-radius: 4px; flex-shrink: 0; border: 1px solid rgba(255,255,255,0.08); }
+.var-color { width: 18px; height: 18px; border-radius: 4px; flex-shrink: 0; border: 1px solid color-mix(in srgb, var(--text) 8%, transparent); }
 .var-name { font-size: 11px; color: var(--text); font-family: 'SF Mono', 'Fira Code', monospace; flex: 1; text-align: left; }
 .var-hex { font-size: 9px; color: var(--text-muted); font-family: 'SF Mono', 'Fira Code', monospace; }
 
diff --git a/src/shell/components/ComponentPreview.vue b/src/shell/components/ComponentPreview.vue
index 2a53e93..87c9cc5 100644
--- a/src/shell/components/ComponentPreview.vue
+++ b/src/shell/components/ComponentPreview.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { ref, reactive, computed, watch } from 'vue'
 import Icon from './Icon.vue'
+import { inferWidget, enumValues, parseDefault } from '../utils/propWidgets'
 
 interface PreviewProp {
   name: string
@@ -44,26 +45,6 @@ const copyOk = ref(false)
 type PropsViewMode = 'table' | 'json' | 'yaml'
 const propsView = ref<PropsViewMode>('table')
 
-// Parse a single-line default-value expression (e.g. `'small'`, `true`, `42`) into a real JS value.
-// Falls back to the raw string if parsing fails. Keeps initial values honest to the extracted type.
-function parseDefault(raw: unknown, type: string | null): unknown {
-  if (raw == null) return undefined
-  const s = String(raw).trim()
-  if (!s || s === 'undefined' || s === 'null') return undefined
-  if (s === 'true') return true
-  if (s === 'false') return false
-  if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s)
-  // Quoted string
-  const m = s.match(/^['"`](.*)['"`]$/)
-  if (m) return m[1]
-  // For enum types like 'a' | 'b', use the first
-  if (type && /'[^']+'/.test(type)) {
-    const first = type.match(/'([^']+)'/)
-    if (first) return first[1]
-  }
-  return s
-}
-
 function initialPropsFor(comp: PreviewComponent): Record<string, unknown> {
   const out: Record<string, unknown> = {}
   for (const p of comp.props) {
@@ -75,21 +56,6 @@ function initialPropsFor(comp: PreviewComponent): Record<string, unknown> {
   return out
 }
 
-function inferWidget(p: PreviewProp): 'boolean' | 'number' | 'enum' | 'string' | 'json' {
-  const t = (p.type || '').toLowerCase()
-  if (t === 'boolean' || t === 'bool') return 'boolean'
-  if (t === 'number' || t === 'int' || t === 'float') return 'number'
-  if (/^(['"][\w-]+['"]\s*\|\s*)+['"][\w-]+['"]\s*$/.test(p.type || '')) return 'enum'
-  if (t === 'string' || t.startsWith('string')) return 'string'
-  // Complex types (objects, arrays, functions) — give the user a JSON escape hatch
-  return 'json'
-}
-
-function enumValues(p: PreviewProp): string[] {
-  if (!p.type) return []
-  return [...p.type.matchAll(/'([^']+)'/g)].map(m => m[1])
-}
-
 function jsonFor(value: unknown): string {
   if (value === undefined) return ''
   try { return JSON.stringify(value) } catch { return '' }
diff --git a/src/shell/components/ComponentsPage.vue b/src/shell/components/ComponentsPage.vue
index c6bbddc..4e3c6d5 100644
--- a/src/shell/components/ComponentsPage.vue
+++ b/src/shell/components/ComponentsPage.vue
@@ -1,10 +1,15 @@
 <script setup lang="ts">
-import { onMounted, ref, watch, nextTick, useTemplateRef } from 'vue'
+import { computed, onMounted, ref, watch, nextTick, useTemplateRef } from 'vue'
 import { useComponentLibrary, colorForLibrary, type LibraryComponent } from '../composables/useProjectComponents'
 import { useWorkspace } from '../composables/useWorkspace'
+import { usePaletteDrag, type PaletteDragItem } from '../composables/usePaletteDrag'
+import { HTML_CATALOG, LAYOUT_PRESETS, type CatalogItem } from '../types'
 import type { useIframeManager } from '../composables/useIframeManager'
+import type { PreviewComponentResult } from '../../shared/bridge-types'
+import type { WireframeInstance, WireframeInstanceStatus } from '../../shared/wireframe-types'
 import Icon from './Icon.vue'
 import MfeFilterDropdown from './MfeFilterDropdown.vue'
+import DesignSessionPanel from './DesignSessionPanel.vue'
 
 const props = defineProps<{
   iframe: ReturnType<typeof useIframeManager>
@@ -12,10 +17,168 @@ const props = defineProps<{
   /** Component name currently emphasized via `dataHighlights.focusedName` —
    *  driven by both list-row hover and iframe element hover. */
   focusedName?: string | null
+  /** Placements persisted on the current route — drives the placements panel
+   *  and "Build this route" (which only batches the 'placed' ones). */
+  placements?: WireframeInstance[]
+  /** Instance ids whose durable anchor no longer resolves (source drifted). */
+  staleIds?: string[]
+  /** Instance ids whose last re-mount attempt threw. */
+  failedIds?: string[]
+  /** Wireframe mode is active — clicking a component opens the generate
+   *  panel instead of the detail preview (which stays behind the info icon). */
+  wireframeActive?: boolean
 }>()
 
+const emit = defineEmits<{ build: []; deletePlacement: [id: string]; runAgent: [taskId: string]; generateComponent: [item: PaletteDragItem] }>()
+
+// ── Placements panel (current route's wireframe instances) ──
+function placementStatus(i: WireframeInstance): WireframeInstanceStatus {
+  return i.status ?? 'placed' // legacy instances predate the field
+}
+const placedCount = computed(() => (props.placements ?? []).filter((i) => placementStatus(i) === 'placed').length)
+const buildingCount = computed(() => (props.placements ?? []).filter((i) => placementStatus(i) === 'building').length)
+const appliedCount = computed(() => (props.placements ?? []).filter((i) => placementStatus(i) === 'applied').length)
+
+function placementName(i: WireframeInstance): string {
+  return i.kind === 'component' ? (i.inserted.componentName ?? i.inserted.tag) : i.inserted.tag
+}
+
+function placementTooltip(i: WireframeInstance): string {
+  const lines = [
+    `${placementName(i)} — ${i.kind}`,
+    `${i.anchor.position} ${i.anchor.component || i.anchor.targetTag || 'target'} (${i.anchor.file}:${i.anchor.line})`,
+  ]
+  if (i.taskId) lines.push(`Task: ${i.taskId}`)
+  return lines.join('\n')
+}
+
 const cl = useComponentLibrary(props.iframe)
 const ws = useWorkspace()
+const paletteDrag = usePaletteDrag()
+
+// ── Palette drag (drag a catalog item onto the live app) ──
+function fidelityLabel(hint: LibraryComponent['fidelityHint']): string {
+  if (hint === 'live') return 'live'
+  if (hint === 'isolated-preview') return 'preview'
+  if (hint === 'placeholder') return 'placeholder'
+  return ''
+}
+
+// Synthesize minimum-viable props so a component renders with visible content
+// instead of empty (a Button with no `label` is an empty box). Display-only —
+// these are NOT persisted as the placed component's real props.
+// 'text'/'name' are intentionally excluded — in many UI libs `text` is a
+// boolean style flag (text/link button) and `name` is a form field id, not
+// display content.
+const CONTENT_PROP_KEYS = new Set(['label', 'value', 'title', 'header', 'content', 'caption', 'placeholder', 'message', 'description'])
+function sampleProps(c: LibraryComponent): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const p of c.props) {
+    const name = p.name
+    const t = (p.type || '').toLowerCase()
+    const stringish = t.includes('string') || t === ''
+    if (p.options && p.options.length) { out[name] = p.options[0]; continue }
+    // Only fill content props that are actually string-typed, so a boolean
+    // `text`/`value` flag isn't turned into a label.
+    if (stringish && CONTENT_PROP_KEYS.has(name.toLowerCase())) { out[name] = c.name; continue }
+    if (!p.required) continue
+    if (t.includes('bool')) out[name] = true
+    else if (t.includes('number')) out[name] = 1
+    else if (t.includes('[]') || t.includes('array')) out[name] = []
+    else if (t.includes('string') || t === '' || t.includes('|')) out[name] = c.name
+    else out[name] = {} // object/unknown required prop → empty obj avoids undefined-access throws
+  }
+  return out
+}
+
+/** Per-component MFE renderability on the current surface, computed once per
+ *  catalog change. Drives draggability, the unavailable chip/tooltip, and the
+ *  block's MFE stamp. */
+const renderInfoByKey = computed(() => {
+  const m = new Map<string, { renderable: boolean; owningMfe: string | null }>()
+  for (const lib of cl.filteredLibraries.value) {
+    for (const c of lib.components) m.set(`${lib.name}:::${c.name}`, cl.surfaceRenderInfo(lib.name, c))
+  }
+  return m
+})
+function rinfo(libName: string, name: string): { renderable: boolean; owningMfe: string | null } {
+  return renderInfoByKey.value.get(`${libName}:::${name}`) ?? { renderable: true, owningMfe: null }
+}
+
+function componentDragItem(libName: string, c: LibraryComponent): PaletteDragItem {
+  const info = rinfo(libName, c.name)
+  const mfe = info.owningMfe ?? ws.currentMfe.value ?? undefined
+  return {
+    kind: 'component', componentName: c.name, tag: c.name, label: c.name, library: libName,
+    module: c.module, fidelityHint: c.fidelityHint ?? 'unknown', previewProps: sampleProps(c),
+    ...(mfe ? { mfe } : {}),
+  }
+}
+
+function catalogDragItem(item: CatalogItem): PaletteDragItem {
+  return {
+    kind: item.category === 'layout-preset' ? 'layout-preset' : 'html',
+    componentName: item.tag, tag: item.tag, label: item.label,
+    props: item.defaultProps, classes: item.defaultClasses, textContent: item.defaultTextContent, category: item.category,
+  }
+}
+
+function onDragStart(e: DragEvent, item: PaletteDragItem) {
+  paletteDrag.startDrag(item)
+  if (e.dataTransfer) {
+    e.dataTransfer.effectAllowed = 'copy'
+    e.dataTransfer.setData('application/x-annotask-palette', JSON.stringify(item))
+    // Use the rendered snapshot as the drag ghost when we already have one.
+    const url = item.kind === 'component' ? previewCache.get(item.componentName)?.dataUrl : undefined
+    if (url) {
+      const img = new Image()
+      img.src = url
+      e.dataTransfer.setDragImage(img, 20, 16)
+    }
+  }
+}
+
+function onDragEnd() {
+  paletteDrag.endDrag()
+}
+
+// Filter the HTML/layout groups by the same search box (usage filters don't apply).
+const q = computed(() => cl.filterText.value.trim().toLowerCase())
+const layoutItems = computed(() => LAYOUT_PRESETS.filter((i) => !q.value || i.label.toLowerCase().includes(q.value)))
+const htmlItems = computed(() => HTML_CATALOG.filter((i) => !q.value || i.label.toLowerCase().includes(q.value)))
+
+// ── Component preview (offscreen render → snapshot) ──
+const previewCache = new Map<string, PreviewComponentResult>()
+const previewState = ref<{ loading: boolean; result: PreviewComponentResult | null }>({ loading: false, result: null })
+
+async function loadPreview(c: LibraryComponent): Promise<void> {
+  const name = c.name
+  const cached = previewCache.get(name)
+  if (cached) { previewState.value = { loading: false, result: cached }; return }
+  previewState.value = { loading: true, result: null }
+  const result = await props.iframe.previewComponent(name, sampleProps(c), c.module, 320)
+  previewCache.set(name, result)
+  // Ignore a stale response if the user moved on to another component.
+  if (cl.selectedComponent.value?.name === name) previewState.value = { loading: false, result }
+}
+
+watch(() => cl.selectedComponent.value?.name, (name) => {
+  previewState.value = { loading: false, result: null }
+  const c = cl.selectedComponent.value
+  if (name && c) void loadPreview(c)
+}, { immediate: true })
+
+function previewPlaceholderText(r: PreviewComponentResult | null): string {
+  if (!r) return 'No preview available.'
+  if (r.reason === 'not-registered') return 'Not loadable on this route — couldn’t resolve its module.'
+  if (r.reason === 'threw') {
+    if (/slot|children/i.test(r.detail || '')) return 'Container component — it needs child content (e.g. tabs/panels) to render.'
+    return 'Couldn’t render standalone — it needs specific props or context.'
+  }
+  if (r.reason === 'rendered-empty') return 'Rendered nothing with sample props — needs real data or content.'
+  if (r.error) return `Couldn’t snapshot the render (${r.error}).`
+  return 'No preview available.'
+}
 
 const COLLAPSED_KEY = 'annotask:componentsCollapsedLibs'
 const collapsedLibs = ref<Set<string>>(new Set())
@@ -71,6 +234,10 @@ function componentTooltip(lib: string, c: LibraryComponent): string {
   lines.push(`${c.props.length} prop${c.props.length === 1 ? '' : 's'}` + (c.slots?.length ? ` · ${c.slots.length} slot${c.slots.length === 1 ? '' : 's'}` : '') + (c.events?.length ? ` · ${c.events.length} event${c.events.length === 1 ? '' : 's'}` : ''))
   if (cl.isOnPageInLib(lib, c.name)) lines.push('● on this page')
   else if (cl.isUsedInLib(lib, c.name)) lines.push('✓ used in this project')
+  const info = rinfo(lib, c.name)
+  if (!info.renderable && info.owningMfe) {
+    lines.push(`⊘ lives in MFE "${info.owningMfe}" — can't render on this surface (predicted)`)
+  }
   return lines.join('\n')
 }
 </script>
@@ -110,6 +277,19 @@ function componentTooltip(lib: string, c: LibraryComponent): string {
         </button>
       </div>
       <MfeFilterDropdown v-if="ws.hasAnyMfes.value" label="Components" />
+      <button
+        v-if="props.placements?.length"
+        class="components-btn build"
+        data-testid="palette-build-route"
+        :disabled="placedCount === 0"
+        :title="placedCount === 0
+          ? 'No new placements to build — the listed ones are already building or applied'
+          : 'Create a wireframe_apply task for this route\'s new placements'"
+        @click="emit('build')"
+      >
+        <Icon name="wand" :size="13" />
+        Build<span class="build-count">{{ placedCount }}</span>
+      </button>
       <button
         class="components-btn icon"
         :title="cl.isLoading.value ? 'Loading…' : 'Reload components'"
@@ -123,6 +303,35 @@ function componentTooltip(lib: string, c: LibraryComponent): string {
 
     <div v-if="cl.loadError.value" class="components-error">{{ cl.loadError.value }}</div>
 
+    <!-- Placements on this route: lifecycle chips + per-instance delete. The
+         placed/building/applied split mirrors the Build button — only the
+         'placed' ones go into the next wireframe_apply task. -->
+    <div v-if="props.placements?.length" class="placements-panel" data-testid="palette-placements">
+      <div class="placements-head">
+        <span class="placements-title">Placements on this route</span>
+        <span v-if="buildingCount" class="placements-summary">{{ buildingCount }} building</span>
+        <span v-if="appliedCount" class="placements-summary">{{ appliedCount }} applied</span>
+      </div>
+      <div v-for="i in props.placements" :key="i.id" class="placement-row" :title="placementTooltip(i)">
+        <span class="placement-name">{{ placementName(i) }}</span>
+        <span class="placement-status" :data-status="placementStatus(i)">{{ placementStatus(i) }}</span>
+        <span class="placement-fidelity" :class="'fid-' + i.fidelity">{{ i.fidelity === 'isolated-preview' ? 'preview' : i.fidelity }}</span>
+        <span v-if="props.staleIds?.includes(i.id)" class="placement-stale" title="The anchor element no longer exists in the source — delete this placement">stale</span>
+        <span v-else-if="props.failedIds?.includes(i.id)" class="placement-stale" title="The last re-mount attempt failed — see the console for details">failed</span>
+        <button
+          class="placement-delete"
+          :title="`Delete placement ${placementName(i)}`"
+          :aria-label="`Delete placement ${placementName(i)}`"
+          @click="emit('deletePlacement', i.id)"
+        >
+          <Icon name="trash" :size="12" />
+        </button>
+      </div>
+    </div>
+
+    <!-- Design session: pending/applied panel edits + apply/undo/discard. -->
+    <DesignSessionPanel @run-agent="emit('runAgent', $event)" />
+
     <div class="components-split">
       <!-- LIST view — visible when no component is selected. -->
       <div v-if="!cl.selectedComponent.value" ref="listRef" class="components-list">
@@ -163,16 +372,26 @@ function componentTooltip(lib: string, c: LibraryComponent): string {
                 selected: cl.selectedKey.value === `${lib.name}:::${c.name}`,
                 focused: focusedName === cl.sourceName(lib.name, c.name),
                 'on-page': cl.isOnPageInLib(lib.name, c.name),
+                unavailable: !rinfo(lib.name, c.name).renderable,
               }"
               :data-component-name="c.name"
-              :title="componentTooltip(lib.name, c)"
-              @click="cl.select(lib.name, c.name)"
+              :title="componentTooltip(lib.name, c) + (rinfo(lib.name, c.name).renderable ? (props.wireframeActive ? '\n↳ click to generate, or drag onto the canvas' : '\n↳ drag onto the app to place') : '')"
+              :draggable="rinfo(lib.name, c.name).renderable"
+              @dragstart="onDragStart($event, componentDragItem(lib.name, c))"
+              @dragend="onDragEnd"
+              @click="rinfo(lib.name, c.name).renderable && props.wireframeActive ? emit('generateComponent', componentDragItem(lib.name, c)) : cl.select(lib.name, c.name)"
               @mouseenter="cl.isOnPageInLib(lib.name, c.name) && cl.setFocus(cl.sourceName(lib.name, c.name))"
               @mouseleave="focusedName === cl.sourceName(lib.name, c.name) && cl.setFocus(null)"
             >
               <div class="item-row">
                 <span class="item-swatch" :style="{ background: colorForLibrary(lib.name) }" />
                 <span class="item-name" :class="{ deprecated: c.deprecated }">{{ c.name }}</span>
+                <button v-if="props.wireframeActive" class="item-info-btn" :title="`Open the ${c.name} detail preview`"
+                  @click.stop="cl.select(lib.name, c.name)">
+                  <Icon name="info" :size="11" />
+                </button>
+                <span v-if="fidelityLabel(c.fidelityHint)" class="item-fidelity" :class="'fid-' + c.fidelityHint" :title="c.providerSignals && c.providerSignals.length ? 'Uses: ' + c.providerSignals.join(', ') : ''">{{ fidelityLabel(c.fidelityHint) }}</span>
+                <span v-if="!rinfo(lib.name, c.name).renderable" class="item-mfe-na" :title="`Lives in MFE ${rinfo(lib.name, c.name).owningMfe} — can't render on this surface`">⊘ {{ rinfo(lib.name, c.name).owningMfe }}</span>
                 <span v-if="cl.isOnPageInLib(lib.name, c.name)" class="item-onpage" title="Rendered on the current route">on page</span>
                 <span v-else-if="cl.isUsedInLib(lib.name, c.name)" class="item-used" title="Referenced somewhere in this project">used</span>
                 <span v-if="matchCount(cl.sourceName(lib.name, c.name)) > 0" class="item-match">
@@ -184,6 +403,48 @@ function componentTooltip(lib: string, c: LibraryComponent): string {
             </button>
           </div>
         </template>
+
+        <!-- Building blocks: HTML elements + layout presets (drag to place).
+             Shown in 'all' mode (the usage filters apply only to library
+             components). -->
+        <template v-if="cl.filterMode.value === 'all'">
+          <div v-if="layoutItems.length" class="lib-group">
+            <div class="lib-group-head static"><span class="lib-group-name">Layout</span><span class="lib-group-count">{{ layoutItems.length }}</span></div>
+            <button
+              v-for="item in layoutItems"
+              :key="'layout-' + item.label"
+              class="components-list-item"
+              draggable="true"
+              :title="item.defaultClasses + '\n↳ drag onto the app to place'"
+              @dragstart="onDragStart($event, catalogDragItem(item))"
+              @dragend="onDragEnd"
+            >
+              <div class="item-row">
+                <Icon name="grid-2x2" :size="13" class="item-glyph" />
+                <span class="item-name">{{ item.label }}</span>
+                <code class="item-meta">{{ item.defaultClasses }}</code>
+              </div>
+            </button>
+          </div>
+          <div v-if="htmlItems.length" class="lib-group">
+            <div class="lib-group-head static"><span class="lib-group-name">Elements</span><span class="lib-group-count">{{ htmlItems.length }}</span></div>
+            <button
+              v-for="item in htmlItems"
+              :key="'html-' + item.label"
+              class="components-list-item"
+              draggable="true"
+              :title="'<' + item.tag + '>\n↳ drag onto the app to place'"
+              @dragstart="onDragStart($event, catalogDragItem(item))"
+              @dragend="onDragEnd"
+            >
+              <div class="item-row">
+                <Icon name="code" :size="13" class="item-glyph" />
+                <span class="item-name">{{ item.label }}</span>
+                <code class="item-meta">&lt;{{ item.tag }}&gt;</code>
+              </div>
+            </button>
+          </div>
+        </template>
       </div>
 
       <!-- DETAIL view — visible when a component is selected. A Back button
@@ -212,6 +473,32 @@ function componentTooltip(lib: string, c: LibraryComponent): string {
           </div>
         </div>
 
+        <!-- Live preview — offscreen render snapshot. Draggable to place. -->
+        <div class="detail-section">
+          <div class="ds-label">Preview</div>
+          <div
+            class="detail-preview"
+            draggable="true"
+            title="Drag onto the app to place"
+            @dragstart="onDragStart($event, componentDragItem(cl.selectedLibrary.value ?? '', cl.selectedComponent.value))"
+            @dragend="onDragEnd"
+          >
+            <div v-if="previewState.loading" class="detail-preview-state">Rendering preview…</div>
+            <img
+              v-else-if="previewState.result?.dataUrl"
+              class="detail-preview-img"
+              :src="previewState.result.dataUrl"
+              :alt="`Preview of ${cl.selectedComponent.value.name}`"
+            />
+            <div v-else class="detail-preview-state placeholder">
+              <Icon name="package" :size="20" />
+              <div class="dp-name">{{ cl.selectedComponent.value.name }}</div>
+              <div class="dp-reason">{{ previewPlaceholderText(previewState.result) }}</div>
+            </div>
+            <div class="detail-preview-hint"><Icon name="mouse-pointer" :size="11" /> Drag onto the app to place</div>
+          </div>
+        </div>
+
         <!-- Props -->
         <div v-if="cl.selectedComponent.value.props.length" class="detail-section">
           <div class="ds-label">Props <span class="ds-hint">({{ cl.selectedComponent.value.props.length }})</span></div>
@@ -478,9 +765,10 @@ function componentTooltip(lib: string, c: LibraryComponent): string {
   border-bottom: 1px solid var(--border);
   background: transparent;
   color: var(--text);
-  cursor: pointer;
+  cursor: grab;
   font-size: 12px;
 }
+.components-list-item:active { cursor: grabbing; }
 .components-list-item:hover { background: var(--surface-2); }
 .components-list-item.selected { background: color-mix(in srgb, var(--accent) 15%, transparent); }
 .components-list-item.focused {
@@ -510,6 +798,16 @@ function componentTooltip(lib: string, c: LibraryComponent): string {
   text-decoration: line-through;
   color: var(--text-muted);
 }
+.item-info-btn {
+  display: inline-flex;
+  align-items: center;
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  padding: 0 2px;
+}
+.item-info-btn:hover { color: var(--text); }
 .item-used {
   font-size: 9px;
   padding: 1px 4px;
@@ -793,4 +1091,208 @@ function componentTooltip(lib: string, c: LibraryComponent): string {
   padding: 1px 5px;
   border-radius: 3px;
 }
+
+/* ── Palette merge: build button, drag affordances, fidelity badges ── */
+.components-btn.build {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  border-color: var(--accent);
+  background: var(--accent);
+  color: var(--text-on-accent, #fff);
+  font-weight: 600;
+}
+.components-btn.build:hover:not(:disabled) { background: var(--accent-hover, var(--accent)); }
+.build-count {
+  min-width: 14px;
+  padding: 0 4px;
+  border-radius: 8px;
+  background: color-mix(in srgb, #000 22%, transparent);
+  font-size: 10px;
+  text-align: center;
+}
+
+/* ── Placements panel (lifecycle of this route's wireframe instances) ── */
+.placements-panel {
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+  max-height: 180px;
+  overflow-y: auto;
+}
+.placements-head {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  padding: 6px 12px 4px;
+}
+.placements-title {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-muted);
+  font-weight: 600;
+}
+.placements-summary {
+  font-size: 10px;
+  color: var(--text-muted);
+}
+.placement-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 3px 12px;
+  font-size: 11px;
+}
+.placement-row:hover { background: var(--surface-2); }
+.placement-name {
+  font-family: var(--font-mono, monospace);
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+  flex: 1;
+}
+.placement-status {
+  font-size: 9px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  font-weight: 600;
+}
+.placement-status[data-status="placed"] {
+  background: color-mix(in srgb, var(--status-pending) 20%, transparent);
+  color: var(--status-pending);
+}
+.placement-status[data-status="building"] {
+  background: color-mix(in srgb, var(--status-in-progress) 20%, transparent);
+  color: var(--status-in-progress);
+}
+.placement-status[data-status="applied"] {
+  background: color-mix(in srgb, var(--status-accepted) 20%, transparent);
+  color: var(--status-accepted);
+}
+.placement-fidelity {
+  font-size: 9px;
+  color: var(--text-muted);
+}
+.placement-stale {
+  font-size: 9px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: color-mix(in srgb, var(--warning) 20%, transparent);
+  color: var(--warning);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  font-weight: 600;
+}
+.placement-delete {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 2px;
+  background: transparent;
+  border: none;
+  border-radius: 3px;
+  color: var(--text-muted);
+  cursor: pointer;
+}
+.placement-delete:hover {
+  color: var(--danger);
+  background: color-mix(in srgb, var(--danger) 12%, transparent);
+}
+
+.lib-group-head.static {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  padding: 4px 8px;
+  cursor: default;
+}
+
+.item-glyph { color: var(--text-muted); flex: 0 0 auto; }
+.item-meta {
+  margin-left: auto;
+  color: var(--text-muted);
+  font-size: 10px;
+  font-family: var(--font-mono, monospace);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 50%;
+}
+
+.item-fidelity {
+  flex: 0 0 auto;
+  font-size: 9px;
+  font-weight: 600;
+  line-height: 1;
+  padding: 2px 5px;
+  border-radius: 6px;
+  color: var(--text-on-accent, #fff);
+}
+.item-fidelity.fid-live { background: var(--success); }
+.item-fidelity.fid-isolated-preview { background: var(--warning); }
+.item-fidelity.fid-placeholder,
+.item-fidelity.fid-unknown { background: var(--role-component); }
+
+/* Component lives in another MFE — can't render a live snapshot here. */
+.item-mfe-na {
+  flex: 0 0 auto;
+  font-size: 9px;
+  font-weight: 600;
+  line-height: 1;
+  padding: 2px 5px;
+  border-radius: 6px;
+  background: color-mix(in srgb, var(--text-muted) 22%, transparent);
+  color: var(--text-muted);
+}
+.components-list-item.unavailable { opacity: 0.55; cursor: not-allowed; }
+.components-list-item.unavailable:hover { border-color: var(--border); }
+
+/* Detail live preview */
+.detail-preview {
+  position: relative;
+  border: 1px dashed var(--border-strong);
+  border-radius: 8px;
+  background:
+    linear-gradient(45deg, var(--surface-2) 25%, transparent 25%, transparent 75%, var(--surface-2) 75%) 0 0 / 16px 16px,
+    var(--surface);
+  padding: 12px;
+  min-height: 80px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  cursor: grab;
+}
+.detail-preview:active { cursor: grabbing; }
+.detail-preview-img {
+  max-width: 100%;
+  max-height: 260px;
+  border-radius: 4px;
+  box-shadow: 0 1px 6px var(--shadow, rgba(0,0,0,0.2));
+  background: #fff;
+}
+.detail-preview-state {
+  color: var(--text-muted);
+  text-align: center;
+  font-size: 11px;
+}
+.detail-preview-state.placeholder { display: flex; flex-direction: column; align-items: center; gap: 4px; color: var(--text-muted); }
+.dp-name { font-size: 12px; font-weight: 600; color: var(--text); }
+.dp-reason { max-width: 260px; line-height: 1.4; }
+.detail-preview-hint {
+  position: absolute;
+  bottom: 4px;
+  right: 6px;
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  font-size: 9px;
+  color: var(--text-muted);
+  opacity: 0.8;
+}
 </style>
diff --git a/src/shell/components/ConfirmDialog.vue b/src/shell/components/ConfirmDialog.vue
index 057f2bb..0cd1379 100644
--- a/src/shell/components/ConfirmDialog.vue
+++ b/src/shell/components/ConfirmDialog.vue
@@ -36,7 +36,7 @@ onUnmounted(() => window.removeEventListener('keydown', onKeydown))
 <style scoped>
 .confirm-backdrop {
   position: fixed; inset: 0; z-index: 100000;
-  background: rgba(0, 0, 0, 0.5);
+  background: var(--overlay);
   display: flex; align-items: center; justify-content: center;
 }
 .confirm-dialog {
@@ -45,7 +45,7 @@ onUnmounted(() => window.removeEventListener('keydown', onKeydown))
   border-radius: 10px;
   padding: 20px 24px;
   width: 320px;
-  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  box-shadow: 0 8px 32px var(--shadow);
 }
 .confirm-message {
   font-size: 13px; color: var(--text, #e4e4e7);
@@ -64,7 +64,7 @@ onUnmounted(() => window.removeEventListener('keydown', onKeydown))
 }
 .confirm-cancel:hover { background: var(--border, #333); color: var(--text, #e4e4e7); }
 .confirm-ok {
-  background: rgba(239, 68, 68, 0.15); color: #ef4444;
+  background: color-mix(in srgb, var(--danger) 15%, transparent); color: var(--danger);
 }
-.confirm-ok:hover { background: #ef4444; color: white; }
+.confirm-ok:hover { background: var(--danger); color: var(--text-on-accent); }
 </style>
diff --git a/src/shell/components/ConversationMessage.vue b/src/shell/components/ConversationMessage.vue
new file mode 100644
index 0000000..b55ecb7
--- /dev/null
+++ b/src/shell/components/ConversationMessage.vue
@@ -0,0 +1,172 @@
+<script setup lang="ts">
+/**
+ * Renders one ThreadMessage in the Conversation work-stream.
+ *
+ * Two surfaces:
+ *   - `blocks` (preferred) → walks the work-stream timeline. Pairs each
+ *     tool_call with its corresponding tool_result by id so each pair is one
+ *     expandable row. Streaming turns can pass `streaming: true` to mark the
+ *     tail block.
+ *   - `content` fallback → legacy turns from before the work-stream existed,
+ *     plus user / system / tool messages that don't have a block list.
+ *     Rendered as markdown (assistant/user) or plain text (system/tool).
+ */
+import { computed } from 'vue'
+import ConversationStreamBlock from './ConversationStreamBlock.vue'
+import { safeMd } from '../utils/safeMd'
+import type { WorkStreamBlock } from '../../shared/work-stream'
+
+interface Props {
+  role: 'user' | 'assistant' | 'system' | 'tool'
+  /** Work-stream timeline. When provided, takes precedence over `content`. */
+  blocks?: WorkStreamBlock[]
+  /** Flat-text fallback for messages without blocks. */
+  content?: string
+  /** Tail block on an in-flight turn gets a blinking cursor. */
+  streaming?: boolean
+  providerLabel?: string
+  modelLabel?: string
+  ts?: number
+}
+
+const props = withDefaults(defineProps<Props>(), { streaming: false, content: '' })
+
+const html = computed(() => {
+  if (props.streaming) return ''
+  if (props.role === 'system' || props.role === 'tool') return ''
+  try { return safeMd(props.content) }
+  catch { return '' }
+})
+
+const fallbackText = computed(() => {
+  if (props.streaming) return props.content
+  if (props.role === 'system' || props.role === 'tool') return props.content
+  return ''
+})
+
+const tsLabel = computed(() => {
+  if (!props.ts) return ''
+  try { return new Date(props.ts).toLocaleTimeString() } catch { return '' }
+})
+
+const roleLabel = computed(() => {
+  if (props.role === 'assistant') return 'Agent output'
+  return props.role
+})
+
+/**
+ * Walk the block list and produce a render plan: each tool_call has its
+ * paired tool_result inlined; standalone results (those without a prior
+ * call in the list) render on their own. Avoids two redundant rows when
+ * the timeline goes call → result.
+ */
+const renderPlan = computed(() => {
+  const blocks = props.blocks ?? []
+  const resultByCallId = new Map<string, Extract<WorkStreamBlock, { kind: 'tool_result' }>>()
+  for (const b of blocks) {
+    if (b.kind === 'tool_result') resultByCallId.set(b.toolUseId, b)
+  }
+  const out: Array<{ block: WorkStreamBlock; paired?: Extract<WorkStreamBlock, { kind: 'tool_result' }>; key: string }> = []
+  const consumedResults = new Set<string>()
+  blocks.forEach((b, idx) => {
+    if (b.kind === 'tool_call') {
+      const paired = resultByCallId.get(b.id)
+      if (paired) consumedResults.add(b.id)
+      out.push({ block: b, paired, key: `c-${b.id}-${idx}` })
+    } else if (b.kind === 'tool_result') {
+      if (consumedResults.has(b.toolUseId)) return // already shown inline
+      out.push({ block: b, key: `r-${b.toolUseId}-${idx}` })
+    } else {
+      out.push({ block: b, key: `b-${idx}` })
+    }
+  })
+  return out
+})
+
+const lastIndex = computed(() => renderPlan.value.length - 1)
+</script>
+
+<template>
+  <div class="cv-msg" :class="`role-${role}`">
+    <div class="cv-msg-meta">
+      <span class="cv-msg-role">{{ roleLabel }}</span>
+      <span v-if="providerLabel" class="cv-msg-provider">{{ providerLabel }}</span>
+      <span v-if="modelLabel" class="cv-msg-model">{{ modelLabel }}</span>
+      <span v-if="tsLabel" class="cv-msg-ts">{{ tsLabel }}</span>
+    </div>
+    <div class="cv-msg-body">
+      <!-- Preferred: render the block timeline. Each entry is a step. -->
+      <template v-if="renderPlan.length > 0">
+        <ConversationStreamBlock
+          v-for="(entry, i) in renderPlan"
+          :key="entry.key"
+          :block="entry.block"
+          :paired-result="entry.paired"
+          :streaming="streaming && i === lastIndex && entry.block.kind === 'text'"
+        />
+      </template>
+      <!-- Legacy fallback: a single content string. -->
+      <template v-else>
+        <div v-if="html" class="cv-msg-markdown" v-html="html" />
+        <div v-else class="cv-msg-text">{{ fallbackText }}<span v-if="streaming" class="cv-cursor">▋</span></div>
+      </template>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.cv-msg {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 10px 12px;
+  border-radius: 8px;
+  background: var(--surface-2);
+}
+.cv-msg.role-user { background: color-mix(in srgb, var(--accent) 10%, var(--surface-2)); }
+.cv-msg.role-assistant { background: var(--surface-2); }
+.cv-msg.role-system,
+.cv-msg.role-tool { background: var(--surface); font-style: italic; }
+
+.cv-msg-meta {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  font-size: 10px;
+  color: var(--text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+.cv-msg-role { font-weight: 700; color: var(--text); }
+.cv-msg-provider,
+.cv-msg-model,
+.cv-msg-ts { font-weight: 500; }
+
+.cv-msg-body { font-size: 13px; color: var(--text); line-height: 1.55; display: flex; flex-direction: column; gap: 8px; }
+.cv-msg-text { white-space: pre-wrap; word-break: break-word; }
+
+:deep(.cv-msg-markdown p) { margin: 0 0 8px; }
+:deep(.cv-msg-markdown p:last-child) { margin-bottom: 0; }
+:deep(.cv-msg-markdown pre) {
+  background: var(--surface-3);
+  border-radius: 4px;
+  padding: 8px 10px;
+  overflow-x: auto;
+  font-size: 12px;
+}
+:deep(.cv-msg-markdown code) {
+  background: var(--surface-3);
+  border-radius: 3px;
+  padding: 1px 4px;
+  font-size: 12px;
+}
+:deep(.cv-msg-markdown pre code) { background: transparent; padding: 0; }
+
+.cv-cursor {
+  display: inline-block;
+  margin-left: 1px;
+  color: var(--accent);
+  animation: cv-blink 1s steps(2) infinite;
+}
+@keyframes cv-blink { to { opacity: 0; } }
+</style>
diff --git a/src/shell/components/ConversationStreamBlock.vue b/src/shell/components/ConversationStreamBlock.vue
new file mode 100644
index 0000000..0b53431
--- /dev/null
+++ b/src/shell/components/ConversationStreamBlock.vue
@@ -0,0 +1,247 @@
+<script setup lang="ts">
+/**
+ * One block in a Conversation work-stream timeline.
+ *
+ * Three kinds today:
+ *   - `text`         → markdown bubble (assistant prose).
+ *   - `tool_call`    → row with a status dot + human summary; expandable for raw input JSON.
+ *   - `tool_result`  → row with a short output preview; expandable for full raw content. Tinted red on isError.
+ *   - `agent_question` → read-only banner pointing to the inline answer composer.
+ *
+ * Tool calls auto-pair with their tool_result by `id` — the parent passes
+ * the result alongside so this component can render the call's pending /
+ * completed state in one row without a second component.
+ */
+import { computed, ref } from 'vue'
+import Icon from './Icon.vue'
+import { safeMd } from '../utils/safeMd'
+import type { WorkStreamBlock } from '../../shared/work-stream'
+
+interface Props {
+  block: WorkStreamBlock
+  /** When true, this is the tail block on an in-flight turn (drives cursor + dot). */
+  streaming?: boolean
+  /** Optional paired tool_result for tool_call rendering (call/result one row). */
+  pairedResult?: Extract<WorkStreamBlock, { kind: 'tool_result' }>
+}
+
+const props = withDefaults(defineProps<Props>(), { streaming: false })
+const expanded = ref(false)
+
+const markdown = computed(() => {
+  if (props.block.kind !== 'text') return ''
+  try { return safeMd(props.block.text) }
+  catch { return '' }
+})
+
+const toolInputJson = computed(() => {
+  if (props.block.kind !== 'tool_call') return ''
+  try { return JSON.stringify(props.block.input, null, 2) }
+  catch { return String(props.block.input) }
+})
+
+const hasPairedResult = computed(() =>
+  props.block.kind === 'tool_call' && !!props.pairedResult,
+)
+</script>
+
+<template>
+  <!-- TEXT — markdown prose. Streaming tail gets a blinking cursor. -->
+  <div v-if="block.kind === 'text'" class="csb-text">
+    <div class="csb-markdown" v-html="markdown" />
+    <span v-if="streaming" class="csb-cursor">▋</span>
+  </div>
+
+  <!-- TOOL CALL — collapsed row with summary; expand to see raw JSON.
+       If a tool_result has already arrived, show "complete"; else "pending". -->
+  <div v-else-if="block.kind === 'tool_call'" class="csb-tool-row">
+    <button
+      type="button"
+      class="csb-tool-head"
+      :class="{ pending: !hasPairedResult, error: pairedResult?.isError }"
+      :data-testid="`tool-call-${block.id}`"
+      @click="expanded = !expanded"
+    >
+      <span class="csb-tool-dot" :class="{ pulse: !hasPairedResult }" />
+      <Icon name="wand" :size="11" />
+      <span class="csb-tool-summary">{{ block.summary }}</span>
+      <Icon :name="expanded ? 'chevron-down' : 'chevron-right'" :size="11" class="csb-tool-chev" />
+    </button>
+    <div v-if="expanded" class="csb-tool-body">
+      <div class="csb-tool-label">Input</div>
+      <pre class="csb-tool-pre">{{ toolInputJson }}</pre>
+      <template v-if="pairedResult">
+        <div class="csb-tool-label">
+          {{ pairedResult.isError ? 'Error' : 'Output' }}
+        </div>
+        <pre class="csb-tool-pre">{{ pairedResult.raw || '(empty)' }}</pre>
+      </template>
+    </div>
+  </div>
+
+  <!-- TOOL RESULT — only rendered when NOT already absorbed into the call row.
+       Parent passes `pairedResult` to suppress, so this is a no-op when paired. -->
+  <div v-else-if="block.kind === 'tool_result'" class="csb-tool-row">
+    <button
+      type="button"
+      class="csb-tool-head"
+      :class="{ error: block.isError }"
+      @click="expanded = !expanded"
+    >
+      <span class="csb-tool-dot" :class="{ error: block.isError }" />
+      <Icon name="check" :size="11" />
+      <span class="csb-tool-summary">{{ block.summary }}</span>
+      <Icon :name="expanded ? 'chevron-down' : 'chevron-right'" :size="11" class="csb-tool-chev" />
+    </button>
+    <div v-if="expanded" class="csb-tool-body">
+      <pre class="csb-tool-pre">{{ block.raw || '(empty)' }}</pre>
+    </div>
+  </div>
+
+  <!-- AGENT QUESTION — read-only banner that points to the inline composer. -->
+  <div v-else-if="block.kind === 'agent_question'" class="csb-question">
+    <Icon name="circle-help" :size="13" />
+    <div>
+      <div class="csb-question-label">Agent paused for input</div>
+      <div class="csb-question-text">{{ block.label }}</div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.csb-text {
+  font-size: 13px;
+  color: var(--text);
+  line-height: 1.55;
+  word-break: break-word;
+}
+:deep(.csb-markdown p) { margin: 0 0 8px; }
+:deep(.csb-markdown p:last-child) { margin-bottom: 0; }
+:deep(.csb-markdown pre) {
+  background: var(--surface-3);
+  border-radius: 4px;
+  padding: 8px 10px;
+  overflow-x: auto;
+  font-size: 12px;
+}
+:deep(.csb-markdown code) {
+  background: var(--surface-3);
+  border-radius: 3px;
+  padding: 1px 4px;
+  font-size: 12px;
+}
+:deep(.csb-markdown pre code) { background: transparent; padding: 0; }
+
+.csb-cursor {
+  display: inline-block;
+  margin-left: 1px;
+  color: var(--accent);
+  animation: csb-blink 1s steps(2) infinite;
+}
+@keyframes csb-blink { to { opacity: 0; } }
+
+.csb-tool-row {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.csb-tool-head {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 8px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  cursor: pointer;
+  font: inherit;
+  font-size: 12px;
+  color: var(--text);
+  text-align: left;
+}
+.csb-tool-head:hover { background: var(--surface-3); }
+.csb-tool-head.error {
+  border-color: color-mix(in srgb, var(--danger) 60%, var(--border));
+  background: color-mix(in srgb, var(--danger) 8%, var(--surface-2));
+}
+
+.csb-tool-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--success);
+  flex: 0 0 auto;
+}
+.csb-tool-dot.error { background: var(--danger); }
+.csb-tool-dot.pulse {
+  background: var(--accent);
+  animation: csb-pulse 1.2s ease-in-out infinite;
+}
+@keyframes csb-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.35; }
+}
+
+.csb-tool-summary {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.csb-tool-chev { color: var(--text-muted); flex: 0 0 auto; }
+
+.csb-tool-body {
+  padding: 6px 8px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  margin-left: 14px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.csb-tool-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-muted);
+  font-weight: 600;
+}
+.csb-tool-pre {
+  margin: 0;
+  background: var(--surface-3);
+  border-radius: 4px;
+  padding: 8px 10px;
+  font-size: 11.5px;
+  line-height: 1.45;
+  max-height: 320px;
+  overflow: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.csb-question {
+  display: flex;
+  gap: 8px;
+  align-items: flex-start;
+  padding: 8px 10px;
+  border: 1px solid color-mix(in srgb, var(--warning) 40%, var(--border));
+  background: color-mix(in srgb, var(--warning) 8%, transparent);
+  border-radius: 4px;
+}
+.csb-question-label {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--warning);
+}
+.csb-question-text {
+  font-size: 12.5px;
+  color: var(--text);
+  line-height: 1.5;
+  margin-top: 2px;
+}
+</style>
diff --git a/src/shell/components/ConversationTab.vue b/src/shell/components/ConversationTab.vue
new file mode 100644
index 0000000..0b88ca2
--- /dev/null
+++ b/src/shell/components/ConversationTab.vue
@@ -0,0 +1,818 @@
+<script setup lang="ts">
+/**
+ * Conversation tab — per-task work-stream observer.
+ *
+ * Renders the agent's live timeline (text + tool calls + tool results) as
+ * the agent works, plus persisted past turns. The composer is for steering
+ * (queue for next turn), not free-form chat — happy-path users never need
+ * to type here.
+ */
+import { ref, watch, computed, onMounted, onBeforeUnmount, nextTick } from 'vue'
+import Icon from './Icon.vue'
+import ConversationMessage from './ConversationMessage.vue'
+import ConversationStreamBlock from './ConversationStreamBlock.vue'
+import TaskAgentFeedback from './TaskAgentFeedback.vue'
+import { useTaskThread, useAgentDetect, fetchAgentDetect } from '../composables/useTaskThread'
+import { useEmbeddedAgent } from '../composables/useEmbeddedAgent'
+import { useWorkingIndicator } from '../composables/useWorkingIndicator'
+import { useProviderSettings } from '../composables/useProviderSettings'
+import { consumeAutoRun } from '../composables/useAgentMode'
+import { requestAutoRunCancel } from '../composables/useAutoRunDriver'
+import { resolveEffectivePermissionMode, NATIVE_PLAN_PROVIDERS } from '../../embedded/permission-mode'
+import { formatTokens } from '../services/embeddedAgent/pricing'
+import type { PermissionMode } from '../../schema'
+import type { Task } from '../composables/useTasks'
+
+interface Props { task: Task }
+const props = defineProps<Props>()
+const emit = defineEmits<{
+  (e: 'open-settings'): void
+  /** Forwarded up to TaskDetailModal → App.vue → respondToAgent. Same
+   *  contract as TaskAgentFeedback's `reply` event. */
+  (e: 'reply', taskId: string, answers: Array<{ id: string; value: string }>): void
+  /** Per-task field patch. Forwarded to TaskDetailModal which already
+   *  brokers the same event up to the App-level PATCH handler. */
+  (e: 'update', taskId: string, fields: Record<string, unknown>): void
+}>()
+
+const thread = useTaskThread()
+const agent = useEmbeddedAgent(thread)
+
+/** Re-open the thread stream after the SSE connection gave up (B3). */
+function retryThread() {
+  if (props.task.id) void thread.open(props.task.id)
+}
+const providerSettings = useProviderSettings()
+const detect = useAgentDetect()
+
+// Permission-mode indicator. Mirrors the resolver in useEmbeddedAgent so the
+// chip always shows the mode the next turn will actually run with. Uses the
+// persona-resolved active provider so the provider-tier override (set in
+// Settings → Agents → provider settings) is honored even when the persona
+// routes to a different provider than the global active one.
+const effectivePermissionMode = computed<PermissionMode>(() => {
+  const taskMode = (props.task as { permissionMode?: PermissionMode }).permissionMode
+  const persona = providerSettings.getPersonaForTaskType(props.task.type)
+  const activeProviderId = persona?.providerId ?? providerSettings.activeProvider.value
+  const providerCfg = providerSettings.settings.value.providers[activeProviderId]
+  const providerMode = (providerCfg as { permissionMode?: PermissionMode }).permissionMode
+  return resolveEffectivePermissionMode(
+    taskMode,
+    providerMode,
+    providerSettings.settings.value.permissionMode,
+  )
+})
+
+/** Providers with native plan enforcement (CLI/sandbox-level). */
+
+const PERMISSION_MODE_TOOLTIPS: Record<PermissionMode, string> = {
+  default: 'Default — the CLI asks before non-trivial actions. In headless mode, refused ops surface as failed tool calls.',
+  plan: 'Plan — read-only. The agent can investigate but not write. Enforced via CLI/sandbox + system-prompt directive.',
+  bypass: 'Bypass — every action auto-approves. Fastest, riskiest.',
+}
+const permissionModeTooltip = computed(() => {
+  if (effectivePermissionMode.value !== 'plan') return PERMISSION_MODE_TOOLTIPS[effectivePermissionMode.value]
+  const persona = providerSettings.getPersonaForTaskType(props.task.type)
+  const activeProviderId = persona?.providerId ?? providerSettings.activeProvider.value
+  if (NATIVE_PLAN_PROVIDERS.has(activeProviderId)) return PERMISSION_MODE_TOOLTIPS.plan
+  return 'Plan (best-effort) — read-only enforced via model directive only. This provider has no native CLI/sandbox plan mode.'
+})
+
+// Inline permission-mode picker on the chip — lets the user flip the
+// per-task override from the Conversation tab when an agent gets stuck
+// without bouncing them back to the Details tab.
+const permPopoverOpen = ref(false)
+const PERMISSION_MODE_MENU: ReadonlyArray<{ id: PermissionMode; hint: string }> = [
+  { id: 'default', hint: 'Ask for non-trivial actions' },
+  { id: 'plan',    hint: 'Read-only' },
+  { id: 'bypass',  hint: 'Auto-approve everything' },
+]
+const currentTaskPermissionMode = computed<PermissionMode | undefined>(
+  () => (props.task as { permissionMode?: PermissionMode }).permissionMode,
+)
+function setTaskPermissionMode(mode: PermissionMode | null) {
+  permPopoverOpen.value = false
+  emit('update', props.task.id, { permissionMode: mode })
+}
+function onDocumentClick(ev: MouseEvent) {
+  if (!permPopoverOpen.value) return
+  const target = ev.target as HTMLElement | null
+  if (target && target.closest('.cv-perm-wrap')) return
+  permPopoverOpen.value = false
+}
+
+// Show the working indicator whenever the embedded agent is streaming OR
+// the task itself is in_progress — covers CLI / external-runner flows where
+// nothing streams locally but an agent is still working on the task.
+const isWorking = computed(() => agent.running.value || props.task.status === 'in_progress')
+
+// The currently-streaming assistant turn, persisted on the thread. Present
+// whether *this* tab owns the run or it's a headless/auto run we're only
+// observing — so it's the reliable source for the run-start anchor and the
+// live block timeline in an observer tab.
+const livePartial = computed(() => thread.messages.value.find((m) => m.isPartial))
+
+// Past turns to render in the persisted list — exclude the in-flight partial,
+// which is rendered separately as the live turn below (so we don't show it
+// twice in the tab that owns the run).
+const displayMessages = computed(() => thread.messages.value.filter((m) => !m.isPartial))
+
+// Live block timeline: prefer this instance's smooth `currentBlocks` when it
+// owns the run; otherwise fall back to the persisted partial's blocks so an
+// observer tab still streams (throttled) instead of seeing nothing.
+const liveBlocks = computed(() =>
+  agent.currentBlocks.value.length > 0
+    ? agent.currentBlocks.value
+    : (livePartial.value?.blocks ?? []),
+)
+
+// Anchor the elapsed timer to the persisted run start so it survives tab
+// remounts and is correct for a tab that attached mid-run.
+const runStartedAt = computed<number | null>(() => livePartial.value?.ts ?? null)
+const working = useWorkingIndicator(isWorking, runStartedAt)
+
+// "Stalled?" hint: the partial turn hasn't produced output for longer than the
+// idle-timeout window (so the watchdog should be about to fire / has fired).
+const ticker = ref(Date.now())
+let tickerTimer: ReturnType<typeof setInterval> | null = null
+const stalled = computed(() => {
+  const idleMs = providerSettings.settings.value.idleTimeoutMs
+  if (idleMs <= 0 || !isWorking.value) return false
+  const last = livePartial.value?.lastEventAt
+  if (typeof last !== 'number') return false
+  return ticker.value - last > idleMs
+})
+
+function cancelRun() {
+  // Cancel a run we own locally AND a headless run owned by the auto-run
+  // driver (the local agent in this tab isn't the one streaming for an
+  // observed auto run).
+  agent.abort()
+  requestAutoRunCancel(props.task.id)
+}
+
+// Auto-load the per-task transcript whenever the bound task changes.
+// If this task was queued for auto-run, fire the first turn with the task
+// description here too — covers the "manually opened mid-run" case where
+// the auto-run driver hasn't claimed the queue yet.
+watch(
+  () => props.task.id,
+  async (id) => {
+    if (!id) return
+    await thread.open(id)
+    await nextTick()
+    scrollToBottom()
+    if (consumeAutoRun(id) && !agent.running.value && thread.messages.value.length === 0) {
+      const seed = (props.task.description ?? '').trim()
+      if (seed.length > 0) {
+        // Seed kick: prompt = task description. The composable also flips
+        // the task into in_progress / review around this turn. Free-form
+        // composer submits later DON'T set isSeed.
+        agent.send(seed, { isSeed: true }).catch(() => { /* surfaced via agent.errorMessage */ })
+      }
+    }
+  },
+  { immediate: true },
+)
+
+onMounted(() => {
+  fetchAgentDetect()
+  document.addEventListener('click', onDocumentClick, true)
+  // Drive the "stalled?" check off a 1s ticker (cheap; only matters while a
+  // run is in flight).
+  tickerTimer = setInterval(() => { ticker.value = Date.now() }, 1000)
+})
+onBeforeUnmount(() => {
+  thread.close()
+  document.removeEventListener('click', onDocumentClick, true)
+  if (tickerTimer) { clearInterval(tickerTimer); tickerTimer = null }
+})
+
+// Token tally combines persisted history (so totals survive reload) with
+// the in-flight `agent.usage` accumulator for the current turn.
+const tokenSummary = computed(() => {
+  let input = agent.usage.value.input
+  let output = agent.usage.value.output
+  for (const m of thread.messages.value) {
+    if (m.usage) {
+      input += m.usage.inputTokens || 0
+      output += m.usage.outputTokens || 0
+    }
+  }
+  return {
+    input: formatTokens(input),
+    output: formatTokens(output),
+    hasUsage: input > 0 || output > 0,
+  }
+})
+
+// Persona pinned to this task type wins over the global active provider —
+// otherwise the header label lies when a persona overrides the provider
+// (e.g. user picked opencode-local for `style_update` while the global
+// active provider is still claude-local).
+const taskPersona = computed(() => providerSettings.getPersonaForTaskType(props.task.type))
+const activeProvider = computed(() =>
+  taskPersona.value?.providerId ?? providerSettings.activeProvider.value,
+)
+const activeModel = computed(() => {
+  const persona = taskPersona.value
+  if (persona && persona.model.length > 0) return persona.model
+  return providerSettings.settings.value.providers[activeProvider.value]?.model || ''
+})
+
+const localCliBlocked = computed(() => {
+  const id = activeProvider.value
+  if (id !== 'claude-local' && id !== 'codex-local' && id !== 'opencode-local' && id !== 'copilot-local') return null
+  const snap = detect.snapshot.value
+  if (!snap) return null
+  const status = snap[id]
+  if (!status.found) return `${id} CLI not installed on PATH`
+  if (!status.loggedIn) return `${id} CLI is installed but not logged in`
+  return null
+})
+
+const composer = ref('')
+const scrollerEl = ref<HTMLElement | null>(null)
+
+function scrollToBottom() {
+  const el = scrollerEl.value
+  if (!el) return
+  el.scrollTop = el.scrollHeight
+}
+
+// Auto-scroll on three signals: new persisted messages, in-flight block
+// growth, and queued-message changes. Block-list length is a cheap proxy
+// for "something happened" without watching deep into each block.
+watch(
+  () => [
+    thread.messages.value.length,
+    liveBlocks.value.length,
+    agent.queuedMessages.value.length,
+  ],
+  async () => { await nextTick(); scrollToBottom() },
+)
+
+async function onSubmit() {
+  const text = composer.value
+  if (!text.trim()) return
+  composer.value = ''
+  // The composable handles the queue/idle branch internally. We don't await
+  // so the composer stays interactive even when a turn is already running.
+  agent.send(text).catch(() => { /* surfaced via agent.errorMessage */ })
+}
+
+function onComposerKey(e: KeyboardEvent) {
+  if (e.key === 'Enter' && !e.shiftKey && !e.isComposing) {
+    e.preventDefault()
+    onSubmit()
+  }
+}
+
+const composerDisabled = computed(() => !!localCliBlocked.value)
+
+/**
+ * The task transitioned to `needs_info` and there's an unanswered
+ * `agent_feedback` entry. While in this state the composer swaps to the
+ * inline answer form (TaskAgentFeedback) and the regular chat composer
+ * is hidden — answering is the only useful action and routes through the
+ * existing `respondToAgent` flow.
+ */
+const pendingFeedbackEntry = computed(() => {
+  if (props.task.status !== 'needs_info') return null
+  const fb = props.task.agent_feedback ?? []
+  if (fb.length === 0) return null
+  const last = fb[fb.length - 1]
+  return last.answered_at ? null : last
+})
+
+const inAnswerMode = computed(() => pendingFeedbackEntry.value !== null)
+
+/** Synthetic block surfaced inline so the work-stream shows the pause. */
+const agentQuestionBlock = computed(() => {
+  const entry = pendingFeedbackEntry.value
+  if (!entry) return null
+  const fb = props.task.agent_feedback ?? []
+  const entryIndex = fb.length - 1
+  // Prefer the entry's `message`; fall back to the first question text so
+  // the inline label is never empty.
+  const label =
+    (typeof entry.message === 'string' && entry.message.trim())
+    || entry.questions[0]?.text
+    || 'Agent needs more info.'
+  return { kind: 'agent_question' as const, entryIndex, label }
+})
+
+function onReply(answers: Array<{ id: string; value: string }>) {
+  emit('reply', props.task.id, answers)
+}
+</script>
+
+<template>
+  <div class="cv-tab">
+    <header class="cv-header">
+      <div class="cv-header-left">
+        <Icon name="bot" :size="13" />
+        <span class="cv-provider">{{ activeProvider }}</span>
+        <span v-if="activeModel" class="cv-model">· {{ activeModel }}</span>
+        <span v-if="isWorking" class="cv-running" :class="{ stalled }" aria-live="polite">
+          <span class="cv-running-dot" />
+          <span class="cv-running-verb">
+            {{ stalled ? 'Stalled?' : (working.verb.value ?? 'Annotasking') }}<span v-if="!stalled" class="cv-running-dots" aria-hidden="true" />
+          </span>
+          <span class="cv-running-elapsed">{{ working.seconds.value }}s</span>
+          <button
+            type="button"
+            class="cv-cancel"
+            title="Cancel this run"
+            data-testid="cv-cancel-run"
+            @click="cancelRun"
+          >
+            <Icon name="x" :size="11" /> Cancel
+          </button>
+        </span>
+      </div>
+      <div class="cv-header-right">
+        <div class="cv-perm-wrap">
+          <button
+            type="button"
+            class="cv-perm"
+            :class="`cv-perm-${effectivePermissionMode}`"
+            :title="permissionModeTooltip"
+            :aria-expanded="permPopoverOpen"
+            aria-haspopup="menu"
+            data-testid="cv-permission-mode"
+            @click="permPopoverOpen = !permPopoverOpen"
+          >
+            <Icon name="lock" :size="10" />
+            {{ effectivePermissionMode }}
+            <Icon name="chevron-down" :size="10" />
+          </button>
+          <div v-if="permPopoverOpen" class="cv-perm-menu" role="menu" @click.stop>
+            <button
+              type="button"
+              role="menuitem"
+              class="cv-perm-menuitem"
+              @click="setTaskPermissionMode(null)"
+            >
+              <span class="cv-perm-menuitem-label">Inherit</span>
+              <span class="cv-perm-menuitem-hint">Use persona / global ({{ effectivePermissionMode }})</span>
+            </button>
+            <button
+              v-for="m in PERMISSION_MODE_MENU"
+              :key="m.id"
+              type="button"
+              role="menuitem"
+              class="cv-perm-menuitem"
+              :class="{ active: currentTaskPermissionMode === m.id }"
+              @click="setTaskPermissionMode(m.id)"
+            >
+              <span class="cv-perm-menuitem-label">{{ m.id }}</span>
+              <span class="cv-perm-menuitem-hint">{{ m.hint }}</span>
+            </button>
+          </div>
+        </div>
+        <span
+          v-if="tokenSummary.hasUsage || isWorking"
+          class="cv-tokens"
+          title="Cumulative tokens this conversation"
+        >
+          {{ tokenSummary.input }} in · {{ tokenSummary.output }} out
+        </span>
+        <button class="cv-icon-btn" @click="emit('open-settings')" title="Open AI settings">
+          <Icon name="sliders-horizontal" :size="12" />
+        </button>
+      </div>
+    </header>
+
+    <div v-if="localCliBlocked" class="cv-banner danger">
+      <Icon name="triangle-alert" :size="12" />
+      <span>{{ localCliBlocked }}. Pick another provider in Settings → AI.</span>
+    </div>
+
+    <!-- Conversation-stream connection state. The agent's own run streams on a
+         separate channel, so this only reflects the read-only transcript feed. -->
+    <div v-if="thread.status.value === 'reconnecting'" class="cv-banner warning">
+      <Icon name="triangle-alert" :size="12" />
+      <span>Reconnecting to the conversation stream…</span>
+    </div>
+    <div v-else-if="thread.status.value === 'error' && thread.error.value" class="cv-banner danger">
+      <Icon name="triangle-alert" :size="12" />
+      <span>{{ thread.error.value }}</span>
+      <button type="button" class="cv-banner-retry" @click="retryThread">Retry</button>
+    </div>
+
+    <div ref="scrollerEl" class="cv-scroller">
+      <div v-if="thread.status.value === 'loading'" class="cv-empty">Loading conversation…</div>
+      <div v-else-if="displayMessages.length === 0 && liveBlocks.length === 0" class="cv-empty">
+        <Icon name="bot" :size="20" />
+        <p>The agent's work shows up here. If you need to steer, type a note — it'll send after the current step.</p>
+      </div>
+
+      <!-- Persisted past turns. Each may have a rich block timeline. The
+           in-flight partial turn is excluded here and rendered below. -->
+      <ConversationMessage
+        v-for="msg in displayMessages"
+        :key="msg.id"
+        :role="msg.role"
+        :content="msg.content"
+        :blocks="msg.blocks"
+        :provider-label="msg.providerId"
+        :model-label="msg.model"
+        :ts="msg.ts"
+      />
+
+      <!-- In-flight turn — streams the block timeline live. Uses this tab's
+           own `currentBlocks` when it owns the run, else the persisted
+           partial's blocks (observer / headless-run case). -->
+      <ConversationMessage
+        v-if="liveBlocks.length > 0"
+        role="assistant"
+        :blocks="liveBlocks"
+        :streaming="isWorking"
+        :provider-label="livePartial?.providerId ?? activeProvider"
+        :model-label="livePartial?.model ?? activeModel"
+      />
+
+      <!-- Agent paused for input — surface inline as a work-stream block so
+           the timeline shows where the agent stopped. The actual answer
+           composer lives below the queue (replaces the chat composer). -->
+      <ConversationStreamBlock
+        v-if="agentQuestionBlock"
+        :block="agentQuestionBlock"
+      />
+
+      <div v-if="agent.errorMessage.value" class="cv-error">
+        <Icon name="triangle-alert" :size="12" />
+        <span>{{ agent.errorMessage.value }}</span>
+      </div>
+    </div>
+
+    <!-- Queued user messages (steering). Each shows a × to cancel. -->
+    <div v-if="agent.queuedMessages.value.length > 0" class="cv-queue">
+      <div class="cv-queue-head">
+        <Icon name="clock" :size="11" />
+        <span>Queued — will send after current turn</span>
+      </div>
+      <div
+        v-for="(msg, i) in agent.queuedMessages.value"
+        :key="i"
+        class="cv-queue-item"
+      >
+        <span class="cv-queue-text">{{ msg }}</span>
+        <button
+          type="button"
+          class="cv-queue-cancel"
+          title="Cancel queued message"
+          @click="agent.cancelQueued(i)"
+        ><Icon name="x" :size="11" /></button>
+      </div>
+    </div>
+
+    <!-- Answer-mode: the chat composer is suppressed; the inline answer
+         form takes its place and routes through `respondToAgent` (same
+         backend path as the Details tab's TaskAgentFeedback). -->
+    <div v-if="inAnswerMode" class="cv-answer">
+      <TaskAgentFeedback
+        :feedback="props.task.agent_feedback ?? []"
+        :task-id="props.task.id"
+        @reply="onReply"
+      />
+    </div>
+
+    <form v-else class="cv-composer" @submit.prevent="onSubmit">
+      <textarea
+        v-model="composer"
+        class="cv-input"
+        rows="3"
+        :placeholder="
+          agent.running.value
+            ? 'Type a note to steer or clarify — will queue and send after current turn'
+            : 'Message the agent — Enter to send, Shift+Enter for newline'
+        "
+        :disabled="composerDisabled"
+        @keydown="onComposerKey"
+      />
+      <div class="cv-composer-actions">
+        <button v-if="agent.running.value" type="button" class="cv-abort" @click="agent.abort()">
+          <Icon name="x" :size="12" />
+          <span>Abort</span>
+        </button>
+        <button type="submit" class="cv-send" :disabled="composerDisabled || !composer.trim()">
+          <Icon :name="agent.running.value ? 'clock' : 'arrow-right'" :size="12" />
+          <span>{{ agent.running.value ? 'Queue' : 'Send' }}</span>
+        </button>
+      </div>
+    </form>
+  </div>
+</template>
+
+<style scoped>
+.cv-tab {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+}
+
+.cv-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+}
+.cv-header-left, .cv-header-right { display: flex; align-items: center; gap: 6px; font-size: 12px; }
+.cv-provider { font-weight: 600; color: var(--text); }
+.cv-model { color: var(--text-muted); }
+.cv-tokens { font-variant-numeric: tabular-nums; color: var(--text-muted); font-size: 11px; }
+
+.cv-perm-wrap { position: relative; }
+.cv-perm {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 2px 7px;
+  border-radius: 999px;
+  font: inherit;
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: lowercase;
+  letter-spacing: 0.02em;
+  border: 1px solid var(--border);
+  background: var(--surface-2);
+  color: var(--text-muted);
+  cursor: pointer;
+}
+.cv-perm:hover { filter: brightness(1.1); }
+.cv-perm:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+
+.cv-perm-menu {
+  position: absolute;
+  right: 0;
+  top: calc(100% + 4px);
+  z-index: 20;
+  min-width: 220px;
+  background: var(--surface-elevated);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  box-shadow: 0 6px 24px var(--shadow);
+  padding: 4px;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+.cv-perm-menuitem {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 1px;
+  font: inherit;
+  font-size: 12px;
+  padding: 6px 10px;
+  border: none;
+  background: transparent;
+  color: var(--text);
+  border-radius: 4px;
+  cursor: pointer;
+  text-align: left;
+}
+.cv-perm-menuitem:hover { background: var(--surface-2); }
+.cv-perm-menuitem.active { background: color-mix(in srgb, var(--accent) 12%, transparent); color: var(--accent); }
+.cv-perm-menuitem-label { font-weight: 600; }
+.cv-perm-menuitem-hint { font-size: 10.5px; color: var(--text-muted); }
+/* Tint by riskiness so a glance at the chip telegraphs what mode is active. */
+.cv-perm-plan    { color: var(--info);    border-color: color-mix(in srgb, var(--info) 45%, var(--border));    background: color-mix(in srgb, var(--info) 10%, var(--surface-2)); }
+.cv-perm-default { color: var(--text); }
+.cv-perm-bypass  { color: var(--warning); border-color: color-mix(in srgb, var(--warning) 50%, var(--border)); background: color-mix(in srgb, var(--warning) 12%, var(--surface-2)); }
+
+.cv-running {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 6px;
+  color: var(--accent);
+  font-size: 11px;
+  margin-left: 4px;
+  letter-spacing: 0.02em;
+}
+.cv-running-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--accent);
+  animation: cv-running-pulse 1.2s ease-in-out infinite;
+  align-self: center;
+}
+.cv-running-verb {
+  font-weight: 600;
+  animation: cv-running-verb-in 320ms ease-out;
+  display: inline-flex;
+  align-items: baseline;
+}
+.cv-running-dots::after {
+  display: inline-block;
+  content: '';
+  width: 1.2em;
+  text-align: left;
+  animation: cv-running-dots 1.4s steps(4, end) infinite;
+}
+.cv-running-elapsed {
+  color: var(--text-muted);
+  font-variant-numeric: tabular-nums;
+  font-weight: 500;
+}
+.cv-running.stalled { color: var(--warning); }
+.cv-running.stalled .cv-running-dot { background: var(--warning); }
+.cv-cancel {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  margin-left: 2px;
+  padding: 1px 6px;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  background: transparent;
+  color: var(--text-muted);
+  font-size: 10px;
+  font-weight: 600;
+  cursor: pointer;
+  align-self: center;
+}
+.cv-cancel:hover { background: color-mix(in srgb, var(--danger) 15%, transparent); color: var(--danger); border-color: var(--danger); }
+@keyframes cv-running-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.3; } }
+@keyframes cv-running-verb-in {
+  from { opacity: 0; transform: translateY(2px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+@keyframes cv-running-dots {
+  0%   { content: ''; }
+  25%  { content: '.'; }
+  50%  { content: '..'; }
+  75%  { content: '...'; }
+  100% { content: ''; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .cv-running-dot,
+  .cv-running-verb,
+  .cv-running-dots::after { animation: none; }
+  .cv-running-dots::after { content: '…'; }
+}
+
+.cv-icon-btn {
+  background: none;
+  border: 1px solid transparent;
+  color: var(--text-muted);
+  border-radius: 4px;
+  padding: 4px 6px;
+  cursor: pointer;
+}
+.cv-icon-btn:hover { background: var(--surface-2); color: var(--text); }
+
+.cv-banner {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 12px;
+  font-size: 12px;
+  background: color-mix(in srgb, var(--danger) 12%, transparent);
+  color: var(--danger);
+  border-bottom: 1px solid color-mix(in srgb, var(--danger) 40%, transparent);
+}
+
+.cv-banner.warning {
+  background: color-mix(in srgb, var(--warning) 12%, transparent);
+  color: var(--warning);
+  border-bottom-color: color-mix(in srgb, var(--warning) 40%, transparent);
+}
+
+.cv-banner-retry {
+  margin-left: auto;
+  padding: 2px 8px;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--text-on-accent);
+  background: var(--accent);
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+}
+.cv-banner-retry:hover { background: var(--accent-hover); }
+
+.cv-scroller {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 12px;
+}
+
+.cv-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  text-align: center;
+  color: var(--text-muted);
+  font-size: 13px;
+  padding: 32px 16px;
+}
+
+.cv-error {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 10px;
+  border-radius: 6px;
+  background: color-mix(in srgb, var(--danger) 12%, transparent);
+  color: var(--danger);
+  font-size: 12px;
+}
+
+.cv-queue {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 6px 12px;
+  border-top: 1px dashed var(--border);
+  background: var(--surface);
+}
+.cv-queue-head {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-muted);
+  font-weight: 700;
+}
+.cv-queue-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 6px 8px;
+  border-radius: 4px;
+  background: var(--surface-2);
+  font-size: 12px;
+}
+.cv-queue-text { flex: 1; color: var(--text); white-space: pre-wrap; word-break: break-word; }
+.cv-queue-cancel {
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  padding: 2px;
+  border-radius: 3px;
+  display: inline-flex;
+  align-items: center;
+}
+.cv-queue-cancel:hover { color: var(--danger); background: color-mix(in srgb, var(--danger) 10%, transparent); }
+
+.cv-composer,
+.cv-answer {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 10px 12px;
+  border-top: 1px solid var(--border);
+  background: var(--surface);
+}
+.cv-input {
+  width: 100%;
+  resize: vertical;
+  min-height: 56px;
+  background: var(--bg);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 8px 10px;
+  font: inherit;
+  font-size: 13px;
+}
+.cv-input:focus { outline: 2px solid var(--accent); outline-offset: -2px; }
+.cv-input:disabled { opacity: 0.6; cursor: not-allowed; }
+
+.cv-composer-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 6px;
+}
+.cv-send, .cv-abort {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  border: none;
+  border-radius: 4px;
+  padding: 6px 10px;
+  font-size: 12px;
+  font-weight: 600;
+  cursor: pointer;
+}
+.cv-send { background: var(--accent); color: var(--text-on-accent); }
+.cv-send:hover:not(:disabled) { background: var(--accent-hover); }
+.cv-send:disabled { opacity: 0.5; cursor: not-allowed; }
+.cv-abort { background: color-mix(in srgb, var(--danger) 12%, transparent); color: var(--danger); }
+.cv-abort:hover { background: var(--danger); color: var(--text-on-accent); }
+</style>
diff --git a/src/shell/components/DataBindingPicker.vue b/src/shell/components/DataBindingPicker.vue
new file mode 100644
index 0000000..6d2bc6d
--- /dev/null
+++ b/src/shell/components/DataBindingPicker.vue
@@ -0,0 +1,470 @@
+<script setup lang="ts">
+/**
+ * Data-source binding picker — search the REAL scanner catalog, pick a
+ * source, drill into its resolved shape, and emit a WireframeDataBinding.
+ *
+ * Honesty rules (the whole point of this component):
+ *   - Entries come from the static catalog only; runtime-discovered endpoints
+ *     have no code identity and contribute no shapes this round.
+ *   - The shape tree renders ONLY when a real API schema answered
+ *     ('api-schema'). Regex-inferred hints ('source-details') show verbatim
+ *     with their confidence; nothing is expanded into a fabricated tree.
+ *   - With no shape at all ('none'), the path/fields inputs are visibly blind.
+ *
+ * Self-contained fetches — deliberately NOT useDataSources(), whose
+ * module-level filter/selection state is shared with the Data view.
+ */
+import { computed, onMounted, ref } from 'vue'
+import Icon from './Icon.vue'
+import { flattenShape, fieldCandidates, sampleRows, buildBinding, type ShapeRow } from '../utils/bindingShape'
+import type { DataSourceShape, DataShapeNode, ProjectDataEntry } from '../../schema'
+import type { WireframeDataBinding } from '../../shared/wireframe-types'
+
+const props = defineProps<{
+  /** Existing binding when reconfiguring — shown as the current chip. */
+  initial?: WireframeDataBinding | null
+}>()
+
+const emit = defineEmits<{
+  select: [binding: WireframeDataBinding]
+  clear: []
+  cancel: []
+}>()
+
+const entries = ref<ProjectDataEntry[]>([])
+const loading = ref(true)
+const loadError = ref<string | null>(null)
+const filter = ref('')
+
+const selected = ref<ProjectDataEntry | null>(null)
+const shape = ref<DataSourceShape | null>(null)
+const shapeLoading = ref(false)
+
+// Drill-down state. pickedPath is null until the user explicitly picks a row
+// — an object ROOT's path is the empty string, so '' can't mean "nothing
+// picked" without falsely highlighting that row.
+const expanded = ref<Set<string>>(new Set())
+const pickedPath = ref<string | null>(null)
+const pickedNode = ref<DataShapeNode | null>(null)
+const pickedFields = ref<Set<string>>(new Set())
+// Free-text fallbacks for the source-details / none rungs.
+const freePath = ref('')
+const freeFields = ref('')
+
+onMounted(async () => {
+  try {
+    const res = await fetch('/__annotask/api/data-sources')
+    const body = await res.json() as { project_entries?: ProjectDataEntry[] }
+    // Static entries only — runtime promotions have file:'' and no shapes.
+    entries.value = (body.project_entries ?? []).filter(e => e.discovered_by !== 'runtime' && e.file)
+  } catch {
+    loadError.value = 'Could not load the data-source catalog'
+  } finally {
+    loading.value = false
+  }
+})
+
+const filtered = computed(() => {
+  const q = filter.value.trim().toLowerCase()
+  if (!q) return entries.value
+  return entries.value.filter(e =>
+    e.name.toLowerCase().includes(q)
+    || e.file.toLowerCase().includes(q)
+    || (e.endpoint ?? '').toLowerCase().includes(q))
+})
+
+// Monotonic token: a cold first resolve (full scan) can take seconds while a
+// later cache-warm pick returns instantly — a stale response must never land
+// on a newer selection.
+let pickSeq = 0
+
+async function pickEntry(entry: ProjectDataEntry): Promise<void> {
+  const seq = ++pickSeq
+  selected.value = entry
+  shape.value = null
+  shapeLoading.value = true
+  expanded.value = new Set()
+  pickedPath.value = null
+  pickedNode.value = null
+  pickedFields.value = new Set()
+  freePath.value = ''
+  freeFields.value = ''
+  try {
+    const params = new URLSearchParams({ name: entry.name, kind: entry.kind })
+    if (entry.file) params.set('file', entry.file)
+    const res = await fetch(`/__annotask/api/data-source-shape?${params}`)
+    const body = await res.json() as DataSourceShape | { error: string }
+    if (seq !== pickSeq) return // a newer pick raced ahead — drop this response
+    // Ambiguous/not-found degrade to the blind view — kind+file disambiguate
+    // in practice, and honesty beats a guessed tree.
+    shape.value = 'error' in body
+      ? { name: entry.name, kind: entry.kind, file: entry.file, shape_source: 'none' }
+      : body
+  } catch {
+    if (seq !== pickSeq) return
+    shape.value = { name: entry.name, kind: entry.kind, file: entry.file, shape_source: 'none' }
+  } finally {
+    if (seq === pickSeq) shapeLoading.value = false
+  }
+}
+
+const rows = computed<ShapeRow[]>(() =>
+  shape.value?.shape ? flattenShape(shape.value.shape, expanded.value) : [])
+
+function toggleExpand(row: ShapeRow): void {
+  const next = new Set(expanded.value)
+  if (next.has(row.path)) next.delete(row.path)
+  else next.add(row.path)
+  expanded.value = next
+}
+
+function pickRow(row: ShapeRow): void {
+  if (!row.selectable) return
+  pickedPath.value = row.path
+  pickedNode.value = row.node
+  pickedFields.value = new Set()
+  if (!expanded.value.has(row.path) && row.expandable) toggleExpand(row)
+}
+
+const candidates = computed(() => (pickedNode.value ? fieldCandidates(pickedNode.value) : []))
+
+function toggleField(key: string): void {
+  const next = new Set(pickedFields.value)
+  if (next.has(key)) next.delete(key)
+  else next.add(key)
+  pickedFields.value = next
+}
+
+const shapeSourceLabel = computed(() => {
+  const s = shape.value
+  if (!s) return null
+  if (s.shape_source === 'api-schema') {
+    const pct = s.match_confidence != null ? ` · match ${Math.round(s.match_confidence * 100)}%` : ''
+    return { cls: 'api-schema', text: `api schema${s.schema_ref ? ` · ${s.schema_ref}` : ''}${pct}` }
+  }
+  if (s.shape_source === 'source-details') {
+    return { cls: 'inferred', text: `inferred (regex, ${s.details_confidence ?? 'low'})` }
+  }
+  return { cls: 'none', text: 'no shape available — entered blind' }
+})
+
+const canBind = computed(() => !!selected.value && !!shape.value && !shapeLoading.value)
+
+function confirm(): void {
+  const entry = selected.value
+  const s = shape.value
+  if (!entry || !s) return
+  const usingTree = s.shape_source === 'api-schema'
+  const path = usingTree ? (pickedPath.value ?? '') : freePath.value
+  const fields = usingTree
+    ? [...pickedFields.value]
+    : freeFields.value.split(',').map(f => f.trim()).filter(Boolean)
+  // Pull REAL contract example rows for the preview (api-schema only); default a
+  // sketch repeat for a list path. propMap is mapped later in the popover.
+  const sample = usingTree && pickedNode.value ? sampleRows(pickedNode.value, fields, 5) : []
+  const isList = path.includes('[]')
+  emit('select', buildBinding(entry, {
+    path,
+    fields,
+    shape_source: s.shape_source,
+    ...(sample.length > 0 ? { sample } : {}),
+    ...(isList ? { repeat: 3 } : {}),
+  }))
+}
+</script>
+
+<template>
+  <div class="binding-picker" data-testid="binding-picker" @pointerdown.stop @click.stop>
+    <div class="bp-head">
+      <span class="bp-title">Bind a data source</span>
+      <span v-if="props.initial" class="bp-current">currently: {{ props.initial.name }}{{ props.initial.path ? ` · ${props.initial.path}` : '' }}</span>
+      <button class="bp-icon-btn" title="Close" data-testid="binding-cancel" @click="emit('cancel')">
+        <Icon name="x" :size="14" />
+      </button>
+    </div>
+
+    <div class="bp-body">
+      <div class="bp-list">
+        <input
+          v-model="filter"
+          class="bp-filter"
+          type="text"
+          placeholder="Search sources by name, file, endpoint…"
+          data-testid="binding-filter"
+        >
+        <div v-if="loading" class="bp-empty">Loading catalog…</div>
+        <div v-else-if="loadError" class="bp-empty">{{ loadError }}</div>
+        <div v-else-if="filtered.length === 0" class="bp-empty">No data sources found</div>
+        <button
+          v-for="e in filtered"
+          :key="`${e.name}:${e.file}`"
+          class="bp-row"
+          :class="{ active: selected?.name === e.name && selected?.file === e.file }"
+          :data-testid="`binding-row-${e.name}`"
+          @click="pickEntry(e)"
+        >
+          <span class="bp-kind" :data-kind="e.kind">{{ e.kind }}</span>
+          <span class="bp-name">{{ e.display_name ?? e.name }}</span>
+          <span v-if="e.endpoint" class="bp-endpoint">{{ e.endpoint }}</span>
+        </button>
+      </div>
+
+      <div class="bp-detail">
+        <div v-if="!selected" class="bp-empty">Pick a source on the left</div>
+        <div v-else-if="shapeLoading" class="bp-empty">Resolving shape…</div>
+        <template v-else-if="shape">
+          <div class="bp-meta">
+            <span class="bp-kind" :data-kind="shape.kind">{{ shape.kind }}</span>
+            <code class="bp-module">{{ shape.file }}</code>
+            <span v-if="shapeSourceLabel" class="bp-shape-tag" :class="shapeSourceLabel.cls">{{ shapeSourceLabel.text }}</span>
+          </div>
+
+          <!-- Rung 1: real contract — walkable tree. -->
+          <template v-if="shape.shape_source === 'api-schema' && shape.shape">
+            <div class="bp-tree" data-testid="binding-shape-tree">
+              <div
+                v-for="row in rows"
+                :key="row.path || '(root)'"
+                class="bp-tree-row"
+                :class="{ picked: pickedPath === row.path, selectable: row.selectable }"
+                :style="{ paddingLeft: `${8 + row.depth * 16}px` }"
+                @click="pickRow(row)"
+              >
+                <button
+                  v-if="row.expandable"
+                  class="bp-twisty"
+                  @click.stop="toggleExpand(row)"
+                >{{ expanded.has(row.path) ? '▾' : '▸' }}</button>
+                <span v-else class="bp-twisty-pad" />
+                <span class="bp-key">{{ row.key }}</span>
+                <span class="bp-type">
+                  {{ row.node.kind === 'scalar' ? row.node.scalar
+                    : row.node.kind === 'array' ? 'array'
+                    : row.node.kind === 'ref' ? `→ ${row.node.ref}`
+                    : row.node.kind }}
+                </span>
+              </div>
+            </div>
+            <div v-if="pickedNode" class="bp-picked">
+              <span class="bp-picked-path">path: <code>{{ pickedPath || '(whole response)' }}</code></span>
+              <div v-if="candidates.length" class="bp-fields">
+                <span class="bp-fields-label">show fields:</span>
+                <label v-for="key in candidates" :key="key" class="bp-field">
+                  <input
+                    type="checkbox"
+                    :checked="pickedFields.has(key)"
+                    :data-testid="`binding-field-${key}`"
+                    @change="toggleField(key)"
+                  >
+                  {{ key }}
+                </label>
+              </div>
+            </div>
+          </template>
+
+          <!-- Rung 2: regex hints, verbatim. Rung 3: nothing. Both fall back to free text. -->
+          <template v-else>
+            <div v-if="shape.shape_source === 'source-details'" class="bp-hints">
+              <div v-if="shape.signature" class="bp-hint"><span>signature</span><code>{{ shape.signature }}</code></div>
+              <div v-if="shape.return_type" class="bp-hint"><span>return type</span><code>{{ shape.return_type }}</code></div>
+              <div v-if="shape.referenced_types?.length" class="bp-hint"><span>types</span><code>{{ shape.referenced_types.join(', ') }}</code></div>
+            </div>
+            <div class="bp-free">
+              <label class="bp-free-row">
+                <span>Path <em>(e.g. planets[] or data.user)</em></span>
+                <input v-model="freePath" type="text" data-testid="binding-path-input" placeholder="optional">
+              </label>
+              <label class="bp-free-row">
+                <span>Fields <em>(comma-separated)</em></span>
+                <input v-model="freeFields" type="text" data-testid="binding-fields-input" placeholder="e.g. name, type">
+              </label>
+            </div>
+          </template>
+        </template>
+      </div>
+    </div>
+
+    <div class="bp-foot">
+      <button v-if="props.initial" class="bp-btn danger" data-testid="binding-clear" @click="emit('clear')">Clear binding</button>
+      <span class="bp-spacer" />
+      <button class="bp-btn" @click="emit('cancel')">Cancel</button>
+      <button class="bp-btn primary" :disabled="!canBind" data-testid="binding-confirm" @click="confirm">Bind</button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.binding-picker {
+  display: flex;
+  flex-direction: column;
+  width: min(640px, 92vw);
+  max-height: min(480px, 80vh);
+  background: var(--surface-elevated);
+  border: 1px solid var(--border-strong);
+  border-radius: 8px;
+  box-shadow: 0 12px 32px var(--shadow);
+  color: var(--text);
+  font-size: 12px;
+}
+.bp-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 12px;
+  border-bottom: 1px solid var(--border);
+}
+.bp-title { font-weight: 600; }
+.bp-current { color: var(--text-muted); font-size: 11px; }
+.bp-icon-btn {
+  margin-left: auto;
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  padding: 2px;
+}
+.bp-icon-btn:hover { color: var(--text); }
+.bp-body {
+  display: grid;
+  grid-template-columns: 240px 1fr;
+  min-height: 0;
+  flex: 1;
+}
+.bp-list {
+  display: flex;
+  flex-direction: column;
+  border-right: 1px solid var(--border);
+  overflow-y: auto;
+}
+.bp-filter {
+  margin: 8px;
+  padding: 5px 8px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  color: var(--text);
+  font-size: 12px;
+}
+.bp-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 10px;
+  background: none;
+  border: none;
+  color: var(--text);
+  cursor: pointer;
+  text-align: left;
+  font-size: 12px;
+}
+.bp-row:hover { background: var(--surface-2); }
+.bp-row.active { background: color-mix(in srgb, var(--accent) 18%, transparent); }
+.bp-kind {
+  flex-shrink: 0;
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-size: 10px;
+  background: color-mix(in srgb, var(--info) 20%, transparent);
+  color: var(--info);
+}
+.bp-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.bp-endpoint {
+  margin-left: auto;
+  color: var(--text-muted);
+  font-size: 10px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  max-width: 40%;
+}
+.bp-detail {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px;
+  overflow-y: auto;
+}
+.bp-empty { color: var(--text-muted); padding: 16px; text-align: center; }
+.bp-meta { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.bp-module { color: var(--text-muted); font-size: 11px; }
+.bp-shape-tag {
+  padding: 1px 6px;
+  border-radius: 3px;
+  font-size: 10px;
+}
+.bp-shape-tag.api-schema { background: color-mix(in srgb, var(--success) 18%, transparent); color: var(--success); }
+.bp-shape-tag.inferred { background: color-mix(in srgb, var(--warning) 18%, transparent); color: var(--warning); }
+.bp-shape-tag.none { background: color-mix(in srgb, var(--text-muted) 18%, transparent); color: var(--text-muted); }
+.bp-tree {
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: var(--surface);
+  font-family: ui-monospace, monospace;
+  font-size: 11px;
+  overflow-y: auto;
+}
+.bp-tree-row {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 3px 8px;
+}
+.bp-tree-row.selectable { cursor: pointer; }
+.bp-tree-row.selectable:hover { background: var(--surface-2); }
+.bp-tree-row.picked { background: color-mix(in srgb, var(--accent) 20%, transparent); }
+.bp-twisty {
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  width: 14px;
+  padding: 0;
+  font-size: 10px;
+}
+.bp-twisty-pad { width: 14px; }
+.bp-key { color: var(--syntax-property); }
+.bp-type { color: var(--text-muted); margin-left: 6px; }
+.bp-picked { display: flex; flex-direction: column; gap: 6px; }
+.bp-picked-path code { color: var(--accent); }
+.bp-fields { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; }
+.bp-fields-label { color: var(--text-muted); }
+.bp-field { display: flex; align-items: center; gap: 4px; cursor: pointer; }
+.bp-hints { display: flex; flex-direction: column; gap: 4px; }
+.bp-hint { display: flex; gap: 8px; align-items: baseline; }
+.bp-hint span { color: var(--text-muted); font-size: 10px; min-width: 72px; }
+.bp-hint code { font-size: 11px; word-break: break-all; }
+.bp-free { display: flex; flex-direction: column; gap: 8px; }
+.bp-free-row { display: flex; flex-direction: column; gap: 3px; }
+.bp-free-row span { color: var(--text-muted); font-size: 11px; }
+.bp-free-row em { font-style: normal; opacity: 0.7; }
+.bp-free-row input {
+  padding: 5px 8px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  color: var(--text);
+  font-size: 12px;
+}
+.bp-foot {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 12px;
+  border-top: 1px solid var(--border);
+}
+.bp-spacer { flex: 1; }
+.bp-btn {
+  padding: 5px 12px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  color: var(--text);
+  cursor: pointer;
+  font-size: 12px;
+}
+.bp-btn:hover { background: var(--surface-3); }
+.bp-btn.primary { background: var(--accent); border-color: var(--accent); color: var(--text-on-accent); }
+.bp-btn.primary:hover { background: var(--accent-hover); }
+.bp-btn.primary:disabled { opacity: 0.5; cursor: default; }
+.bp-btn.danger { color: var(--danger); border-color: color-mix(in srgb, var(--danger) 40%, transparent); background: none; }
+</style>
diff --git a/src/shell/components/DataSourcesPage.vue b/src/shell/components/DataSourcesPage.vue
index fae2ec5..3341b42 100644
--- a/src/shell/components/DataSourcesPage.vue
+++ b/src/shell/components/DataSourcesPage.vue
@@ -265,13 +265,6 @@ function libraryTooltip(lib: { name: string; version?: string; detected_patterns
   return lines.join('\n')
 }
 
-const showCreateForm = ref(false)
-const createDesired = ref('')
-const createDescription = ref('')
-const createRationale = ref('')
-const createError = ref<string | null>(null)
-const createSuccessId = ref<string | null>(null)
-
 function kindLabel(kind: DataSource['kind']): string {
   switch (kind) {
     case 'composable': return 'hook'
@@ -297,37 +290,6 @@ const selectedSchemaBadge = computed(() => {
   return { text: 'external', tone: 'warn' as const }
 })
 
-function openCreate() {
-  createDesired.value = ''
-  createDescription.value = ''
-  createRationale.value = ''
-  createError.value = null
-  createSuccessId.value = null
-  showCreateForm.value = true
-}
-
-async function submitCreate() {
-  createError.value = null
-  if (!createDesired.value.trim() || !createDescription.value.trim()) {
-    createError.value = 'Description and desired change are required'
-    return
-  }
-  const res = await ds.createApiUpdateTask({
-    description: createDescription.value.trim(),
-    desired_change: createDesired.value.trim(),
-    rationale: createRationale.value.trim() || undefined,
-  })
-  if (res.ok) {
-    createSuccessId.value = res.id
-    showCreateForm.value = false
-  } else {
-    createError.value = res.error
-  }
-}
-
-function cancelCreate() {
-  showCreateForm.value = false
-}
 </script>
 
 <template>
@@ -606,36 +568,6 @@ function cancelCreate() {
                 {{ selectedSchemaBadge.text }}
               </span>
             </div>
-            <div v-if="ds.selectedSchemaLink.value?.schema_in_repo" class="detail-actions">
-              <button data-testid="btn-create-api-task" class="data-btn primary" @click="openCreate">Create API Update Task</button>
-            </div>
-            <div v-else-if="ds.selectedSchemaLink.value && !ds.selectedSchemaLink.value.schema_in_repo" class="detail-note">
-              External API — schema cannot be edited from here.
-            </div>
-          </div>
-
-          <div v-if="createSuccessId" class="detail-success">
-            Created <code>{{ createSuccessId }}</code> with type <code>api_update</code>.
-          </div>
-
-          <div v-if="showCreateForm" class="create-form">
-            <label>
-              <span>Task description (markdown)</span>
-              <textarea v-model="createDescription" rows="2" placeholder="e.g. Add expires_at to the Cat response so the badge can show expiration." />
-            </label>
-            <label>
-              <span>Desired change</span>
-              <textarea v-model="createDesired" rows="2" placeholder="e.g. Add nullable `expires_at: string` (ISO date) to the Cat response schema and the backend handler." />
-            </label>
-            <label>
-              <span>Rationale (optional)</span>
-              <textarea v-model="createRationale" rows="1" placeholder="Why is this change needed?" />
-            </label>
-            <div v-if="createError" class="create-error">{{ createError }}</div>
-            <div class="create-actions">
-              <button data-testid="btn-submit-api-task" class="data-btn primary" @click="submitCreate">Create task</button>
-              <button class="data-btn" @click="cancelCreate">Cancel</button>
-            </div>
           </div>
 
           <DataSourceDetailPane
diff --git a/src/shell/components/DesignSessionPanel.vue b/src/shell/components/DesignSessionPanel.vue
new file mode 100644
index 0000000..15d4753
--- /dev/null
+++ b/src/shell/components/DesignSessionPanel.vue
@@ -0,0 +1,226 @@
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import { useDesignSession } from '../composables/useDesignSession'
+import ConfirmDialog from './ConfirmDialog.vue'
+
+const emit = defineEmits<{
+  /** Apply minted a task — the parent hands it to the embedded-agent auto-run
+   *  when a provider is configured (otherwise it sits for an external agent). */
+  'run-agent': [taskId: string]
+}>()
+
+const session = useDesignSession()
+
+const pendingEntries = computed(() => session.entries.value.filter(
+  (e) => !e.instanceId && (e.live.status === 'pending' || e.live.status === 'failed'),
+))
+const applyingEntries = computed(() => session.entries.value.filter((e) => e.live.status === 'applying'))
+const writtenCount = computed(() => session.entries.value.filter((e) => e.live.status === 'written').length)
+const files = computed(() => Object.entries(session.snapshotState.value.files)
+  .map(([file, s]) => ({ file, ...s })))
+const lastBatch = computed(() => {
+  const batches = session.snapshotState.value.batches
+  return batches.length ? batches[batches.length - 1] : null
+})
+const banner = computed(() => session.lastError.value ?? session.syncError.value)
+
+const confirmingDiscard = ref(false)
+
+function statusChip(status: string): string {
+  if (status === 'pending') return 'pending'
+  if (status === 'applying') return 'applying…'
+  if (status === 'written') return 'written'
+  return 'failed'
+}
+
+async function onApply() {
+  const result = await session.applyNow()
+  if (result) emit('run-agent', result.taskId)
+}
+
+async function onDiscard() {
+  confirmingDiscard.value = false
+  await session.discardSession()
+}
+</script>
+
+<template>
+  <div v-if="session.entries.value.length || files.length" class="session-panel" data-testid="design-session-panel">
+    <div class="session-head">
+      <span class="session-title">Design session</span>
+      <span v-if="writtenCount" class="session-summary written">{{ writtenCount }} in source</span>
+      <span v-if="applyingEntries.length" class="session-summary applying">{{ applyingEntries.length }} applying</span>
+    </div>
+
+    <div v-if="banner" class="session-banner" role="alert">{{ banner }}</div>
+
+    <div v-for="e in session.entries.value.filter((x) => !x.instanceId)" :key="e.id" class="session-row" :title="`${e.anchor.file}:${e.anchor.line}`">
+      <span class="session-desc">{{ e.change.description }}</span>
+      <span class="session-chip" :class="e.live.status">{{ statusChip(e.live.status) }}</span>
+    </div>
+
+    <div v-if="files.length" class="session-files">
+      <div v-for="f in files" :key="f.file" class="session-file-row">
+        <code class="session-file">{{ f.file }}</code>
+        <template v-if="f.status === 'diverged'">
+          <span class="session-chip failed" title="Edited outside Annotask — undo/discard will not touch it">diverged</span>
+          <button class="session-detach" title="Keep the current file bytes and remove it from the session" @click="session.detachFile(f.file)">Detach</button>
+        </template>
+      </div>
+    </div>
+
+    <div class="session-actions">
+      <button
+        class="session-apply"
+        :disabled="session.applyInFlight.value || pendingEntries.length === 0"
+        :title="pendingEntries.length === 0
+          ? 'No pending edits — make a change in the properties panel or drop a component'
+          : 'Snapshot the touched files and hand the pending edits to the agent to write into source'"
+        @click="onApply"
+      >{{ session.applyInFlight.value ? 'Applying…' : `Apply ${pendingEntries.length || ''} edit${pendingEntries.length === 1 ? '' : 's'} (agent)` }}</button>
+      <button
+        v-if="lastBatch"
+        class="session-undo"
+        :disabled="session.applyInFlight.value"
+        :title="session.applyInFlight.value
+          ? 'Wait for the current apply to finish before undoing'
+          : 'Restore the files this apply touched to their pre-apply bytes'"
+        @click="session.undoLastBatch()"
+      >Undo last apply</button>
+      <button
+        class="session-discard"
+        :disabled="session.applyInFlight.value"
+        :title="session.applyInFlight.value
+          ? 'Wait for the current apply to finish before discarding'
+          : 'Restore every touched file to its session-start bytes and remove session placements'"
+        @click="confirmingDiscard = true"
+      >Discard session</button>
+    </div>
+
+    <ConfirmDialog
+      v-if="confirmingDiscard"
+      :message="`Discard the design session? Every file the agent touched is restored to its session-start bytes${files.length ? ` (${files.length} file${files.length === 1 ? '' : 's'})` : ''} and session placements are removed.`"
+      confirmLabel="Discard session"
+      @confirm="onDiscard"
+      @cancel="confirmingDiscard = false"
+    />
+  </div>
+</template>
+
+<style scoped>
+.session-panel {
+  border-top: 1px solid var(--border);
+  padding: 10px 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.session-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.session-title {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--text-muted);
+}
+.session-summary {
+  font-size: 10px;
+  color: var(--text-muted);
+}
+.session-summary.written { color: var(--success); }
+.session-summary.applying { color: var(--status-in-progress, var(--info)); }
+.session-banner {
+  font-size: 11px;
+  padding: 6px 8px;
+  border-radius: 4px;
+  background: color-mix(in srgb, var(--danger) 12%, transparent);
+  border: 1px solid color-mix(in srgb, var(--danger) 30%, transparent);
+  color: var(--danger);
+}
+.session-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+.session-desc {
+  font-size: 11px;
+  color: var(--text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1;
+  min-width: 0;
+}
+.session-chip {
+  font-size: 9px;
+  padding: 1px 6px;
+  border-radius: 999px;
+  white-space: nowrap;
+}
+.session-chip.pending { background: color-mix(in srgb, var(--status-pending) 18%, transparent); color: var(--status-pending); }
+.session-chip.applying { background: color-mix(in srgb, var(--status-in-progress) 18%, transparent); color: var(--status-in-progress); }
+.session-chip.written { background: color-mix(in srgb, var(--status-accepted) 18%, transparent); color: var(--status-accepted); }
+.session-chip.failed { background: color-mix(in srgb, var(--danger) 18%, transparent); color: var(--danger); }
+.session-files {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.session-file-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.session-file {
+  font-size: 10px;
+  color: var(--text-muted);
+  font-family: ui-monospace, monospace;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1;
+  min-width: 0;
+}
+.session-detach {
+  font-size: 10px;
+  background: transparent;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  color: var(--text-muted);
+  padding: 1px 6px;
+  cursor: pointer;
+}
+.session-actions {
+  display: flex;
+  gap: 6px;
+  flex-wrap: wrap;
+  margin-top: 2px;
+}
+.session-actions button {
+  font-size: 11px;
+  border-radius: 4px;
+  padding: 4px 10px;
+  cursor: pointer;
+  border: 1px solid var(--border);
+  background: var(--surface-2);
+  color: var(--text);
+}
+.session-actions button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.session-apply {
+  background: var(--accent) !important;
+  border-color: var(--accent) !important;
+  color: var(--text-on-accent) !important;
+}
+.session-discard {
+  color: var(--danger) !important;
+  border-color: color-mix(in srgb, var(--danger) 40%, transparent) !important;
+}
+</style>
diff --git a/src/shell/components/DesignTokenEditor.vue b/src/shell/components/DesignTokenEditor.vue
new file mode 100644
index 0000000..480f9ee
--- /dev/null
+++ b/src/shell/components/DesignTokenEditor.vue
@@ -0,0 +1,521 @@
+<script setup lang="ts">
+/**
+ * Reusable design-token editor.
+ *
+ * Used in two contexts:
+ *   1. ThemePage.vue — spec comes from useDesignSpec(), edits produce
+ *      commit tasks via the parent's collectEdits() / commitChanges().
+ *   2. InitWizard.vue — spec comes from the init draft, edits are
+ *      immediately written back via `update:spec` so they serialize on
+ *      Save. No commit/discard bar needed (the wizard's Save button does it).
+ *
+ * The component owns the variant-selection state and the in-flight edit
+ * maps. If a parent wants to read collected edits (ThemePage), it calls
+ * the `collectEdits()` exposed method. If a parent just wants the mutated
+ * spec object (InitWizard), it listens to `update:spec`.
+ */
+
+import { ref, computed, watch, defineExpose, type MaybeRef, toRef } from 'vue'
+import type { DesignSpecToken, DesignSpecTheme, DesignSpecThemeSelector } from '../../schema'
+import ColorPalettePicker from './ColorPalettePicker.vue'
+import ThemeAddTokenForm from './ThemeAddTokenForm.vue'
+
+const props = withDefaults(defineProps<{
+  /** The spec to display. Pass `null` to show the empty/loading state. */
+  spec: Record<string, any> | null
+  /**
+   * When true, the variant bar drives only local UI state — clicking a
+   * variant tab doesn't attempt to activate it in an iframe. Set to true
+   * in the init wizard; leave false (default) in ThemePage where the
+   * parent passes `onActivateVariant`.
+   */
+  localOnly?: boolean
+  /** Called when the user clicks a variant tab (ThemePage passes this to
+   *  drive the iframe; init wizard omits it). */
+  onActivateVariant?: (selector: DesignSpecThemeSelector | null | undefined, all?: DesignSpecThemeSelector[]) => Promise<void>
+}>(), { localOnly: false })
+
+const emit = defineEmits<{
+  /** Emitted on every token edit — carries the mutated spec so the parent
+   *  (e.g. init wizard) can persist it. ThemePage listens too but derives
+   *  tasks from collectEdits() instead. */
+  (e: 'update:spec', spec: Record<string, any>): void
+}>()
+
+const activeSection = ref<'colors' | 'typography' | 'spacing' | 'borders'>('colors')
+
+// ── Theme variants ────────────────────────────────────────
+const FALLBACK_THEME: DesignSpecTheme = { id: 'default', name: 'Default', selector: { kind: 'default' } }
+
+const themes = computed<DesignSpecTheme[]>(() => {
+  const list = props.spec?.themes
+  return Array.isArray(list) && list.length > 0 ? list : [FALLBACK_THEME]
+})
+
+const defaultThemeId = computed(() => props.spec?.defaultTheme || themes.value[0]?.id || 'default')
+const pinnedThemeId  = ref<string | null>(null)
+const activeThemeId  = computed(() => pinnedThemeId.value ?? defaultThemeId.value)
+const activeTheme    = computed<DesignSpecTheme>(() => themes.value.find(t => t.id === activeThemeId.value) ?? themes.value[0])
+
+watch(() => props.spec, () => { pinnedThemeId.value = null })
+
+function setActiveTheme(id: string) {
+  const target = themes.value.find(t => t.id === id)
+  if (!target) return
+  if (!props.localOnly && props.onActivateVariant) {
+    pinnedThemeId.value = null
+    void props.onActivateVariant(target.selector, themes.value.map(t => t.selector))
+    return
+  }
+  pinnedThemeId.value = id === defaultThemeId.value ? null : id
+}
+
+// ── Token lists ───────────────────────────────────────────
+const colors   = computed(() => (props.spec?.colors ?? []) as DesignSpecToken[])
+const families = computed(() => (props.spec?.typography?.families ?? []) as DesignSpecToken[])
+const scale    = computed(() => (props.spec?.typography?.scale ?? []) as DesignSpecToken[])
+const weights  = computed(() => (props.spec?.typography?.weights ?? []) as string[])
+const spacing  = computed(() => (props.spec?.spacing ?? []) as DesignSpecToken[])
+const radius   = computed(() => (props.spec?.borders?.radius ?? []) as DesignSpecToken[])
+
+// ── Edit maps ─────────────────────────────────────────────
+function editKey(themeId: string, role: string) { return `${themeId}::${role}` }
+
+const editedColors   = ref(new Map<string, string>())
+const editedFamilies = ref(new Map<string, string>())
+const editedScale    = ref(new Map<string, string>())
+const editedSpacing  = ref(new Map<string, string>())
+const editedRadius   = ref(new Map<string, string>())
+
+const newColors   = ref<DesignSpecToken[]>([])
+const newFamilies = ref<DesignSpecToken[]>([])
+const newScale    = ref<DesignSpecToken[]>([])
+const newSpacing  = ref<DesignSpecToken[]>([])
+const newRadius   = ref<DesignSpecToken[]>([])
+
+const addingNew = ref<string | null>(null)
+
+// ── Value helpers ─────────────────────────────────────────
+function originalValue(token: DesignSpecToken): string {
+  const values = token.values || {}
+  const v = values[activeThemeId.value] ?? values[defaultThemeId.value]
+  if (v !== undefined) return v
+  // Handle old single-value shape
+  if (typeof (token as any).value === 'string') return (token as any).value
+  return Object.values(values)[0] ?? ''
+}
+
+function getEffectiveValue(token: DesignSpecToken, editMap: MaybeRef<Map<string, string>>): string {
+  return toRef(editMap).value.get(editKey(activeThemeId.value, token.role)) ?? originalValue(token)
+}
+
+function isEdited(token: DesignSpecToken, editMap: MaybeRef<Map<string, string>>): boolean {
+  const edited = toRef(editMap).value.get(editKey(activeThemeId.value, token.role))
+  return edited !== undefined && edited !== originalValue(token)
+}
+
+function newTokenDisplayValue(token: DesignSpecToken): string {
+  return token.values?.[activeThemeId.value] ?? Object.values(token.values ?? {})[0] ?? ''
+}
+
+// ── Edit handlers ─────────────────────────────────────────
+function emitUpdate() {
+  if (!props.spec) return
+  // Bake edits into a mutated copy of the spec for the parent.
+  function bake(tokens: DesignSpecToken[], editMap: Map<string, string>): DesignSpecToken[] {
+    return tokens.map(tok => {
+      const updated: Record<string, string> = { ...(tok.values ?? {}) }
+      for (const [k, v] of editMap) {
+        const [themeId, role] = k.split('::')
+        if (role === tok.role) updated[themeId] = v
+      }
+      return { ...tok, values: updated }
+    })
+  }
+  const updatedSpec = {
+    ...props.spec,
+    colors: [...bake(colors.value, editedColors.value), ...newColors.value],
+    typography: {
+      ...props.spec.typography,
+      families: [...bake(families.value, editedFamilies.value), ...newFamilies.value],
+      scale:    [...bake(scale.value, editedScale.value), ...newScale.value],
+      weights:  weights.value,
+    },
+    spacing: [...bake(spacing.value, editedSpacing.value), ...newSpacing.value],
+    borders: {
+      ...props.spec.borders,
+      radius: [...bake(radius.value, editedRadius.value), ...newRadius.value],
+    },
+  }
+  emit('update:spec', updatedSpec)
+}
+
+function onColorChange(token: DesignSpecToken, value: string) {
+  editedColors.value.set(editKey(activeThemeId.value, token.role), value)
+  editedColors.value = new Map(editedColors.value)
+  emitUpdate()
+}
+
+function onTokenChange(token: DesignSpecToken, value: string, editMap: MaybeRef<Map<string, string>>) {
+  const r = toRef(editMap)
+  r.value.set(editKey(activeThemeId.value, token.role), value)
+  r.value = new Map(r.value)
+  emitUpdate()
+}
+
+// ── Add/remove new tokens ─────────────────────────────────
+function startAdd(section: string) { addingNew.value = section }
+function cancelAdd() { addingNew.value = null }
+
+function confirmAdd(payload: { role: string; value: string; cssVar?: string }) {
+  const token: DesignSpecToken = {
+    role: payload.role,
+    values: { [activeThemeId.value]: payload.value },
+    cssVar: payload.cssVar,
+    source: 'new',
+  }
+  switch (addingNew.value) {
+    case 'colors':   newColors.value   = [...newColors.value, token];   break
+    case 'families': newFamilies.value = [...newFamilies.value, token]; break
+    case 'scale':    newScale.value    = [...newScale.value, token];    break
+    case 'spacing':  newSpacing.value  = [...newSpacing.value, token];  break
+    case 'radius':   newRadius.value   = [...newRadius.value, token];   break
+  }
+  addingNew.value = null
+  emitUpdate()
+}
+
+function removeNew(list: MaybeRef<DesignSpecToken[]>, index: number) {
+  toRef(list).value = toRef(list).value.filter((_, i) => i !== index)
+  emitUpdate()
+}
+
+// ── Edit counts (used by ThemePage for the commit bar) ────
+function countEditsForSection(editMap: Map<string, string>, tokens: DesignSpecToken[]): number {
+  let n = 0
+  for (const t of tokens) for (const tid of Object.keys(t.values || {}))
+    if (editMap.has(editKey(tid, t.role))) n++
+  return n
+}
+
+const colorEditCount   = computed(() => countEditsForSection(editedColors.value, colors.value))
+const familyEditCount  = computed(() => countEditsForSection(editedFamilies.value, families.value))
+const scaleEditCount   = computed(() => countEditsForSection(editedScale.value, scale.value))
+const spacingEditCount = computed(() => countEditsForSection(editedSpacing.value, spacing.value))
+const radiusEditCount  = computed(() => countEditsForSection(editedRadius.value, radius.value))
+
+const totalChanges = computed(() =>
+  colorEditCount.value + familyEditCount.value + scaleEditCount.value +
+  spacingEditCount.value + radiusEditCount.value +
+  newColors.value.length + newFamilies.value.length + newScale.value.length +
+  newSpacing.value.length + newRadius.value.length
+)
+
+// ── Exposed for ThemePage ─────────────────────────────────
+interface ThemeEdit {
+  category: string; role: string; cssVar: string | null; theme_variant: string
+  theme_selector: DesignSpecTheme['selector'] | null; before: string | null
+  after: string; sourceFile: string | null; sourceLine: number | null; isNew: boolean
+}
+
+function collectEdits(): ThemeEdit[] {
+  const edits: ThemeEdit[] = []
+  function pushEditsFor(cat: string, tok: DesignSpecToken, map: Map<string, string>) {
+    for (const themeId of Object.keys(tok.values || {})) {
+      const after = map.get(editKey(themeId, tok.role))
+      const before = tok.values[themeId]
+      if (after === undefined || after === before) continue
+      edits.push({ category: cat, role: tok.role, cssVar: tok.cssVar || null,
+        theme_variant: themeId, theme_selector: themes.value.find(t => t.id === themeId)?.selector ?? null,
+        before, after, sourceFile: tok.sourceFile || null, sourceLine: tok.sourceLine || null, isNew: false })
+    }
+  }
+  function pushNewFor(cat: string, tok: DesignSpecToken) {
+    for (const [themeId, value] of Object.entries(tok.values || {})) {
+      edits.push({ category: cat, role: tok.role, cssVar: tok.cssVar || null,
+        theme_variant: themeId, theme_selector: themes.value.find(t => t.id === themeId)?.selector ?? null,
+        before: null, after: value ?? '', sourceFile: null, sourceLine: null, isNew: true })
+    }
+  }
+  for (const t of colors.value)   pushEditsFor('colors', t, editedColors.value)
+  for (const t of families.value) pushEditsFor('typography.families', t, editedFamilies.value)
+  for (const t of scale.value)    pushEditsFor('typography.scale', t, editedScale.value)
+  for (const t of spacing.value)  pushEditsFor('spacing', t, editedSpacing.value)
+  for (const t of radius.value)   pushEditsFor('borders.radius', t, editedRadius.value)
+  for (const t of newColors.value)   pushNewFor('colors', t)
+  for (const t of newFamilies.value) pushNewFor('typography.families', t)
+  for (const t of newScale.value)    pushNewFor('typography.scale', t)
+  for (const t of newSpacing.value)  pushNewFor('spacing', t)
+  for (const t of newRadius.value)   pushNewFor('borders.radius', t)
+  return edits
+}
+
+function resetEdits() {
+  editedColors.value = new Map(); editedFamilies.value = new Map()
+  editedScale.value  = new Map(); editedSpacing.value  = new Map(); editedRadius.value = new Map()
+  newColors.value = []; newFamilies.value = []; newScale.value = []
+  newSpacing.value = []; newRadius.value = []
+}
+
+defineExpose({ collectEdits, resetEdits, totalChanges, activeThemeId })
+</script>
+
+<template>
+  <div class="dte">
+    <!-- No spec yet -->
+    <div v-if="!spec" class="dte-empty">
+      <p>No design spec — run the scanner first.</p>
+    </div>
+
+    <template v-else>
+      <!-- Variant bar -->
+      <div v-if="themes.length > 1" class="variant-bar">
+        <div class="variant-tabs">
+          <button
+            v-for="t in themes"
+            :key="t.id"
+            :class="['variant-tab', { active: t.id === activeThemeId, pinned: t.id === pinnedThemeId }]"
+            @click="setActiveTheme(t.id)"
+          >
+            <span v-if="t.id === defaultThemeId && !pinnedThemeId" class="variant-dot" />
+            {{ t.name }}
+          </button>
+        </div>
+        <button v-if="pinnedThemeId" class="variant-follow-btn" @click="pinnedThemeId = null">
+          Follow default
+        </button>
+      </div>
+
+      <!-- Section tabs -->
+      <div class="theme-tabs">
+        <button :class="['theme-tab', { active: activeSection === 'colors' }]" @click="activeSection = 'colors'">
+          Colors <span v-if="colorEditCount + newColors.length" class="theme-tab-badge">{{ colorEditCount + newColors.length }}</span>
+        </button>
+        <button :class="['theme-tab', { active: activeSection === 'typography' }]" @click="activeSection = 'typography'">
+          Type <span v-if="familyEditCount + scaleEditCount + newFamilies.length + newScale.length" class="theme-tab-badge">{{ familyEditCount + scaleEditCount + newFamilies.length + newScale.length }}</span>
+        </button>
+        <button :class="['theme-tab', { active: activeSection === 'spacing' }]" @click="activeSection = 'spacing'">
+          Spacing <span v-if="spacingEditCount + newSpacing.length" class="theme-tab-badge">{{ spacingEditCount + newSpacing.length }}</span>
+        </button>
+        <button :class="['theme-tab', { active: activeSection === 'borders' }]" @click="activeSection = 'borders'">
+          Borders <span v-if="radiusEditCount + newRadius.length" class="theme-tab-badge">{{ radiusEditCount + newRadius.length }}</span>
+        </button>
+      </div>
+
+      <!-- Content -->
+      <div class="theme-content">
+
+        <!-- COLORS -->
+        <div v-if="activeSection === 'colors'" class="theme-section">
+          <div v-if="colors.length === 0 && newColors.length === 0" class="theme-section-empty">No color tokens detected</div>
+          <div v-for="token in colors" :key="token.role" class="token-row">
+            <div class="token-info">
+              <span class="token-role" :class="{ edited: isEdited(token, editedColors) }">{{ token.role }}</span>
+              <code class="token-source">{{ token.source }}</code>
+            </div>
+            <div class="token-controls">
+              <div class="color-swatch-wrapper">
+                <ColorPalettePicker :modelValue="getEffectiveValue(token, editedColors)" :showTokens="false" @update:modelValue="onColorChange(token, $event)" />
+              </div>
+              <input class="token-value-input color-hex" :value="getEffectiveValue(token, editedColors)" @change="onColorChange(token, ($event.target as HTMLInputElement).value)" />
+              <span v-if="!token.cssVar" class="no-preview-badge">no preview</span>
+            </div>
+          </div>
+          <div v-for="(token, i) in newColors" :key="'nc-'+i" class="token-row new">
+            <div class="token-info"><span class="token-role new-badge">+ {{ token.role }}</span></div>
+            <div class="token-controls">
+              <div class="color-swatch-inline" :style="{ background: newTokenDisplayValue(token) }" />
+              <code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code>
+              <button class="token-remove" @click="removeNew(newColors, i)">&times;</button>
+            </div>
+          </div>
+          <ThemeAddTokenForm :active="addingNew === 'colors'" role-placeholder="Role (e.g. info)" value-placeholder="Value (e.g. #3b82f6)" css-var-placeholder="CSS var (optional)" @add="confirmAdd" @cancel="cancelAdd" />
+          <button v-if="addingNew !== 'colors'" class="add-token-btn" @click="startAdd('colors')">+ Add Color</button>
+        </div>
+
+        <!-- TYPOGRAPHY -->
+        <div v-if="activeSection === 'typography'" class="theme-section">
+          <h4 class="section-subtitle">Font Families</h4>
+          <div v-if="families.length === 0 && newFamilies.length === 0" class="theme-section-empty">No font families detected</div>
+          <div v-for="token in families" :key="token.role" class="token-row">
+            <div class="token-info"><span class="token-role" :class="{ edited: isEdited(token, editedFamilies) }">{{ token.role }}</span><code class="token-source">{{ token.source }}</code></div>
+            <div class="token-controls"><input class="token-value-input wide" :value="getEffectiveValue(token, editedFamilies)" @change="onTokenChange(token, ($event.target as HTMLInputElement).value, editedFamilies)" /></div>
+          </div>
+          <div v-for="(token, i) in newFamilies" :key="'nf-'+i" class="token-row new">
+            <div class="token-info"><span class="token-role new-badge">+ {{ token.role }}</span></div>
+            <div class="token-controls"><code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code><button class="token-remove" @click="removeNew(newFamilies, i)">&times;</button></div>
+          </div>
+          <ThemeAddTokenForm :active="addingNew === 'families'" role-placeholder="Role (e.g. display)" value-placeholder="Value (e.g. Poppins, sans-serif)" @add="confirmAdd" @cancel="cancelAdd" />
+          <button v-if="addingNew !== 'families'" class="add-token-btn" @click="startAdd('families')">+ Add Family</button>
+
+          <h4 class="section-subtitle" style="margin-top:16px">Font Scale</h4>
+          <div v-if="scale.length === 0 && newScale.length === 0" class="theme-section-empty">No font sizes detected</div>
+          <div v-for="token in scale" :key="token.role" class="token-row">
+            <div class="token-info"><span class="token-role" :class="{ edited: isEdited(token, editedScale) }">{{ token.role }}</span><code class="token-source">{{ token.source }}</code></div>
+            <div class="token-controls">
+              <input class="token-value-input" :value="getEffectiveValue(token, editedScale)" @change="onTokenChange(token, ($event.target as HTMLInputElement).value, editedScale)" />
+              <div class="font-size-preview" :style="{ fontSize: getEffectiveValue(token, editedScale) }">Aa</div>
+            </div>
+          </div>
+          <div v-for="(token, i) in newScale" :key="'ns-'+i" class="token-row new">
+            <div class="token-info"><span class="token-role new-badge">+ {{ token.role }}</span></div>
+            <div class="token-controls"><code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code><button class="token-remove" @click="removeNew(newScale, i)">&times;</button></div>
+          </div>
+          <ThemeAddTokenForm :active="addingNew === 'scale'" role-placeholder="Role (e.g. 2xl)" value-placeholder="Value (e.g. 1.5rem)" @add="confirmAdd" @cancel="cancelAdd" />
+          <button v-if="addingNew !== 'scale'" class="add-token-btn" @click="startAdd('scale')">+ Add Size</button>
+
+          <template v-if="weights.length">
+            <h4 class="section-subtitle" style="margin-top:16px">Weights</h4>
+            <div class="weight-chips"><span v-for="w in weights" :key="w" class="weight-chip">{{ w }}</span></div>
+          </template>
+        </div>
+
+        <!-- SPACING -->
+        <div v-if="activeSection === 'spacing'" class="theme-section">
+          <div v-if="spacing.length === 0 && newSpacing.length === 0" class="theme-section-empty">No spacing tokens detected</div>
+          <div v-for="token in spacing" :key="token.role" class="token-row">
+            <div class="token-info"><span class="token-role" :class="{ edited: isEdited(token, editedSpacing) }">{{ token.role }}</span><code class="token-source">{{ token.source }}</code></div>
+            <div class="token-controls">
+              <input class="token-value-input" :value="getEffectiveValue(token, editedSpacing)" @change="onTokenChange(token, ($event.target as HTMLInputElement).value, editedSpacing)" />
+              <div class="spacing-preview"><div class="spacing-bar" :style="{ width: getEffectiveValue(token, editedSpacing) }" /></div>
+            </div>
+          </div>
+          <div v-for="(token, i) in newSpacing" :key="'nsp-'+i" class="token-row new">
+            <div class="token-info"><span class="token-role new-badge">+ {{ token.role }}</span></div>
+            <div class="token-controls"><code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code><button class="token-remove" @click="removeNew(newSpacing, i)">&times;</button></div>
+          </div>
+          <ThemeAddTokenForm :active="addingNew === 'spacing'" role-placeholder="Role (e.g. 2xl)" value-placeholder="Value (e.g. 32px)" @add="confirmAdd" @cancel="cancelAdd" />
+          <button v-if="addingNew !== 'spacing'" class="add-token-btn" @click="startAdd('spacing')">+ Add Spacing</button>
+        </div>
+
+        <!-- BORDERS -->
+        <div v-if="activeSection === 'borders'" class="theme-section">
+          <h4 class="section-subtitle">Border Radius</h4>
+          <div v-if="radius.length === 0 && newRadius.length === 0" class="theme-section-empty">No border radius tokens detected</div>
+          <div v-for="token in radius" :key="token.role" class="token-row">
+            <div class="token-info"><span class="token-role" :class="{ edited: isEdited(token, editedRadius) }">{{ token.role }}</span><code class="token-source">{{ token.source }}</code></div>
+            <div class="token-controls">
+              <input class="token-value-input" :value="getEffectiveValue(token, editedRadius)" @change="onTokenChange(token, ($event.target as HTMLInputElement).value, editedRadius)" />
+              <div class="radius-preview" :style="{ borderRadius: getEffectiveValue(token, editedRadius) }" />
+            </div>
+          </div>
+          <div v-for="(token, i) in newRadius" :key="'nr-'+i" class="token-row new">
+            <div class="token-info"><span class="token-role new-badge">+ {{ token.role }}</span></div>
+            <div class="token-controls"><code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code><button class="token-remove" @click="removeNew(newRadius, i)">&times;</button></div>
+          </div>
+          <ThemeAddTokenForm :active="addingNew === 'radius'" role-placeholder="Role (e.g. xl)" value-placeholder="Value (e.g. 16px)" @add="confirmAdd" @cancel="cancelAdd" />
+          <button v-if="addingNew !== 'radius'" class="add-token-btn" @click="startAdd('radius')">+ Add Radius</button>
+        </div>
+
+      </div>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.dte { display: flex; flex-direction: column; height: 100%; overflow: hidden; }
+.dte-empty { padding: 24px; text-align: center; font-size: 12px; color: var(--text-muted); }
+
+/* Variant bar — identical to ThemePage */
+.variant-bar {
+  display: flex; align-items: center; gap: 6px;
+  padding: 6px 12px; border-bottom: 1px solid var(--border);
+  background: var(--surface-2); flex-shrink: 0;
+}
+.variant-tabs { display: flex; flex: 1; gap: 4px; overflow-x: auto; }
+.variant-tab {
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 3px 10px; font-size: 11px; font-weight: 500;
+  background: transparent; border: 1px solid var(--border);
+  color: var(--text-muted); border-radius: 4px; cursor: pointer;
+  white-space: nowrap; transition: all 0.15s;
+}
+.variant-tab:hover { color: var(--text); }
+.variant-tab.active { color: var(--text); background: var(--surface-elevated); border-color: var(--accent); }
+.variant-tab.pinned { border-style: dashed; }
+.variant-dot {
+  width: 6px; height: 6px; border-radius: 50%; background: var(--accent);
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 25%, transparent); flex-shrink: 0;
+}
+.variant-follow-btn {
+  padding: 3px 8px; font-size: 10px; font-weight: 500;
+  background: transparent; border: 1px solid var(--border);
+  color: var(--text-muted); border-radius: 4px; cursor: pointer; white-space: nowrap;
+}
+.variant-follow-btn:hover { color: var(--text); background: var(--surface-elevated); }
+
+/* Section tabs */
+.theme-tabs { display: flex; border-bottom: 1px solid var(--border); flex-shrink: 0; }
+.theme-tab {
+  flex: 1; padding: 8px 4px; font-size: 11px; font-weight: 500;
+  background: none; border: none; border-bottom: 2px solid transparent;
+  color: var(--text-muted); cursor: pointer; transition: all 0.15s;
+}
+.theme-tab:hover { color: var(--text); }
+.theme-tab.active { color: var(--accent); border-bottom-color: var(--accent); }
+.theme-tab-badge {
+  display: inline-flex; align-items: center; justify-content: center;
+  min-width: 14px; height: 14px; padding: 0 3px; font-size: 9px; font-weight: 700;
+  background: var(--danger); color: white; border-radius: 7px; margin-left: 3px;
+}
+
+/* Content */
+.theme-content { flex: 1; overflow-y: auto; padding: 12px; }
+.theme-section { display: flex; flex-direction: column; gap: 2px; }
+.theme-section-empty {
+  padding: 16px 0; text-align: center; font-size: 11px;
+  color: var(--text-muted); opacity: 0.6;
+}
+.section-subtitle {
+  font-size: 10px; font-weight: 600; text-transform: uppercase;
+  letter-spacing: 0.05em; color: var(--text-muted); padding: 6px 0 4px;
+}
+
+/* Token rows */
+.token-row {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 6px 8px; border-radius: 6px; gap: 8px; transition: background 0.1s;
+}
+.token-row:hover { background: var(--surface-2); }
+.token-row.new { background: color-mix(in srgb, var(--accent) 6%, transparent); }
+.token-info { display: flex; flex-direction: column; gap: 1px; min-width: 0; flex-shrink: 1; }
+.token-role { font-size: 12px; font-weight: 500; color: var(--text); white-space: nowrap; }
+.token-role.edited { color: var(--accent); }
+.token-role.new-badge { color: var(--success); font-weight: 600; }
+.token-source { font-size: 9px; color: var(--text-muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 160px; }
+.token-controls { display: flex; align-items: center; gap: 6px; flex-shrink: 0; }
+.token-value-input {
+  width: 80px; padding: 3px 6px; font-size: 11px; font-family: monospace;
+  background: var(--bg); border: 1px solid var(--border); border-radius: 4px;
+  color: var(--text); outline: none;
+}
+.token-value-input:focus { border-color: var(--accent); }
+.token-value-input.wide { width: 160px; }
+.token-value-input.color-hex { width: 72px; }
+.token-value-ro { font-size: 11px; color: var(--text-muted); }
+.token-remove {
+  width: 18px; height: 18px; border: none; background: none; color: var(--text-muted);
+  font-size: 14px; cursor: pointer; display: flex; align-items: center;
+  justify-content: center; border-radius: 3px;
+}
+.token-remove:hover { color: var(--danger); background: color-mix(in srgb, var(--danger) 10%, transparent); }
+.no-preview-badge { font-size: 8px; color: var(--text-muted); opacity: 0.6; white-space: nowrap; }
+.color-swatch-wrapper { flex-shrink: 0; }
+.color-swatch-inline {
+  width: 20px; height: 20px; border-radius: 4px; border: 1px solid var(--border); flex-shrink: 0;
+}
+.font-size-preview { color: var(--text); line-height: 1; white-space: nowrap; }
+.weight-chips { display: flex; flex-wrap: wrap; gap: 4px; padding: 4px 0; }
+.weight-chip {
+  font-size: 10px; padding: 2px 8px; background: var(--surface-2);
+  border: 1px solid var(--border); border-radius: 4px; color: var(--text-muted);
+}
+.spacing-preview { width: 60px; height: 12px; background: var(--surface-2); border-radius: 2px; overflow: hidden; }
+.spacing-bar { height: 100%; background: var(--accent); border-radius: 2px; max-width: 100%; transition: width 0.15s; }
+.radius-preview { width: 24px; height: 24px; background: var(--accent); transition: border-radius 0.15s; }
+.add-token-btn {
+  padding: 6px; margin-top: 4px; font-size: 11px; color: var(--text-muted);
+  background: none; border: 1px dashed var(--border); border-radius: 6px; cursor: pointer; transition: all 0.1s;
+}
+.add-token-btn:hover { color: var(--accent); border-color: var(--accent); }
+</style>
diff --git a/src/shell/components/DrawnSectionOverlay.vue b/src/shell/components/DrawnSectionOverlay.vue
deleted file mode 100644
index 3ccc401..0000000
--- a/src/shell/components/DrawnSectionOverlay.vue
+++ /dev/null
@@ -1,325 +0,0 @@
-<script setup lang="ts">
-import { ref, watch, nextTick } from 'vue'
-import { safeMd } from '../utils/safeMd'
-import type { DrawnSection } from '../composables/useAnnotations'
-
-const props = defineProps<{
-  sections: DrawnSection[]
-  selectedId: string | null
-  drawingRect: { x: number; y: number; width: number; height: number } | null
-  sectionTaskMap: Record<string, string>
-}>()
-
-const emit = defineEmits<{
-  select: [id: string]
-  remove: [id: string]
-  'update-prompt': [id: string, prompt: string]
-  'update-rect': [id: string, rect: { x: number; y: number; width: number; height: number }]
-  submit: [id: string]
-}>()
-
-const editingId = ref<string | null>(null)
-const textareaRef = ref<HTMLTextAreaElement | null>(null)
-
-// ── Drag / resize state ──
-const dragState = ref<{
-  id: string
-  mode: 'move' | 'resize'
-  handle?: string
-  startX: number; startY: number
-  origX: number; origY: number; origW: number; origH: number
-} | null>(null)
-
-function hasTask(id: string): boolean {
-  return !!props.sectionTaskMap[id]
-}
-
-function renderMd(text: string): string {
-  return safeMd(text)
-}
-
-function startEditing(id: string) {
-  editingId.value = id
-  nextTick(() => textareaRef.value?.focus())
-}
-
-function onTextareaBlur(e: FocusEvent, id: string) {
-  const section = (e.target as HTMLElement).closest('.drawn-section')
-  if (section && section.contains(e.relatedTarget as Node)) return
-  editingId.value = null
-}
-
-// ── Move (drag header) ──
-function onMoveDown(e: PointerEvent, section: DrawnSection) {
-  e.preventDefault()
-  e.stopPropagation()
-  dragState.value = {
-    id: section.id, mode: 'move',
-    startX: e.clientX, startY: e.clientY,
-    origX: section.x, origY: section.y, origW: section.width, origH: section.height,
-  }
-  window.addEventListener('pointermove', onDragMove)
-  window.addEventListener('pointerup', onDragUp)
-}
-
-// ── Resize ──
-function onResizeDown(e: PointerEvent, section: DrawnSection, handle: string) {
-  e.preventDefault()
-  e.stopPropagation()
-  dragState.value = {
-    id: section.id, mode: 'resize', handle,
-    startX: e.clientX, startY: e.clientY,
-    origX: section.x, origY: section.y, origW: section.width, origH: section.height,
-  }
-  window.addEventListener('pointermove', onDragMove)
-  window.addEventListener('pointerup', onDragUp)
-}
-
-function onDragMove(e: PointerEvent) {
-  const d = dragState.value
-  if (!d) return
-  const dx = e.clientX - d.startX
-  const dy = e.clientY - d.startY
-
-  if (d.mode === 'move') {
-    emit('update-rect', d.id, { x: d.origX + dx, y: d.origY + dy, width: d.origW, height: d.origH })
-    return
-  }
-
-  let x = d.origX, y = d.origY, w = d.origW, h = d.origH
-  const handle = d.handle || ''
-  if (handle.includes('e')) w = Math.max(60, d.origW + dx)
-  if (handle.includes('s')) h = Math.max(60, d.origH + dy)
-  if (handle.includes('w')) { w = Math.max(60, d.origW - dx); x = d.origX + d.origW - w }
-  if (handle.includes('n')) { h = Math.max(60, d.origH - dy); y = d.origY + d.origH - h }
-  emit('update-rect', d.id, { x, y, width: w, height: h })
-}
-
-function onDragUp() {
-  dragState.value = null
-  window.removeEventListener('pointermove', onDragMove)
-  window.removeEventListener('pointerup', onDragUp)
-}
-</script>
-
-<template>
-  <!-- Drawing preview -->
-  <div
-    v-if="drawingRect && drawingRect.width > 5 && drawingRect.height > 5"
-    class="section-preview"
-    :style="{
-      left: drawingRect.x + 'px', top: drawingRect.y + 'px',
-      width: drawingRect.width + 'px', height: drawingRect.height + 'px',
-    }"
-  />
-
-  <!-- Existing sections -->
-  <div
-    v-for="section in sections"
-    :key="section.id"
-    class="drawn-section"
-    :class="{ selected: section.id === selectedId, submitted: hasTask(section.id) }"
-    :style="{
-      left: section.x + 'px', top: section.y + 'px',
-      width: section.width + 'px', height: section.height + 'px',
-    }"
-    @click.stop="emit('select', section.id)"
-  >
-    <!-- Collapsed view when not selected -->
-    <template v-if="section.id !== selectedId">
-      <div class="section-badge-float">
-        <span>#{{ section.number }}</span>
-        <span v-if="hasTask(section.id)" class="badge-check">&#10003;</span>
-      </div>
-      <div v-if="section.prompt" class="section-hint" v-html="renderMd(section.prompt)" />
-    </template>
-
-    <!-- Full UI when selected -->
-    <template v-else>
-      <div class="section-header" @pointerdown="onMoveDown($event, section)" style="cursor: grab;">
-        <span class="section-badge">#{{ section.number }}</span>
-        <span v-if="hasTask(section.id)" class="section-status">Task added</span>
-        <span class="section-dims-inline">{{ Math.round(section.width) }}×{{ Math.round(section.height) }}px</span>
-        <button class="section-delete" @click.stop="emit('remove', section.id)" @pointerdown.stop title="Delete section">×</button>
-      </div>
-
-      <div class="section-body">
-        <textarea
-          v-if="editingId === section.id"
-          ref="textareaRef"
-          class="section-editor"
-          :value="section.prompt"
-          placeholder="Describe what should go here... (supports markdown)"
-          @input="emit('update-prompt', section.id, ($event.target as HTMLTextAreaElement).value)"
-          @blur="onTextareaBlur($event, section.id)"
-          @keydown.escape="editingId = null"
-          @click.stop
-        />
-        <div v-else class="section-md-preview" @click.stop="startEditing(section.id)">
-          <div v-if="section.prompt" class="md-content" v-html="renderMd(section.prompt)" />
-          <span v-else class="md-placeholder">Click to describe what should go here...</span>
-        </div>
-      </div>
-
-      <div class="section-footer">
-        <span v-if="section.placement" class="section-placement">{{ section.placement }}</span>
-        <button
-          class="section-submit"
-          :class="{ update: hasTask(section.id) }"
-          :disabled="!section.prompt.trim()"
-          @click.stop="emit('submit', section.id)"
-          @pointerdown.stop
-        >{{ hasTask(section.id) ? 'Update Task' : 'Add Task' }}</button>
-      </div>
-
-      <!-- Resize handles -->
-      <div class="resize-handle rh-n" @pointerdown="onResizeDown($event, section, 'n')" />
-      <div class="resize-handle rh-s" @pointerdown="onResizeDown($event, section, 's')" />
-      <div class="resize-handle rh-e" @pointerdown="onResizeDown($event, section, 'e')" />
-      <div class="resize-handle rh-w" @pointerdown="onResizeDown($event, section, 'w')" />
-      <div class="resize-handle rh-ne" @pointerdown="onResizeDown($event, section, 'ne')" />
-      <div class="resize-handle rh-nw" @pointerdown="onResizeDown($event, section, 'nw')" />
-      <div class="resize-handle rh-se" @pointerdown="onResizeDown($event, section, 'se')" />
-      <div class="resize-handle rh-sw" @pointerdown="onResizeDown($event, section, 'sw')" />
-    </template>
-  </div>
-</template>
-
-<style scoped>
-.section-preview {
-  position: fixed;
-  z-index: 10003;
-  border: 2px dashed var(--mode-draw);
-  background: rgba(0, 0, 0, 0.15);
-  border-radius: 6px;
-  pointer-events: none;
-}
-
-.drawn-section {
-  position: fixed;
-  z-index: 10003;
-  border: 2px dashed rgba(107, 114, 128, 0.4);
-  border-radius: 6px;
-  display: flex;
-  flex-direction: column;
-  overflow: visible;
-  cursor: pointer;
-  transition: border-color 0.15s, background 0.15s, box-shadow 0.15s;
-}
-.drawn-section.submitted {
-  border-color: rgba(107, 114, 128, 0.6);
-}
-.drawn-section.selected {
-  border-color: var(--mode-draw);
-  border-style: solid;
-  background: rgba(24, 24, 27, 0.95);
-  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.25);
-  cursor: default;
-}
-
-/* Collapsed badge */
-.section-badge-float {
-  position: absolute; top: 4px; left: 4px;
-  display: flex; align-items: center; gap: 3px;
-  font-size: 9px; font-weight: 700; color: var(--text);
-  background: rgba(24, 24, 27, 0.8); padding: 1px 5px; border-radius: 3px;
-  pointer-events: none;
-}
-.badge-check { color: var(--success); font-size: 10px; }
-
-/* Faint hint when collapsed */
-.section-hint {
-  padding: 22px 8px 4px;
-  font-size: 10px; color: var(--text-muted); line-height: 1.3;
-  overflow: hidden; pointer-events: none;
-  max-height: 100%; opacity: 0.5;
-}
-.section-hint :deep(*) { margin: 0; font-size: 10px; }
-
-/* Header */
-.section-header {
-  display: flex; align-items: center; gap: 6px;
-  padding: 4px 8px;
-  background: rgba(255, 255, 255, 0.05);
-  border-bottom: 1px solid rgba(255, 255, 255, 0.08);
-  flex-shrink: 0;
-  user-select: none;
-}
-.section-badge { font-size: 9px; font-weight: 700; color: var(--text); }
-.section-status { font-size: 8px; color: var(--success); font-weight: 600; }
-.section-dims-inline { font-size: 8px; color: rgba(255,255,255,0.25); margin-left: auto; }
-.section-delete {
-  width: 16px; height: 16px; border: none; background: none;
-  color: var(--text-muted); font-size: 14px; cursor: pointer; padding: 0;
-  display: flex; align-items: center; justify-content: center;
-}
-.section-delete:hover { color: var(--danger); }
-
-/* Body */
-.section-body {
-  flex: 1; min-height: 0; display: flex; flex-direction: column;
-  overflow: hidden;
-}
-
-/* Editor (raw markdown) */
-.section-editor {
-  flex: 1; padding: 8px; border: none; background: transparent;
-  color: var(--text); font-size: 11px; line-height: 1.5;
-  resize: none; outline: none; font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
-  min-height: 40px;
-}
-.section-editor::placeholder { color: rgba(255,255,255,0.2); }
-
-/* Preview (rendered markdown) */
-.section-md-preview {
-  flex: 1; padding: 8px; overflow-y: auto;
-  cursor: text; min-height: 40px;
-}
-.md-content { font-size: 12px; line-height: 1.5; color: var(--text); }
-.md-content :deep(h1) { font-size: 16px; font-weight: 700; margin: 0 0 6px; color: var(--text); }
-.md-content :deep(h2) { font-size: 14px; font-weight: 700; margin: 0 0 4px; color: var(--text); }
-.md-content :deep(h3) { font-size: 13px; font-weight: 600; margin: 0 0 4px; color: var(--text); }
-.md-content :deep(p) { margin: 0 0 6px; }
-.md-content :deep(ul), .md-content :deep(ol) { margin: 0 0 6px; padding-left: 18px; }
-.md-content :deep(li) { margin: 0 0 2px; }
-.md-content :deep(code) { font-size: 10px; background: rgba(255,255,255,0.08); padding: 1px 4px; border-radius: 3px; color: var(--text-muted); }
-.md-content :deep(pre) { font-size: 10px; background: rgba(255,255,255,0.05); padding: 6px; border-radius: 4px; margin: 0 0 6px; overflow-x: auto; }
-.md-content :deep(strong) { font-weight: 700; color: var(--text); }
-.md-placeholder { font-size: 11px; color: rgba(255,255,255,0.2); font-style: italic; }
-
-/* Footer with submit */
-.section-footer {
-  display: flex; align-items: center; gap: 6px;
-  padding: 4px 8px;
-  border-top: 1px solid rgba(255, 255, 255, 0.08);
-  flex-shrink: 0;
-}
-.section-placement { font-size: 8px; color: var(--text-muted); background: rgba(255,255,255,0.08); padding: 1px 4px; border-radius: 3px; }
-.section-submit {
-  margin-left: auto;
-  padding: 3px 10px; border: none; border-radius: 4px;
-  font-size: 10px; font-weight: 600; cursor: pointer;
-  background: var(--accent); color: var(--text-on-accent);
-  transition: background 0.1s;
-}
-.section-submit:hover { background: var(--accent-hover); }
-.section-submit:disabled { opacity: 0.3; cursor: not-allowed; }
-.section-submit.update { background: var(--success); }
-.section-submit.update:hover { opacity: 0.9; }
-
-/* ── Resize handles ── */
-.resize-handle { position: absolute; z-index: 1; }
-.rh-n  { top: -4px; left: 8px; right: 8px; height: 8px; cursor: n-resize; }
-.rh-s  { bottom: -4px; left: 8px; right: 8px; height: 8px; cursor: s-resize; }
-.rh-e  { right: -4px; top: 8px; bottom: 8px; width: 8px; cursor: e-resize; }
-.rh-w  { left: -4px; top: 8px; bottom: 8px; width: 8px; cursor: w-resize; }
-.rh-nw, .rh-ne, .rh-sw, .rh-se {
-  width: 10px; height: 10px;
-  background: var(--mode-draw); border: 1.5px solid var(--text);
-  border-radius: 2px;
-}
-.rh-nw { top: -5px; left: -5px; cursor: nw-resize; }
-.rh-ne { top: -5px; right: -5px; cursor: ne-resize; }
-.rh-sw { bottom: -5px; left: -5px; cursor: sw-resize; }
-.rh-se { bottom: -5px; right: -5px; cursor: se-resize; }
-</style>
diff --git a/src/shell/components/ElementStyleEditor.vue b/src/shell/components/ElementStyleEditor.vue
index 58db0a7..9d782d8 100644
--- a/src/shell/components/ElementStyleEditor.vue
+++ b/src/shell/components/ElementStyleEditor.vue
@@ -31,10 +31,11 @@ const emit = defineEmits<{
 
 const activeTab = ref<'layout' | 'spacing' | 'size' | 'style' | 'classes'>('layout')
 
-type StyleOrClassChange = StyleChangeRecord | ClassChangeRecord
+type PendingChange = StyleChangeRecord | ClassChangeRecord
 
-const styleClassChanges = computed<StyleOrClassChange[]>(() =>
-  props.changes.filter((c): c is StyleOrClassChange => c.type === 'style_update' || c.type === 'class_update')
+const styleClassChanges = computed<PendingChange[]>(() =>
+  props.changes.filter((c): c is PendingChange =>
+    c.type === 'style_update' || c.type === 'class_update')
 )
 
 function onStyleChange(property: string, value: string, tokenRole?: string) {
@@ -72,24 +73,31 @@ const localApplyToGroup = computed({
       </label>
     </div>
 
-    <div class="panel-tabs">
-      <button :class="['tab', { active: activeTab === 'layout' }]" @click="activeTab = 'layout'" title="Edit display, flex, and grid properties">Layout</button>
-      <button :class="['tab', { active: activeTab === 'spacing' }]" @click="activeTab = 'spacing'" title="Edit padding and margin">Spacing</button>
-      <button :class="['tab', { active: activeTab === 'size' }]" @click="activeTab = 'size'" title="Edit width, height, and constraints">Size</button>
-      <button :class="['tab', { active: activeTab === 'style' }]" @click="activeTab = 'style'" title="Edit colors, typography, and appearance">Style</button>
-      <button :class="['tab', { active: activeTab === 'classes' }]" @click="activeTab = 'classes'" title="Edit CSS classes directly">Classes</button>
+    <!-- A wireframe placement has no source anchor yet — a style edit here
+         would journal an entry the apply loop can't snapshot or verify. -->
+    <div v-if="selectedElementRole === 'placement'" class="placement-note">
+      Wireframe placement — edit it via the palette and placements panel.
     </div>
+    <template v-else>
+      <div class="panel-tabs">
+        <button :class="['tab', { active: activeTab === 'layout' }]" @click="activeTab = 'layout'" title="Edit display, flex, and grid properties">Layout</button>
+        <button :class="['tab', { active: activeTab === 'spacing' }]" @click="activeTab = 'spacing'" title="Edit padding and margin">Spacing</button>
+        <button :class="['tab', { active: activeTab === 'size' }]" @click="activeTab = 'size'" title="Edit width, height, and constraints">Size</button>
+        <button :class="['tab', { active: activeTab === 'style' }]" @click="activeTab = 'style'" title="Edit colors, typography, and appearance">Style</button>
+        <button :class="['tab', { active: activeTab === 'classes' }]" @click="activeTab = 'classes'" title="Edit CSS classes directly">Classes</button>
+      </div>
 
-    <div class="tab-content">
-      <LayoutControls v-if="activeTab === 'layout'" :computedStyles="liveStyles" @change="onStyleChange" />
-      <SpacingControls v-if="activeTab === 'spacing'" :computedStyles="liveStyles" @change="onStyleChange" />
-      <SizeControls v-if="activeTab === 'size'" :computedStyles="liveStyles" @change="onStyleChange" />
-      <AppearanceControls v-if="activeTab === 'style'" :computedStyles="liveStyles" @change="onStyleChange" />
-      <div v-if="activeTab === 'classes'" class="classes-tab">
-        <textarea v-model="localClasses" class="class-editor" rows="4" @blur="onClassBlur" @keydown.enter.ctrl="onClassBlur" placeholder="Edit CSS classes..." />
-        <p class="hint">Ctrl+Enter or blur to apply</p>
+      <div class="tab-content">
+        <LayoutControls v-if="activeTab === 'layout'" :computedStyles="liveStyles" @change="onStyleChange" />
+        <SpacingControls v-if="activeTab === 'spacing'" :computedStyles="liveStyles" @change="onStyleChange" />
+        <SizeControls v-if="activeTab === 'size'" :computedStyles="liveStyles" @change="onStyleChange" />
+        <AppearanceControls v-if="activeTab === 'style'" :computedStyles="liveStyles" @change="onStyleChange" />
+        <div v-if="activeTab === 'classes'" class="classes-tab">
+          <textarea v-model="localClasses" class="class-editor" rows="4" @blur="onClassBlur" @keydown.enter.ctrl="onClassBlur" placeholder="Edit CSS classes..." />
+          <p class="hint">Ctrl+Enter or blur to apply</p>
+        </div>
       </div>
-    </div>
+    </template>
 
     <div v-if="styleClassChanges.length" class="changes-footer">
       <div class="changes-list">
@@ -128,4 +136,10 @@ const localApplyToGroup = computed({
   overflow-y: auto;
   padding: 8px 12px;
 }
+
+.placement-note {
+  font-size: 11px;
+  color: var(--text-muted);
+  padding: 8px 12px;
+}
 </style>
diff --git a/src/shell/components/ErrorsTab.vue b/src/shell/components/ErrorsTab.vue
index 15c7d42..9119fce 100644
--- a/src/shell/components/ErrorsTab.vue
+++ b/src/shell/components/ErrorsTab.vue
@@ -258,7 +258,7 @@ function onCreateTask(entry: ErrorEntry) {
 
 .error-stack {
   display: flex; flex-direction: column; gap: 2px;
-  padding: 8px; border-radius: 6px; background: rgba(0,0,0,0.3);
+  padding: 8px; border-radius: 6px; background: var(--bg);
   overflow-x: auto;
 }
 .stack-line {
diff --git a/src/shell/components/FindingDrawer.vue b/src/shell/components/FindingDrawer.vue
index ca58e3a..4d186b3 100644
--- a/src/shell/components/FindingDrawer.vue
+++ b/src/shell/components/FindingDrawer.vue
@@ -43,7 +43,7 @@ function onKeydown(e: KeyboardEvent) {
 
 <style scoped>
 .fd-overlay { position: fixed; inset: 0; z-index: 50000; display: flex; justify-content: flex-end; }
-.fd-backdrop { position: absolute; inset: 0; background: rgba(0,0,0,0.4); }
+.fd-backdrop { position: absolute; inset: 0; background: var(--overlay); }
 .fd-drawer {
   position: relative; width: min(480px, 85vw); height: 100%;
   background: var(--surface); color: var(--text); border-left: 1px solid var(--border);
diff --git a/src/shell/components/HelpOverlay.vue b/src/shell/components/HelpOverlay.vue
index 30ec37f..98a2881 100644
--- a/src/shell/components/HelpOverlay.vue
+++ b/src/shell/components/HelpOverlay.vue
@@ -45,7 +45,6 @@
             <div class="shortcut-row"><kbd>V</kbd><span>Select</span></div>
             <div class="shortcut-row"><kbd>P</kbd><span>Pin</span></div>
             <div class="shortcut-row"><kbd>A</kbd><span>Arrow</span></div>
-            <div class="shortcut-row"><kbd>D</kbd><span>Draw Section</span></div>
             <div class="shortcut-row"><kbd>H</kbd><span>Highlight Text</span></div>
             <div class="shortcut-row"><kbd>I</kbd><span>Interact Mode</span></div>
           </div>
@@ -68,7 +67,7 @@
       <!-- Annotate -->
       <div v-else-if="helpSection === 'annotate'" class="help-page">
         <h2 class="help-page-title">Annotate</h2>
-        <p class="help-intro">The <strong>Annotate</strong> tab is where you mark up your running app. Drop pins, draw arrows, outline new sections, highlight text — every annotation becomes a task for your AI agent with element metadata, source location, and optional screenshots.</p>
+        <p class="help-intro">The <strong>Annotate</strong> tab is where you mark up your running app. Drop pins, draw arrows, highlight text — every annotation becomes a task for your AI agent with element metadata, source location, and optional screenshots. (Sections are wireframe sketch material now — draw them on the wireframe canvas in the Design tab.)</p>
 
         <h3 id="annotate-tools" class="help-section-title">Tools</h3>
         <div class="help-feature-list">
@@ -84,10 +83,6 @@
             <div class="help-feature-header"><kbd>A</kbd> Arrow</div>
             <p>Draw arrows between elements to show relationships or flow. Arrows snap to element edges with bezier curves. Drag endpoints to reposition. Six color presets available.</p>
           </div>
-          <div class="help-feature">
-            <div class="help-feature-header"><kbd>D</kbd> Draw Section</div>
-            <p>Draw a rectangular area to describe a new content section. Includes a markdown editor for detailed descriptions. Sections are movable and resizable.</p>
-          </div>
           <div class="help-feature">
             <div class="help-feature-header"><kbd>H</kbd> Highlight Text</div>
             <p>Select text in your app to highlight it. The highlight attaches to the DOM range and tracks scroll. Create tasks referencing the highlighted content.</p>
@@ -121,16 +116,13 @@
       <!-- Audit -->
       <div v-else-if="helpSection === 'audit'" class="help-page">
         <h2 class="help-page-title">Audit</h2>
-        <p class="help-intro">Monitor runtime health and code quality. The <strong>Audit</strong> tab has five sub-sections: <strong>A11y</strong>, <strong>Data</strong>, <strong>Libraries</strong>, <strong>Performance</strong>, and <strong>Errors</strong>. Each surfaces findings you can turn into fix tasks with one click.</p>
+        <p class="help-intro">Monitor runtime health and code quality. The <strong>Audit</strong> tab has four sub-sections: <strong>A11y</strong>, <strong>Data</strong>, <strong>Performance</strong>, and <strong>Errors</strong>. Each surfaces findings you can turn into fix tasks with one click.</p>
 
         <h3 id="audit-a11y" class="help-section-title">A11y</h3>
         <p class="help-text">Automated WCAG audits powered by <strong>axe-core</strong> (bundled locally — no CDN). Scan the full page or a specific element. Violations group by rule with impact levels (critical, serious, moderate, minor). Each violation shows affected elements, selectors, and a WCAG reference. Click the task button to create an <strong>a11y_fix</strong> task with everything the agent needs.</p>
 
         <h3 id="audit-data" class="help-section-title">Data</h3>
-        <p class="help-text">Discovers data sources in your app — composables, stores, <code>fetch</code>/<code>axios</code> calls, tRPC, GraphQL, route loaders. Hover a data source row to highlight elements that consume it. Matches endpoints against detected API schemas (OpenAPI, GraphQL, tRPC) so the agent knows what shape comes back. Backend-contract edits create <strong>api_update</strong> tasks with schema and data-source context.</p>
-
-        <h3 id="audit-libraries" class="help-section-title">Libraries</h3>
-        <p class="help-text">Shows data-fetching and state libraries detected in your project — TanStack Query, Pinia, Redux, Zustand, Apollo, SWR, and more — with the files that use them. Useful when your agent needs to know which patterns to follow.</p>
+        <p class="help-text">Discovers data sources in your app — composables, stores, <code>fetch</code>/<code>axios</code> calls, tRPC, GraphQL, route loaders. Hover a data source row to highlight elements that consume it. Matches endpoints against detected API schemas (OpenAPI, GraphQL, tRPC) so the agent knows what shape comes back.</p>
 
         <h3 id="audit-perf" class="help-section-title">Performance</h3>
         <p class="help-text">Web Vitals (LCP, FID, CLS, TTFB), navigation timing, resource/bundle breakdown. Click <strong>Scan</strong> for a snapshot, <strong>Record</strong> to capture a session of interactions. Findings surface slow vitals, large bundles, render-blocking resources, excessive DOM size. Each finding can become a <strong>perf_fix</strong> task.</p>
@@ -186,13 +178,12 @@
         <h3 id="tasks-types" class="help-section-title">Task Types</h3>
         <p class="help-text">
           <strong>annotation</strong> (pins, arrows, notes, highlights),
-          <strong>section_request</strong> (drawn sections),
+          <strong>section_request</strong> (legacy — sections are wireframe sketch material now),
           <strong>style_update</strong> (inspector edits — CSS changes),
           <strong>theme_update</strong> (design token edits),
           <strong>a11y_fix</strong> (WCAG violation fix),
           <strong>error_fix</strong> (console error fix),
-          <strong>perf_fix</strong> (performance finding fix),
-          <strong>api_update</strong> (backend contract edits).
+          <strong>perf_fix</strong> (performance finding fix).
         </p>
 
         <h3 id="tasks-panel" class="help-section-title">Tasks Panel</h3>
@@ -333,7 +324,7 @@
         <p class="help-intro">Open Settings from the gear icon in the toolbar. Controls for appearance and shell behavior.</p>
 
         <h3 id="settings-themes" class="help-section-title">Themes</h3>
-        <p class="help-text">18 built-in themes (Dark, Light, Monokai, Solarized, Nord, One Dark, Dracula, GitHub, Catppuccin Mocha, Gruvbox, Rosé Pine, Synthwave '84, Cobalt, plus high-contrast and deuteranopia). Create custom themes via Settings → Appearance → "Create Custom Theme" — all 63 CSS variables are exposed with live preview.</p>
+        <p class="help-text">18 built-in themes (Dark, Light, Monokai, Solarized, Nord, One Dark, Dracula, GitHub, Catppuccin Mocha, Gruvbox, Rosé Pine, Synthwave '84, Cobalt, plus high-contrast and deuteranopia). Create custom themes via Settings → Appearance → "Create Custom Theme" — all 62 CSS variables are exposed with live preview.</p>
         <p class="help-text">Enable <strong>System preference</strong> to auto-pair a dark theme with a light theme and follow your OS.</p>
 
         <h3 id="settings-task-options" class="help-section-title">Task Options</h3>
diff --git a/src/shell/components/Icon.vue b/src/shell/components/Icon.vue
index c98eca5..640add9 100644
--- a/src/shell/components/Icon.vue
+++ b/src/shell/components/Icon.vue
@@ -5,6 +5,7 @@ import {
   Activity,
   ArrowRight,
   Bot,
+  BringToFront,
   Check,
   ChevronDown,
   ChevronLeft,
@@ -18,6 +19,8 @@ import {
   Copy,
   Database,
   FileSearch,
+  FileText,
+  Frame,
   Grid2x2,
   Highlighter,
   Info,
@@ -39,6 +42,7 @@ import {
   RotateCw,
   ScanSearch,
   Search,
+  SendToBack,
   Settings,
   SlidersHorizontal,
   SquareCheckBig,
@@ -56,6 +60,7 @@ const REGISTRY = {
   'activity': Activity,
   'arrow-right': ArrowRight,
   'bot': Bot,
+  'bring-to-front': BringToFront,
   'check': Check,
   'chevron-down': ChevronDown,
   'chevron-left': ChevronLeft,
@@ -69,6 +74,8 @@ const REGISTRY = {
   'copy': Copy,
   'database': Database,
   'file-search': FileSearch,
+  'file-text': FileText,
+  'frame': Frame,
   'grid-2x2': Grid2x2,
   'highlighter': Highlighter,
   'info': Info,
@@ -90,6 +97,7 @@ const REGISTRY = {
   'rotate-cw': RotateCw,
   'scan-search': ScanSearch,
   'search': Search,
+  'send-to-back': SendToBack,
   'settings': Settings,
   'sliders-horizontal': SlidersHorizontal,
   'square-check-big': SquareCheckBig,
diff --git a/src/shell/components/InitWizard.vue b/src/shell/components/InitWizard.vue
new file mode 100644
index 0000000..6dcb034
--- /dev/null
+++ b/src/shell/components/InitWizard.vue
@@ -0,0 +1,2778 @@
+<template>
+  <div class="init-modal-backdrop">
+    <div class="init-modal" role="dialog" aria-modal="true" aria-labelledby="init-modal-title">
+      <header class="init-modal-header">
+        <h2 id="init-modal-title" class="init-modal-title">Set up Annotask</h2>
+        <button
+          class="init-modal-close"
+          type="button"
+          @click="flow.closeWizard"
+          aria-label="Close"
+          title="Close — reopens on reload until you choose a workflow or finish setup"
+        >
+          <svg width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" aria-hidden="true">
+            <path d="M4 4l8 8M12 4l-8 8" />
+          </svg>
+        </button>
+      </header>
+
+      <ol class="init-stepper" aria-label="Setup steps">
+        <li v-for="(step, i) in stepperLabels" :key="step.id"
+            class="init-stepper-item"
+            :class="{ active: flow.wizardStep.value === step.id, done: doneSteps.has(step.id), clickable: canJumpTo(step.id) }">
+          <button
+            type="button"
+            class="init-stepper-btn"
+            :disabled="!canJumpTo(step.id)"
+            :aria-current="flow.wizardStep.value === step.id ? 'step' : undefined"
+            @click="jumpToStep(step.id)"
+          >
+            <span class="init-stepper-num">{{ i + 1 }}</span>
+            <span class="init-stepper-label">{{ step.label }}</span>
+          </button>
+        </li>
+      </ol>
+
+      <div class="init-wizard-body">
+      <!-- Step 0: pick workflow (skill/MCP vs embedded agent) -->
+      <section v-if="flow.wizardStep.value === 'mode'" class="init-step" aria-label="Choose Annotask workflow">
+        <h2 class="init-step-title">How do you want to apply design changes?</h2>
+        <p class="init-step-lead">
+          Annotask annotates the UI in the browser; the code edits can come from
+          your own editor agent or from an agent running inside Annotask itself.
+          Pick whichever fits — you can switch later from <strong>Settings → General</strong>.
+        </p>
+
+        <div class="init-mode-choices" role="radiogroup" aria-label="Workflow">
+          <button
+            type="button"
+            role="radio"
+            class="init-mode-choice"
+            :class="{ selected: selectedMode === 'skill' }"
+            :aria-checked="selectedMode === 'skill'"
+            @click="selectedMode = 'skill'"
+          >
+            <div class="init-mode-body">
+              <div class="init-mode-head">
+                <span class="init-mode-title">Use my editor agent</span>
+                <span class="init-mode-badge init-mode-badge-stable">Recommended</span>
+              </div>
+              <p class="init-mode-blurb">
+                Annotate here; drive init and apply from your own editor agent
+                (Claude Code, Cursor, Windsurf, …). Annotask installs two skills
+                — <code>/annotask-init</code> and <code>/annotask-apply</code> —
+                and exposes an MCP server at
+                <code>http://localhost:5173/__annotask/mcp</code>. No in-shell
+                chat, no spawned subprocesses.
+              </p>
+              <ul class="init-mode-bullets">
+                <li>You stay in your editor; Annotask is read-only on the agent side.</li>
+                <li>Tasks land in <code>.annotask/</code> for your agent to pick up.</li>
+                <li>Works with any editor agent that supports MCP or slash skills.</li>
+              </ul>
+            </div>
+          </button>
+
+          <button
+            type="button"
+            role="radio"
+            class="init-mode-choice"
+            :class="{ selected: selectedMode === 'embedded' }"
+            :aria-checked="selectedMode === 'embedded'"
+            @click="selectedMode = 'embedded'"
+          >
+            <div class="init-mode-body">
+              <div class="init-mode-head">
+                <span class="init-mode-title">Run an agent inside Annotask</span>
+                <span class="init-mode-badge init-mode-badge-experimental">Experimental</span>
+              </div>
+              <p class="init-mode-blurb">
+                Spawn a local CLI agent (claude · codex · opencode · copilot)
+                directly from the Annotask sidebar. Tasks stream live to a
+                Conversation tab and auto-run on creation. One-window
+                experience; great when you don't already have an editor agent
+                set up.
+              </p>
+              <ul class="init-mode-bullets">
+                <li>In-shell Conversation tab with live tool-call streaming.</li>
+                <li>Auto-run on task creation (configurable in Settings).</li>
+                <li>Requires at least one supported CLI installed locally.</li>
+              </ul>
+              <p class="init-mode-warning">
+                <strong>Heads up:</strong> the CLIs run headlessly inside the
+                shell, so they need <strong>bypass</strong> permission mode
+                (claude's <code>--dangerously-skip-permissions</code>, codex's
+                <code>--full-auto</code>, etc.) — there's no interactive
+                prompt to approve tool calls. Pick the editor-agent option
+                if you'd rather review each action in your own terminal.
+              </p>
+            </div>
+          </button>
+        </div>
+
+        <div class="init-step-actions">
+          <button
+            class="init-btn-primary"
+            type="button"
+            :disabled="selectedMode === null"
+            @click="confirmModeChoice"
+          >
+            Continue →
+          </button>
+        </div>
+      </section>
+
+      <!-- Step 1: select init agent -->
+      <section v-else-if="flow.wizardStep.value === 'agent'" class="init-step" aria-label="Select an init agent">
+        <h2 class="init-step-title">Select an init agent</h2>
+        <p class="init-step-lead">
+          The <strong>init agent</strong> runs once to set up Annotask for this
+          project. It reads your codebase and writes the design and agent
+          configuration that the per-task agents will use later.
+        </p>
+
+        <ul class="init-agent-duties">
+          <li>
+            <strong>Detect framework &amp; styling.</strong>
+            Reads <code>package.json</code> and config files to identify Vue / React / Svelte /
+            Solid / Astro and the CSS approach (Tailwind, CSS variables, SCSS, scoped CSS, …).
+          </li>
+          <li>
+            <strong>Extract design tokens.</strong>
+            Walks your CSS, Tailwind config, and theme files to pull out the colors,
+            typography scale, spacing, and border radii your app actually uses —
+            written to <code>.annotask/design-spec.json</code>.
+          </li>
+          <li>
+            <strong>Write a style guide.</strong>
+            Captures the conventions in your code (naming, structure, accessibility patterns,
+            error / loading conventions) as a human-readable <code>STYLE_GUIDE.md</code> the
+            per-task agents read before making changes.
+          </li>
+          <li>
+            <strong>Configure per-task agents.</strong>
+            Writes <code>.annotask/agents.json</code> with project-specific directions for each
+            task-type agent (style fixes, a11y, errors, performance, API changes). You can
+            edit these later in Settings → Agents.
+          </li>
+        </ul>
+
+        <p class="init-step-note">
+          Pick whichever provider you'd like for this one-time setup. Local CLIs
+          (Claude Code, Codex, opencode) reuse your existing login; cloud providers
+          need an API key. The per-task agents are seeded to use the same local
+          provider as the init agent, and you can change them later in Settings.
+        </p>
+
+        <AgentQuickSetup :hide-plan-mode="true" :hide-permission-mode="true" />
+        <div class="init-step-actions">
+          <button class="init-btn-primary" :disabled="!flow.hasConfiguredProvider.value" @click="advanceFromAgent">
+            Continue →
+          </button>
+        </div>
+
+        <p class="init-alt">
+          Alternatively, open your editor agent (Claude Code, Cursor, Windsurf, …) and run:
+        </p>
+        <pre class="init-cmd"><code>/annotask-init</code></pre>
+      </section>
+
+      <!-- Step 2: scan project -->
+      <section v-else-if="flow.wizardStep.value === 'scan'" class="init-step" aria-label="Scanning project">
+        <h2 class="init-step-title">
+          {{ flow.rescanMode.value ? 'Re-scan your project' : 'Scanning your project' }}
+          <span v-if="initWorking.verb.value" class="init-working" aria-live="polite">
+            <span class="init-working-dot" />
+            <span class="init-working-verb" :key="initWorking.verb.value">
+              {{ initWorking.verb.value }}<span class="init-working-dots" aria-hidden="true" />
+            </span>
+            <span class="init-working-elapsed">{{ initWorking.seconds.value }}s</span>
+          </span>
+        </h2>
+        <p class="init-step-lead">
+          <template v-if="flow.rescanMode.value">
+            Pick which scanners to re-run. Anything you leave unchecked stays as it
+            is on disk — re-scanning replaces only the targets you select.
+          </template>
+          <template v-else>
+            Your AI scans <code>package.json</code>, CSS files, and Tailwind config to
+            extract design tokens, write a style guide, and configure a dedicated agent
+            for each task type. Review and edit everything before saving.
+          </template>
+        </p>
+
+        <div v-if="flow.initState.value.steps.length === 0 && !flow.rescanMode.value" class="init-empty">
+          Click <strong>Start</strong> to begin.
+        </div>
+
+        <template v-if="flow.initState.value.steps.length > 0">
+          <!-- First-run progress list. In rescan mode the status indicators
+               are folded into the toggle list below, so we hide this. -->
+          <ul v-if="!flow.rescanMode.value" class="init-progress-list" aria-live="polite">
+            <li v-for="s in flow.initState.value.steps" :key="s.id" class="init-progress-row" :class="s.status">
+              <span class="init-progress-marker" :class="s.status" aria-hidden="true">
+                <span v-if="s.status === 'success'">✓</span>
+                <span v-else-if="s.status === 'error'">✕</span>
+                <span v-else-if="s.status === 'running'" class="init-spinner" />
+              </span>
+              <span class="init-progress-label">{{ s.label }}</span>
+              <span v-if="s.message" class="init-progress-message">{{ s.message }}</span>
+            </li>
+          </ul>
+
+          <!-- Agent streaming output — only shows when the agent step is running/done -->
+          <div
+            v-if="agentLines.length > 0"
+            class="init-agent-log"
+            ref="agentLogRef"
+            aria-live="polite"
+            aria-label="Agent output">
+            <div class="init-agent-log-header">
+              <Icon name="bot" :size="12" />
+              <span>Agent output</span>
+            </div>
+            <div class="init-agent-log-body">
+              <p v-for="(line, i) in agentLines" :key="i" class="init-agent-line">{{ line }}</p>
+            </div>
+          </div>
+
+          <!-- Live token usage tally for the agent CLI calls. Show as soon as
+               the run starts (turns = 0) so the user sees the counter exists
+               and watches it accumulate. -->
+          <div
+            v-if="flow.initState.value.running || (initTokenUsage && initTokenUsage.turns > 0)"
+            class="init-token-usage"
+            data-testid="init-token-usage"
+            aria-label="Token usage so far"
+          >
+            <span class="init-token-pill" title="Input tokens">↑ {{ formatTokens(initTokenUsage?.inputTokens ?? 0) }}</span>
+            <span class="init-token-pill" title="Output tokens">↓ {{ formatTokens(initTokenUsage?.outputTokens ?? 0) }}</span>
+            <span
+              v-if="initTokenUsage && (initTokenUsage.cacheReadTokens > 0 || initTokenUsage.cacheCreationTokens > 0)"
+              class="init-token-pill init-token-pill-cache"
+              :title="`Cache read ${initTokenUsage.cacheReadTokens.toLocaleString()} · write ${initTokenUsage.cacheCreationTokens.toLocaleString()}`"
+            >
+              ⧉ {{ formatTokens(initTokenUsage.cacheReadTokens + initTokenUsage.cacheCreationTokens) }}
+            </span>
+            <span class="init-token-meta">
+              {{ initTokenUsage?.turns ?? 0 }} agent call{{ (initTokenUsage?.turns ?? 0) === 1 ? '' : 's' }}
+            </span>
+          </div>
+        </template>
+
+        <!-- Rescan: same visual as the first-run progress list, but the
+             circle marker is clickable and acts as the per-step toggle. -->
+        <ul
+          v-if="flow.rescanMode.value"
+          class="init-progress-list init-progress-list-rescan"
+          aria-label="Scanners to re-run"
+        >
+          <li
+            v-for="opt in SCAN_OPTIONS"
+            :key="opt.key"
+            class="init-progress-row"
+            :class="[liveScanStatus(opt.stepId), { selected: !scanOpts[opt.key] }]"
+          >
+            <button
+              type="button"
+              class="init-progress-marker init-progress-marker-toggle"
+              :class="[liveScanStatus(opt.stepId), { selected: !scanOpts[opt.key] }]"
+              :disabled="flow.initState.value.running"
+              :aria-pressed="!scanOpts[opt.key]"
+              :aria-label="`${!scanOpts[opt.key] ? 'Skip' : 'Include'} ${opt.label}`"
+              @click="scanOpts[opt.key] = !scanOpts[opt.key]"
+            >
+              <span v-if="liveScanStatus(opt.stepId) === 'success'">✓</span>
+              <span v-else-if="liveScanStatus(opt.stepId) === 'error'">✕</span>
+              <span v-else-if="liveScanStatus(opt.stepId) === 'running'" class="init-spinner" />
+              <span v-else-if="!scanOpts[opt.key]" class="init-marker-dot" aria-hidden="true" />
+            </button>
+            <span class="init-progress-label">
+              {{ opt.label }}
+              <span v-if="opt.hint" class="init-progress-hint" v-html="opt.hint" />
+            </span>
+            <span class="init-progress-when">{{ scanTargetLabel(opt.targetId) }}</span>
+          </li>
+        </ul>
+
+        <!-- First-run scan options — kept as a collapsed details summary -->
+        <div
+          v-if="!flow.rescanMode.value && !flow.initState.value.running && flow.initState.value.result !== 'awaiting_review'"
+          class="init-scan-opts"
+        >
+          <details class="init-scan-opts-inner">
+            <summary>Scan options</summary>
+            <ul class="init-scan-opt-list">
+              <li v-for="opt in SCAN_OPTIONS" :key="opt.key">
+                <label class="init-scan-opt">
+                  <input type="checkbox" :checked="!scanOpts[opt.key]"
+                    @change="scanOpts[opt.key] = !($event.target as HTMLInputElement).checked" />
+                  <span class="init-scan-opt-main">
+                    <span>{{ opt.label }}</span>
+                    <span v-if="opt.hint" class="init-scan-opt-hint" v-html="opt.hint" />
+                  </span>
+                </label>
+              </li>
+            </ul>
+          </details>
+        </div>
+
+        <div class="init-step-actions">
+          <!-- First-run: Start / Retry. Hidden once the scan reaches review
+               (success or awaiting_review) so the Review → button takes over. -->
+          <button v-if="!flow.rescanMode.value
+                          && !flow.initState.value.running
+                          && flow.initState.value.result !== 'awaiting_review'
+                          && flow.initState.value.result !== 'success'"
+                  class="init-btn-primary"
+                  @click="() => flow.startRun(scanOpts)">
+            {{ flow.initState.value.result ? 'Retry' : 'Start' }}
+          </button>
+          <!-- Rescan: always exposed (even after a prior successful run) so
+               the user can re-run selected scanners. Disabled when nothing
+               is selected. -->
+          <button v-if="flow.rescanMode.value && !flow.initState.value.running"
+                  class="init-btn-primary"
+                  :disabled="!hasSelectedScan"
+                  @click="() => flow.startRun(scanOpts)">
+            Run selected scans
+          </button>
+          <button v-if="flow.initState.value.running" class="init-btn-secondary" @click="flow.cancelRun">
+            Cancel
+          </button>
+          <button v-if="flow.initState.value.result === 'awaiting_review'
+                        || flow.initState.value.result === 'success'"
+                  class="init-btn-secondary" @click="goToReviewFromScan">
+            Review →
+          </button>
+        </div>
+
+        <p v-if="flow.initState.value.error" class="init-error">
+          {{ flow.initState.value.error }}
+        </p>
+      </section>
+
+      <!-- Step 3: review — sub-stepped -->
+      <section v-else class="init-step init-step-review" aria-label="Review draft">
+        <!-- Sub-step progress dots -->
+        <nav class="review-subnav" aria-label="Review sub-steps">
+          <button
+            v-for="(rs, i) in REVIEW_SUBSTEPS"
+            :key="rs.id"
+            type="button"
+            class="review-subnav-item"
+            :class="{ active: reviewSubStep === i, done: i < reviewSubStep }"
+            @click="reviewSubStep = i"
+            :aria-current="reviewSubStep === i ? 'step' : undefined">
+            <span class="review-subnav-dot" aria-hidden="true" />
+            <span class="review-subnav-label">{{ rs.label }}</span>
+          </button>
+        </nav>
+
+        <!-- ── Sub-step 0: Framework ── -->
+        <div v-if="reviewSubStep === 0" class="review-panel">
+          <div class="review-panel-header">
+            <span class="review-panel-icon"><Icon name="settings" :size="20" /></span>
+            <div>
+              <h3 class="review-panel-title">Framework</h3>
+              <p class="review-panel-desc">Confirm what Annotask detected from <code>package.json</code>.</p>
+            </div>
+          </div>
+          <div class="init-grid">
+            <label class="init-field">
+              <span>Name</span>
+              <input type="text" :value="framework.name ?? ''" @input="updateFw('name', ($event.target as HTMLInputElement).value)" />
+            </label>
+            <label class="init-field">
+              <span>Version</span>
+              <input type="text" :value="framework.version ?? ''" @input="updateFw('version', ($event.target as HTMLInputElement).value)" />
+            </label>
+            <label class="init-field init-field-full">
+              <span>Styling approach (comma-separated)</span>
+              <input type="text" :value="(framework.styling ?? []).join(', ')"
+                     @input="updateFwStyling(($event.target as HTMLInputElement).value)" />
+            </label>
+          </div>
+        </div>
+
+        <!-- ── Sub-step 1: Themes & Tokens ── -->
+        <div v-else-if="reviewSubStep === 1" class="review-panel review-panel-tokens">
+          <div class="review-panel-header">
+            <span class="review-panel-icon"><Icon name="palette" :size="20" /></span>
+            <div>
+              <h3 class="review-panel-title">Themes & Tokens</h3>
+              <p class="review-panel-desc">Exact same editor as the Design → Tokens tab. Theme variants at the top; Colors / Type / Spacing / Borders below.</p>
+            </div>
+          </div>
+          <DesignTokenEditor
+            :spec="flow.draftSpec.value as Record<string, any>"
+            :local-only="true"
+            @update:spec="flow.draftSpec.value = $event"
+            class="init-token-editor"
+          />
+        </div>
+
+        <!-- ── Sub-step 2: Components ── -->
+        <div v-else-if="reviewSubStep === 2" class="review-panel">
+          <div class="review-panel-header">
+            <span class="review-panel-icon"><Icon name="package" :size="20" /></span>
+            <div>
+              <h3 class="review-panel-title">Component library</h3>
+              <p class="review-panel-desc">The primary UI component library for this project. Agents use this when inserting or editing components.</p>
+            </div>
+          </div>
+          <div v-if="components?.library" class="init-token-row" style="margin-bottom:8px">
+            <div class="init-token-info">
+              <span class="init-token-role">{{ components.library }}</span>
+              <code v-if="components.version" class="init-token-source">{{ components.version }}</code>
+            </div>
+            <span class="init-token-badge">detected</span>
+          </div>
+          <p v-else class="init-empty-small" style="margin-bottom:8px">No component library matched the detected framework.</p>
+          <p class="init-section-hint">
+            Component usage (which components are actually imported) is tracked live at runtime. Open <strong>Design → Components</strong> after the shell loads to see the full usage index.
+          </p>
+        </div>
+
+        <!-- ── Sub-step 3: APIs & Data ── -->
+        <div v-else-if="reviewSubStep === 3" class="review-panel">
+          <div class="review-panel-header">
+            <span class="review-panel-icon"><Icon name="database" :size="20" /></span>
+            <div>
+              <h3 class="review-panel-title">APIs & Data sources</h3>
+              <p class="review-panel-desc">Review what the scanner found — remove noise, add anything it missed. Agents use this to pick the right hooks and endpoints.</p>
+            </div>
+          </div>
+
+          <!-- Sub-tabs -->
+          <div class="panel-tabs">
+            <button class="panel-tab" :class="{ active: apisTab === 'schemas' }" @click="apisTab = 'schemas'">
+              API schemas <span class="panel-tab-count">{{ apiSchemas.length }}</span>
+            </button>
+            <button class="panel-tab" :class="{ active: apisTab === 'sources' }" @click="apisTab = 'sources'">
+              Data sources <span class="panel-tab-count">{{ dsEntries.length }}</span>
+            </button>
+          </div>
+
+          <!-- Tab: Data sources -->
+          <template v-if="apisTab === 'sources'">
+            <p class="init-section-hint" v-if="dsLibraries.length > 0">
+              Detected libraries:
+              <span v-for="lib in dsLibraries" :key="lib" class="init-lib-badge">{{ lib }}</span>
+            </p>
+            <ul v-if="dsEntries.length > 0" class="init-data-list">
+              <li v-for="(e, i) in dsEntries" :key="i" class="init-data-row">
+                <span class="init-data-kind">{{ e.kind }}</span>
+                <span class="init-data-name">{{ e.name }}</span>
+                <button class="init-data-remove" @click="removeDataEntry(i)" aria-label="Remove">×</button>
+              </li>
+            </ul>
+            <p v-else class="init-empty-small">No project data sources detected.</p>
+            <div class="init-data-add">
+              <input v-model="newDsName" type="text" placeholder="hook or store name (e.g. useProducts)" @keydown.enter.prevent="addDataEntry" />
+              <select v-model="newDsKind">
+                <option value="composable">composable</option>
+                <option value="store">store</option>
+                <option value="fetch">fetch</option>
+                <option value="graphql">graphql</option>
+                <option value="rpc">rpc</option>
+              </select>
+              <button class="init-btn-secondary" @click="addDataEntry" :disabled="!newDsName.trim()">+ Add</button>
+            </div>
+          </template>
+
+          <!-- Tab: API schemas -->
+          <template v-else>
+            <ul v-if="apiSchemas.length > 0" class="init-data-list">
+              <li v-for="(s, i) in apiSchemas" :key="i" class="init-data-row">
+                <span class="init-data-kind">{{ s.kind }}</span>
+                <span class="init-data-name">{{ s.location }}</span>
+                <button class="init-data-remove" @click="removeSchema(i)" aria-label="Remove">×</button>
+              </li>
+            </ul>
+            <p v-else class="init-empty-small">No API schemas detected.</p>
+            <div class="init-data-add">
+              <input v-model="newSchemaLoc" type="text" placeholder="path or URL (e.g. /openapi.json)" @keydown.enter.prevent="addSchema" />
+              <select v-model="newSchemaKind">
+                <option value="openapi">openapi</option>
+                <option value="graphql">graphql</option>
+                <option value="trpc">trpc</option>
+                <option value="jsonschema">jsonschema</option>
+              </select>
+              <button class="init-btn-secondary" @click="addSchema" :disabled="!newSchemaLoc.trim()">+ Add</button>
+            </div>
+          </template>
+        </div>
+
+        <!-- ── Sub-step 5: Agent directions ── -->
+        <div v-else-if="reviewSubStep === 5" class="review-panel review-panel-agents">
+          <div class="review-panel-header">
+            <span class="review-panel-icon"><Icon name="bot" :size="20" /></span>
+            <div>
+              <h3 class="review-panel-title">Agent directions</h3>
+              <p class="review-panel-desc">
+                Project-specific context your AI reads before applying each task type.
+                Written by the init agent — click any agent to view or edit its directions.
+              </p>
+            </div>
+          </div>
+
+          <!-- Global default permission mode for per-task agents. The
+               wizard intentionally omits "Default" — annotask runs every
+               CLI headless (`--print` / `exec` / `run` / `-p`), so there
+               is no human to answer "may I write this file?" prompts and
+               default mode results in silent denial of every Edit/Bash
+               call. Bypass (write) and Plan (read-only) are the only two
+               modes that actually do anything in this pipeline. -->
+          <div class="init-perm-row">
+            <label class="init-perm-label">
+              <span class="init-perm-label-title">Default permission mode</span>
+              <span class="init-perm-label-hint">How per-task agents approve actions after init. Override per persona or per task later.</span>
+            </label>
+            <select
+              class="init-perm-select"
+              data-testid="init-permission-mode"
+              :value="globalPermissionMode"
+              @change="setGlobalPermissionMode(($event.target as HTMLSelectElement).value)"
+            >
+              <option v-for="m in INIT_PERMISSION_MODE_OPTIONS" :key="m.id" :value="m.id">{{ m.label }}</option>
+            </select>
+          </div>
+          <p class="init-perm-note">
+            Note: per-task agents run headlessly — there's no human to answer
+            permission prompts. Only <strong>Bypass</strong> (writes allowed)
+            and <strong>Plan</strong> (read-only) actually do anything; a
+            "Default" mode would deny every Edit and Bash call silently. The
+            initial scan separately always runs in its CLI's least-permissive
+            headless mode and writes inside <code>.annotask/</code> only.
+          </p>
+
+          <AgentDirectionsPanel class="init-adp" />
+        </div>
+
+        <!-- ── Sub-step 4: Style guide ── -->
+        <div v-else class="review-panel">
+          <div class="review-panel-header">
+            <span class="review-panel-icon"><Icon name="file-search" :size="20" /></span>
+            <div>
+              <h3 class="review-panel-title">Style guide</h3>
+              <p class="review-panel-desc">Agents read <code>.annotask/STYLE_GUIDE.md</code> before every task. The agent wrote a draft — review it here, or load an existing file from your project.</p>
+            </div>
+          </div>
+
+          <!-- File override row -->
+          <div class="init-guide-file-row">
+            <label class="init-guide-file-label">Load from file</label>
+            <div class="init-guide-file-input-row">
+              <input
+                v-model="styleGuideFilePath"
+                type="text"
+                class="init-guide-file-input"
+                placeholder="e.g. docs/CONTRIBUTING.md or .cursor/rules"
+                @keydown.enter.prevent="loadStyleGuideFile"
+              />
+              <button
+                class="init-btn-secondary"
+                :disabled="!styleGuideFilePath.trim() || styleGuideFileLoading"
+                @click="loadStyleGuideFile"
+              >{{ styleGuideFileLoading ? 'Loading…' : 'Load' }}</button>
+            </div>
+            <p v-if="styleGuideFileError" class="init-guide-file-error">{{ styleGuideFileError }}</p>
+          </div>
+
+          <!-- Preview / Edit toggle -->
+          <div class="init-guide-toolbar">
+            <div class="init-guide-toggle" role="group" aria-label="Editor mode">
+              <button :class="['init-guide-mode', { active: guideMode === 'preview' }]" @click="guideMode = 'preview'">
+                <Icon name="scan-search" :size="12" /> Preview
+              </button>
+              <button :class="['init-guide-mode', { active: guideMode === 'edit' }]" @click="guideMode = 'edit'">
+                <Icon name="pencil" :size="12" /> Edit
+              </button>
+            </div>
+          </div>
+
+          <!-- Rendered markdown preview -->
+          <div
+            v-if="guideMode === 'preview'"
+            class="init-style-preview markdown-body"
+            v-html="renderedGuide || emptyGuideHtml"
+          />
+
+          <MarkdownEditor
+            v-else
+            :model-value="flow.draftStyleGuide.value"
+            @update:model-value="flow.setStyleGuide($event)"
+            class="init-style-guide"
+            aria-label="Style guide markdown"
+            show-line-numbers
+            placeholder="# Project style guide&#10;&#10;## Naming conventions&#10;&#10;## Component patterns&#10;&#10;## Things to avoid"
+          />
+
+          <label v-if="draft?.styleGuideExists" class="init-overwrite-toggle" style="margin-top:8px">
+            <input type="checkbox" :checked="flow.overwriteStyleGuide.value"
+                   @change="flow.setOverwriteStyleGuide(($event.target as HTMLInputElement).checked)" />
+            <span>Overwrite existing <code>.annotask/STYLE_GUIDE.md</code> on save</span>
+          </label>
+        </div>
+
+        <!-- Navigation -->
+        <div class="review-nav">
+          <button v-if="reviewSubStep > 0" class="init-btn-secondary" @click="reviewSubStep--">← Back</button>
+          <div class="review-nav-right">
+            <button v-if="reviewSubStep < REVIEW_SUBSTEPS.length - 1"
+                    class="init-btn-primary" @click="reviewSubStep++">
+              Next →
+            </button>
+            <template v-else>
+              <button class="init-skip-btn" @click="flow.skipInit" style="margin-right:auto">
+                Use skill instead
+              </button>
+              <button class="init-btn-secondary" :disabled="saving" @click="onRetry">Re-scan</button>
+              <button class="init-btn-primary" :disabled="saving" @click="onSave">
+                {{ saving ? 'Saving…' : 'Accept & Save' }}
+              </button>
+            </template>
+          </div>
+        </div>
+
+        <p v-if="flow.initState.value.committedAt" class="init-success">
+          ✓ Saved — wizard will close.
+        </p>
+        <p v-if="flow.initState.value.error && flow.initState.value.result === 'error'" class="init-error">
+          {{ flow.initState.value.error }}
+        </p>
+      </section>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref, watch } from 'vue'
+import AgentQuickSetup from './AgentQuickSetup.vue'
+import AgentDirectionsPanel from './AgentDirectionsPanel.vue'
+import DesignTokenEditor from './DesignTokenEditor.vue'
+import MarkdownEditor from './MarkdownEditor.vue'
+import Icon from './Icon.vue'
+import { useInitFlow } from '../composables/useInitFlow'
+import { useWorkingIndicator } from '../composables/useWorkingIndicator'
+import { useAgentConfigs } from '../composables/useAgentConfigs'
+import { useProviderSettings } from '../composables/useProviderSettings'
+import { BUILT_IN_PERSONAS } from '../../embedded/persona'
+import { PERMISSION_MODES, type PermissionMode } from '../../schema'
+import { marked } from 'marked'
+
+const flow = useInitFlow()
+const initRunning = computed(() => flow.initState.value.running)
+const initWorking = useWorkingIndicator(initRunning)
+const agentConfigs = useAgentConfigs()
+const providerSettings = useProviderSettings()
+const saving = ref(false)
+
+// Permission-mode picker shown in the Agent directions sub-step. `'default'`
+// is the safe "Auto" default: each CLI runs the least-permissive mode that
+// still applies tasks headlessly (codex/copilot sandboxed/minimal; claude/
+// opencode escalate to bypass via normalizeHeadlessMode). `'bypass'` (all
+// sandboxes off) is the explicit opt-in.
+const INIT_PERMISSION_MODE_OPTIONS: ReadonlyArray<{ id: PermissionMode; label: string }> = [
+  { id: 'default', label: 'Auto — safe per-CLI default (recommended)' },
+  { id: 'plan',    label: 'Plan — read-only' },
+  { id: 'bypass',  label: 'Bypass — auto-approve everything, all sandboxes off' },
+]
+const globalPermissionMode = computed<PermissionMode>(() => providerSettings.settings.value.permissionMode)
+function setGlobalPermissionMode(value: string) {
+  if (!(PERMISSION_MODES as readonly string[]).includes(value)) return
+  providerSettings.setPermissionMode(value as PermissionMode)
+}
+
+// Agent directions review state
+const agentDraftDirections = ref<Record<string, string>>({})
+const agentDirSaving = ref<Record<string, boolean>>({})
+
+// Hydrate local draft whenever configs arrive from the server
+watch(
+  agentConfigs.configs,
+  (configs) => {
+    for (const p of BUILT_IN_PERSONAS) {
+      agentDraftDirections.value[p.id] = configs[p.id]?.projectDirections ?? ''
+    }
+  },
+  { immediate: true, deep: true },
+)
+
+async function saveAgentDirection(personaId: string) {
+  agentDirSaving.value[personaId] = true
+  await agentConfigs.save(personaId, { projectDirections: agentDraftDirections.value[personaId] ?? '' })
+  agentDirSaving.value[personaId] = false
+}
+const agentLogRef = ref<HTMLElement | null>(null)
+// Default to preview; reset to edit only when a new scan result arrives
+const guideMode = ref<'edit' | 'preview'>('preview')
+watch(() => flow.draftStyleGuide.value, () => { guideMode.value = 'preview' }, { once: false })
+
+// Style-guide file override
+const styleGuideFilePath = ref('')
+const styleGuideFileLoading = ref(false)
+const styleGuideFileError = ref('')
+
+const emptyGuideHtml = '<p style="opacity:0.5;font-style:italic">Nothing to preview yet.</p>'
+
+async function loadStyleGuideFile() {
+  const p = styleGuideFilePath.value.trim()
+  if (!p) return
+  styleGuideFileLoading.value = true
+  styleGuideFileError.value = ''
+  try {
+    const res = await fetch(`/__annotask/api/read-file?path=${encodeURIComponent(p)}`)
+    if (!res.ok) {
+      const err = await res.json().catch(() => null)
+      throw new Error(err?.error?.message ?? `HTTP ${res.status}`)
+    }
+    const data = await res.json()
+    flow.setStyleGuide(data.content ?? '')
+    flow.setOverwriteStyleGuide(true)
+    guideMode.value = 'preview'
+  } catch (e) {
+    styleGuideFileError.value = (e as Error).message
+  } finally {
+    styleGuideFileLoading.value = false
+  }
+}
+
+// Scan options — which optional steps to run.
+// Defaults differ by mode:
+//   - first-run init: everything ON (skip flags false) so the full pipeline runs
+//   - re-scan mode: everything OFF (skip flags true) so the user explicitly opts in
+import type { ScanOptions } from '../composables/useInitFlow'
+const scanOpts = ref<ScanOptions>({
+  skipAgentScan: false,
+  skipAgentConfigs: false,
+  skipComponents: false,
+  skipDataSources: false,
+  skipApiSchemas: false,
+})
+
+// Reset toggles whenever the wizard enters the scan step. In re-scan mode
+// default to "skip everything" so the user opts into the specific scanners
+// they want to re-run.
+watch(
+  () => [flow.wizardStep.value, flow.rescanMode.value] as const,
+  ([step, rescan]) => {
+    if (step !== 'scan') return
+    scanOpts.value = rescan
+      ? { skipAgentScan: true, skipAgentConfigs: true, skipComponents: true, skipDataSources: true, skipApiSchemas: true }
+      : { skipAgentScan: false, skipAgentConfigs: false, skipComponents: false, skipDataSources: false, skipApiSchemas: false }
+    if (rescan) fetchScanTargets()
+  },
+  { immediate: true },
+)
+
+// True when at least one scanner is selected to run — drives Start-button
+// enablement in re-scan mode.
+const hasSelectedScan = computed(() => {
+  const o = scanOpts.value
+  return !(o.skipAgentScan && o.skipAgentConfigs && o.skipComponents && o.skipDataSources && o.skipApiSchemas)
+})
+
+// Single source of truth for the scanner list — drives both the toggleable
+// checklist and (in rescan mode) the per-row status + timestamp indicators.
+// `stepId` matches the IDs emitted by the server-side init runner.
+type ScanOptionKey =
+  | 'skipAgentScan'
+  | 'skipAgentConfigs'
+  | 'skipComponents'
+  | 'skipDataSources'
+  | 'skipApiSchemas'
+
+const SCAN_OPTIONS: Array<{
+  key: ScanOptionKey
+  stepId: string
+  targetId: string
+  label: string
+  hint?: string
+}> = [
+  {
+    key: 'skipAgentScan',
+    stepId: 'agent-scan',
+    targetId: 'designSpec',
+    label: 'Scan design tokens & style guide',
+    hint: 'Runs the LLM scan that produces <code>design-spec.json</code> and <code>STYLE_GUIDE.md</code>',
+  },
+  {
+    key: 'skipAgentConfigs',
+    stepId: 'agent-configs',
+    targetId: 'agentConfigs',
+    label: 'Write agent directions',
+    hint: 'Configures AI personas for each task type',
+  },
+  { key: 'skipComponents',  stepId: 'components',   targetId: 'designSpec', label: 'Scan component library' },
+  { key: 'skipDataSources', stepId: 'data-sources', targetId: 'designSpec', label: 'Scan data sources' },
+  { key: 'skipApiSchemas',  stepId: 'api-schemas',  targetId: 'designSpec', label: 'Scan API schemas' },
+]
+
+// Status of a given scanner in the *current* init run, if any. Used to fold
+// the prior-run progress indicators into the toggle list in rescan mode.
+function scanRowStatus(stepId: string): '' | 'pending' | 'running' | 'success' | 'error' | 'skipped' {
+  const step = flow.initState.value.steps.find((s) => s.id === stepId)
+  return step?.status ?? ''
+}
+
+// Marker status for the rescan toggle list. Suppresses stale ✓ / ✕ marks
+// from prior runs so the selection screen looks fresh when the user
+// reopens the wizard; status only surfaces while a rescan is in flight.
+function liveScanStatus(stepId: string): ReturnType<typeof scanRowStatus> {
+  if (!flow.initState.value.running) return ''
+  return scanRowStatus(stepId)
+}
+
+// Per-target presence + mtime metadata for the re-scan UI. Fetched lazily
+// when the user lands on the scan step in rescan mode.
+const scanTargets = ref<Record<string, { exists: boolean; mtime: number | null }>>({})
+async function fetchScanTargets() {
+  try {
+    const res = await fetch('/__annotask/api/init/scan-targets')
+    if (res.ok) scanTargets.value = await res.json()
+  } catch { /* offline — leave empty */ }
+}
+
+function scanTargetLabel(id: string): string {
+  const t = scanTargets.value[id]
+  if (!t || !t.exists || !t.mtime) return 'Not yet scanned'
+  const ms = Date.now() - t.mtime
+  const sec = Math.floor(ms / 1000)
+  if (sec < 60) return 'Scanned just now'
+  const min = Math.floor(sec / 60)
+  if (min < 60) return `Scanned ${min}m ago`
+  const hr = Math.floor(min / 60)
+  if (hr < 24) return `Scanned ${hr}h ago`
+  const day = Math.floor(hr / 24)
+  return `Scanned ${day}d ago`
+}
+
+const renderedGuide = computed(() => {
+  const md = flow.draftStyleGuide.value?.trim()
+  if (!md) return '<p style="opacity:0.5;font-style:italic">Nothing to preview yet.</p>'
+  try {
+    return marked.parse(md, { async: false, gfm: true, breaks: false }) as string
+  } catch {
+    return `<pre>${md}</pre>`
+  }
+})
+
+// Keep agent log scrolled to bottom as new lines arrive
+const agentLines = computed(() => flow.initState.value.agentLines ?? [])
+const initTokenUsage = computed(() => flow.initState.value.tokenUsage ?? null)
+
+function formatTokens(n: number): string {
+  if (n < 1000) return n.toString()
+  if (n < 1_000_000) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`
+  return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 2 : 1)}M`
+}
+watch(agentLines, () => {
+  nextTick(() => {
+    if (agentLogRef.value) agentLogRef.value.scrollTop = agentLogRef.value.scrollHeight
+  })
+})
+
+// Sub-step state for the Review step — resets whenever the user re-enters Review.
+const reviewSubStep = ref(0)
+watch(() => flow.wizardStep.value, (step) => { if (step === 'review') reviewSubStep.value = 0 })
+
+const REVIEW_SUBSTEPS = [
+  { id: 'framework',        label: 'Framework' },
+  { id: 'themes-tokens',    label: 'Themes & Tokens' },
+  { id: 'components',       label: 'Components' },
+  { id: 'apis-data',        label: 'APIs & Data' },
+  { id: 'style-guide',      label: 'Style guide' },
+  { id: 'agent-directions', label: 'Agent directions' },
+] as const
+
+// Panel-level sub-tabs
+const themesTab = ref<'themes' | 'colors' | 'typography' | 'spacing'>('themes')
+const apisTab   = ref<'sources' | 'schemas'>('schemas')
+
+// ── APIs & Data tab state ─────────────────────────────────
+interface DsEntry { name: string; kind: string; used_count?: number }
+interface SchemaEntry { kind: string; location: string }
+
+const dsLibraries = ref<string[]>([])
+const dsEntries   = ref<DsEntry[]>([])
+const apiSchemas  = ref<SchemaEntry[]>([])
+const newDsName   = ref('')
+const newDsKind   = ref('composable')
+const newSchemaLoc  = ref('')
+const newSchemaKind = ref('openapi')
+let apisDataLoaded = false
+
+async function loadApisData() {
+  if (apisDataLoaded) return
+  apisDataLoaded = true
+  try {
+    const [dsRes, schRes] = await Promise.all([
+      fetch('/__annotask/api/data-sources').then(r => r.ok ? r.json() : null),
+      fetch('/__annotask/api/api-schemas').then(r => r.ok ? r.json() : null),
+    ])
+    if (dsRes) {
+      dsLibraries.value = (dsRes.libraries ?? []).map((l: any) => l.name).slice(0, 8)
+      dsEntries.value = (dsRes.project_entries ?? []).map((e: any) => ({ name: e.name, kind: e.kind, used_count: e.used_count }))
+    }
+    if (schRes) {
+      apiSchemas.value = (schRes.schemas ?? []).map((s: any) => ({ kind: s.kind, location: s.location }))
+    }
+    // Mirror into draftSpec so they serialize on commit
+    syncDataToDraft()
+  } catch { /* offline */ }
+}
+
+watch(() => reviewSubStep.value, (step) => {
+  if (step === 3) loadApisData()
+  if (step === 5) agentConfigs.refresh()
+})
+
+function syncDataToDraft() {
+  flow.draftSpec.value = {
+    ...flow.draftSpec.value,
+    dataSources: dsEntries.value,
+    apiSchemas: apiSchemas.value,
+  }
+}
+
+function removeDataEntry(i: number) {
+  dsEntries.value = dsEntries.value.filter((_, idx) => idx !== i)
+  syncDataToDraft()
+}
+function addDataEntry() {
+  const name = newDsName.value.trim()
+  if (!name) return
+  dsEntries.value = [...dsEntries.value, { name, kind: newDsKind.value }]
+  newDsName.value = ''
+  syncDataToDraft()
+}
+function removeSchema(i: number) {
+  apiSchemas.value = apiSchemas.value.filter((_, idx) => idx !== i)
+  syncDataToDraft()
+}
+function addSchema() {
+  const location = newSchemaLoc.value.trim()
+  if (!location) return
+  apiSchemas.value = [...apiSchemas.value, { kind: newSchemaKind.value, location }]
+  newSchemaLoc.value = ''
+  syncDataToDraft()
+}
+
+// ── Token data from real draft ────────────────────────────
+const colorTokens = computed(() => {
+  const raw = (flow.draftSpec.value as any).colors
+  return Array.isArray(raw) ? raw as Array<Record<string, any>> : []
+})
+const typographyFamilies = computed(() => {
+  const t = (flow.draftSpec.value as any).typography
+  return Array.isArray(t?.families) ? t.families as Array<Record<string, any>> : []
+})
+const typographyScale = computed(() => {
+  const t = (flow.draftSpec.value as any).typography
+  return Array.isArray(t?.scale) ? t.scale as Array<Record<string, any>> : []
+})
+const spacingTokens = computed(() => {
+  const raw = (flow.draftSpec.value as any).spacing
+  return Array.isArray(raw) ? raw as Array<Record<string, any>> : []
+})
+const borderTokens = computed(() => {
+  const b = (flow.draftSpec.value as any).borders
+  return Array.isArray(b?.radius) ? b.radius as Array<Record<string, any>> : []
+})
+const typographyWeights = computed(() => {
+  const t = (flow.draftSpec.value as any).typography
+  return Array.isArray(t?.weights) ? t.weights as string[] : []
+})
+
+const hasAnyTokens = computed(() =>
+  colorTokens.value.length > 0 || typographyFamilies.value.length > 0 ||
+  typographyScale.value.length > 0 || spacingTokens.value.length > 0 || borderTokens.value.length > 0
+)
+
+/** Resolve a token's display value — handles both `value` (old shape) and
+ *  `values: { themeId: colorStr }` (new multi-variant shape). */
+function tokenDisplayValue(token: Record<string, any>): string {
+  if (typeof token.value === 'string') return token.value
+  if (token.values && typeof token.values === 'object') {
+    const vals = Object.values(token.values as Record<string, string>)
+    return vals.find(v => v) ?? ''
+  }
+  return ''
+}
+
+// ── Token categories empty-state ─────────────────────────
+const TOKEN_CATEGORIES = [
+  { id: 'colors',     label: 'Colors',     hint: '--primary, --background, …' },
+  { id: 'typography', label: 'Typography',  hint: 'font-family, scale, weights' },
+  { id: 'spacing',    label: 'Spacing',     hint: '--space-sm, --space-md, …' },
+  { id: 'borders',    label: 'Borders',     hint: 'radius variants' },
+] as const
+
+// ── Style guide section editor ───────────────────────────
+// Section metadata — headings, placeholders, and preferred row height.
+const GUIDE_SECTION_META: Record<string, { placeholder: string; rows: number }> = {
+  'Naming conventions': {
+    placeholder: 'e.g. PascalCase components, camelCase composables, kebab-case CSS classes',
+    rows: 2,
+  },
+  'Spacing & layout': {
+    placeholder: 'e.g. 4px base unit; cards use --space-md padding; grid is 12-column',
+    rows: 2,
+  },
+  'Component patterns': {
+    placeholder: 'e.g. wrap form inputs in <FormField label="…">; prefer Radix primitives over custom',
+    rows: 3,
+  },
+  'Things to avoid': {
+    placeholder: "e.g. don't add new dependencies; don't refactor for cleanliness; preserve inline styles",
+    rows: 2,
+  },
+  'Project context': {
+    placeholder: 'A sentence or two about what this project does. Helps agents pick tone in copy edits.',
+    rows: 2,
+  },
+}
+const FALLBACK_META = { placeholder: 'Your notes here…', rows: 2 }
+
+interface GuideSection { heading: string; content: string; placeholder: string; rows: number }
+
+function parseGuideSections(markdown: string): GuideSection[] {
+  // Split on `## ` headings, preserving the first `# ` title as an ignored preamble.
+  const lines = markdown.split(/\r?\n/)
+  const sections: GuideSection[] = []
+  let currentHeading = ''
+  let currentLines: string[] = []
+
+  for (const line of lines) {
+    if (line.startsWith('## ')) {
+      if (currentHeading) {
+        sections.push(makeSection(currentHeading, currentLines))
+      }
+      currentHeading = line.replace(/^##\s+/, '').trim()
+      currentLines = []
+    } else if (currentHeading) {
+      currentLines.push(line)
+    }
+    // Lines before the first ## (the # title, intro paragraph) are skipped.
+  }
+  if (currentHeading) sections.push(makeSection(currentHeading, currentLines))
+
+  // If no sections found (empty / unexpected format), produce a single freeform section.
+  if (sections.length === 0) {
+    sections.push({ heading: 'Notes', content: markdown.trim(), placeholder: 'Your notes here…', rows: 6 })
+  }
+  return sections
+}
+
+function makeSection(heading: string, lines: string[]): GuideSection {
+  const meta = GUIDE_SECTION_META[heading] ?? FALLBACK_META
+  // Strip leading/trailing blank lines and HTML comment placeholders.
+  const raw = lines.join('\n').trim().replace(/^<!--.*?-->$/gm, '').trim()
+  return { heading, content: raw, placeholder: meta.placeholder, rows: meta.rows }
+}
+
+function serializeGuideSections(sections: GuideSection[]): string {
+  const preamble = '# Project style guide\n\nAnnotask agents read this file before applying tasks. Fill in the sections\nbelow to teach them your project\'s conventions. Empty sections are fine —\nagents will fall back to inferring from the existing code.'
+  const body = sections.map(s => {
+    const content = s.content.trim()
+    return `## ${s.heading}\n\n${content.length > 0 ? content : `<!-- ${s.placeholder} -->`}`
+  }).join('\n\n')
+  return `${preamble}\n\n${body}\n`
+}
+
+const guidesections = ref<GuideSection[]>([])
+
+// Hydrate once when the draft lands and keep in sync with external resets.
+watch(
+  () => flow.draftStyleGuide.value,
+  (md) => {
+    const parsed = parseGuideSections(md)
+    // Only re-parse if sections are structurally different to avoid clobbering
+    // edits the user has in flight.
+    if (guidesections.value.length === 0 ||
+        parsed.map(s => s.heading).join() !== guidesections.value.map(s => s.heading).join()) {
+      guidesections.value = parsed
+    }
+  },
+  { immediate: true },
+)
+
+function onSectionInput(idx: number, value: string) {
+  if (idx < 0 || idx >= guidesections.value.length) return
+  guidesections.value[idx] = { ...guidesections.value[idx], content: value }
+  flow.setStyleGuide(serializeGuideSections(guidesections.value))
+}
+
+const ALL_STEP_LABELS = [
+  { id: 'mode', label: 'Choose workflow' },
+  { id: 'agent', label: 'Pick init agent' },
+  { id: 'scan', label: 'Scan project' },
+  { id: 'review', label: 'Review & Save' },
+] as const
+
+// Hide the 'mode' step in the stepper once the user has already chosen a
+// workflow (re-opens from settings, re-scans). The user can't "go back" to
+// re-pick the workflow from inside the wizard — that toggle lives in
+// Settings → General.
+const stepperLabels = computed(() => {
+  const choice = providerSettings.settings.value.embeddedAgentEnabled
+  if (choice == null) return ALL_STEP_LABELS
+  return ALL_STEP_LABELS.filter(s => s.id !== 'mode')
+})
+
+const doneSteps = computed(() => {
+  const set = new Set<string>()
+  const order = ['mode', 'agent', 'scan', 'review'] as const
+  for (const id of order) {
+    if (id === flow.wizardStep.value) break
+    set.add(id)
+  }
+  return set
+})
+
+const framework = computed(() => (flow.draftSpec.value.framework ?? {}) as Record<string, any>)
+const themes = computed(() => Array.isArray(flow.draftSpec.value.themes) ? flow.draftSpec.value.themes : [])
+const components = computed(() => flow.draftSpec.value.components as { library: string; version?: string; used?: string[] } | null)
+const draft = computed(() => flow.initState.value.draft)
+
+function updateFw(key: string, value: string) {
+  flow.updateFramework({ [key]: value })
+}
+
+function updateFwStyling(raw: string) {
+  const styling = raw.split(',').map(s => s.trim()).filter(s => s.length > 0)
+  flow.updateFramework({ styling })
+}
+
+function onThemePatch(idx: number, patch: Record<string, any>) {
+  flow.updateTheme(idx, patch)
+}
+
+function onSelectorPatch(idx: number, patch: Record<string, any>) {
+  flow.updateThemeSelector(idx, patch)
+}
+
+async function onSave() {
+  saving.value = true
+  const ok = await flow.commitDraft()
+  saving.value = false
+  if (ok) flow.closeWizard()
+}
+
+async function onRetry() {
+  await flow.startRun()
+}
+
+// True when the user is allowed to jump directly to the given step.
+// Forward jumps from `agent` require a configured provider; jumping to
+// Review requires that the project has either an active scan draft or is
+// already initialized (so we can hydrate from disk).
+function canJumpTo(stepId: string): boolean {
+  if (stepId === flow.wizardStep.value) return false
+  if (flow.initState.value.running) return false
+  // 'mode' is a first-run pivot — once the user has chosen, it's not
+  // re-enterable from the stepper. Change it from Settings → General.
+  if (stepId === 'mode') return false
+  if (stepId === 'agent') return true
+  if (stepId === 'scan') return true
+  if (stepId === 'review') {
+    if (flow.initState.value.result === 'awaiting_review') return true
+    if (flow.isInitialized.value) return true
+    return false
+  }
+  return false
+}
+
+function jumpToStep(stepId: string) {
+  if (!canJumpTo(stepId)) return
+  if (stepId === 'mode' || stepId === 'agent' || stepId === 'scan' || stepId === 'review') {
+    flow.goToStep(stepId as 'mode' | 'agent' | 'scan' | 'review')
+  }
+}
+
+// Page 0 selection. 'skill' commits the user to MCP/skill mode and closes
+// the wizard immediately without touching .annotask/. 'embedded' opts the
+// user into the in-shell agent UI and advances to the provider-setup step.
+const selectedMode = ref<'skill' | 'embedded' | null>(null)
+
+function confirmModeChoice() {
+  if (selectedMode.value === 'skill') {
+    providerSettings.setEmbeddedAgentEnabled(false)
+    flow.closeWizard()
+    return
+  }
+  if (selectedMode.value === 'embedded') {
+    providerSettings.setEmbeddedAgentEnabled(true)
+    providerSettings.setAgentMode('auto')
+    flow.goToStep('agent')
+  }
+}
+
+function advanceFromAgent() {
+  flow.nextStep()
+  // In rescan mode the user is choosing which scans to (re-)run, so don't
+  // auto-start. In first-run init, kick off the full scan unless a draft is
+  // already awaiting review.
+  if (flow.rescanMode.value) return
+  if (!flow.initState.value.running && (!flow.initState.value.result || flow.initState.value.result === 'awaiting_review')) {
+    if (flow.initState.value.result !== 'awaiting_review') {
+      flow.startRun()
+    }
+  }
+}
+
+// Advance to the Review step from Scan. Used for both "Review →" (after a
+// successful scan) and "Skip to Review →" (rescan mode, nothing selected).
+function goToReviewFromScan() {
+  flow.goToStep('review')
+}
+
+function close() {
+  flow.closeWizard()
+}
+</script>
+
+<style scoped>
+.init-modal-backdrop {
+  position: fixed;
+  inset: 0;
+  /* Above every shell surface — topbar, sidebar, overlays, highlights. */
+  z-index: 30000;
+  background: var(--surface);
+  display: flex;
+  flex-direction: column;
+  /* Soft body-copy color — light grey on dark themes, dark grey on light
+     themes — by mixing the foreground toward the surface. Use this for
+     paragraphs/lists; reserve full `var(--text)` for titles, alerts, and
+     emphasized inline spans. */
+  --init-text-body: color-mix(in srgb, var(--text) 78%, var(--surface));
+}
+
+.init-modal {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.init-modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 14px 20px;
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+.init-modal-title {
+  font-size: 16px;
+  font-weight: 700;
+  color: var(--text);
+  margin: 0;
+}
+
+.init-modal-close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  background: none;
+  border: 1px solid transparent;
+  color: var(--text-muted);
+  cursor: pointer;
+  border-radius: 4px;
+  padding: 0;
+}
+.init-modal-close:hover { color: var(--text); background: var(--surface-2); border-color: var(--border); }
+.init-modal-close:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+
+.init-stepper {
+  display: flex;
+  gap: 0;
+  padding: 10px 16px;
+  list-style: none;
+  margin: 0;
+  border-bottom: 1px solid var(--border);
+  flex-shrink: 0;
+}
+
+.init-stepper-item {
+  display: flex;
+  align-items: center;
+  padding: 0;
+  color: var(--text);
+  opacity: 0.7;
+  font-size: 14px;
+  font-weight: 600;
+  position: relative;
+}
+.init-stepper-item.active { opacity: 1; }
+
+.init-stepper-btn {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 16px;
+  background: transparent;
+  border: none;
+  color: inherit;
+  font: inherit;
+  font-weight: inherit;
+  cursor: default;
+  border-radius: 6px;
+}
+.init-stepper-item.clickable .init-stepper-btn {
+  cursor: pointer;
+}
+.init-stepper-item.clickable .init-stepper-btn:hover {
+  background: var(--surface-2);
+  color: var(--text);
+}
+.init-stepper-item.clickable .init-stepper-btn:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+.init-stepper-btn:disabled {
+  cursor: default;
+}
+
+.init-stepper-item + .init-stepper-item::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 50%;
+  width: 1px;
+  height: 16px;
+  background: var(--border);
+  transform: translateY(-50%);
+}
+
+.init-stepper-item.active { color: var(--text); }
+.init-stepper-item.active .init-stepper-num {
+  background: var(--accent);
+  color: var(--text-on-accent);
+  border-color: var(--accent);
+}
+.init-stepper-item.done .init-stepper-num {
+  background: var(--success);
+  border-color: var(--success);
+  color: var(--text-on-accent);
+}
+
+.init-stepper-num {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 22px;
+  height: 22px;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+  background: var(--surface-2);
+  font-size: 11px;
+  font-weight: 600;
+}
+
+.init-wizard-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 24px 0;
+  display: flex;
+  flex-direction: column;
+  /* Centre content with a comfortable max-width while using the full screen */
+  align-items: center;
+}
+
+/* Constrain direct children (steps) to a readable width */
+.init-wizard-body > * {
+  width: 100%;
+  max-width: 860px;
+  padding: 0 28px;
+}
+
+.init-step {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.init-step-title {
+  font-size: 22px;
+  font-weight: 700;
+  margin: 0;
+  color: var(--text);
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 12px;
+  letter-spacing: -0.01em;
+}
+
+.init-working {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 6px;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--accent);
+  letter-spacing: 0.02em;
+}
+.init-working-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--accent);
+  align-self: center;
+  animation: init-working-pulse 1.2s ease-in-out infinite;
+}
+.init-working-verb {
+  font-weight: 600;
+  animation: init-working-verb-in 320ms ease-out;
+  display: inline-flex;
+  align-items: baseline;
+}
+.init-working-dots::after {
+  display: inline-block;
+  content: '';
+  width: 1.2em;
+  text-align: left;
+  animation: init-working-dots 1.4s steps(4, end) infinite;
+}
+.init-working-elapsed {
+  color: var(--text-muted);
+  font-variant-numeric: tabular-nums;
+  font-weight: 500;
+}
+@keyframes init-working-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.3; } }
+@keyframes init-working-verb-in {
+  from { opacity: 0; transform: translateY(2px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+@keyframes init-working-dots {
+  0%   { content: ''; }
+  25%  { content: '.'; }
+  50%  { content: '..'; }
+  75%  { content: '...'; }
+  100% { content: ''; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .init-working-dot,
+  .init-working-verb,
+  .init-working-dots::after { animation: none; }
+  .init-working-dots::after { content: '…'; }
+}
+
+.init-step-lead {
+  font-size: 15px;
+  line-height: 1.65;
+  color: var(--init-text-body);
+  margin: 0;
+}
+
+.init-step-lead code,
+.init-section-hint code,
+.init-agent-duties code,
+.init-step-note code,
+.init-skip-btn code {
+  background: var(--surface-2);
+  padding: 1px 6px;
+  border-radius: 3px;
+  font-size: 14px;
+  color: var(--text);
+}
+
+.init-agent-duties {
+  margin: 0;
+  padding: 0 0 0 20px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.init-agent-duties li {
+  font-size: 15px;
+  line-height: 1.6;
+  color: var(--init-text-body);
+}
+.init-agent-duties strong {
+  color: var(--text);
+  font-weight: 700;
+}
+
+.init-step-note {
+  font-size: 14px;
+  line-height: 1.6;
+  color: var(--init-text-body);
+  margin: 0;
+  padding: 10px 14px;
+  border-left: 3px solid var(--accent);
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+  border-radius: 4px;
+}
+
+.init-step-actions {
+  display: flex;
+  gap: 8px;
+  padding-top: 8px;
+}
+
+/* Page 0: workflow chooser */
+.init-mode-choices {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  margin: 12px 0 4px;
+}
+.init-mode-choice {
+  display: block;
+  width: 100%;
+  text-align: left;
+  font: inherit;
+  color: inherit;
+  padding: 14px 16px;
+  border: 2px solid var(--border);
+  border-radius: 8px;
+  background: var(--surface-2);
+  cursor: pointer;
+  transition: border-color 120ms ease, background 120ms ease;
+}
+.init-mode-choice:hover:not(.selected) {
+  border-color: color-mix(in srgb, var(--accent) 40%, var(--border));
+  background: var(--surface-3);
+}
+.init-mode-choice:focus-visible {
+  outline: none;
+  border-color: var(--accent);
+}
+.init-mode-choice.selected {
+  border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 8%, var(--surface-2));
+}
+.init-mode-body { display: flex; flex-direction: column; gap: 8px; flex: 1; }
+.init-mode-head { display: flex; align-items: center; gap: 10px; }
+.init-mode-title { font-size: 17px; font-weight: 700; color: var(--text); letter-spacing: -0.005em; }
+.init-mode-badge {
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  padding: 3px 8px;
+  border-radius: 4px;
+}
+.init-mode-badge-stable {
+  background: color-mix(in srgb, var(--success) 28%, transparent);
+  color: var(--text);
+}
+.init-mode-badge-experimental {
+  background: color-mix(in srgb, var(--warning) 28%, transparent);
+  color: var(--text);
+}
+.init-mode-blurb {
+  margin: 0;
+  font-size: 15px;
+  color: var(--init-text-body);
+  line-height: 1.6;
+}
+.init-mode-blurb code,
+.init-mode-bullets code {
+  background: var(--surface-3);
+  padding: 1px 6px;
+  border-radius: 3px;
+  font-size: 14px;
+  color: var(--text);
+}
+.init-mode-bullets {
+  margin: 6px 0 0;
+  padding-left: 18px;
+  font-size: 14px;
+  color: var(--init-text-body);
+  line-height: 1.65;
+}
+.init-mode-bullets li { margin-bottom: 3px; }
+
+.init-mode-warning {
+  margin: 10px 0 0;
+  padding: 10px 14px;
+  font-size: 14px;
+  line-height: 1.55;
+  color: var(--init-text-body);
+  background: color-mix(in srgb, var(--warning) 22%, transparent);
+  border-left: 3px solid var(--warning);
+  border-radius: 4px;
+}
+.init-mode-warning strong { color: var(--text); font-weight: 700; }
+.init-mode-warning code {
+  background: var(--surface-3);
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-size: 13px;
+  color: var(--text);
+}
+
+.init-btn-primary,
+.init-btn-secondary {
+  font: inherit;
+  font-size: 14px;
+  font-weight: 600;
+  padding: 10px 20px;
+  border-radius: 6px;
+  cursor: pointer;
+  transition: background 120ms ease, border-color 120ms ease;
+}
+
+.init-btn-primary {
+  background: var(--accent);
+  color: var(--text-on-accent);
+  border: 1px solid var(--accent);
+}
+.init-btn-primary:hover:not(:disabled) { background: var(--accent-hover); }
+.init-btn-primary:disabled { opacity: 0.5; cursor: not-allowed; }
+
+.init-btn-secondary {
+  background: var(--surface-2);
+  color: var(--text);
+  border: 1px solid var(--border);
+}
+.init-btn-secondary:hover:not(:disabled) { background: var(--surface-3); }
+
+.init-step-actions-split {
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 10px;
+}
+
+.init-alt {
+  margin: 16px 0 0;
+  padding-top: 12px;
+  border-top: 1px solid var(--border);
+  font-size: 14px;
+  color: var(--init-text-body);
+}
+.init-cmd {
+  margin: 6px 0 0;
+  padding: 10px 14px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  font-size: 14px;
+  color: var(--text);
+  overflow-x: auto;
+}
+.init-cmd code {
+  background: transparent;
+  padding: 0;
+  font-size: 14px;
+  color: var(--text);
+}
+
+.init-skip-btn {
+  font: inherit;
+  font-size: 13px;
+  background: none;
+  border: none;
+  color: var(--text);
+  cursor: pointer;
+  padding: 4px 0;
+  text-decoration: underline;
+  text-decoration-color: var(--text-muted);
+  text-underline-offset: 2px;
+}
+.init-skip-btn:hover { color: var(--accent); }
+
+.init-empty {
+  font-size: 15px;
+  color: var(--init-text-body);
+  padding: 18px;
+  border: 1px dashed var(--border);
+  border-radius: 6px;
+}
+.init-empty-small {
+  font-size: 14px;
+  color: var(--init-text-body);
+  margin: 4px 0 0;
+}
+
+.init-progress-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--surface);
+}
+
+.init-progress-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 14px;
+  font-size: 12px;
+  border-bottom: 1px solid var(--border);
+}
+.init-progress-row:last-child { border-bottom: none; }
+.init-progress-row { font-size: 14px; }
+.init-progress-row.success { color: var(--text); }
+.init-progress-row.pending { color: var(--text); opacity: 0.7; }
+.init-progress-row.running { color: var(--text); }
+.init-progress-row.error { color: var(--text); font-weight: 600; }
+.init-progress-row.skipped { color: var(--text); opacity: 0.55; }
+
+.init-progress-marker {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+  font-size: 10px;
+  background: var(--surface-2);
+}
+.init-progress-marker.success { background: var(--success); border-color: var(--success); color: var(--text-on-accent); }
+.init-progress-marker.error { background: var(--danger); border-color: var(--danger); color: var(--text-on-accent); }
+.init-progress-marker.running { background: var(--accent-muted); border-color: var(--accent); }
+
+/* Rescan-mode clickable marker — same visual as the read-only marker, but
+   acts as a per-step include/skip toggle. */
+.init-progress-marker-toggle {
+  padding: 0;
+  cursor: pointer;
+  font: inherit;
+  font-size: 10px;
+  transition: background 120ms, border-color 120ms;
+}
+.init-progress-marker-toggle:hover:not(:disabled) {
+  border-color: var(--accent);
+}
+.init-progress-marker-toggle:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+}
+.init-progress-marker-toggle:disabled {
+  cursor: default;
+}
+.init-progress-marker-toggle.selected:not(.success):not(.error):not(.running) {
+  border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 12%, var(--surface-2));
+}
+.init-marker-dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--accent);
+}
+
+.init-progress-list-rescan .init-progress-row {
+  align-items: flex-start;
+  cursor: default;
+}
+.init-progress-list-rescan .init-progress-row:not(.selected):not(.success):not(.error):not(.running) {
+  opacity: 0.55;
+}
+.init-progress-hint {
+  display: block;
+  margin-top: 2px;
+  font-size: 13px;
+  color: var(--init-text-body);
+}
+.init-progress-when {
+  flex-shrink: 0;
+  font-size: 13px;
+  color: var(--init-text-body);
+  opacity: 0.8;
+  font-style: italic;
+  margin-left: 8px;
+  padding-top: 1px;
+}
+
+.init-spinner {
+  display: inline-block;
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  border: 1.5px solid color-mix(in srgb, var(--accent) 30%, transparent);
+  border-top-color: var(--accent);
+  animation: init-spin 700ms linear infinite;
+}
+@keyframes init-spin { to { transform: rotate(360deg); } }
+
+.init-progress-label { flex: 1; }
+
+/* ── Agent streaming log ── */
+.init-agent-log {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  overflow: hidden;
+  max-height: 200px;
+  display: flex;
+  flex-direction: column;
+}
+.init-agent-log-header {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 10px;
+  background: var(--surface-2);
+  border-bottom: 1px solid var(--border);
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--text);
+  flex-shrink: 0;
+}
+.init-agent-log-body {
+  flex: 1;
+  overflow-y: auto;
+  padding: 8px 10px;
+  background: var(--surface);
+}
+.init-agent-line {
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, monospace);
+  font-size: 11px;
+  line-height: 1.5;
+  color: var(--text);
+  margin: 0;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.init-progress-message {
+  font-size: 13px;
+  color: var(--text);
+}
+
+.init-error {
+  color: var(--init-text-body);
+  background: color-mix(in srgb, var(--danger) 22%, transparent);
+  border-left: 3px solid var(--danger);
+  padding: 10px 14px;
+  border-radius: 4px;
+  font-size: 15px;
+  font-weight: 500;
+  line-height: 1.55;
+  margin: 0;
+}
+.init-success {
+  color: var(--init-text-body);
+  background: color-mix(in srgb, var(--success) 22%, transparent);
+  border-left: 3px solid var(--success);
+  padding: 10px 14px;
+  border-radius: 4px;
+  font-size: 15px;
+  font-weight: 500;
+  line-height: 1.55;
+  margin: 0;
+}
+
+/* Review-step sections */
+.init-section {
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  padding: 14px 16px;
+  background: var(--surface);
+  margin: 0;
+}
+.init-section legend {
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--text);
+  padding: 0 6px;
+}
+.init-section-hint {
+  font-size: 14px;
+  line-height: 1.55;
+  color: var(--init-text-body);
+  margin: 4px 0 12px;
+}
+
+.init-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 10px 12px;
+}
+
+.init-field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  font-size: 14px;
+  color: var(--init-text-body);
+}
+.init-field span { font-weight: 600; color: var(--text); }
+.init-field input,
+.init-field select,
+.init-field textarea {
+  font: inherit;
+  font-size: 12px;
+  padding: 6px 8px;
+  border-radius: 4px;
+  border: 1px solid var(--border);
+  background: var(--surface);
+  color: var(--text);
+}
+.init-field-full { grid-column: 1 / -1; }
+
+.init-themes {
+  list-style: none;
+  margin: 0 0 12px;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.init-theme-row {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 10px 12px;
+  background: var(--surface-2);
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.init-theme-grid {
+  grid-template-columns: repeat(3, 1fr);
+}
+
+.init-default-toggle {
+  display: inline-flex;
+  flex-direction: row !important;
+  align-items: center;
+  gap: 4px;
+  font-size: 11px;
+}
+.init-default-toggle input { margin: 0; }
+
+.init-theme-delete {
+  align-self: flex-end;
+  font-size: 11px;
+  padding: 4px 10px;
+}
+
+.init-readout {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: baseline;
+  font-size: 13px;
+  color: var(--text);
+}
+.init-readout-key { font-weight: 600; }
+.init-readout-version {
+  font-size: 11px;
+  color: var(--text-muted);
+  font-family: var(--font-mono, ui-monospace, monospace);
+}
+.init-readout-meta {
+  font-size: 11px;
+  color: var(--text-muted);
+}
+
+.init-style-guide {
+  width: 100%;
+  font: inherit;
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, monospace);
+  font-size: 12px;
+  line-height: 1.5;
+  padding: 10px 12px;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: var(--surface-2);
+  color: var(--text);
+  resize: vertical;
+}
+
+.init-overwrite-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  color: var(--text-muted);
+  margin-top: 8px;
+}
+.init-overwrite-toggle code { font-size: 11px; }
+
+/* ── APIs & Data tab ── */
+.init-lib-badge {
+  display: inline-block;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  font-size: 11px;
+  padding: 1px 7px;
+  margin-left: 4px;
+}
+
+.init-data-list {
+  list-style: none;
+  margin: 0 0 8px;
+  padding: 0;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  overflow: hidden;
+}
+.init-data-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 7px 10px;
+  border-bottom: 1px solid var(--border);
+  font-size: 12px;
+}
+.init-data-row:last-child { border-bottom: none; }
+.init-data-kind {
+  font-size: 10px;
+  color: var(--text-muted);
+  background: var(--surface-2);
+  border-radius: 3px;
+  padding: 1px 6px;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+.init-data-name {
+  flex: 1;
+  color: var(--text);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, monospace);
+}
+.init-data-remove {
+  flex-shrink: 0;
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  font-size: 16px;
+  line-height: 1;
+  padding: 0 2px;
+  border-radius: 3px;
+}
+.init-data-remove:hover { color: var(--danger); background: color-mix(in srgb, var(--danger) 10%, transparent); }
+
+.init-data-add {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+}
+.init-data-add input {
+  flex: 1;
+  font: inherit;
+  font-size: 12px;
+  padding: 6px 9px;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  background: var(--surface);
+  color: var(--text);
+}
+.init-data-add select {
+  font: inherit;
+  font-size: 12px;
+  padding: 6px 8px;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  background: var(--surface);
+  color: var(--text);
+}
+
+/* ── Style guide toolbar + editor ── */
+.init-guide-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  margin-bottom: 6px;
+}
+
+.init-guide-toggle {
+  display: inline-flex;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 2px;
+  gap: 2px;
+}
+
+.init-guide-mode {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font: inherit;
+  font-size: 11px;
+  font-weight: 500;
+  padding: 4px 10px;
+  border: none;
+  background: transparent;
+  color: var(--text-muted);
+  border-radius: 4px;
+  cursor: pointer;
+  transition: background 100ms, color 100ms;
+}
+.init-guide-mode:hover { color: var(--text); }
+.init-guide-mode.active {
+  background: var(--surface);
+  color: var(--text);
+  box-shadow: 0 1px 3px var(--shadow);
+}
+
+.init-style-guide {
+  width: 100%;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--surface);
+  min-height: 420px;
+}
+.init-style-guide:focus-within {
+  border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 3%, var(--surface));
+}
+
+.init-style-preview {
+  min-height: 420px;
+  padding: 16px 18px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--surface);
+  overflow-y: auto;
+  font-size: 13px;
+  line-height: 1.65;
+  color: var(--text);
+}
+
+/* Markdown body styles for the preview */
+.init-style-preview :deep(h1) { font-size: 18px; font-weight: 700; margin: 0 0 12px; }
+.init-style-preview :deep(h2) { font-size: 14px; font-weight: 600; margin: 20px 0 8px; padding-bottom: 4px; border-bottom: 1px solid var(--border); color: var(--text); }
+.init-style-preview :deep(h3) { font-size: 13px; font-weight: 600; margin: 14px 0 6px; }
+.init-style-preview :deep(p) { margin: 0 0 10px; color: var(--text); }
+.init-style-preview :deep(ul), .init-style-preview :deep(ol) { margin: 0 0 10px; padding-left: 20px; }
+.init-style-preview :deep(li) { margin-bottom: 4px; color: var(--text); }
+.init-style-preview :deep(code) { background: var(--surface-2); padding: 1px 5px; border-radius: 3px; font-size: 11.5px; font-family: var(--font-mono, ui-monospace, monospace); }
+.init-style-preview :deep(pre) { background: var(--surface-2); padding: 10px 12px; border-radius: 6px; overflow-x: auto; margin: 0 0 10px; }
+.init-style-preview :deep(pre code) { background: none; padding: 0; }
+.init-style-preview :deep(blockquote) { border-left: 3px solid var(--accent); margin: 0 0 10px; padding: 4px 12px; color: var(--text-muted); }
+.init-style-preview :deep(hr) { border: none; border-top: 1px solid var(--border); margin: 16px 0; }
+.init-style-preview :deep(strong) { font-weight: 600; }
+
+/* ── Review step sub-nav ── */
+.init-step-review {
+  gap: 0;
+}
+
+.review-subnav {
+  display: flex;
+  gap: 0;
+  padding: 0 0 16px;
+  border-bottom: 1px solid var(--border);
+  margin-bottom: 20px;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+.review-subnav-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 12px;
+  border-radius: 20px;
+  border: 1px solid transparent;
+  background: none;
+  color: var(--text-muted);
+  font: inherit;
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 100ms, color 100ms, border-color 100ms;
+}
+.review-subnav-item:hover { background: var(--surface-2); color: var(--text); }
+.review-subnav-item.active {
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+  border-color: color-mix(in srgb, var(--accent) 40%, transparent);
+  color: var(--accent);
+}
+.review-subnav-item.done { color: var(--text-muted); }
+.review-subnav-item.done .review-subnav-dot { background: var(--success); }
+
+.review-subnav-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--border);
+  flex-shrink: 0;
+}
+.review-subnav-item.active .review-subnav-dot { background: var(--accent); }
+
+/* ── Review panel ── */
+.review-panel-tokens {
+  /* Let DesignTokenEditor manage its own scroll — prevent double-scroll */
+  overflow: hidden;
+}
+.init-token-editor {
+  flex: 1;
+  min-height: 0;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  overflow: hidden;
+}
+
+.review-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  flex: 1;
+  min-height: 200px;
+}
+
+.review-panel-header {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+}
+
+.review-panel-icon {
+  font-size: 22px;
+  line-height: 1;
+  flex-shrink: 0;
+  margin-top: 2px;
+}
+
+.review-panel-title {
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--text);
+  margin: 0 0 4px;
+}
+
+.review-panel-desc {
+  font-size: 13px;
+  color: var(--text-muted);
+  margin: 0;
+  line-height: 1.5;
+}
+.review-panel-desc code { background: var(--surface-2); padding: 1px 5px; border-radius: 3px; }
+
+.review-callout {
+  background: var(--surface-2);
+  border-left: 3px solid var(--accent);
+  border-radius: 6px;
+  padding: 12px 14px;
+  font-size: 12px;
+  color: var(--text);
+  line-height: 1.55;
+}
+.review-callout code { background: var(--surface-3); padding: 1px 5px; border-radius: 3px; font-size: 11px; }
+
+/* ── Review navigation ── */
+.review-nav {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-top: auto;
+  padding-top: 16px;
+  border-top: 1px solid var(--border);
+}
+
+.review-nav-right {
+  display: flex;
+  gap: 8px;
+  margin-left: auto;
+}
+
+/* ── Panel-level sub-tabs ── */
+.panel-tabs {
+  display: flex;
+  gap: 0;
+  border-bottom: 1px solid var(--border);
+  margin-bottom: 14px;
+}
+.panel-tab {
+  font: inherit;
+  font-size: 12px;
+  font-weight: 500;
+  padding: 7px 16px;
+  background: none;
+  border: none;
+  border-bottom: 2px solid transparent;
+  color: var(--text-muted);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  transition: color 100ms, border-color 100ms;
+}
+.panel-tab:hover { color: var(--text); }
+.panel-tab.active {
+  color: var(--accent);
+  border-bottom-color: var(--accent);
+  font-weight: 600;
+}
+.panel-tab-count {
+  background: var(--surface-2);
+  border-radius: 9px;
+  font-size: 10px;
+  font-weight: 600;
+  padding: 1px 6px;
+  color: var(--text-muted);
+}
+.panel-tab.active .panel-tab-count {
+  background: color-mix(in srgb, var(--accent) 15%, transparent);
+  color: var(--accent);
+}
+
+/* ── Section sub-label ── */
+.init-section-label {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--text-muted);
+  margin: 12px 0 6px;
+}
+
+/* ── Token sections matching ThemePage layout ── */
+.init-token-section {
+  margin-bottom: 8px;
+}
+.init-token-section-title {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--text-muted);
+  padding: 4px 8px;
+  margin: 0 0 2px;
+  border-bottom: 1px solid var(--border);
+}
+
+/* Re-use ThemePage's .token-row classes verbatim */
+.token-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 6px 8px;
+  border-radius: 6px;
+  gap: 8px;
+  transition: background 80ms;
+}
+.token-row:hover { background: var(--surface-2); }
+.token-info { display: flex; flex-direction: column; gap: 2px; min-width: 0; flex: 1; }
+.token-role { font-size: 12px; font-weight: 500; color: var(--text); white-space: nowrap; }
+.token-source {
+  font-size: 9px; color: var(--text-muted); white-space: nowrap;
+  overflow: hidden; text-overflow: ellipsis; max-width: 180px;
+}
+.token-controls { display: flex; align-items: center; gap: 8px; flex-shrink: 0; }
+.color-swatch-inline {
+  width: 20px; height: 20px; border-radius: 4px;
+  border: 1px solid color-mix(in srgb, var(--border) 60%, transparent);
+  flex-shrink: 0;
+}
+.token-value-text {
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, monospace);
+  font-size: 11px; color: var(--text-muted);
+}
+.font-sample {
+  font-size: 11px; max-width: 160px;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.font-size-preview {
+  color: var(--text); line-height: 1; min-width: 20px; text-align: center;
+}
+.spacing-preview { display: flex; align-items: center; width: 60px; }
+.spacing-bar {
+  height: 6px; background: var(--accent-muted); border-radius: 2px;
+  max-width: 60px; min-width: 2px;
+}
+.radius-preview {
+  width: 20px; height: 20px;
+  background: var(--accent-muted);
+  border: 1px solid var(--accent);
+}
+
+/* ── Design-token & component rows (ThemePage-style) ── */
+.init-token-categories {
+  list-style: none;
+  margin: 0 0 4px;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.init-token-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 8px 10px;
+  border-radius: 6px;
+  gap: 8px;
+  transition: background 80ms;
+}
+.init-token-row:hover { background: var(--surface-2); }
+
+.init-token-info {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+.init-token-role {
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--text);
+  white-space: nowrap;
+}
+.init-token-source {
+  font-size: 10px;
+  color: var(--text-muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 200px;
+}
+
+.init-token-badge {
+  font-size: 10px;
+  font-weight: 600;
+  padding: 2px 8px;
+  border-radius: 4px;
+  background: color-mix(in srgb, var(--success) 15%, transparent);
+  color: var(--success);
+  border: 1px solid color-mix(in srgb, var(--success) 30%, transparent);
+  white-space: nowrap;
+}
+.init-token-badge.muted {
+  background: var(--surface-2);
+  color: var(--text-muted);
+  border-color: var(--border);
+}
+
+/* ── Style guide structured sections ── */
+.init-guide-sections {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.init-guide-section {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  overflow: hidden;
+}
+.init-guide-section + .init-guide-section { margin-top: 6px; }
+
+.init-guide-section-label {
+  display: block;
+  padding: 8px 12px 4px;
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--text-muted);
+  background: var(--surface-2);
+  border-bottom: 1px solid var(--border);
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+
+.init-guide-section-body {
+  display: block;
+  width: 100%;
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.55;
+  padding: 10px 12px;
+  border: none;
+  background: var(--surface);
+  color: var(--text);
+  resize: vertical;
+  min-height: 48px;
+}
+.init-guide-section-body:focus {
+  outline: none;
+  background: color-mix(in srgb, var(--accent) 4%, var(--surface));
+}
+
+/* ── Agent directions sub-step ── */
+.review-panel-agents {
+  overflow: hidden;
+}
+
+.init-perm-row {
+  display: flex;
+  gap: 16px;
+  align-items: center;
+  padding: 12px 14px;
+  margin-bottom: 12px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--surface-2);
+}
+.init-perm-label {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  flex: 1;
+  min-width: 0;
+}
+.init-perm-label-title { font-size: 12px; font-weight: 600; color: var(--text); }
+.init-perm-label-hint  { font-size: 11px; color: var(--text-muted); line-height: 1.4; }
+.init-perm-select {
+  font: inherit;
+  font-size: 12px;
+  padding: 6px 10px;
+  border: 1px solid var(--border);
+  background: var(--surface);
+  color: var(--text);
+  border-radius: 5px;
+  min-width: 280px;
+}
+.init-perm-select:focus { outline: none; border-color: var(--accent); }
+
+.init-perm-note {
+  margin: -6px 0 16px;
+  padding: 10px 14px;
+  font-size: 14px;
+  line-height: 1.55;
+  color: var(--init-text-body);
+  background: color-mix(in srgb, var(--warning) 22%, transparent);
+  border-left: 3px solid var(--warning);
+  border-radius: 4px;
+}
+.init-perm-note code {
+  font-size: 13px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: var(--surface-2);
+  color: var(--text);
+}
+
+.init-adp {
+  flex: 1;
+  min-height: 380px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  overflow: hidden;
+}
+
+/* ── Scan options disclosure ── */
+.init-scan-opts {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--surface-2);
+  padding: 8px 12px;
+  font-size: 12px;
+}
+.init-scan-opts summary {
+  cursor: pointer;
+  font-weight: 500;
+  color: var(--text-muted);
+  user-select: none;
+}
+.init-scan-opts summary:hover { color: var(--text); }
+
+.init-scan-opt-list {
+  list-style: none;
+  margin: 8px 0 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.init-scan-opt {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  cursor: pointer;
+  font-size: 12px;
+  color: var(--text);
+}
+.init-scan-opt input { margin: 0; cursor: pointer; }
+.init-scan-opt-status {
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 11px;
+  font-weight: 700;
+  color: var(--text-muted);
+}
+.init-scan-opt-list > li.success .init-scan-opt-status { color: var(--success); }
+.init-scan-opt-list > li.error   .init-scan-opt-status { color: var(--danger); }
+.init-scan-opt-list > li.running .init-scan-opt-status { color: var(--accent); }
+.init-scan-opt-list > li.skipped .init-scan-opt-status { color: var(--text-muted); opacity: 0.6; }
+.init-scan-opt-main {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  flex: 1;
+  min-width: 0;
+}
+.init-scan-opt-hint {
+  font-size: 11px;
+  color: var(--text-muted);
+}
+.init-scan-opt-when {
+  font-size: 11px;
+  color: var(--text-muted);
+  font-style: italic;
+  flex-shrink: 0;
+  margin-left: 8px;
+}
+
+/* ── Re-scan mode: toggles take the primary surface ── */
+.init-scan-opts-rescan {
+  background: var(--surface);
+  padding: 14px 16px;
+}
+.init-scan-opts-rescan .init-scan-opt-list { margin-top: 0; gap: 12px; }
+.init-scan-opts-rescan .init-scan-opt {
+  align-items: center;
+  padding: 8px 10px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--surface-2);
+  transition: border-color 120ms, background 120ms;
+}
+.init-scan-opts-rescan .init-scan-opt:hover {
+  border-color: var(--border-strong);
+}
+.init-scan-opts-rescan .init-scan-opt:has(input:checked) {
+  border-color: color-mix(in srgb, var(--accent) 50%, var(--border));
+  background: color-mix(in srgb, var(--accent) 6%, var(--surface));
+}
+
+/* ── Style guide file override ── */
+.init-guide-file-row {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 10px 12px;
+  background: var(--surface-2);
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.init-guide-file-label {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.init-guide-file-input-row {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+}
+
+.init-guide-file-input {
+  flex: 1;
+  font: inherit;
+  font-size: 12px;
+  padding: 6px 9px;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  background: var(--surface);
+  color: var(--text);
+}
+.init-guide-file-input:focus { outline: 2px solid var(--accent); outline-offset: -1px; }
+
+.init-guide-file-error {
+  font-size: 11px;
+  color: var(--danger);
+  margin: 0;
+}
+
+/* ── Agent directions review panel ── */
+.init-agent-dir-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.init-agent-dir-row {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  overflow: hidden;
+  background: var(--surface);
+}
+
+.init-agent-dir-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 12px;
+  background: var(--surface-2);
+  border-bottom: 1px solid var(--border);
+}
+
+.init-agent-dir-name {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text);
+}
+
+.init-agent-dir-types {
+  font-size: 10px;
+  color: var(--text-muted);
+  font-family: var(--font-mono, ui-monospace, monospace);
+}
+
+.init-agent-dir-textarea {
+  display: block;
+  width: 100%;
+  font: inherit;
+  font-size: 12.5px;
+  line-height: 1.5;
+  padding: 8px 12px;
+  border: none;
+  background: var(--surface);
+  color: var(--text);
+  resize: vertical;
+  min-height: 64px;
+}
+.init-agent-dir-textarea:focus {
+  outline: none;
+  background: color-mix(in srgb, var(--accent) 3%, var(--surface));
+}
+
+.init-agent-dir-actions {
+  display: flex;
+  justify-content: flex-end;
+  padding: 6px 10px;
+  border-top: 1px solid var(--border);
+  background: var(--surface-2);
+}
+
+.init-btn-xs {
+  font-size: 11px;
+  padding: 4px 12px;
+}
+
+.init-token-usage {
+  display: flex; gap: 6px; flex-wrap: wrap; align-items: center;
+  margin-top: 8px; padding: 6px 8px; border-radius: 6px;
+  background: var(--surface-2); border: 1px solid var(--border);
+}
+.init-token-pill {
+  font-size: 11px; font-family: monospace; padding: 2px 6px; border-radius: 4px;
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+  color: var(--text);
+  border: 1px solid color-mix(in srgb, var(--accent) 22%, transparent);
+}
+.init-token-pill-cache {
+  background: color-mix(in srgb, var(--info) 12%, transparent);
+  border-color: color-mix(in srgb, var(--info) 22%, transparent);
+}
+.init-token-meta { font-size: 11px; color: var(--text-muted); }
+</style>
diff --git a/src/shell/components/LibrariesPage.vue b/src/shell/components/LibrariesPage.vue
index cce8a0f..8872235 100644
--- a/src/shell/components/LibrariesPage.vue
+++ b/src/shell/components/LibrariesPage.vue
@@ -330,7 +330,7 @@ onMounted(refresh)
 .comp-name { font-weight: 600; flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .used-badge {
   font-size: 9px; font-weight: 700; text-transform: uppercase; letter-spacing: 0.03em;
-  color: #22c55e; background: rgba(34, 197, 94, 0.1);
+  color: var(--success); background: color-mix(in srgb, var(--success) 10%, transparent);
   padding: 1px 5px; border-radius: 3px; flex-shrink: 0;
 }
 .comp-prop-count {
@@ -357,9 +357,9 @@ onMounted(refresh)
   background: var(--bg); border: 1px solid var(--border); border-radius: 6px;
   white-space: pre; overflow-x: auto;
 }
-.syn-kw { color: #c792ea; }
+.syn-kw { color: var(--purple); }
 .syn-name { color: var(--accent); }
-.syn-str { color: #c3e88d; }
+.syn-str { color: var(--syntax-string); }
 
 .detail-section { }
 .section-header { display: flex; align-items: center; gap: 8px; margin-bottom: 12px; }
@@ -378,11 +378,11 @@ onMounted(refresh)
 .props-table th:last-child { border-radius: 0 6px 0 0; }
 .props-table td { padding: 8px 12px; border-bottom: 1px solid var(--border); vertical-align: top; }
 .props-table tr:last-child td { border-bottom: none; }
-.props-table tbody tr:hover { background: rgba(255,255,255,0.02); }
+.props-table tbody tr:hover { background: color-mix(in srgb, var(--text) 2%, transparent); }
 
 .prop-name { font-size: 13px; color: var(--accent); font-weight: 600; }
 .prop-type { font-size: 12px; color: var(--text-muted); word-break: break-all; }
-.req-badge { font-size: 10px; font-weight: 700; color: #f59e0b; text-transform: uppercase; }
+.req-badge { font-size: 10px; font-weight: 700; color: var(--warning); text-transform: uppercase; }
 .prop-default { font-size: 12px; color: var(--text-muted); }
 
 /* Context explanation page */
@@ -395,19 +395,19 @@ onMounted(refresh)
   margin: 0 0 16px;
   font-size: 20px;
   font-weight: 700;
-  color: #fff;
+  color: var(--text);
 }
 .context-page p {
   margin: 0 0 12px;
   font-size: 14px;
-  color: #ccc;
+  color: var(--text-muted);
   line-height: 1.7;
 }
 .context-page h3 {
   margin: 0 0 8px;
   font-size: 14px;
   font-weight: 700;
-  color: #fff;
+  color: var(--text);
 }
 
 /* Flow diagram */
@@ -448,7 +448,7 @@ onMounted(refresh)
   display: flex; flex-direction: column; gap: 6px;
 }
 .context-section li {
-  font-size: 14px; color: #ccc; line-height: 1.6;
+  font-size: 14px; color: var(--text-muted); line-height: 1.6;
 }
 .context-section code {
   font-family: 'SF Mono', 'Fira Code', Consolas, monospace;
diff --git a/src/shell/components/MarkdownEditor.vue b/src/shell/components/MarkdownEditor.vue
new file mode 100644
index 0000000..be61248
--- /dev/null
+++ b/src/shell/components/MarkdownEditor.vue
@@ -0,0 +1,205 @@
+<template>
+  <div
+    ref="hostRef"
+    class="md-editor"
+    :class="{ 'md-editor-bordered': bordered }"
+    :aria-label="ariaLabel"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onBeforeUnmount, watch } from 'vue'
+import { EditorView, keymap, placeholder, lineNumbers, highlightActiveLine, drawSelection } from '@codemirror/view'
+import { EditorState, Compartment } from '@codemirror/state'
+import { history, defaultKeymap, historyKeymap, indentWithTab } from '@codemirror/commands'
+import { searchKeymap } from '@codemirror/search'
+import {
+  HighlightStyle,
+  syntaxHighlighting,
+  bracketMatching,
+} from '@codemirror/language'
+import { markdown, markdownLanguage } from '@codemirror/lang-markdown'
+import { tags as t } from '@lezer/highlight'
+
+/**
+ * Markdown editor backed by CodeMirror 6.
+ *
+ * Why CM6 vs a textarea overlay:
+ *   - Caret never drifts (CM owns its own selection model).
+ *   - Real soft-wrap with proper line numbers and active-line styling.
+ *   - Bracket matching, undo/redo, search keymap — table stakes for editing
+ *     longer agent prompts.
+ *   - Theming via `EditorView.theme` keeps the editor visually in sync with
+ *     the shell's CSS vars across all 18 built-in themes (we map each token
+ *     to a `var(--…)` so theme switches just work without re-mounting CM).
+ *
+ * API is intentionally narrow (`v-model` + placeholder) so this drops into
+ * any spot a `<textarea>` previously lived.
+ */
+const props = withDefaults(
+  defineProps<{
+    modelValue: string
+    placeholder?: string
+    ariaLabel?: string
+    bordered?: boolean
+    /** Show the gutter with line numbers. Default off — most prompt
+     *  editors don't want it, but the style-guide editor turns it on. */
+    showLineNumbers?: boolean
+  }>(),
+  { placeholder: '', ariaLabel: 'Markdown editor', bordered: false, showLineNumbers: false },
+)
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+}>()
+
+const hostRef = ref<HTMLDivElement | null>(null)
+let view: EditorView | null = null
+
+// Compartments let us hot-swap a single facet without rebuilding the editor —
+// theme tokens use CSS vars so we don't need to swap on theme change, but
+// placeholder text + line numbers can change between mounts of the same
+// editor (e.g. swapping personas in AgentDirectionsPanel).
+const placeholderCompartment = new Compartment()
+const gutterCompartment = new Compartment()
+
+/** Map Lezer tags to themed CSS vars so a theme switch (dark↔light, Monokai
+ *  etc.) re-colors the editor without remounting CodeMirror. */
+const markdownHighlight = HighlightStyle.define([
+  { tag: [t.heading1, t.heading2, t.heading3, t.heading4, t.heading5, t.heading6, t.heading], color: 'var(--accent)', fontWeight: '600' },
+  { tag: t.strong, color: 'var(--text)', fontWeight: '700' },
+  { tag: t.emphasis, color: 'var(--text)', fontStyle: 'italic' },
+  { tag: t.strikethrough, textDecoration: 'line-through', color: 'var(--text-muted)' },
+  { tag: t.link, color: 'var(--text-link)', textDecoration: 'underline' },
+  { tag: t.url, color: 'var(--text-link)' },
+  { tag: t.monospace, color: 'var(--syntax-string)', backgroundColor: 'color-mix(in srgb, var(--surface-2) 80%, transparent)' },
+  { tag: [t.quote], color: 'var(--text-muted)', fontStyle: 'italic' },
+  { tag: t.list, color: 'var(--accent)' },
+  { tag: t.contentSeparator, color: 'var(--text-muted)' },
+  { tag: t.processingInstruction, color: 'var(--text-muted)' },
+  // Code fences + inline code content.
+  { tag: t.string, color: 'var(--syntax-string)' },
+  { tag: t.number, color: 'var(--syntax-number)' },
+  { tag: t.bool, color: 'var(--syntax-boolean)' },
+  { tag: t.comment, color: 'var(--text-muted)', fontStyle: 'italic' },
+  { tag: t.keyword, color: 'var(--syntax-property)' },
+  { tag: t.atom, color: 'var(--syntax-boolean)' },
+  { tag: t.meta, color: 'var(--text-muted)' },
+])
+
+/** Theme that maps every CM6 surface to the shell's CSS vars. */
+const themeExt = EditorView.theme({
+  '&': {
+    height: '100%',
+    fontSize: '12.5px',
+    color: 'var(--text)',
+    backgroundColor: 'transparent',
+  },
+  '&.cm-focused': { outline: 'none' },
+  '.cm-scroller': {
+    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+    lineHeight: '1.6',
+  },
+  '.cm-content': {
+    padding: '14px 18px',
+    caretColor: 'var(--text)',
+  },
+  '.cm-line': { padding: '0' },
+  '.cm-cursor, .cm-dropCursor': { borderLeftColor: 'var(--text)' },
+  '&.cm-focused .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection': {
+    backgroundColor: 'color-mix(in srgb, var(--accent) 30%, transparent)',
+  },
+  '.cm-activeLine': {
+    backgroundColor: 'color-mix(in srgb, var(--accent) 4%, transparent)',
+  },
+  '.cm-gutters': {
+    backgroundColor: 'transparent',
+    color: 'var(--text-muted)',
+    border: 'none',
+    borderRight: '1px solid var(--border)',
+  },
+  '.cm-activeLineGutter': {
+    backgroundColor: 'transparent',
+    color: 'var(--text)',
+  },
+  '.cm-placeholder': {
+    color: 'var(--text-muted)',
+  },
+  '.cm-matchingBracket, &.cm-focused .cm-matchingBracket': {
+    backgroundColor: 'color-mix(in srgb, var(--accent) 25%, transparent)',
+    outline: 'none',
+  },
+}, { dark: false })
+
+function makeExtensions() {
+  return [
+    history(),
+    drawSelection(),
+    highlightActiveLine(),
+    bracketMatching(),
+    EditorView.lineWrapping,
+    markdown({ base: markdownLanguage }),
+    syntaxHighlighting(markdownHighlight),
+    themeExt,
+    keymap.of([indentWithTab, ...defaultKeymap, ...historyKeymap, ...searchKeymap]),
+    placeholderCompartment.of(placeholder(props.placeholder)),
+    gutterCompartment.of(props.showLineNumbers ? lineNumbers() : []),
+    EditorView.updateListener.of((u) => {
+      if (u.docChanged) {
+        const next = u.state.doc.toString()
+        if (next !== props.modelValue) emit('update:modelValue', next)
+      }
+    }),
+  ]
+}
+
+onMounted(() => {
+  if (!hostRef.value) return
+  view = new EditorView({
+    state: EditorState.create({ doc: props.modelValue, extensions: makeExtensions() }),
+    parent: hostRef.value,
+  })
+})
+
+onBeforeUnmount(() => { view?.destroy(); view = null })
+
+// External writes to v-model (e.g. user switched persona): replace the doc
+// without echoing back through the change listener.
+watch(() => props.modelValue, (next) => {
+  if (!view) return
+  if (next === view.state.doc.toString()) return
+  view.dispatch({
+    changes: { from: 0, to: view.state.doc.length, insert: next },
+  })
+})
+
+watch(() => props.placeholder, (next) => {
+  view?.dispatch({ effects: placeholderCompartment.reconfigure(placeholder(next)) })
+})
+
+watch(() => props.showLineNumbers, (next) => {
+  view?.dispatch({ effects: gutterCompartment.reconfigure(next ? lineNumbers() : []) })
+})
+</script>
+
+<style scoped>
+.md-editor {
+  flex: 1;
+  min-height: 0;
+  display: flex;
+  background: var(--surface);
+  overflow: hidden;
+}
+.md-editor-bordered {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+}
+.md-editor :deep(.cm-editor) {
+  flex: 1;
+  height: 100%;
+  width: 100%;
+}
+.md-editor:focus-within {
+  background: color-mix(in srgb, var(--accent) 2%, var(--surface));
+}
+</style>
diff --git a/src/shell/components/ModeToolbar.vue b/src/shell/components/ModeToolbar.vue
index a6e1788..cbae8ae 100644
--- a/src/shell/components/ModeToolbar.vue
+++ b/src/shell/components/ModeToolbar.vue
@@ -21,9 +21,6 @@ const emit = defineEmits<{ 'update:modelValue': [mode: InteractionMode] }>()
     <button data-testid="tool-arrow" :class="['mode-btn arrow', { active: modelValue === 'arrow' }]" @click="emit('update:modelValue', 'arrow')" title="Arrow (A)">
       <Icon name="arrow-right" :stroke-width="2.5" />
     </button>
-    <button data-testid="tool-draw" :class="['mode-btn draw', { active: modelValue === 'draw' }]" @click="emit('update:modelValue', 'draw')" title="Draw Section (D)">
-      <Icon name="square-plus" />
-    </button>
     <button data-testid="tool-highlight" :class="['mode-btn mode-highlight', { active: modelValue === 'highlight' }]" @click="emit('update:modelValue', 'highlight')" title="Highlight Text (H)">
       <Icon name="highlighter" />
     </button>
@@ -47,7 +44,6 @@ const emit = defineEmits<{ 'update:modelValue': [mode: InteractionMode] }>()
 .mode-btn.active { background: var(--accent); border-color: var(--accent); color: var(--text-on-accent); }
 .mode-btn.mode-pin.active { background: var(--pin-color); border-color: var(--pin-color); color: white; }
 .mode-btn.arrow.active { background: var(--mode-arrow); border-color: var(--mode-arrow); }
-.mode-btn.draw.active { background: var(--mode-draw); border-color: var(--mode-draw); }
 .mode-btn.mode-highlight.active { background: var(--mode-highlight); border-color: var(--mode-highlight); }
 .mode-sep { width: 1px; height: 18px; background: var(--border); margin: 0 2px; align-self: center; }
 </style>
diff --git a/src/shell/components/OverlayLegend.vue b/src/shell/components/OverlayLegend.vue
new file mode 100644
index 0000000..e38304f
--- /dev/null
+++ b/src/shell/components/OverlayLegend.vue
@@ -0,0 +1,205 @@
+<script setup lang="ts">
+/**
+ * On-canvas legend for the active overlay sources. Renders in a corner of the
+ * canvas so the user can decode rect colors WITHOUT looking away at the
+ * sidebar — the core fix for "color means three different things and nothing
+ * on the canvas says which".
+ *
+ * Two modes, chosen from the sources themselves:
+ *   - identity  → one row per source (swatch + label), hover to focus that
+ *                 source's rects (reuses the same focus path as the sidebar).
+ *   - latency   → the Network tab colors by latency, so a per-endpoint legend
+ *                 would be noise; instead we show the latency buckets and a
+ *                 "Color: latency" header so an orange rect reads as "slow",
+ *                 not "second source".
+ */
+import { computed } from 'vue'
+import { colorForSource, type DataHighlightSource } from '../composables/useDataHighlights'
+
+const props = defineProps<{
+  sources: DataHighlightSource[]
+  focusedName: string | null
+  /** True when more elements matched than the overlay cap draws. */
+  truncated?: boolean
+  /** Rects actually drawn (capped). */
+  shown?: number
+  /** True total matched this pass (uncapped) — drives "showing N of M". */
+  total?: number
+}>()
+
+const emit = defineEmits<{ (e: 'focus', name: string | null): void }>()
+
+const isLatency = computed(() => props.sources.some(s => s.encoding === 'latency'))
+
+/** Mirrors `colorForLatency` / `latencyBucketLabel` in useDataSources.ts. */
+const latencyBuckets = [
+  { label: 'fast · <200ms', color: 'var(--success)' },
+  { label: 'ok · <500ms', color: 'var(--warning)' },
+  { label: 'slow · <1s', color: 'var(--annotation-orange)' },
+  { label: 'very slow · ≥1s', color: 'var(--danger)' },
+  { label: 'no data', color: 'var(--text-muted)' },
+]
+
+const items = computed(() =>
+  props.sources.map(s => ({
+    name: s.name,
+    label: s.defaultLabel ?? s.name,
+    color: s.color ?? colorForSource(s.name),
+    approximate: s.confidence === 'fallback' || s.confidence === 'runtime-only',
+  })),
+)
+</script>
+
+<template>
+  <div class="overlay-legend" @mouseleave="emit('focus', null)">
+    <div class="ol-head">
+      <span class="ol-title">{{ isLatency ? 'Color: latency' : 'Highlights' }}</span>
+      <span class="ol-count">{{ sources.length }}</span>
+    </div>
+
+    <!-- Latency mode: fixed buckets, not per-endpoint. -->
+    <div v-if="isLatency" class="ol-list">
+      <div v-for="b in latencyBuckets" :key="b.label" class="ol-row">
+        <span class="ol-swatch ol-solid" :style="{ '--sw': b.color }" />
+        <span class="ol-label">{{ b.label }}</span>
+      </div>
+    </div>
+
+    <!-- Identity mode: one row per source, hover to focus. -->
+    <div v-else class="ol-list ol-scroll">
+      <button
+        v-for="it in items"
+        :key="it.name"
+        type="button"
+        class="ol-row ol-row-btn"
+        :class="{ focused: it.name === focusedName, dimmed: focusedName && it.name !== focusedName }"
+        @mouseenter="emit('focus', it.name)"
+        @focus="emit('focus', it.name)"
+        @blur="emit('focus', null)"
+      >
+        <span class="ol-swatch" :class="it.approximate ? 'ol-dotted' : 'ol-solid'" :style="{ '--sw': it.color }" />
+        <span class="ol-label">{{ it.label }}</span>
+        <span v-if="it.approximate" class="ol-approx" title="Approximate — file-level / runtime-only match">≈</span>
+      </button>
+    </div>
+
+    <!-- Density: never hide overflow silently. When the rect cap clips matches,
+         say so explicitly so the user knows the picture is incomplete. -->
+    <div v-if="truncated" class="ol-trunc" title="Too many matches to draw at once — narrow the selection or filter to see specific ones">
+      <span class="ol-trunc-dot" />
+      Showing {{ (shown ?? 0).toLocaleString() }} of {{ (total ?? 0).toLocaleString() }} — too dense
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.overlay-legend {
+  position: absolute;
+  left: 10px;
+  bottom: 10px;
+  z-index: 10002;
+  max-width: 240px;
+  padding: 6px;
+  background: var(--surface-glass, var(--surface));
+  backdrop-filter: blur(6px);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  box-shadow: 0 2px 10px var(--shadow);
+  font-size: 11px;
+  pointer-events: auto;
+  user-select: none;
+}
+
+.ol-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 1px 4px 5px;
+  color: var(--text-muted);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  font-size: 9.5px;
+}
+.ol-count {
+  min-width: 16px;
+  height: 15px;
+  padding: 0 4px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--surface-2, var(--surface));
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  font-size: 9px;
+}
+
+.ol-list { display: flex; flex-direction: column; gap: 1px; }
+.ol-scroll { max-height: 184px; overflow-y: auto; }
+
+.ol-row {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  padding: 3px 5px;
+  border-radius: 5px;
+  color: var(--text);
+  line-height: 1.2;
+}
+.ol-row-btn {
+  width: 100%;
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+  font: inherit;
+  transition: background 0.1s ease-out, opacity 0.1s ease-out;
+}
+.ol-row-btn:hover,
+.ol-row-btn.focused { background: color-mix(in srgb, var(--accent) 14%, transparent); }
+.ol-row-btn.dimmed { opacity: 0.45; }
+
+.ol-swatch {
+  flex: 0 0 auto;
+  width: 16px;
+  height: 0;
+  border-radius: 1px;
+}
+.ol-solid { border-top: 3px solid var(--sw); }
+/* Dotted swatch mirrors the approximate (file-level/runtime) rect border. */
+.ol-dotted { border-top: 3px dotted var(--sw); }
+
+.ol-label {
+  flex: 1 1 auto;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.ol-approx {
+  flex: 0 0 auto;
+  font-family: monospace;
+  font-weight: 700;
+  color: var(--text-muted);
+}
+
+.ol-trunc {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 4px;
+  padding: 4px 5px;
+  border-top: 1px solid var(--border);
+  color: var(--warning);
+  font-size: 10px;
+  font-weight: 600;
+  line-height: 1.2;
+}
+.ol-trunc-dot {
+  flex: 0 0 auto;
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--warning);
+}
+</style>
diff --git a/src/shell/components/PerfResourceTables.vue b/src/shell/components/PerfResourceTables.vue
index db9337b..895e31e 100644
--- a/src/shell/components/PerfResourceTables.vue
+++ b/src/shell/components/PerfResourceTables.vue
@@ -91,7 +91,7 @@ function shortenUrl(url: string): string {
 .resource-table { margin-top: 6px; font-size: 10px; }
 .resource-header, .resource-row { display: grid; grid-template-columns: 1fr 60px 60px 60px; gap: 4px; padding: 3px 0; }
 .resource-header { font-weight: 700; color: var(--text-muted); border-bottom: 1px solid var(--border); text-transform: uppercase; font-size: 9px; }
-.resource-row { color: var(--text); border-bottom: 1px solid rgba(255,255,255,0.04); }
+.resource-row { color: var(--text); border-bottom: 1px solid color-mix(in srgb, var(--text) 4%, transparent); }
 .resource-row.heavy { color: var(--warning); }
 .res-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .res-type { color: var(--text-muted); }
diff --git a/src/shell/components/PinOverlay.vue b/src/shell/components/PinOverlay.vue
index 5ea8e9c..6675a23 100644
--- a/src/shell/components/PinOverlay.vue
+++ b/src/shell/components/PinOverlay.vue
@@ -44,12 +44,12 @@ const emit = defineEmits<{
   justify-content: center;
   cursor: pointer;
   transform: translate(-11px, -11px);
-  box-shadow: 0 2px 6px rgba(0,0,0,0.3);
+  box-shadow: 0 2px 6px var(--shadow);
   transition: all 0.15s;
   border: 2px solid white;
 }
 .pin:hover { transform: translate(-11px, -11px) scale(1.2); }
-.pin.selected { background: var(--pin-color); box-shadow: 0 0 0 3px color-mix(in srgb, var(--pin-color) 30%, transparent), 0 2px 6px rgba(0,0,0,0.3); }
+.pin.selected { background: var(--pin-color); box-shadow: 0 0 0 3px color-mix(in srgb, var(--pin-color) 30%, transparent), 0 2px 6px var(--shadow); }
 .pin.has-action { background: var(--purple); }
 .pin.has-note.has-action { background: var(--purple); }
 
diff --git a/src/shell/components/PropWidgetRows.vue b/src/shell/components/PropWidgetRows.vue
new file mode 100644
index 0000000..5f0593d
--- /dev/null
+++ b/src/shell/components/PropWidgetRows.vue
@@ -0,0 +1,75 @@
+<script setup lang="ts">
+/**
+ * Type-aware prop editor rows — extracted from the legacy generate panel so the
+ * inline block popover and any other prop UI share one widget switch. Pure: it
+ * renders the current values and emits `set` on change; the parent owns where
+ * the value lands.
+ */
+import { inferWidget, enumValues, type WidgetProp } from '../utils/propWidgets'
+
+const props = defineProps<{
+  rows: WidgetProp[]
+  values: Record<string, unknown>
+  /** data-testid prefix (e.g. 'wf-prop' → 'wf-prop-label'). */
+  testidPrefix?: string
+}>()
+
+const emit = defineEmits<{ set: [name: string, value: unknown] }>()
+
+function jsonValue(name: string): string {
+  const v = props.values[name]
+  if (v === undefined) return ''
+  return typeof v === 'string' ? v : JSON.stringify(v)
+}
+
+function setJson(name: string, raw: string): void {
+  if (raw.trim() === '') { emit('set', name, undefined); return }
+  try { emit('set', name, JSON.parse(raw)) } catch { /* invalid — keep previous */ }
+}
+
+const tid = (name: string) => `${props.testidPrefix ?? 'prop'}-${name}`
+</script>
+
+<template>
+  <div v-for="p in rows" :key="p.name" class="pw-row">
+    <code class="pw-name" :title="p.type ?? ''">{{ p.name }}</code>
+    <template v-if="inferWidget(p) === 'boolean'">
+      <input type="checkbox" :checked="values[p.name] === true" :data-testid="tid(p.name)"
+        @change="(e) => emit('set', p.name, (e.target as HTMLInputElement).checked)">
+    </template>
+    <template v-else-if="inferWidget(p) === 'number'">
+      <input type="number" class="pw-input" :value="(values[p.name] as number) ?? ''" :data-testid="tid(p.name)"
+        @input="(e) => { const v = (e.target as HTMLInputElement).value; emit('set', p.name, v === '' ? undefined : Number(v)) }">
+    </template>
+    <template v-else-if="inferWidget(p) === 'enum'">
+      <select class="pw-input" :value="(values[p.name] as string) ?? ''" :data-testid="tid(p.name)"
+        @change="(e) => emit('set', p.name, (e.target as HTMLSelectElement).value || undefined)">
+        <option value="">—</option>
+        <option v-for="opt in enumValues(p)" :key="opt" :value="opt">{{ opt }}</option>
+      </select>
+    </template>
+    <template v-else-if="inferWidget(p) === 'string'">
+      <input type="text" class="pw-input" :value="(values[p.name] as string) ?? ''" :data-testid="tid(p.name)"
+        @input="(e) => emit('set', p.name, (e.target as HTMLInputElement).value || undefined)">
+    </template>
+    <template v-else>
+      <input type="text" class="pw-input" placeholder="JSON" :value="jsonValue(p.name)" :data-testid="tid(p.name)"
+        @change="(e) => setJson(p.name, (e.target as HTMLInputElement).value)">
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.pw-row { display: flex; align-items: center; gap: 8px; margin-bottom: 4px; }
+.pw-name { min-width: 84px; font-size: 11px; color: var(--syntax-property); overflow: hidden; text-overflow: ellipsis; }
+.pw-input {
+  flex: 1;
+  min-width: 0;
+  padding: 4px 6px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  color: var(--text);
+  font-size: 11px;
+}
+</style>
diff --git a/src/shell/components/ProviderSettingsPanel.vue b/src/shell/components/ProviderSettingsPanel.vue
new file mode 100644
index 0000000..f87193d
--- /dev/null
+++ b/src/shell/components/ProviderSettingsPanel.vue
@@ -0,0 +1,538 @@
+<script setup lang="ts">
+/**
+ * LLM Providers panel — CLI-only.
+ *
+ * Trimmed-down config surface for the four local-CLI providers Annotask
+ * drives (claude, codex, opencode, copilot). Everything HTTP-provider-
+ * specific (API keys, endpoint URLs, paperclip, …) is gone — those will
+ * come back behind an explicit "API" tab when the tool-write loop is wired
+ * for HTTP providers.
+ *
+ * What lives here:
+ *   - Active provider (compact dropdown, top-right, shows detection status)
+ *   - Global permission mode (per-provider override per CLI)
+ *   - Per-provider permission mode override + extra-args input
+ *   - Local-CLI status / billing note (claude-local)
+ *   - Guardrails (redaction + event log toggle, clear log)
+ *
+ * Moved elsewhere:
+ *   - Agent mode    → General tab (AgentModePanel.vue)
+ *   - Token usage   → Usage tab (UsagePanel.vue)
+ *   - Model + Effort → per-persona / per-task (AgentDirectionsPanel.vue,
+ *                     TaskDetailModal.vue chip)
+ */
+import { computed, ref, watch, onMounted } from 'vue'
+import Icon from './Icon.vue'
+import { useProviderSettings } from '../composables/useProviderSettings'
+import { fetchAgentDetect, useAgentDetect } from '../composables/useTaskThread'
+import { isActiveProviderReady } from '../../embedded/provider-config'
+import type { ProviderConfig, ProviderId } from '../../embedded/provider-config'
+import { PERMISSION_MODES, type PermissionMode } from '../../schema'
+import { NATIVE_PLAN_PROVIDERS } from '../../embedded/permission-mode'
+
+const store = useProviderSettings()
+const settings = store.settings
+const active = computed<ProviderId>(() => settings.value.activeProvider)
+
+const CLI_PROVIDER_IDS = ['claude-local', 'codex-local', 'opencode-local', 'copilot-local'] as const satisfies readonly ProviderId[]
+type CliProviderId = typeof CLI_PROVIDER_IDS[number]
+
+const providerMeta: Record<CliProviderId, { label: string; short: string; bin: string }> = {
+  'claude-local':   { label: 'Claude (local CLI)',   short: 'Claude',   bin: 'claude'   },
+  'codex-local':    { label: 'Codex (local CLI)',    short: 'Codex',    bin: 'codex'    },
+  'opencode-local': { label: 'opencode (local CLI)', short: 'opencode', bin: 'opencode' },
+  'copilot-local':  { label: 'Copilot (local CLI)',  short: 'Copilot',  bin: 'copilot'  },
+}
+
+// The provider picker (and its snap-to-CLI watch) lives in SettingsOverlay
+// now so the picker is shared between sub-tabs (Providers + Usage). This
+// panel just reads `active` from the store and renders its own content.
+
+// Local-CLI detection drives the readiness banner under the panel header
+// (the picker badge lives in the parent tab header).
+const detect = useAgentDetect()
+onMounted(() => { fetchAgentDetect() })
+
+// Mirror the detect snapshot into the provider-settings probe so the rest of
+// the app (Conversation tab, agent-mode auto-run gate, …) sees a consistent
+// "is this CLI ready" answer.
+watch(
+  () => detect.snapshot.value,
+  (snap) => {
+    if (!snap) return
+    store.setLocalCliProbe({
+      'claude-local':   !!(snap['claude-local'].found   && snap['claude-local'].loggedIn),
+      'codex-local':    !!(snap['codex-local'].found    && snap['codex-local'].loggedIn),
+      'opencode-local': !!(snap['opencode-local'].found && snap['opencode-local'].loggedIn),
+      'copilot-local':  !!(snap['copilot-local']?.found && snap['copilot-local']?.loggedIn),
+    })
+  },
+  { immediate: true },
+)
+
+const localReadiness = computed(() => {
+  const snap = detect.snapshot.value
+  return {
+    'claude-local':   !!(snap && snap['claude-local'].found   && snap['claude-local'].loggedIn),
+    'codex-local':    !!(snap && snap['codex-local'].found    && snap['codex-local'].loggedIn),
+    'opencode-local': !!(snap && snap['opencode-local'].found && snap['opencode-local'].loggedIn),
+    'copilot-local':  !!(snap && snap['copilot-local']?.found && snap['copilot-local']?.loggedIn),
+  }
+})
+const activeReady = computed(() => isActiveProviderReady(settings.value, localReadiness.value))
+
+function statusForCli(id: CliProviderId): 'ready' | 'unauth' | 'missing' | 'probing' {
+  const snap = detect.snapshot.value
+  if (!snap) return 'probing'
+  const s = snap[id]
+  if (!s || !s.found) return 'missing'
+  if (!s.loggedIn) return 'unauth'
+  return 'ready'
+}
+
+const activeStatus = computed(() => statusForCli(active.value as CliProviderId))
+const activeStatusTone = computed<'success' | 'warning' | 'danger' | 'muted'>(() => {
+  switch (activeStatus.value) {
+    case 'ready':   return 'success'
+    case 'unauth':  return 'warning'
+    case 'missing': return 'danger'
+    case 'probing': return 'muted'
+  }
+})
+
+// ── Per-provider permission mode + extra args ─────────────────────────────
+const providerPermissionMode = computed<string>(() => {
+  const cfg = settings.value.providers[active.value]
+  return (cfg as { permissionMode?: PermissionMode }).permissionMode ?? ''
+})
+function setProviderPermissionMode(value: string) {
+  if (value === '') {
+    store.setProviderPermissionMode(active.value, null)
+    return
+  }
+  if (!(PERMISSION_MODES as readonly string[]).includes(value)) return
+  store.setProviderPermissionMode(active.value, value as PermissionMode)
+}
+
+const extraArgsText = ref('')
+function syncExtraArgsFromStore() {
+  const cfg = settings.value.providers[active.value] as { extraArgs?: string[] }
+  extraArgsText.value = (cfg.extraArgs ?? []).join(' ')
+}
+watch(active, syncExtraArgsFromStore, { immediate: true })
+watch(() => settings.value.providers[active.value], syncExtraArgsFromStore, { deep: true })
+
+/**
+ * Split a CLI-args string into argv, honoring single/double quotes and
+ * backslash escapes so `--foo "bar baz"` becomes ['--foo', 'bar baz'] instead
+ * of the three broken fragments a naive whitespace split produced. Unbalanced
+ * quotes degrade gracefully (the open run becomes one token). Args go straight
+ * into spawn argv (shell:false), so there's no shell to re-interpret them.
+ */
+function tokenizeArgs(input: string): string[] {
+  const out: string[] = []
+  let cur = ''
+  let quote: '"' | "'" | null = null
+  let has = false
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]
+    if (quote) {
+      if (ch === '\\' && quote === '"' && i + 1 < input.length) { cur += input[++i]; continue }
+      if (ch === quote) { quote = null; continue }
+      cur += ch
+      continue
+    }
+    if (ch === '"' || ch === "'") { quote = ch; has = true; continue }
+    if (ch === '\\' && i + 1 < input.length) { cur += input[++i]; has = true; continue }
+    if (/\s/.test(ch)) {
+      if (has) { out.push(cur); cur = ''; has = false }
+      continue
+    }
+    cur += ch
+    has = true
+  }
+  if (has) out.push(cur)
+  return out.filter(s => s.length > 0)
+}
+
+function commitExtraArgs() {
+  const current = settings.value.providers[active.value]
+  store.setProviderConfig({ ...current, extraArgs: tokenizeArgs(extraArgsText.value) } as ProviderConfig)
+}
+
+// ── Global permission mode ────────────────────────────────────────────────
+
+const PERMISSION_MODE_HINTS: Record<PermissionMode, string> = {
+  default: 'Auto (recommended) — least-permissive mode that still applies tasks: codex runs in its --full-auto sandbox and copilot at minimal access; claude/opencode have no headless ask-mode, so this runs as bypass for them.',
+  plan: 'Read-only. Agent investigates but cannot write. Enforced via CLI/sandbox + model directive.',
+  bypass: 'Auto-approve everything, all sandboxes off (incl. shell + writes outside the repo). Fastest, riskiest — opt-in.',
+}
+
+const planModeHint = computed(() => {
+  if (settings.value.permissionMode !== 'plan') return PERMISSION_MODE_HINTS[settings.value.permissionMode]
+  if (NATIVE_PLAN_PROVIDERS.has(active.value)) {
+    return 'Read-only. Agent investigates but cannot write. Enforced via CLI/sandbox + model directive.'
+  }
+  return 'Read-only (best-effort). This provider lacks native plan enforcement — read-only is enforced via model directive only, not CLI/OS sandbox.'
+})
+function setGlobalPermissionMode(mode: PermissionMode) {
+  store.setPermissionMode(mode)
+}
+
+// ── Guardrails ────────────────────────────────────────────────────────────
+function onClearEventLog() {
+  store.eventLog.clear()
+}
+</script>
+
+<template>
+  <div class="ai-panel provider-panel">
+    <!-- Readiness banner — picker lives in the parent tab header now. -->
+    <div
+      class="ai-validation"
+      :class="`tone-${activeStatusTone}`"
+      data-testid="provider-readiness"
+    >
+      <Icon :name="activeReady ? 'check' : 'info'" :size="12" />
+      <span v-if="activeReady">
+        {{ providerMeta[active as CliProviderId].label }} is ready.
+      </span>
+      <span v-else-if="activeStatus === 'missing'">
+        <code>{{ providerMeta[active as CliProviderId].bin }}</code> is not on your PATH.
+        Install the CLI to use this provider.
+      </span>
+      <span v-else-if="activeStatus === 'unauth'">
+        Found <code>{{ providerMeta[active as CliProviderId].bin }}</code> but it's not
+        logged in. Run <code>{{ providerMeta[active as CliProviderId].bin }} login</code>
+        in a terminal.
+      </span>
+      <span v-else>Probing local CLI…</span>
+    </div>
+
+    <!-- Global permission mode. The floor for all providers. Per-provider
+         and per-task overrides win. -->
+    <section class="ai-section" aria-label="Permission mode">
+      <div class="ai-section-head">
+        <h3 class="ai-section-title">Permission mode</h3>
+        <p class="ai-section-desc">
+          Global default for how agents approve actions. The per-provider
+          dropdown below can override it for one CLI; the chip menu on each
+          task can override that.
+        </p>
+      </div>
+      <div class="agent-mode-strip" role="radiogroup" aria-label="Permission mode">
+        <button
+          v-for="m in PERMISSION_MODES"
+          :key="m"
+          type="button"
+          role="radio"
+          :aria-checked="settings.permissionMode === m"
+          :class="['agent-mode-btn', { active: settings.permissionMode === m }]"
+          :data-testid="`global-permission-mode-${m}`"
+          @click="setGlobalPermissionMode(m)"
+        >
+          {{ m }}
+        </button>
+      </div>
+      <p class="ai-hint">{{ planModeHint }}</p>
+    </section>
+
+    <!-- Per-provider settings — permission override + extra args. -->
+    <section class="ai-section" aria-label="Provider settings">
+      <div class="ai-section-head">
+        <h3 class="ai-section-title">{{ providerMeta[active as CliProviderId].short }} settings</h3>
+        <p class="ai-section-desc">
+          Overrides specific to this CLI. Model and effort live on each
+          persona — adjust them in the Agents tab.
+        </p>
+      </div>
+
+      <div class="ai-field">
+        <label class="ai-label" :for="`engine-perm-${active}`">Permission mode override</label>
+        <select
+          :id="`engine-perm-${active}`"
+          class="ai-input"
+          :value="providerPermissionMode"
+          data-testid="engine-permission-mode"
+          @change="setProviderPermissionMode(($event.target as HTMLSelectElement).value)"
+        >
+          <option value="">Inherit global ({{ settings.permissionMode }})</option>
+          <option v-for="m in PERMISSION_MODES" :key="m" :value="m">{{ m }}</option>
+        </select>
+        <p class="ai-hint">
+          Useful when one CLI sandboxes natively (codex) and another doesn't
+          (claude). Tasks can override this further via the chip menu.
+        </p>
+      </div>
+
+      <div class="ai-field">
+        <label class="ai-label" :for="`engine-extra-${active}`">Extra CLI args</label>
+        <input
+          :id="`engine-extra-${active}`"
+          type="text"
+          class="ai-input"
+          :value="extraArgsText"
+          :placeholder="`Appended to ${providerMeta[active as CliProviderId].bin} command`"
+          data-testid="engine-extra-args"
+          @input="extraArgsText = ($event.target as HTMLInputElement).value"
+          @change="commitExtraArgs"
+          @blur="commitExtraArgs"
+        />
+        <p class="ai-hint">
+          Space-separated; quote values with spaces (e.g. <code>--foo "bar baz"</code>).
+          Passed as-is after Annotask's canonical args.
+        </p>
+      </div>
+    </section>
+
+    <!-- Claude Code billing nuance — Pro/Max headless usage draws from the
+         Agent SDK credit pool starting 2026-06-15. Surface it here so users
+         on a paid Claude plan know what they're picking. -->
+    <section
+      v-if="active === 'claude-local'"
+      class="ai-section"
+      aria-label="Claude billing"
+    >
+      <div class="ai-validation tone-info" data-testid="claude-local-billing-note">
+        <Icon name="info" :size="12" />
+        <span>
+          On Pro/Max plans, Annotask's calls run via Claude Code's headless
+          mode and (from 2026-06-15) draw from your
+          <strong>Agent SDK credit pool</strong> — separate from your
+          interactive session limit.
+          <a
+            href="https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan"
+            target="_blank"
+            rel="noopener"
+          >Details</a>.
+        </span>
+      </div>
+    </section>
+
+    <!-- Guardrails: redaction + local event log. -->
+    <section class="ai-section" aria-label="Guardrails">
+      <div class="ai-section-head">
+        <h3 class="ai-section-title">Guardrails</h3>
+        <p class="ai-section-desc">
+          Defaults are on. The event log is local-only — nothing leaves your
+          browser.
+        </p>
+      </div>
+
+      <label class="ai-toggle">
+        <input
+          type="checkbox"
+          :checked="settings.redactionEnabled"
+          data-testid="redaction-enabled"
+          @change="store.setRedactionEnabled(($event.target as HTMLInputElement).checked)"
+        />
+        <span>Redact common secret patterns before sending to provider</span>
+      </label>
+
+      <label class="ai-toggle">
+        <input
+          type="checkbox"
+          :checked="settings.eventLogEnabled"
+          data-testid="event-log-enabled"
+          @change="store.setEventLogEnabled(($event.target as HTMLInputElement).checked)"
+        />
+        <span>Record local-only event log (provider, model, tokens, latency)</span>
+      </label>
+
+      <div class="ai-actions">
+        <button
+          type="button"
+          class="ai-btn ai-btn-ghost"
+          data-testid="clear-event-log"
+          @click="onClearEventLog"
+        >
+          Clear event log
+        </button>
+      </div>
+    </section>
+
+    <section class="ai-section" aria-label="Run safety">
+      <div class="ai-section-head">
+        <h3 class="ai-section-title">Run safety</h3>
+        <p class="ai-section-desc">
+          Stop a stuck agent from running forever. Set either to 0 to disable.
+        </p>
+      </div>
+
+      <div class="ai-field">
+        <label class="ai-label" for="idle-timeout">Idle timeout (seconds)</label>
+        <input
+          id="idle-timeout"
+          type="number"
+          min="0"
+          step="10"
+          class="ai-input"
+          data-testid="idle-timeout"
+          :value="Math.round(settings.idleTimeoutMs / 1000)"
+          @change="store.setIdleTimeoutMs(Number(($event.target as HTMLInputElement).value) * 1000)"
+        />
+        <p class="ai-hint">Cancel a run that produces no output for this long.</p>
+      </div>
+
+      <div class="ai-field">
+        <label class="ai-label" for="max-duration">Max run duration (minutes)</label>
+        <input
+          id="max-duration"
+          type="number"
+          min="0"
+          step="1"
+          class="ai-input"
+          data-testid="max-run-duration"
+          :value="Math.round(settings.maxRunDurationMs / 60000)"
+          @change="store.setMaxRunDurationMs(Number(($event.target as HTMLInputElement).value) * 60000)"
+        />
+        <p class="ai-hint">Absolute ceiling per run, regardless of activity.</p>
+      </div>
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.ai-panel.provider-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 22px;
+}
+
+/* ── Readiness banner ── */
+.ai-validation {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-radius: 6px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  font-size: 12px;
+  line-height: 1.45;
+  color: var(--text);
+}
+.ai-validation code {
+  font-size: 11px;
+  padding: 1px 5px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 3px;
+  font-variant-numeric: tabular-nums;
+}
+.ai-validation.tone-success { color: var(--success); border-color: color-mix(in srgb, var(--success) 40%, var(--border)); }
+.ai-validation.tone-warning { color: var(--warning); border-color: color-mix(in srgb, var(--warning) 40%, var(--border)); }
+.ai-validation.tone-danger  { color: var(--danger);  border-color: color-mix(in srgb, var(--danger)  40%, var(--border)); }
+.ai-validation.tone-info    { color: var(--info);    border-color: color-mix(in srgb, var(--info)    40%, var(--border)); }
+.ai-validation.tone-muted   { color: var(--text-muted); }
+
+/* ── Sections ── */
+.ai-section {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.ai-section-head {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.ai-section-title {
+  margin: 0;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--text);
+}
+.ai-section-desc {
+  margin: 0;
+  font-size: 11.5px;
+  color: var(--text-muted);
+  line-height: 1.5;
+}
+.ai-hint {
+  margin: 0;
+  font-size: 11px;
+  color: var(--text-muted);
+  line-height: 1.45;
+}
+
+/* ── Permission mode strip ── */
+.agent-mode-strip {
+  display: inline-flex;
+  gap: 2px;
+  padding: 3px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 7px;
+  align-self: flex-start;
+}
+.agent-mode-btn {
+  font: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  padding: 5px 16px;
+  border: none;
+  background: transparent;
+  color: var(--text-muted);
+  border-radius: 5px;
+  cursor: pointer;
+  text-transform: lowercase;
+}
+.agent-mode-btn:hover:not(.active):not(:disabled) { color: var(--text); }
+.agent-mode-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+.agent-mode-btn.active {
+  background: var(--surface);
+  color: var(--text);
+  box-shadow: 0 1px 3px var(--shadow);
+}
+
+/* ── Per-provider fields ── */
+.ai-field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.ai-label {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text);
+}
+.ai-input {
+  font: inherit;
+  font-size: 13px;
+  padding: 7px 10px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--surface-2);
+  color: var(--text);
+}
+.ai-input:focus { outline: none; border-color: var(--accent); }
+.ai-input:hover:not(:focus) { border-color: color-mix(in srgb, var(--accent) 40%, var(--border)); }
+
+/* ── Toggles + actions ── */
+.ai-toggle {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12.5px;
+  color: var(--text);
+  cursor: pointer;
+}
+.ai-actions {
+  display: flex;
+  gap: 8px;
+}
+.ai-btn {
+  font: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  padding: 6px 14px;
+  border-radius: 5px;
+  cursor: pointer;
+  border: 1px solid var(--border);
+  background: var(--surface-2);
+  color: var(--text);
+}
+.ai-btn:hover { border-color: var(--text-muted); }
+.ai-btn-ghost { background: transparent; }
+</style>
diff --git a/src/shell/components/ReportViewer.vue b/src/shell/components/ReportViewer.vue
index a56885c..74377e3 100644
--- a/src/shell/components/ReportViewer.vue
+++ b/src/shell/components/ReportViewer.vue
@@ -120,7 +120,7 @@ function onKeydown(e: KeyboardEvent) {
 .report-backdrop {
   position: absolute;
   inset: 0;
-  background: rgba(0, 0, 0, 0.4);
+  background: var(--overlay);
 }
 .report-drawer {
   position: relative;
diff --git a/src/shell/components/SettingsOverlay.vue b/src/shell/components/SettingsOverlay.vue
index 4a6e760..954ebcb 100644
--- a/src/shell/components/SettingsOverlay.vue
+++ b/src/shell/components/SettingsOverlay.vue
@@ -1,45 +1,243 @@
 <template>
   <div class="fullscreen-overlay settings-overlay">
     <FullscreenOverlayHeader title="Settings" @close="$emit('close')" />
-    <div class="settings-content">
-      <div class="settings-page">
-        <h2 class="settings-page-title">Appearance</h2>
-
-        <div class="settings-section">
-          <label class="settings-label">Theme</label>
-          <p class="settings-desc">Pick a shell theme that contrasts with your app.</p>
-
-          <label class="settings-system-toggle">
-            <input type="checkbox" :checked="shellTheme.activeThemeId.value === 'system'"
-              @change="onSystemToggle(($event.target as HTMLInputElement).checked)" />
-            <span>Use system preference</span>
-          </label>
-
-          <template v-for="group in themeGroups" :key="group.key">
-            <template v-if="themesInGroup(group.key).length">
-              <div class="settings-group-label">{{ group.label }}</div>
-              <div class="settings-theme-grid">
-                <button
-                  v-for="t in themesInGroup(group.key)"
-                  :key="t.id"
-                  :class="['settings-theme-card', { active: isActiveTheme(t.id) }]"
-                  @click="shellTheme.setTheme(t.id)"
-                  :title="t.description"
+    <div class="settings-layout">
+      <nav class="settings-sidebar" aria-label="Settings sections">
+        <button
+          v-for="t in tabs"
+          :key="t.id"
+          type="button"
+          class="settings-nav-btn"
+          :class="{ active: activeTab === t.id }"
+          :aria-current="activeTab === t.id ? 'page' : undefined"
+          :data-testid="`settings-tab-${t.id}`"
+          @click="activeTab = t.id"
+        >
+          <Icon :name="t.icon" :size="14" />
+          <span>{{ t.label }}</span>
+        </button>
+      </nav>
+
+      <div class="settings-content">
+        <!-- Agents tab — task-type-routed personas (provider/model/effort overrides). -->
+        <section v-if="activeTab === 'agents'" class="settings-page settings-page--wide" aria-label="Agent personas">
+          <h2 class="settings-page-title">Agents</h2>
+          <AgentsPanel />
+        </section>
+
+        <!-- LLM Providers tab — provider config + usage metrics as sub-views.
+             The provider picker is lifted here so both sub-tabs share it:
+             Usage filters its metrics to the selected provider. -->
+        <section v-else-if="activeTab === 'providers'" class="settings-page settings-page--wide" aria-label="LLM providers">
+          <div class="settings-page-header">
+            <div class="settings-page-header-text">
+              <h2 class="settings-page-title">LLM Providers</h2>
+              <p class="settings-page-lead">
+                Configure the CLIs Annotask can call and track cumulative
+                token usage. Per-persona overrides live in the Agents tab.
+              </p>
+            </div>
+            <label class="provider-picker">
+              <span class="provider-picker-label">Provider</span>
+              <select
+                class="provider-picker-select"
+                :value="providerSettings.activeProvider.value"
+                data-testid="provider-select"
+                @change="providerSettings.setActiveProvider(($event.target as HTMLSelectElement).value as ProviderId)"
+              >
+                <option
+                  v-for="id in CLI_PROVIDER_IDS"
+                  :key="id"
+                  :value="id"
                 >
-                  <div class="theme-card-swatches">
-                    <span class="theme-swatch" :style="{ background: t.colors.bg }" />
-                    <span class="theme-swatch" :style="{ background: t.colors.surface }" />
-                    <span class="theme-swatch" :style="{ background: t.colors.accent }" />
-                    <span class="theme-swatch" :style="{ background: t.colors.danger }" />
-                    <span class="theme-swatch" :style="{ background: t.colors.text }" />
-                  </div>
-                  <span class="theme-card-name">{{ t.name }}</span>
-                </button>
+                  {{ providerMeta[id].short }} · {{ STATUS_LABEL[statusForCli(id)] }}
+                </option>
+              </select>
+            </label>
+          </div>
+
+          <nav class="settings-subtabs" role="tablist" aria-label="LLM Providers sub-views">
+            <button
+              type="button"
+              role="tab"
+              :aria-selected="providersSubTab === 'config'"
+              :class="['settings-subtab', { active: providersSubTab === 'config' }]"
+              data-testid="providers-subtab-config"
+              @click="providersSubTab = 'config'"
+            >
+              Configuration
+            </button>
+            <button
+              type="button"
+              role="tab"
+              :aria-selected="providersSubTab === 'usage'"
+              :class="['settings-subtab', { active: providersSubTab === 'usage' }]"
+              data-testid="providers-subtab-usage"
+              @click="providersSubTab = 'usage'"
+            >
+              Usage
+            </button>
+          </nav>
+
+          <ProviderSettingsPanel v-if="providersSubTab === 'config'" />
+          <UsagePanel v-else :provider-id="providerSettings.activeProvider.value" />
+        </section>
+
+        <!-- General tab — agent mode + project setup. -->
+        <section v-else-if="activeTab === 'general'" class="settings-page" aria-label="General settings">
+          <h2 class="settings-page-title">General</h2>
+          <p class="settings-page-lead">
+            Agent behavior, project setup, and the design-spec status. LLM
+            provider configuration lives in LLM Providers; token usage lives
+            in Usage.
+          </p>
+
+          <!-- Top-level embedded-agent toggle. When off, the user is in
+               skill/MCP mode — Conversation tab, auto-run, and the per-task
+               agent UI are all hidden. The MCP server keeps running so the
+               user's own editor agent can still call /annotask-apply. -->
+          <div class="settings-section">
+            <label class="settings-label">Embedded agent</label>
+            <p class="settings-desc">
+              Run a local CLI agent (claude · codex · opencode · copilot) inside
+              Annotask. When off, you stay in skill/MCP mode and drive apply
+              from your own editor agent.
+            </p>
+            <div class="embedded-toggle-row">
+              <label class="embedded-toggle">
+                <input
+                  type="checkbox"
+                  :checked="embeddedAgentOn"
+                  @change="onEmbeddedAgentToggle(($event.target as HTMLInputElement).checked)"
+                />
+                <span class="embedded-toggle-track" aria-hidden="true">
+                  <span class="embedded-toggle-thumb" />
+                </span>
+                <span class="embedded-toggle-text">
+                  {{ embeddedAgentOn ? 'Embedded agent on' : 'Skill / MCP mode' }}
+                </span>
+              </label>
+              <span class="embedded-toggle-badge">Experimental</span>
+            </div>
+
+            <div v-if="!embeddedAgentOn" class="skill-mode-banner">
+              <strong>You're in skill / MCP mode.</strong>
+              Open your editor agent (Claude Code, Cursor, Windsurf, …) and run
+              <code>/annotask-init</code> to scan this project, then
+              <code>/annotask-apply</code> for pending tasks. Or call the MCP
+              server directly at
+              <code>http://localhost:5173/__annotask/mcp</code>.
+            </div>
+          </div>
+
+          <!-- Agent mode — sub-control: how aggressively the embedded agent runs.
+               Disabled when the top-level toggle above is off. -->
+          <div
+            class="settings-section"
+            :class="{ 'settings-section--disabled': !embeddedAgentOn }"
+            :aria-disabled="!embeddedAgentOn"
+          >
+            <label class="settings-label">Agent mode</label>
+            <p v-if="!embeddedAgentOn" class="settings-desc">
+              Enable the embedded agent above to change how it runs.
+            </p>
+            <AgentModePanel />
+          </div>
+
+          <!-- Current spec summary -->
+          <div class="settings-section">
+            <label class="settings-label">Design spec status</label>
+            <div v-if="specInitialized" class="proj-spec-summary">
+              <div class="proj-spec-row">
+                <span class="proj-spec-key">Framework</span>
+                <span class="proj-spec-val">{{ specFramework }}</span>
+              </div>
+              <div class="proj-spec-row">
+                <span class="proj-spec-key">Themes</span>
+                <span class="proj-spec-val">{{ specThemes }}</span>
+              </div>
+              <div class="proj-spec-row">
+                <span class="proj-spec-key">Colors</span>
+                <span class="proj-spec-val">{{ specColorCount }} token{{ specColorCount === 1 ? '' : 's' }}</span>
+              </div>
+              <div class="proj-spec-row">
+                <span class="proj-spec-key">Typography</span>
+                <span class="proj-spec-val">{{ specTypoCount }} entries</span>
               </div>
+              <div v-if="specComponents" class="proj-spec-row">
+                <span class="proj-spec-key">Components</span>
+                <span class="proj-spec-val">{{ specComponents }}</span>
+              </div>
+            </div>
+            <p v-else class="settings-desc" style="color: var(--warning)">
+              Project not initialized — open the init wizard to set up the design spec.
+            </p>
+          </div>
+
+          <!-- Actions -->
+          <div class="settings-section">
+            <label class="settings-label">Setup wizard</label>
+            <template v-if="specInitialized">
+              <p class="settings-desc">
+                Re-run the full setup wizard. Each scan is optional — pick what
+                you want to refresh, or skip straight to Review to edit the
+                current tokens, style guide, and agent directions in place.
+              </p>
+              <button class="proj-reinit-btn" @click="openReinit">
+                Re-init
+              </button>
+            </template>
+            <template v-else>
+              <p class="settings-desc">
+                Run the setup wizard to scan your project and configure Annotask.
+              </p>
+              <button class="proj-reinit-btn" @click="openReinit">
+                Open setup wizard
+              </button>
             </template>
-          </template>
-          <button class="settings-create-btn" @click="$emit('update:showThemeEditor', true)">+ Create Custom Theme</button>
-        </div>
+          </div>
+        </section>
+
+        <!-- Appearance tab — preserved verbatim. -->
+        <section v-else class="settings-page" aria-label="Appearance settings">
+          <h2 class="settings-page-title">Appearance</h2>
+
+          <div class="settings-section">
+            <label class="settings-label">Theme</label>
+            <p class="settings-desc">Pick a shell theme that contrasts with your app.</p>
+
+            <label class="settings-system-toggle">
+              <input type="checkbox" :checked="shellTheme.activeThemeId.value === 'system'"
+                @change="onSystemToggle(($event.target as HTMLInputElement).checked)" />
+              <span>Use system preference</span>
+            </label>
+
+            <template v-for="group in themeGroups" :key="group.key">
+              <template v-if="themesInGroup(group.key).length">
+                <div class="settings-group-label">{{ group.label }}</div>
+                <div class="settings-theme-grid">
+                  <button
+                    v-for="t in themesInGroup(group.key)"
+                    :key="t.id"
+                    :class="['settings-theme-card', { active: isActiveTheme(t.id) }]"
+                    @click="shellTheme.setTheme(t.id)"
+                    :title="t.description"
+                  >
+                    <div class="theme-card-swatches">
+                      <span class="theme-swatch" :style="{ background: t.colors.bg }" />
+                      <span class="theme-swatch" :style="{ background: t.colors.surface }" />
+                      <span class="theme-swatch" :style="{ background: t.colors.accent }" />
+                      <span class="theme-swatch" :style="{ background: t.colors.danger }" />
+                      <span class="theme-swatch" :style="{ background: t.colors.text }" />
+                    </div>
+                    <span class="theme-card-name">{{ t.name }}</span>
+                  </button>
+                </div>
+              </template>
+            </template>
+            <button class="settings-create-btn" @click="$emit('update:showThemeEditor', true)">+ Create Custom Theme</button>
+          </div>
+        </section>
       </div>
     </div>
     <ShellThemeEditor v-if="showThemeEditor" @close="$emit('update:showThemeEditor', false)" />
@@ -47,9 +245,71 @@
 </template>
 
 <script setup lang="ts">
+import { ref, computed, watch, onMounted } from 'vue'
 import FullscreenOverlayHeader from './FullscreenOverlayHeader.vue'
 import ShellThemeEditor from './ShellThemeEditor.vue'
+import AgentsPanel from './AgentsPanel.vue'
+import { useDesignSpec } from '../composables/useDesignSpec'
+import { useInitFlow } from '../composables/useInitFlow'
+import { useProviderSettings } from '../composables/useProviderSettings'
+import { fetchAgentDetect, useAgentDetect } from '../composables/useTaskThread'
+import Icon, { type IconName } from './Icon.vue'
 import type { useShellTheme } from '../composables/useShellTheme'
+import ProviderSettingsPanel from './ProviderSettingsPanel.vue'
+import AgentModePanel from './AgentModePanel.vue'
+import UsagePanel from './UsagePanel.vue'
+import type { ProviderId } from '../../embedded/provider-config'
+
+type TabId = 'general' | 'providers' | 'agents' | 'appearance'
+type ProvidersSubTab = 'config' | 'usage'
+
+// ── LLM Providers tab: shared provider picker (lives in the tab header so
+// both sub-tabs see the same active provider) ─────────────────────────────
+const providerSettings = useProviderSettings()
+const detect = useAgentDetect()
+
+const CLI_PROVIDER_IDS = ['claude-local', 'codex-local', 'opencode-local', 'copilot-local'] as const satisfies readonly ProviderId[]
+type CliProviderId = typeof CLI_PROVIDER_IDS[number]
+
+const providerMeta: Record<CliProviderId, { short: string }> = {
+  'claude-local':   { short: 'Claude'   },
+  'codex-local':    { short: 'Codex'    },
+  'opencode-local': { short: 'opencode' },
+  'copilot-local':  { short: 'Copilot'  },
+}
+
+const STATUS_LABEL = {
+  ready: 'Ready',
+  unauth: 'Not logged in',
+  missing: 'Not installed',
+  probing: 'Probing…',
+} as const
+
+function statusForCli(id: CliProviderId): keyof typeof STATUS_LABEL {
+  const snap = detect.snapshot.value
+  if (!snap) return 'probing'
+  const s = snap[id]
+  if (!s || !s.found) return 'missing'
+  if (!s.loggedIn) return 'unauth'
+  return 'ready'
+}
+
+// Detection drives the picker badges and the readiness banner in the
+// Providers sub-tab. Fetch once when settings opens.
+onMounted(() => { fetchAgentDetect() })
+
+// Snap active provider to a local CLI if the user landed here with a stale
+// HTTP provider stored as active (pre-CLI-only change). Fires before either
+// sub-tab renders so Usage's `byProvider[active]` lookup always hits a CLI.
+watch(
+  () => providerSettings.activeProvider.value,
+  (id) => {
+    if (!(CLI_PROVIDER_IDS as readonly ProviderId[]).includes(id)) {
+      providerSettings.setActiveProvider('claude-local')
+    }
+  },
+  { immediate: true },
+)
 
 interface Props {
   shellTheme: ReturnType<typeof useShellTheme>
@@ -57,11 +317,83 @@ interface Props {
 }
 
 const props = defineProps<Props>()
-defineEmits<{
+const emit = defineEmits<{
   (e: 'close'): void
   (e: 'update:showThemeEditor', value: boolean): void
 }>()
 
+const tabs: Array<{ id: TabId; label: string; icon: IconName }> = [
+  { id: 'general',    label: 'General',       icon: 'settings' },
+  { id: 'providers',  label: 'LLM Providers', icon: 'sliders-horizontal' },
+  { id: 'agents',     label: 'Agents',        icon: 'bot' },
+  { id: 'appearance', label: 'Appearance',    icon: 'palette' },
+]
+
+// LLM Providers has two sub-views: provider config (the panel) and usage
+// (cumulative token metrics). Defaults to config when first opening the tab.
+const providersSubTab = ref<ProvidersSubTab>('config')
+
+// ── Project tab ──────────────────────────────────────────
+const { designSpec, isInitialized: specInitialized } = useDesignSpec()
+const initFlow = useInitFlow()
+
+const specFramework = computed(() => {
+  const fw = designSpec.value?.framework
+  if (!fw) return '—'
+  return [fw.name, fw.version].filter(Boolean).join(' ') + (fw.styling?.length ? ` (${fw.styling.join(', ')})` : '')
+})
+
+const specThemes = computed(() => {
+  const themes = designSpec.value?.themes
+  if (!themes?.length) return '—'
+  return themes.map((t: any) => t.name || t.id).join(', ')
+})
+
+const specColorCount = computed(() => designSpec.value?.colors?.length ?? 0)
+
+const specTypoCount = computed(() => {
+  const t = designSpec.value?.typography
+  return (t?.families?.length ?? 0) + (t?.scale?.length ?? 0)
+})
+
+const specComponents = computed(() => {
+  const c = designSpec.value?.components
+  if (!c?.library) return null
+  return [c.library, c.version].filter(Boolean).join(' ')
+})
+
+function openReinit() {
+  emit('close')
+  // Re-init runs the full init flow (agent → scan → review → save). The
+  // `rescan: true` flag is what marks individual scans as opt-in/skippable.
+  if (specInitialized.value) {
+    initFlow.openWizard('agent', { rescan: true })
+  } else {
+    initFlow.openWizard('agent')
+  }
+}
+
+// True when the embedded-agent feature is on. Treats the first-run `null`
+// (user hasn't decided yet) the same as off — until they pick, no embedded
+// surface should claim to be enabled.
+const embeddedAgentOn = computed(() =>
+  providerSettings.settings.value.embeddedAgentEnabled === true,
+)
+
+function onEmbeddedAgentToggle(on: boolean) {
+  providerSettings.setEmbeddedAgentEnabled(on)
+  // Flipping on from off → drop the user into the provider-setup step so
+  // they can actually pick a CLI before the embedded UI starts spawning
+  // anything. (No-op when the project is already initialized — they can
+  // still re-open from Setup wizard below if they want a re-scan.)
+  if (on && !specInitialized.value) {
+    emit('close')
+    initFlow.openWizard('agent')
+  }
+}
+
+const activeTab = ref<TabId>('general')
+
 const themeGroups = [
   { key: 'default', label: 'Default' },
   { key: 'high-contrast', label: 'High Contrast' },
@@ -86,3 +418,296 @@ function onSystemToggle(useSystem: boolean) {
   st.setTheme(useSystem ? 'system' : st.resolvedTheme.value.id)
 }
 </script>
+
+<style scoped>
+/* Agents tab needs more horizontal room for the persona table than the
+   default 560px settings-page width. */
+.settings-page.settings-page--wide {
+  max-width: 960px;
+}
+
+/* ── Embedded-agent toggle (General tab) ── */
+.embedded-toggle-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-top: 8px;
+}
+.embedded-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  cursor: pointer;
+  user-select: none;
+}
+.embedded-toggle input { position: absolute; opacity: 0; pointer-events: none; }
+.embedded-toggle-track {
+  width: 34px;
+  height: 20px;
+  border-radius: 999px;
+  background: var(--surface-3);
+  border: 1px solid var(--border);
+  position: relative;
+  transition: background 120ms ease, border-color 120ms ease;
+}
+.embedded-toggle-thumb {
+  position: absolute;
+  top: 1px;
+  left: 1px;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  background: var(--text-muted);
+  transition: transform 120ms ease, background 120ms ease;
+}
+.embedded-toggle input:checked + .embedded-toggle-track {
+  background: color-mix(in srgb, var(--accent) 30%, var(--surface-3));
+  border-color: var(--accent);
+}
+.embedded-toggle input:checked + .embedded-toggle-track .embedded-toggle-thumb {
+  transform: translateX(14px);
+  background: var(--accent);
+}
+.embedded-toggle input:focus-visible + .embedded-toggle-track {
+  box-shadow: 0 0 0 2px var(--focus-ring);
+}
+.embedded-toggle-text { font-size: 12px; font-weight: 600; color: var(--text); }
+.embedded-toggle-badge {
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  padding: 2px 6px;
+  border-radius: 4px;
+  background: color-mix(in srgb, var(--warning) 18%, transparent);
+  color: var(--warning);
+}
+.skill-mode-banner {
+  margin-top: 10px;
+  padding: 10px 12px;
+  background: color-mix(in srgb, var(--info) 8%, var(--surface-2));
+  border: 1px solid color-mix(in srgb, var(--info) 30%, var(--border));
+  border-radius: 6px;
+  font-size: 12px;
+  color: var(--text);
+  line-height: 1.55;
+}
+.skill-mode-banner code {
+  background: var(--surface-3);
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-size: 11px;
+}
+.settings-section--disabled {
+  opacity: 0.55;
+  pointer-events: none;
+}
+/* Re-enable the heading + helper text inside a disabled section so the user
+   can still read what's gated. Only the interactive children are dimmed. */
+.settings-section--disabled .settings-label,
+.settings-section--disabled .settings-desc {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+/* ── Project tab ── */
+.proj-spec-summary {
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  overflow: hidden;
+  margin-top: 8px;
+}
+.proj-spec-row {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--border);
+  font-size: 12px;
+}
+.proj-spec-row:last-child { border-bottom: none; }
+.proj-spec-key {
+  width: 90px;
+  flex-shrink: 0;
+  font-weight: 600;
+  color: var(--text-muted);
+  font-size: 11px;
+}
+.proj-spec-val {
+  color: var(--text);
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, monospace);
+  font-size: 11.5px;
+}
+
+.proj-reinit-btn {
+  margin-top: 8px;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  padding: 9px 18px;
+  border-radius: 6px;
+  background: var(--accent);
+  color: var(--text-on-accent);
+  border: none;
+  cursor: pointer;
+  transition: background 120ms;
+}
+.proj-reinit-btn:hover { background: var(--accent-hover); }
+
+.settings-layout {
+  flex: 1;
+  display: flex;
+  min-height: 0;
+}
+
+.settings-sidebar {
+  width: 200px;
+  flex-shrink: 0;
+  border-right: 1px solid var(--border);
+  padding: 12px 8px;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.settings-nav-btn {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  background: none;
+  border: none;
+  border-radius: 6px;
+  cursor: pointer;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 500;
+  color: var(--text);
+  text-align: left;
+  width: 100%;
+  transition: background 120ms ease, color 120ms ease;
+}
+
+.settings-nav-btn:hover { background: var(--surface-2); }
+.settings-nav-btn:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 1px;
+}
+.settings-nav-btn.active {
+  background: var(--accent-muted);
+  color: var(--text);
+  font-weight: 600;
+}
+.settings-nav-btn.active :deep(svg) { color: var(--accent); }
+
+.settings-page-lead {
+  font-size: 12px;
+  color: var(--text-muted);
+  line-height: 1.55;
+  margin: -10px 0 24px;
+  max-width: 560px;
+}
+.settings-page-lead strong { color: var(--text); font-weight: 600; }
+
+/* ── LLM Providers tab header (title left, provider picker right) ── */
+.settings-page-header {
+  display: flex;
+  align-items: flex-end;
+  justify-content: space-between;
+  gap: 16px;
+  margin-bottom: 16px;
+}
+.settings-page-header .settings-page-title { margin-bottom: 0; }
+.settings-page-header-text {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  flex: 1;
+  min-width: 0;
+}
+.settings-page-header-text .settings-page-lead { margin: 0; }
+
+.provider-picker {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  flex-shrink: 0;
+  min-width: 240px;
+}
+.provider-picker-label {
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--text-muted);
+}
+.provider-picker-select {
+  font: inherit;
+  font-size: 13px;
+  padding: 7px 10px;
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  background: var(--surface-2);
+  color: var(--text);
+}
+.provider-picker-select:focus { outline: none; border-color: var(--accent); }
+.provider-picker-select:hover { border-color: color-mix(in srgb, var(--accent) 50%, var(--border)); }
+
+/* ── Sub-tabs (LLM Providers: Providers | Usage) ──
+ * Classic page-tab treatment: horizontal labels with a colored underline
+ * under the active one, sharing a bottom border with the whole strip.
+ * Distinct from the segmented "toggle" pill used for Agent mode and the
+ * permission chip — those convey "pick one of N modes"; these convey
+ * "switch between sub-pages of the same screen." */
+.settings-subtabs {
+  display: flex;
+  gap: 4px;
+  margin: 0 0 20px;
+  border-bottom: 1px solid var(--border);
+}
+.settings-subtab {
+  position: relative;
+  font: inherit;
+  font-size: 13px;
+  font-weight: 500;
+  padding: 9px 14px 10px;
+  border: none;
+  background: transparent;
+  color: var(--text-muted);
+  cursor: pointer;
+  /* Reserve the underline thickness so hover/focus don't reflow neighbors. */
+  margin-bottom: -1px;
+  border-bottom: 2px solid transparent;
+  transition: color 120ms ease, border-color 120ms ease;
+}
+.settings-subtab:hover:not(.active) { color: var(--text); }
+.settings-subtab:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: -2px;
+  border-radius: 3px 3px 0 0;
+}
+.settings-subtab.active {
+  color: var(--text);
+  font-weight: 600;
+  border-bottom-color: var(--accent);
+}
+
+@media (max-width: 640px) {
+  .settings-layout { flex-direction: column; }
+  .settings-sidebar {
+    width: auto;
+    flex-direction: row;
+    border-right: none;
+    border-bottom: 1px solid var(--border);
+    overflow-x: auto;
+    padding: 6px 10px;
+    gap: 4px;
+  }
+  .settings-nav-btn {
+    flex: 0 0 auto;
+    width: auto;
+    padding: 6px 12px;
+    white-space: nowrap;
+  }
+}
+</style>
diff --git a/src/shell/components/ShellThemeEditor.vue b/src/shell/components/ShellThemeEditor.vue
index d4310c8..667540e 100644
--- a/src/shell/components/ShellThemeEditor.vue
+++ b/src/shell/components/ShellThemeEditor.vue
@@ -89,7 +89,7 @@ const COLOR_GROUPS = [
   { label: 'Palette', keys: ['purple', 'orange', 'cyan', 'indigo'] },
   { label: 'Status', keys: ['status-pending', 'status-in-progress', 'status-review', 'status-denied', 'status-accepted', 'status-needs-info', 'status-blocked'] },
   { label: 'Severity', keys: ['severity-critical', 'severity-serious', 'severity-moderate', 'severity-minor'] },
-  { label: 'Modes', keys: ['mode-interact', 'mode-arrow', 'mode-draw', 'mode-highlight'] },
+  { label: 'Modes', keys: ['mode-interact', 'mode-arrow', 'mode-highlight'] },
   { label: 'Layout', keys: ['layout-flex', 'layout-grid'] },
   { label: 'Roles', keys: ['role-container', 'role-content', 'role-component'] },
   { label: 'Syntax', keys: ['syntax-property', 'syntax-string', 'syntax-number', 'syntax-boolean', 'syntax-null', 'syntax-operator', 'syntax-punctuation'] },
diff --git a/src/shell/components/SpacingControls.vue b/src/shell/components/SpacingControls.vue
index ddb9ad2..a9fbcee 100644
--- a/src/shell/components/SpacingControls.vue
+++ b/src/shell/components/SpacingControls.vue
@@ -66,16 +66,16 @@ const margin = computed(() => parseSides(props.computedStyles['margin'] || '0'))
 
 .margin-box {
   padding: 20px 28px;
-  background: rgba(249, 115, 22, 0.08);
-  border: 1px dashed rgba(249, 115, 22, 0.3);
+  background: color-mix(in srgb, var(--orange) 8%, transparent);
+  border: 1px dashed color-mix(in srgb, var(--orange) 30%, transparent);
   border-radius: 6px;
   min-width: 220px;
 }
 
 .padding-box {
   padding: 18px 24px;
-  background: rgba(34, 197, 94, 0.08);
-  border: 1px dashed rgba(34, 197, 94, 0.3);
+  background: color-mix(in srgb, var(--success) 8%, transparent);
+  border: 1px dashed color-mix(in srgb, var(--success) 30%, transparent);
   border-radius: 4px;
   width: 100%;
 }
@@ -84,7 +84,7 @@ const margin = computed(() => parseSides(props.computedStyles['margin'] || '0'))
   padding: 8px 12px;
   background: var(--accent);
   border-radius: 3px;
-  color: white;
+  color: var(--text-on-accent);
   font-size: 10px;
   font-weight: 600;
   text-align: center;
@@ -99,8 +99,8 @@ const margin = computed(() => parseSides(props.computedStyles['margin'] || '0'))
   opacity: 0.6;
 }
 
-.margin-label { top: 3px; left: 6px; color: #f97316; }
-.padding-label { top: 2px; left: 5px; color: #22c55e; }
+.margin-label { top: 3px; left: 6px; color: var(--orange); }
+.padding-label { top: 2px; left: 5px; color: var(--success); }
 
 .side-input {
   position: absolute;
diff --git a/src/shell/components/TaskCard.vue b/src/shell/components/TaskCard.vue
index 02fe595..e21679a 100644
--- a/src/shell/components/TaskCard.vue
+++ b/src/shell/components/TaskCard.vue
@@ -2,7 +2,7 @@
   <div class="task-card" :class="task.status" :data-testid="'task-card'" :data-task-id="task.id" :data-task-type="task.type" :data-task-status="task.status" @click="$emit('open-detail', task.id)">
     <div v-if="task.resolution" class="task-card-resolution">{{ task.resolution }}</div>
     <div class="task-card-header">
-      <span class="task-status-dot" :class="task.status" />
+      <span class="task-status-dot" :class="[task.status, { 'active-run': isActiveRun }]" />
       <span class="task-card-desc task-card-md" v-html="safeMd(task.description)"></span>
       <button data-testid="btn-delete-task" class="task-card-close" @click.stop="$emit('confirm-delete', task.id)" title="Delete task">×</button>
     </div>
@@ -65,12 +65,21 @@
 </template>
 
 <script setup lang="ts">
+import { computed } from 'vue'
 import TaskOptionsToggles from './TaskOptionsToggles.vue'
 import ScreenshotUploader from './ScreenshotUploader.vue'
 import { safeMd } from '../utils/safeMd'
+import { useAgentMode } from '../composables/useAgentMode'
 import type { AnnotaskTask } from '../../schema'
 import type { DataContextProbeResult } from '../services/dataContextClient'
 
+// Live-activity indicator. The embedded agent records its in-flight task
+// ids in useAgentMode().activeRuns; we read that here to pulse the status
+// dot independently of the task's persisted `status` field. Chat-only
+// flows never flip `task.status` to in_progress, but the dot should still
+// signal "the agent is working."
+const { activeRuns } = useAgentMode()
+
 interface Props {
   task: AnnotaskTask
   isDenying: boolean
@@ -82,7 +91,8 @@ interface Props {
   dataContextProbe: DataContextProbeResult | null
 }
 
-defineProps<Props>()
+const props = defineProps<Props>()
+const isActiveRun = computed(() => activeRuns.value.has(props.task.id))
 defineEmits<{
   (e: 'open-detail', id: string): void
   (e: 'confirm-delete', id: string): void
diff --git a/src/shell/components/TaskDetailModal.vue b/src/shell/components/TaskDetailModal.vue
index 5f26038..31f454c 100644
--- a/src/shell/components/TaskDetailModal.vue
+++ b/src/shell/components/TaskDetailModal.vue
@@ -6,10 +6,16 @@ import ConfirmDialog from './ConfirmDialog.vue'
 import TaskAgentFeedback from './TaskAgentFeedback.vue'
 import TaskInteractionHistory from './TaskInteractionHistory.vue'
 import TaskJsonView from './TaskJsonView.vue'
+import ConversationTab from './ConversationTab.vue'
 import Icon from './Icon.vue'
+import { useProviderSettings } from '../composables/useProviderSettings'
+import { requestAutoRun } from '../composables/useAgentMode'
+import { PERMISSION_MODES, type PermissionMode } from '../../schema'
 
 const props = defineProps<{
   task: Task
+  /** Optional initial tab. Used by agent-mode auto-run to land on Conversation. */
+  initialTab?: 'details' | 'conversation'
 }>()
 
 const emit = defineEmits<{
@@ -19,8 +25,91 @@ const emit = defineEmits<{
   delete: [id: string]
   update: [id: string, fields: Record<string, unknown>]
   reply: [id: string, answers: Array<{ id: string; value: string }>]
+  'open-settings': []
 }>()
 
+type ModalTab = 'details' | 'conversation'
+const activeTab = ref<ModalTab>(props.initialTab ?? 'details')
+
+// Honour late-arriving initialTab changes — App.vue may set it after the
+// modal mounts (e.g. agent-mode auto-run on a task that was already opened).
+// Only react to *upgrades* to 'conversation'. The auto-run queue drains
+// to empty as soon as ConversationTab consumes its entry, which would
+// otherwise flip the prop back to 'details' and reset state the user just
+// chose via the Run-with-agent button or the tab strip.
+watch(
+  () => props.initialTab,
+  (next) => { if (next === 'conversation') activeTab.value = next },
+)
+
+// Agent-mode gating: 'off' hides the Conversation tab entirely and steers
+// the user to the terminal flow (/annotask-apply, MCP). 'manual' shows the
+// tab but the agent only runs when the user clicks Run-with-agent. 'auto'
+// fires on task creation (handled in useTaskWorkflows).
+const providerSettings = useProviderSettings()
+const agentMode = computed(() => providerSettings.settings.value.agentMode)
+const agentReady = computed(() => providerSettings.ready.value)
+// Embedded UI is gated on two things now: the top-level feature toggle
+// (`embeddedAgentEnabled`) and the per-task aggressiveness (`agentMode`).
+// When the user is in skill/MCP mode (`embeddedAgentEnabled !== true`) the
+// Conversation tab and Run-with-agent button never appear, regardless of
+// what `agentMode` is set to.
+const embeddedAgentEnabled = computed(
+  () => providerSettings.settings.value.embeddedAgentEnabled === true,
+)
+const showConversationTab = computed(
+  () => embeddedAgentEnabled.value && agentMode.value !== 'off',
+)
+
+const canManualRun = computed(() =>
+  embeddedAgentEnabled.value
+  && agentMode.value === 'manual'
+  && agentReady.value
+  && (props.task.status === 'pending' || props.task.status === 'denied' || props.task.status === 'needs_info'),
+)
+
+function runWithAgent() {
+  requestAutoRun(props.task.id, 'manual')
+  activeTab.value = 'conversation'
+}
+
+// ── Per-task permission mode override ──
+// Resolved at run time as `task ?? global`. Showing "Inherit" as the default
+// keeps the override sparse — only set on tasks the user wants to treat
+// differently from their global default.
+const PERMISSION_MODE_OPTIONS: ReadonlyArray<{ id: PermissionMode; label: string }> = [
+  { id: 'default', label: 'Default — ask for non-trivial actions' },
+  { id: 'plan',    label: 'Plan — read-only' },
+  { id: 'bypass',  label: 'Bypass — auto-approve everything' },
+]
+if (PERMISSION_MODE_OPTIONS.length !== PERMISSION_MODES.length) {
+  // eslint-disable-next-line no-console
+  console.warn('[annotask] TaskDetailModal PERMISSION_MODE_OPTIONS out of sync')
+}
+
+const taskPermissionMode = computed<string>(() => (props.task as { permissionMode?: PermissionMode }).permissionMode ?? '')
+
+// Reflects the mode the task would run with if the user picks "Inherit".
+// Mirrors the resolver: provider override beats global. Uses the persona's
+// provider when one matches the task type so the dropdown shows what'll
+// actually fire on a Run-with-agent click.
+const inheritedPermissionMode = computed<PermissionMode>(() => {
+  const persona = providerSettings.getPersonaForTaskType(props.task.type)
+  const activeProviderId = persona?.providerId ?? providerSettings.activeProvider.value
+  const providerCfg = providerSettings.settings.value.providers[activeProviderId]
+  const providerMode = (providerCfg as { permissionMode?: PermissionMode }).permissionMode
+  return providerMode ?? providerSettings.settings.value.permissionMode
+})
+
+function setTaskPermissionMode(value: string) {
+  if (value === '') {
+    emit('update', props.task.id, { permissionMode: null })
+    return
+  }
+  if (!(PERMISSION_MODES as readonly string[]).includes(value)) return
+  emit('update', props.task.id, { permissionMode: value })
+}
+
 const previewImage = ref<string | null>(null)
 const editing = ref(false)
 const editText = ref('')
@@ -50,6 +139,12 @@ const feedbackHtml = computed(() => safeMd(props.task.feedback || ''))
 
 const blockedReasonHtml = computed(() => safeMd(props.task.blocked_reason || ''))
 
+function formatTokens(n: number): string {
+  if (n < 1000) return n.toString()
+  if (n < 1_000_000) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`
+  return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 2 : 1)}M`
+}
+
 // ── Selected elements (from context) ──
 interface ElementInfo {
   tag: string
@@ -214,8 +309,53 @@ function onKeydown(e: KeyboardEvent) {
       <!-- JSON view -->
       <TaskJsonView v-if="showJson" :task="task" />
 
+      <!-- Tab strip — Details holds the existing fields; Conversation hosts
+           the embedded chat scoped to this task. -->
+      <nav v-else class="td-tabs" aria-label="Task detail sections">
+        <button
+          type="button"
+          class="td-tab"
+          :class="{ active: activeTab === 'details' }"
+          :aria-current="activeTab === 'details' ? 'page' : undefined"
+          @click="activeTab = 'details'"
+        >Details</button>
+        <button
+          v-if="showConversationTab"
+          type="button"
+          class="td-tab"
+          :class="{ active: activeTab === 'conversation' }"
+          :aria-current="activeTab === 'conversation' ? 'page' : undefined"
+          @click="activeTab = 'conversation'"
+        >
+          <Icon name="bot" :size="12" />
+          <span>Conversation</span>
+        </button>
+
+        <!-- Manual-mode "Run with agent" — flanks the tab strip on the right
+             so it reads as the primary call-to-action for this task. -->
+        <button
+          v-if="canManualRun"
+          type="button"
+          class="td-tab td-tab-run"
+          data-testid="btn-modal-run-agent"
+          title="Open the Conversation tab and start the agent on this task"
+          @click="runWithAgent"
+        >
+          <Icon name="bot" :size="12" />
+          <span>Run with agent</span>
+        </button>
+      </nav>
+
+      <ConversationTab
+        v-if="!showJson && activeTab === 'conversation' && showConversationTab"
+        :task="task"
+        @open-settings="emit('open-settings')"
+        @reply="(taskId, answers) => emit('reply', taskId, answers)"
+        @update="(taskId, fields) => emit('update', taskId, fields)"
+      />
+
       <!-- Body -->
-      <div v-else class="td-body">
+      <div v-else-if="!showJson" class="td-body">
         <!-- Description: rendered markdown → click to edit inline -->
         <section class="td-section">
           <div v-if="editing" class="td-editor">
@@ -240,6 +380,21 @@ function onKeydown(e: KeyboardEvent) {
           <div v-else class="td-markdown" data-testid="task-detail-description" :class="{ 'td-clickable': isEditable }" v-html="descriptionHtml" @click="isEditable ? startEditing() : undefined" />
         </section>
 
+        <!-- Permission mode override (per-task). Inherit = use persona/global. -->
+        <section class="td-section td-perm-section">
+          <h4 class="td-label">Permission mode</h4>
+          <select
+            class="td-perm-select"
+            data-testid="task-permission-mode"
+            :value="taskPermissionMode"
+            @change="setTaskPermissionMode(($event.target as HTMLSelectElement).value)"
+          >
+            <option value="">Inherit ({{ inheritedPermissionMode }})</option>
+            <option v-for="m in PERMISSION_MODE_OPTIONS" :key="m.id" :value="m.id">{{ m.label }}</option>
+          </select>
+          <p class="td-perm-hint">Controls how the agent approves actions on this task. Wins over the persona and global settings.</p>
+        </section>
+
         <!-- Selected Elements -->
         <section v-if="selectedElements.length" class="td-section">
           <h4 class="td-label">Element{{ selectedElements.length > 1 ? 's' : '' }}</h4>
@@ -318,6 +473,23 @@ function onKeydown(e: KeyboardEvent) {
           <div class="td-resolution">{{ task.resolution }}</div>
         </section>
 
+        <!-- Token usage -->
+        <section v-if="task.tokenUsage && task.tokenUsage.turns > 0" class="td-section">
+          <h4 class="td-label">Token Usage</h4>
+          <div class="td-usage" data-testid="task-token-usage">
+            <span class="td-usage-pill" title="Input tokens">↑ {{ formatTokens(task.tokenUsage.inputTokens) }}</span>
+            <span class="td-usage-pill" title="Output tokens">↓ {{ formatTokens(task.tokenUsage.outputTokens) }}</span>
+            <span
+              v-if="task.tokenUsage.cacheReadTokens > 0 || task.tokenUsage.cacheCreationTokens > 0"
+              class="td-usage-pill td-usage-cache"
+              :title="`Cache read ${task.tokenUsage.cacheReadTokens.toLocaleString()} · write ${task.tokenUsage.cacheCreationTokens.toLocaleString()}`"
+            >
+              ⧉ {{ formatTokens(task.tokenUsage.cacheReadTokens + task.tokenUsage.cacheCreationTokens) }}
+            </span>
+            <span class="td-usage-meta">{{ task.tokenUsage.turns }} turn{{ task.tokenUsage.turns === 1 ? '' : 's' }}</span>
+          </div>
+        </section>
+
         <!-- Blocked reason -->
         <section v-if="task.blocked_reason" class="td-section">
           <h4 class="td-label">Blocked</h4>
@@ -422,7 +594,7 @@ function onKeydown(e: KeyboardEvent) {
 }
 .td-backdrop {
   position: absolute; inset: 0;
-  background: rgba(0, 0, 0, 0.4);
+  background: var(--overlay);
 }
 .td-drawer {
   position: relative;
@@ -488,6 +660,25 @@ function onKeydown(e: KeyboardEvent) {
   color: var(--text-muted); margin-bottom: 8px;
 }
 
+/* Permission-mode picker */
+.td-perm-select {
+  width: 100%;
+  font: inherit;
+  font-size: 12px;
+  padding: 6px 10px;
+  border: 1px solid var(--border);
+  background: var(--surface-2);
+  color: var(--text);
+  border-radius: 5px;
+}
+.td-perm-select:focus { outline: none; border-color: var(--accent); }
+.td-perm-hint {
+  margin: 6px 2px 0;
+  font-size: 11px;
+  line-height: 1.4;
+  color: var(--text-muted);
+}
+
 /* Inline editor */
 .td-editor {
   border: 1px solid var(--border); border-radius: 8px; overflow: hidden;
@@ -699,6 +890,46 @@ function onKeydown(e: KeyboardEvent) {
 .td-accept:hover { background: var(--success); color: var(--text-on-accent); }
 .td-deny-btn { background: color-mix(in srgb, var(--danger) 12%, transparent); color: var(--danger); }
 .td-deny-btn:hover { background: var(--danger); color: var(--text-on-accent); }
+.td-tabs {
+  display: flex;
+  gap: 4px;
+  padding: 6px 12px 0;
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+}
+.td-tab {
+  display: inline-flex; align-items: center; gap: 6px;
+  background: none; border: none;
+  padding: 8px 12px;
+  font: inherit; font-size: 12px; font-weight: 500;
+  color: var(--text-muted); cursor: pointer;
+  border-bottom: 2px solid transparent;
+  margin-bottom: -1px;
+}
+.td-tab:hover { color: var(--text); }
+.td-tab.active {
+  color: var(--text);
+  font-weight: 600;
+  border-bottom-color: var(--accent);
+}
+.td-tab:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: -1px;
+  border-radius: 4px;
+}
+
+/* Run-with-agent CTA — visually distinct from the regular tabs so users
+   read it as an action, not a passive navigation. Pushed to the right. */
+.td-tab.td-tab-run {
+  margin-left: auto;
+  color: var(--accent);
+  font-weight: 700;
+  border-bottom: none;
+}
+.td-tab.td-tab-run:hover {
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+  border-radius: 4px;
+}
 .td-delete-header-btn {
   width: 28px; height: 28px; display: flex; align-items: center; justify-content: center;
   border: none; border-radius: 6px; cursor: pointer; transition: all 0.12s;
@@ -712,6 +943,19 @@ function onKeydown(e: KeyboardEvent) {
   border-left: 3px solid var(--success); font-size: 12px; color: var(--syntax-string); line-height: 1.5;
 }
 
+/* Token usage */
+.td-usage { display: flex; gap: 6px; flex-wrap: wrap; align-items: center; }
+.td-usage-pill {
+  font-size: 11px; font-family: monospace; padding: 2px 6px; border-radius: 4px;
+  background: color-mix(in srgb, var(--accent) 10%, transparent);
+  color: var(--text); border: 1px solid color-mix(in srgb, var(--accent) 20%, transparent);
+}
+.td-usage-pill.td-usage-cache {
+  background: color-mix(in srgb, var(--info) 10%, transparent);
+  border-color: color-mix(in srgb, var(--info) 20%, transparent);
+}
+.td-usage-meta { font-size: 11px; color: var(--text-muted); }
+
 /* Status: needs_info */
 .td-status.needs_info { background: color-mix(in srgb, var(--status-needs-info) 15%, transparent); color: var(--syntax-boolean); }
 
diff --git a/src/shell/components/TaskInteractionHistory.vue b/src/shell/components/TaskInteractionHistory.vue
index b67aa4e..ed9eabc 100644
--- a/src/shell/components/TaskInteractionHistory.vue
+++ b/src/shell/components/TaskInteractionHistory.vue
@@ -68,7 +68,7 @@ const historyNavPath = computed<string[]>(() => (props.interactionHistory as any
 .td-nav-route { color: var(--text); font-family: ui-monospace, 'SF Mono', monospace; }
 .td-nav-sep { color: var(--text-muted); }
 .td-log { display: flex; flex-direction: column; font-family: ui-monospace, 'SF Mono', monospace; font-size: 10px; }
-.td-log-entry { display: flex; align-items: baseline; gap: 6px; padding: 2px 0; border-bottom: 1px solid rgba(255,255,255,0.04); }
+.td-log-entry { display: flex; align-items: baseline; gap: 6px; padding: 2px 0; border-bottom: 1px solid color-mix(in srgb, var(--text) 4%, transparent); }
 .td-log-idx { color: var(--text-muted); min-width: 18px; text-align: right; font-variant-numeric: tabular-nums; }
 .td-log-event { font-size: 9px; font-weight: 700; text-transform: uppercase; padding: 0 4px; border-radius: 2px; flex-shrink: 0; }
 .td-log-event.route_change { color: var(--accent); background: color-mix(in srgb, var(--accent) 15%, transparent); }
diff --git a/src/shell/components/TasksPanel.vue b/src/shell/components/TasksPanel.vue
index dc5a0da..fb04446 100644
--- a/src/shell/components/TasksPanel.vue
+++ b/src/shell/components/TasksPanel.vue
@@ -7,6 +7,15 @@
         @click="$emit('update:showReportPanel', !showReportPanel)" title="View all tasks as JSON">
         JSON
       </button>
+      <button
+        v-if="canBatchRun"
+        data-testid="btn-run-pending"
+        class="new-task-toggle"
+        title="Queue every pending task with the embedded agent"
+        @click="$emit('run-pending')"
+      >
+        Run pending ({{ pendingCount }})
+      </button>
       <button data-testid="btn-new-task" class="new-task-toggle" @click="$emit('toggle-new-task')" title="Create a general task (not tied to an element)">
         {{ showNewTaskForm ? '−' : '+' }} New
       </button>
@@ -93,6 +102,10 @@ interface Props {
   includeRenderedHtml: boolean
   includeDataContext: boolean
   dataContextProbe: DataContextProbeResult | null
+  /** True when the embedded agent is available AND there's at least one
+   *  pending task to hand off. App.vue computes this from agentMode + ready. */
+  canBatchRun?: boolean
+  pendingCount?: number
 }
 
 defineProps<Props>()
@@ -114,5 +127,6 @@ defineEmits<{
   (e: 'cancel-deny'): void
   (e: 'start-snip'): void
   (e: 'remove-screenshot'): void
+  (e: 'run-pending'): void
 }>()
 </script>
diff --git a/src/shell/components/ThemePage.vue b/src/shell/components/ThemePage.vue
index b4fc2c0..df57605 100644
--- a/src/shell/components/ThemePage.vue
+++ b/src/shell/components/ThemePage.vue
@@ -1,13 +1,12 @@
 <script setup lang="ts">
-import { ref, computed, watch, type Ref, type MaybeRef, toRef } from 'vue'
+import { ref, computed, type Ref } from 'vue'
 import { useDesignSpec } from '../composables/useDesignSpec'
 import { useThemePreview } from '../composables/useThemePreview'
 import { useTasks } from '../composables/useTasks'
-import type { DesignSpecToken, DesignSpecTheme, DesignSpecThemeSelector, ColorSchemeInfo } from '../../schema'
+import type { DesignSpecThemeSelector, ColorSchemeInfo } from '../../schema'
 import type { ColorSchemeResult } from '../../shared/bridge-types'
-import ColorPalettePicker from './ColorPalettePicker.vue'
 import ThemeLibrariesTab from './ThemeLibrariesTab.vue'
-import ThemeAddTokenForm from './ThemeAddTokenForm.vue'
+import DesignTokenEditor from './DesignTokenEditor.vue'
 import Icon from './Icon.vue'
 
 const props = defineProps<{
@@ -30,364 +29,47 @@ const themePreview = useThemePreview(
 )
 const taskSystem = useTasks()
 
-const activeSection = ref<'colors' | 'typography' | 'spacing' | 'borders' | 'libraries'>('colors')
+const editorRef = ref<InstanceType<typeof DesignTokenEditor> | null>(null)
+const activeLibrariesTab = ref(false)
 
-// ── Theme variants ──
-// Every token stores per-variant values keyed by theme id. `activeThemeId`
-// drives which value the UI shows and which variant edits are attributed to.
-const FALLBACK_THEME: DesignSpecTheme = { id: 'default', name: 'Default', selector: { kind: 'default' } }
+const totalChanges = computed(() => editorRef.value?.totalChanges ?? 0)
 
-const themes = computed<DesignSpecTheme[]>(() => {
-  const list = designSpec.value?.themes
-  return Array.isArray(list) && list.length > 0 ? list : [FALLBACK_THEME]
-})
-
-const defaultThemeId = computed(() =>
-  designSpec.value?.defaultTheme || themes.value[0]?.id || 'default'
-)
-
-/** User-pinned variant (null = follow the iframe). */
-const pinnedThemeId = ref<string | null>(null)
-
-/**
- * Match the iframe's detected color scheme to one of the spec's theme variants.
- * Preference order:
- *   1. Exact DOM marker match — most reliable (e.g. data-bs-theme="dark")
- *   2. Scheme classification — theme whose `scheme` field matches light/dark
- *   3. Default theme id from the spec
- */
-function matchTheme(cs: ColorSchemeResult | null | undefined, list: DesignSpecTheme[], fallback: string): string {
-  if (!cs) return fallback
-  if (cs.marker) {
-    const m = cs.marker
-    for (const t of list) {
-      const sel = t.selector
-      if (m.kind === 'attribute' && sel.kind === 'attribute' && sel.name === m.name && (sel.value === undefined || sel.value === m.value) && (sel.host === undefined || sel.host === m.host)) return t.id
-      if (m.kind === 'class' && sel.kind === 'class' && sel.name === m.name && (sel.host === undefined || sel.host === m.host)) return t.id
-    }
-  }
-  for (const t of list) if (t.scheme === cs.scheme) return t.id
-  return fallback
-}
-
-const detectedThemeId = computed(() => matchTheme(props.colorScheme ?? null, themes.value, defaultThemeId.value))
-const activeThemeId = computed(() => pinnedThemeId.value ?? detectedThemeId.value)
-const activeTheme = computed<DesignSpecTheme>(() =>
-  themes.value.find(t => t.id === activeThemeId.value) ?? themes.value[0]
-)
-
-/**
- * Live preview is only safe when the variant being edited matches what the
- * iframe is actually rendering. Otherwise we'd paint dark-theme overrides
- * onto a light-mode viewport (or vice versa) and mislead the user.
- */
-const previewMatchesIframe = computed(() => activeThemeId.value === detectedThemeId.value)
-
-function setActiveTheme(id: string) {
-  const target = themes.value.find(t => t.id === id)
-  if (!target) return
+async function activateVariant(selector: import('../../schema').DesignSpecThemeSelector | null | undefined, all?: import('../../schema').DesignSpecThemeSelector[]) {
+  if (!props.activateColorScheme) return
   themePreview.clearAll()
-  // Drive the iframe into this variant when the selector is one we can apply
-  // from JS (attribute or class). Media-query variants can't be forced — those
-  // just pin the edit target and show a hint. `default` means clear all sibling
-  // markers, which the plugin handles.
-  const canDrive = target.selector.kind === 'attribute'
-    || target.selector.kind === 'class'
-    || target.selector.kind === 'default'
-  if (canDrive && props.activateColorScheme) {
-    pinnedThemeId.value = null
-    const selectors = themes.value.map(t => t.selector)
-    void props.activateColorScheme(target.selector, selectors)
-    return
-  }
-  // Fallback: can't drive this variant — just pin the edit target.
-  pinnedThemeId.value = id === detectedThemeId.value ? null : id
-}
-function followIframe() {
-  pinnedThemeId.value = null
-  themePreview.clearAll()
-}
-
-// Clear any stale preview overrides whenever the active variant changes — we
-// don't want light edits bleeding into dark view or across theme swaps.
-watch(activeThemeId, () => themePreview.clearAll())
-
-// ── Editing state ──
-// Edit maps are keyed by `${themeId}::${role}` so edits in different variants
-// don't collide. `newTokens` keep their values map directly on the token.
-function editKey(themeId: string, role: string) { return `${themeId}::${role}` }
-
-const editedColors = ref<Map<string, string>>(new Map())
-const editedFamilies = ref<Map<string, string>>(new Map())
-const editedScale = ref<Map<string, string>>(new Map())
-const editedSpacing = ref<Map<string, string>>(new Map())
-const editedRadius = ref<Map<string, string>>(new Map())
-
-const newColors = ref<DesignSpecToken[]>([])
-const newFamilies = ref<DesignSpecToken[]>([])
-const newScale = ref<DesignSpecToken[]>([])
-const newSpacing = ref<DesignSpecToken[]>([])
-const newRadius = ref<DesignSpecToken[]>([])
-
-const addingNew = ref<string | null>(null)
-
-// ── Computed token lists ──
-const colors = computed(() => designSpec.value?.colors ?? [])
-const families = computed(() => designSpec.value?.typography?.families ?? [])
-const scale = computed(() => designSpec.value?.typography?.scale ?? [])
-const weights = computed(() => designSpec.value?.typography?.weights ?? [])
-const spacing = computed(() => designSpec.value?.spacing ?? [])
-const radius = computed(() => designSpec.value?.borders?.radius ?? [])
-const icons = computed(() => designSpec.value?.icons ?? null)
-const components = computed(() => designSpec.value?.components ?? null)
-
-/** Count edits across ALL variants, not just the active one. */
-function countEditsForSection(editMap: Map<string, string>, tokens: DesignSpecToken[]): number {
-  let n = 0
-  for (const t of tokens) {
-    for (const tid of Object.keys(t.values || {})) {
-      if (editMap.has(editKey(tid, t.role))) n++
-    }
-  }
-  return n
-}
-
-const colorEditCount = computed(() => countEditsForSection(editedColors.value, colors.value))
-const familyEditCount = computed(() => countEditsForSection(editedFamilies.value, families.value))
-const scaleEditCount = computed(() => countEditsForSection(editedScale.value, scale.value))
-const spacingEditCount = computed(() => countEditsForSection(editedSpacing.value, spacing.value))
-const radiusEditCount = computed(() => countEditsForSection(editedRadius.value, radius.value))
-
-const totalChanges = computed(() =>
-  colorEditCount.value + familyEditCount.value + scaleEditCount.value +
-  spacingEditCount.value + radiusEditCount.value +
-  newColors.value.length + newFamilies.value.length + newScale.value.length +
-  newSpacing.value.length + newRadius.value.length
-)
-
-// ── Token value helpers ──
-function originalValue(token: DesignSpecToken): string {
-  const values = token.values || {}
-  // Prefer the active variant, then the spec's default, then any value in the map.
-  const v = values[activeThemeId.value] ?? values[defaultThemeId.value]
-  if (v !== undefined) return v
-  const first = Object.values(values)[0]
-  return first ?? ''
-}
-
-function getEffectiveValue(token: DesignSpecToken, editMap: MaybeRef<Map<string, string>>): string {
-  const map = toRef(editMap).value
-  return map.get(editKey(activeThemeId.value, token.role)) ?? originalValue(token)
-}
-
-function isEdited(token: DesignSpecToken, editMap: MaybeRef<Map<string, string>>): boolean {
-  const map = toRef(editMap).value
-  const edited = map.get(editKey(activeThemeId.value, token.role))
-  return edited !== undefined && edited !== originalValue(token)
-}
-
-// ── Edit handlers ──
-function onColorChange(token: DesignSpecToken, value: string) {
-  editedColors.value.set(editKey(activeThemeId.value, token.role), value)
-  editedColors.value = new Map(editedColors.value)
-  if (token.cssVar && previewMatchesIframe.value) themePreview.setOverride(token.cssVar, value)
-}
-
-function onTokenChange(
-  token: DesignSpecToken,
-  value: string,
-  editMap: MaybeRef<Map<string, string>>
-) {
-  const r = toRef(editMap)
-  r.value.set(editKey(activeThemeId.value, token.role), value)
-  r.value = new Map(r.value)
-  if (token.cssVar && previewMatchesIframe.value) themePreview.setOverride(token.cssVar, value)
-}
-
-// ── Add new token ──
-function startAdd(section: string) { addingNew.value = section }
-function cancelAdd() { addingNew.value = null }
-
-function confirmAdd(payload: { role: string; value: string; cssVar?: string }) {
-  // New tokens are scoped to the active variant only. Other variants start
-  // blank so the commit task can ask the agent to decide the right value.
-  const token: DesignSpecToken = {
-    role: payload.role,
-    values: { [activeThemeId.value]: payload.value },
-    cssVar: payload.cssVar,
-    source: 'new',
-  }
-  switch (addingNew.value) {
-    case 'colors': newColors.value = [...newColors.value, token]; break
-    case 'families': newFamilies.value = [...newFamilies.value, token]; break
-    case 'scale': newScale.value = [...newScale.value, token]; break
-    case 'spacing': newSpacing.value = [...newSpacing.value, token]; break
-    case 'radius': newRadius.value = [...newRadius.value, token]; break
-  }
-  if (token.cssVar && previewMatchesIframe.value) themePreview.setOverride(token.cssVar, payload.value)
-  addingNew.value = null
-}
-
-function removeNew(list: MaybeRef<DesignSpecToken[]>, index: number) {
-  const r = toRef(list)
-  const token = r.value[index]
-  if (token.cssVar) themePreview.removeOverride(token.cssVar)
-  r.value = r.value.filter((_, i) => i !== index)
-}
-
-function newTokenDisplayValue(token: DesignSpecToken): string {
-  return token.values[activeThemeId.value] ?? Object.values(token.values)[0] ?? ''
-}
-
-// ── Commit ──
-/**
- * Every Commit produces a single `theme_update` task carrying all edits in
- * `context.edits[]`. The agent groups by `sourceFile`, applies edits per file
- * in one pass, then patches `.annotask/design-spec.json` so the Theme page
- * hot-reloads from the updated spec (the server's file watcher broadcasts
- * `designspec:updated` on write).
- */
-interface ThemeEdit {
-  category: string
-  role: string
-  cssVar: string | null
-  theme_variant: string
-  theme_selector: DesignSpecTheme['selector'] | null
-  before: string | null
-  after: string
-  sourceFile: string | null
-  sourceLine: number | null
-  isNew: boolean
-}
-
-function collectEdits(): ThemeEdit[] {
-  const edits: ThemeEdit[] = []
-
-  function pushEditsFor(category: string, token: DesignSpecToken, editMap: Map<string, string>) {
-    for (const themeId of Object.keys(token.values || {})) {
-      const after = editMap.get(editKey(themeId, token.role))
-      const before = token.values[themeId]
-      if (after === undefined || after === before) continue
-      const variant = themes.value.find(t => t.id === themeId)
-      edits.push({
-        category,
-        role: token.role,
-        cssVar: token.cssVar || null,
-        theme_variant: themeId,
-        theme_selector: variant?.selector ?? null,
-        before,
-        after,
-        sourceFile: token.sourceFile || null,
-        sourceLine: token.sourceLine || null,
-        isNew: false,
-      })
-    }
-  }
-
-  function pushNewFor(category: string, token: DesignSpecToken) {
-    // A staged new token may carry multiple variant values at once — emit one
-    // edit per variant so the agent adds the variable to every relevant block.
-    const entries = Object.entries(token.values || {})
-    if (entries.length === 0) {
-      // No variant values specified — fall back to the active variant with an
-      // empty string so the agent has a placeholder location.
-      entries.push([activeThemeId.value, ''])
-    }
-    for (const [themeId, value] of entries) {
-      const variant = themes.value.find(t => t.id === themeId)
-      edits.push({
-        category,
-        role: token.role,
-        cssVar: token.cssVar || null,
-        theme_variant: themeId,
-        theme_selector: variant?.selector ?? null,
-        before: null,
-        after: value ?? '',
-        sourceFile: null,
-        sourceLine: null,
-        isNew: true,
-      })
-    }
-  }
-
-  for (const token of colors.value) pushEditsFor('colors', token, editedColors.value)
-  for (const token of families.value) pushEditsFor('typography.families', token, editedFamilies.value)
-  for (const token of scale.value) pushEditsFor('typography.scale', token, editedScale.value)
-  for (const token of spacing.value) pushEditsFor('spacing', token, editedSpacing.value)
-  for (const token of radius.value) pushEditsFor('borders.radius', token, editedRadius.value)
-
-  for (const token of newColors.value) pushNewFor('colors', token)
-  for (const token of newFamilies.value) pushNewFor('typography.families', token)
-  for (const token of newScale.value) pushNewFor('typography.scale', token)
-  for (const token of newSpacing.value) pushNewFor('spacing', token)
-  for (const token of newRadius.value) pushNewFor('borders.radius', token)
-
-  return edits
+  await props.activateColorScheme(selector ?? null, all)
 }
 
-function buildConsolidatedTask(): Record<string, unknown> | null {
-  const edits = collectEdits()
-  if (edits.length === 0) return null
+async function commitChanges() {
+  const editor = editorRef.value
+  if (!editor) return
+  const edits = editor.collectEdits()
+  if (edits.length === 0) { editor.resetEdits(); return }
   const styling = designSpec.value?.framework?.styling ?? []
-  const variantCount = new Set(edits.map(e => e.theme_variant)).size
+  const variantCount = new Set(edits.map((e: any) => e.theme_variant)).size
   const variantSuffix = variantCount > 1 ? ` across ${variantCount} variants` : ''
-  // Anchor the task card at the first known source file so the task list
-  // shows something meaningful — the agent must still read context.edits to
-  // find every file.
-  const anchorEdit = edits.find(e => e.sourceFile) ?? edits[0]
-  return {
-    type: 'theme_update',
-    action: 'theme_update',
+  const anchorEdit = edits.find((e: any) => e.sourceFile) ?? edits[0]
+  const task = {
+    type: 'theme_update' as const, action: 'theme_update',
     description: `Update ${edits.length} design token${edits.length === 1 ? '' : 's'}${variantSuffix}`,
-    file: anchorEdit.sourceFile || '',
-    line: anchorEdit.sourceLine || 0,
-    intent: 'Apply the listed token edits to their source CSS/config files, then patch .annotask/design-spec.json so the Theme page reflects the new values.',
-    context: {
-      styling,
-      specFile: '.annotask/design-spec.json',
-      edits,
-    },
+    file: (anchorEdit as any).sourceFile || '', line: (anchorEdit as any).sourceLine || 0,
+    intent: 'Apply the listed token edits to their source CSS/config files, then patch .annotask/design-spec.json.',
+    context: { styling, specFile: '.annotask/design-spec.json', edits },
   }
-}
-
-/**
- * Clear edit state. Pass `clearPreview: false` on commit so the user keeps
- * seeing their colors in the iframe — the edits are now agent tasks, and the
- * real file change happens asynchronously. The preview naturally drops once
- * `designspec:updated` reloads the spec with the new base values.
- */
-function resetEdits(opts: { clearPreview?: boolean } = { clearPreview: true }) {
-  editedColors.value = new Map()
-  editedFamilies.value = new Map()
-  editedScale.value = new Map()
-  editedSpacing.value = new Map()
-  editedRadius.value = new Map()
-  newColors.value = []
-  newFamilies.value = []
-  newScale.value = []
-  newSpacing.value = []
-  newRadius.value = []
-  if (opts.clearPreview !== false) themePreview.clearAll()
-}
-
-async function commitChanges() {
-  const task = buildConsolidatedTask()
-  if (!task) { resetEdits(); return }
   const colorScheme = await props.getColorScheme()
   await taskSystem.createTask(colorScheme ? { ...task, color_scheme: colorScheme } : task)
-  // Keep the preview live — the agent will update the source files shortly
-  // and the `designspec:updated` WebSocket push will swap in the real values.
-  resetEdits({ clearPreview: false })
+  editor.resetEdits()
 }
 
 function discardChanges() {
-  resetEdits()
+  editorRef.value?.resetEdits()
+  themePreview.clearAll()
 }
 </script>
 
 <template>
   <div class="theme-page">
-    <!-- Header -->
+    <!-- Commit/discard bar -->
     <div class="theme-header">
       <span class="theme-title">Design Tokens</span>
       <div v-if="totalChanges > 0" class="theme-actions">
@@ -395,9 +77,10 @@ function discardChanges() {
         <button class="theme-btn commit" @click="commitChanges">Commit</button>
         <button class="theme-btn discard" @click="discardChanges">Discard</button>
       </div>
+      <!-- Libraries tab toggle lives here since DesignTokenEditor doesn't render it -->
+      <button v-else :class="['theme-btn small', { active: activeLibrariesTab }]" @click="activeLibrariesTab = !activeLibrariesTab">Libraries</button>
     </div>
 
-    <!-- Loading / Empty -->
     <div v-if="isLoading" class="theme-empty">
       <p>Loading design spec...</p>
     </div>
@@ -408,659 +91,37 @@ function discardChanges() {
     </div>
 
     <template v-else>
-      <!-- Variant tabs — only shown when the spec has more than one variant.
-           The dot marks the variant the iframe is currently rendering; clicking
-           a tab pins the Theme page to that variant so you can edit it even
-           while viewing a different one in the iframe. -->
-      <div v-if="themes.length > 1" class="variant-bar">
-        <div class="variant-tabs">
-          <button
-            v-for="t in themes"
-            :key="t.id"
-            :class="['variant-tab', { active: t.id === activeThemeId, pinned: t.id === pinnedThemeId, detected: t.id === detectedThemeId }]"
-            @click="setActiveTheme(t.id)"
-            :title="t.id === detectedThemeId ? 'Currently active in iframe' : 'Click to edit this variant'"
-          >
-            <span v-if="t.id === detectedThemeId" class="variant-dot" />
-            {{ t.name }}
-          </button>
-        </div>
-        <button v-if="pinnedThemeId" class="variant-follow-btn" @click="followIframe" title="Resume auto-selecting the iframe's active variant">Follow iframe</button>
-      </div>
-      <div v-if="!previewMatchesIframe" class="variant-hint">
-        Editing <strong>{{ activeTheme.name }}</strong> — switch the app to this variant in the iframe to preview changes.
-      </div>
-
-      <!-- Section tabs -->
-      <div class="theme-tabs">
-        <button :class="['theme-tab', { active: activeSection === 'colors' }]" @click="activeSection = 'colors'">
-          Colors <span v-if="colorEditCount + newColors.length" class="theme-tab-badge">{{ colorEditCount + newColors.length }}</span>
-        </button>
-        <button :class="['theme-tab', { active: activeSection === 'typography' }]" @click="activeSection = 'typography'">
-          Type <span v-if="familyEditCount + scaleEditCount + newFamilies.length + newScale.length" class="theme-tab-badge">{{ familyEditCount + scaleEditCount + newFamilies.length + newScale.length }}</span>
-        </button>
-        <button :class="['theme-tab', { active: activeSection === 'spacing' }]" @click="activeSection = 'spacing'">
-          Spacing <span v-if="spacingEditCount + newSpacing.length" class="theme-tab-badge">{{ spacingEditCount + newSpacing.length }}</span>
-        </button>
-        <button :class="['theme-tab', { active: activeSection === 'borders' }]" @click="activeSection = 'borders'">
-          Borders <span v-if="radiusEditCount + newRadius.length" class="theme-tab-badge">{{ radiusEditCount + newRadius.length }}</span>
-        </button>
-        <button :class="['theme-tab', { active: activeSection === 'libraries' }]" @click="activeSection = 'libraries'">Libraries</button>
-      </div>
-
-      <!-- Content -->
-      <div class="theme-content">
-
-        <!-- COLORS -->
-        <div v-if="activeSection === 'colors'" class="theme-section">
-          <div v-if="colors.length === 0 && newColors.length === 0" class="theme-section-empty">No color tokens detected</div>
-          <div v-for="token in colors" :key="token.role" class="token-row">
-            <div class="token-info">
-              <span class="token-role" :class="{ edited: isEdited(token, editedColors) }">{{ token.role }}</span>
-              <code class="token-source">{{ token.source }}</code>
-            </div>
-            <div class="token-controls">
-              <div class="color-swatch-wrapper">
-                <ColorPalettePicker
-                  :modelValue="getEffectiveValue(token, editedColors)"
-                  :showTokens="false"
-                  @update:modelValue="onColorChange(token, $event)"
-                />
-              </div>
-              <input
-                class="token-value-input color-hex"
-                :value="getEffectiveValue(token, editedColors)"
-                @change="onColorChange(token, ($event.target as HTMLInputElement).value)"
-              />
-              <span v-if="!token.cssVar" class="no-preview-badge" title="No CSS variable — preview unavailable">no preview</span>
-            </div>
-          </div>
-          <!-- New color tokens -->
-          <div v-for="(token, i) in newColors" :key="'new-'+i" class="token-row new">
-            <div class="token-info">
-              <span class="token-role new-badge">+ {{ token.role }}</span>
-            </div>
-            <div class="token-controls">
-              <div class="color-swatch-inline" :style="{ background: newTokenDisplayValue(token) }" />
-              <code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code>
-              <button class="token-remove" @click="removeNew(newColors, i)">&times;</button>
-            </div>
-          </div>
-          <ThemeAddTokenForm
-            :active="addingNew === 'colors'"
-            role-placeholder="Role (e.g. info)"
-            value-placeholder="Value (e.g. #3b82f6)"
-            css-var-placeholder="CSS var (optional, e.g. --color-info)"
-            @add="confirmAdd"
-            @cancel="cancelAdd"
-          />
-          <button v-if="addingNew !== 'colors'" class="add-token-btn" @click="startAdd('colors')">+ Add Color</button>
-        </div>
-
-        <!-- TYPOGRAPHY -->
-        <div v-if="activeSection === 'typography'" class="theme-section">
-          <h4 class="section-subtitle">Font Families</h4>
-          <div v-if="families.length === 0 && newFamilies.length === 0" class="theme-section-empty">No font families detected</div>
-          <div v-for="token in families" :key="token.role" class="token-row">
-            <div class="token-info">
-              <span class="token-role" :class="{ edited: isEdited(token, editedFamilies) }">{{ token.role }}</span>
-              <code class="token-source">{{ token.source }}</code>
-            </div>
-            <div class="token-controls">
-              <input
-                class="token-value-input wide"
-                :value="getEffectiveValue(token, editedFamilies)"
-                @change="onTokenChange(token, ($event.target as HTMLInputElement).value, editedFamilies)"
-              />
-            </div>
-          </div>
-          <div v-for="(token, i) in newFamilies" :key="'new-'+i" class="token-row new">
-            <div class="token-info"><span class="token-role new-badge">+ {{ token.role }}</span></div>
-            <div class="token-controls">
-              <code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code>
-              <button class="token-remove" @click="removeNew(newFamilies, i)">&times;</button>
-            </div>
-          </div>
-          <ThemeAddTokenForm
-            :active="addingNew === 'families'"
-            role-placeholder="Role (e.g. display)"
-            value-placeholder="Value (e.g. Poppins, sans-serif)"
-            @add="confirmAdd"
-            @cancel="cancelAdd"
-          />
-          <button v-if="addingNew !== 'families'" class="add-token-btn" @click="startAdd('families')">+ Add Family</button>
-
-          <h4 class="section-subtitle" style="margin-top: 16px">Font Scale</h4>
-          <div v-if="scale.length === 0 && newScale.length === 0" class="theme-section-empty">No font sizes detected</div>
-          <div v-for="token in scale" :key="token.role" class="token-row">
-            <div class="token-info">
-              <span class="token-role" :class="{ edited: isEdited(token, editedScale) }">{{ token.role }}</span>
-              <code class="token-source">{{ token.source }}</code>
-            </div>
-            <div class="token-controls">
-              <input
-                class="token-value-input"
-                :value="getEffectiveValue(token, editedScale)"
-                @change="onTokenChange(token, ($event.target as HTMLInputElement).value, editedScale)"
-              />
-              <div class="font-size-preview" :style="{ fontSize: getEffectiveValue(token, editedScale) }">Aa</div>
-            </div>
-          </div>
-          <div v-for="(token, i) in newScale" :key="'new-'+i" class="token-row new">
-            <div class="token-info"><span class="token-role new-badge">+ {{ token.role }}</span></div>
-            <div class="token-controls">
-              <code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code>
-              <button class="token-remove" @click="removeNew(newScale, i)">&times;</button>
-            </div>
-          </div>
-          <ThemeAddTokenForm
-            :active="addingNew === 'scale'"
-            role-placeholder="Role (e.g. 2xl)"
-            value-placeholder="Value (e.g. 1.5rem)"
-            @add="confirmAdd"
-            @cancel="cancelAdd"
-          />
-          <button v-if="addingNew !== 'scale'" class="add-token-btn" @click="startAdd('scale')">+ Add Size</button>
-
-          <h4 v-if="weights.length" class="section-subtitle" style="margin-top: 16px">Weights</h4>
-          <div v-if="weights.length" class="weight-chips">
-            <span v-for="w in weights" :key="w" class="weight-chip">{{ w }}</span>
-          </div>
-        </div>
-
-        <!-- SPACING -->
-        <div v-if="activeSection === 'spacing'" class="theme-section">
-          <div v-if="spacing.length === 0 && newSpacing.length === 0" class="theme-section-empty">No spacing tokens detected</div>
-          <div v-for="token in spacing" :key="token.role" class="token-row">
-            <div class="token-info">
-              <span class="token-role" :class="{ edited: isEdited(token, editedSpacing) }">{{ token.role }}</span>
-              <code class="token-source">{{ token.source }}</code>
-            </div>
-            <div class="token-controls">
-              <input
-                class="token-value-input"
-                :value="getEffectiveValue(token, editedSpacing)"
-                @change="onTokenChange(token, ($event.target as HTMLInputElement).value, editedSpacing)"
-              />
-              <div class="spacing-preview">
-                <div class="spacing-bar" :style="{ width: getEffectiveValue(token, editedSpacing) }" />
-              </div>
-            </div>
-          </div>
-          <div v-for="(token, i) in newSpacing" :key="'new-'+i" class="token-row new">
-            <div class="token-info"><span class="token-role new-badge">+ {{ token.role }}</span></div>
-            <div class="token-controls">
-              <code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code>
-              <button class="token-remove" @click="removeNew(newSpacing, i)">&times;</button>
-            </div>
-          </div>
-          <ThemeAddTokenForm
-            :active="addingNew === 'spacing'"
-            role-placeholder="Role (e.g. 2xl)"
-            value-placeholder="Value (e.g. 32px)"
-            @add="confirmAdd"
-            @cancel="cancelAdd"
-          />
-          <button v-if="addingNew !== 'spacing'" class="add-token-btn" @click="startAdd('spacing')">+ Add Spacing</button>
-        </div>
-
-        <!-- BORDERS -->
-        <div v-if="activeSection === 'borders'" class="theme-section">
-          <h4 class="section-subtitle">Border Radius</h4>
-          <div v-if="radius.length === 0 && newRadius.length === 0" class="theme-section-empty">No border radius tokens detected</div>
-          <div v-for="token in radius" :key="token.role" class="token-row">
-            <div class="token-info">
-              <span class="token-role" :class="{ edited: isEdited(token, editedRadius) }">{{ token.role }}</span>
-              <code class="token-source">{{ token.source }}</code>
-            </div>
-            <div class="token-controls">
-              <input
-                class="token-value-input"
-                :value="getEffectiveValue(token, editedRadius)"
-                @change="onTokenChange(token, ($event.target as HTMLInputElement).value, editedRadius)"
-              />
-              <div class="radius-preview" :style="{ borderRadius: getEffectiveValue(token, editedRadius) }" />
-            </div>
-          </div>
-          <div v-for="(token, i) in newRadius" :key="'new-'+i" class="token-row new">
-            <div class="token-info"><span class="token-role new-badge">+ {{ token.role }}</span></div>
-            <div class="token-controls">
-              <code class="token-value-ro">{{ newTokenDisplayValue(token) }}</code>
-              <button class="token-remove" @click="removeNew(newRadius, i)">&times;</button>
-            </div>
-          </div>
-          <ThemeAddTokenForm
-            :active="addingNew === 'radius'"
-            role-placeholder="Role (e.g. xl)"
-            value-placeholder="Value (e.g. 16px)"
-            @add="confirmAdd"
-            @cancel="cancelAdd"
-          />
-          <button v-if="addingNew !== 'radius'" class="add-token-btn" @click="startAdd('radius')">+ Add Radius</button>
-        </div>
-
-        <!-- LIBRARIES -->
-        <ThemeLibrariesTab v-if="activeSection === 'libraries'" :design-spec="designSpec ?? null" />
-
-      </div>
+      <ThemeLibrariesTab v-if="activeLibrariesTab" :design-spec="designSpec ?? null" />
+      <DesignTokenEditor
+        v-else
+        ref="editorRef"
+        :spec="designSpec as Record<string, any> | null"
+        :on-activate-variant="activateVariant"
+      />
     </template>
   </div>
 </template>
 
 <style scoped>
-.theme-page {
-  display: flex;
-  flex-direction: column;
-  height: 100%;
-  overflow: hidden;
-}
-
-.theme-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  padding: 10px 16px;
-  border-bottom: 1px solid var(--border);
-  flex-shrink: 0;
-}
-.theme-title {
-  font-size: 13px;
-  font-weight: 600;
-  color: var(--text);
-}
-.theme-actions {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-}
-.theme-change-count {
-  font-size: 11px;
-  color: var(--text-muted);
-}
-.theme-btn {
-  padding: 4px 12px;
-  font-size: 11px;
-  font-weight: 600;
-  border: none;
-  border-radius: 5px;
-  cursor: pointer;
-}
-.theme-btn.commit {
-  background: var(--accent);
-  color: white;
-}
+.theme-page { display: flex; flex-direction: column; height: 100%; overflow: hidden; }
+
+.theme-header { display: flex; align-items: center; justify-content: space-between; padding: 10px 16px; border-bottom: 1px solid var(--border); flex-shrink: 0; }
+.theme-title { font-size: 13px; font-weight: 600; color: var(--text); }
+.theme-actions { display: flex; align-items: center; gap: 8px; }
+.theme-change-count { font-size: 11px; color: var(--text-muted); }
+.theme-btn { padding: 4px 12px; font-size: 11px; font-weight: 600; border: none; border-radius: 5px; cursor: pointer; }
+.theme-btn.commit { background: var(--accent); color: white; }
 .theme-btn.commit:hover { opacity: 0.9; }
 .theme-btn.commit:disabled { opacity: 0.4; cursor: not-allowed; }
-.theme-btn.discard {
-  background: var(--surface-2);
-  color: var(--text-muted);
-  border: 1px solid var(--border);
-}
+.theme-btn.discard { background: var(--surface-2); color: var(--text-muted); border: 1px solid var(--border); }
 .theme-btn.discard:hover { color: var(--text); background: var(--border); }
-.theme-btn.small { padding: 3px 10px; font-size: 10px; }
+.theme-btn.small { padding: 3px 10px; font-size: 10px; background: var(--surface-2); border: 1px solid var(--border); color: var(--text-muted); }
+.theme-btn.small:hover { color: var(--text); }
+.theme-btn.small.active { color: var(--accent); border-color: var(--accent); }
 
 /* Empty state */
-.theme-empty {
-  flex: 1;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: 8px;
-  color: var(--text-muted);
-  text-align: center;
-  padding: 24px;
-}
+.theme-empty { flex: 1; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 8px; color: var(--text-muted); text-align: center; padding: 24px; }
 .theme-empty p { font-size: 13px; }
 .theme-empty-hint { font-size: 11px; opacity: 0.7; }
-.theme-empty code {
-  background: rgba(59,130,246,0.15);
-  padding: 1px 6px;
-  border-radius: 3px;
-  font-weight: 600;
-  color: #60a5fa;
-}
-
-/* Variant bar — shown only when the spec has multiple theme variants */
-.variant-bar {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 6px 12px;
-  border-bottom: 1px solid var(--border);
-  background: var(--surface-2);
-  flex-shrink: 0;
-}
-.variant-tabs {
-  display: flex;
-  flex: 1;
-  gap: 4px;
-  overflow-x: auto;
-}
-.variant-tab {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  padding: 3px 10px;
-  font-size: 11px;
-  font-weight: 500;
-  background: transparent;
-  border: 1px solid var(--border);
-  color: var(--text-muted);
-  border-radius: 4px;
-  cursor: pointer;
-  white-space: nowrap;
-  transition: all 0.15s;
-}
-.variant-tab:hover { color: var(--text); }
-.variant-tab.active {
-  color: var(--text);
-  background: var(--surface-elevated);
-  border-color: var(--accent);
-}
-.variant-tab.pinned {
-  border-style: dashed;
-}
-.variant-dot {
-  width: 6px;
-  height: 6px;
-  border-radius: 50%;
-  background: var(--accent);
-  box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent) 25%, transparent);
-  flex-shrink: 0;
-}
-.variant-follow-btn {
-  padding: 3px 8px;
-  font-size: 10px;
-  font-weight: 500;
-  background: transparent;
-  border: 1px solid var(--border);
-  color: var(--text-muted);
-  border-radius: 4px;
-  cursor: pointer;
-  white-space: nowrap;
-}
-.variant-follow-btn:hover { color: var(--text); background: var(--surface-elevated); }
-.variant-hint {
-  padding: 6px 12px;
-  font-size: 11px;
-  color: var(--warning);
-  background: color-mix(in srgb, var(--warning) 10%, transparent);
-  border-bottom: 1px solid var(--border);
-}
-.variant-hint strong { font-weight: 600; }
-
-/* Tabs */
-.theme-tabs {
-  display: flex;
-  border-bottom: 1px solid var(--border);
-  flex-shrink: 0;
-}
-.theme-tab {
-  flex: 1;
-  padding: 8px 4px;
-  font-size: 11px;
-  font-weight: 500;
-  background: none;
-  border: none;
-  border-bottom: 2px solid transparent;
-  color: var(--text-muted);
-  cursor: pointer;
-  transition: all 0.15s;
-}
-.theme-tab:hover { color: var(--text); }
-.theme-tab.active { color: var(--accent); border-bottom-color: var(--accent); }
-.theme-tab-badge {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  min-width: 14px;
-  height: 14px;
-  padding: 0 3px;
-  font-size: 9px;
-  font-weight: 700;
-  background: var(--danger);
-  color: white;
-  border-radius: 7px;
-  margin-left: 3px;
-}
-
-/* Content */
-.theme-content {
-  flex: 1;
-  overflow-y: auto;
-  padding: 12px;
-}
-
-.theme-section { display: flex; flex-direction: column; gap: 2px; }
-.theme-section-empty {
-  padding: 16px 0;
-  text-align: center;
-  font-size: 11px;
-  color: var(--text-muted);
-  opacity: 0.6;
-}
-.section-subtitle {
-  font-size: 10px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-  color: var(--text-muted);
-  padding: 6px 0 4px;
-}
-
-/* Token rows */
-.token-row {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  padding: 6px 8px;
-  border-radius: 6px;
-  gap: 8px;
-  transition: background 0.1s;
-}
-.token-row:hover { background: var(--surface-2); }
-.token-row.new { background: rgba(59,130,246,0.06); }
-
-.token-info {
-  display: flex;
-  flex-direction: column;
-  gap: 1px;
-  min-width: 0;
-  flex-shrink: 1;
-}
-.token-role {
-  font-size: 12px;
-  font-weight: 500;
-  color: var(--text);
-  white-space: nowrap;
-}
-.token-role.edited { color: var(--accent); }
-.token-role.new-badge { color: #22c55e; font-weight: 600; }
-.token-source {
-  font-size: 9px;
-  color: var(--text-muted);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  max-width: 160px;
-}
-
-.token-controls {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  flex-shrink: 0;
-}
-
-.token-value-input {
-  width: 80px;
-  padding: 3px 6px;
-  font-size: 11px;
-  font-family: monospace;
-  background: var(--bg);
-  border: 1px solid var(--border);
-  border-radius: 4px;
-  color: var(--text);
-  outline: none;
-}
-.token-value-input:focus { border-color: var(--accent); }
-.token-value-input.wide { width: 160px; }
-.token-value-input.color-hex { width: 72px; }
-
-.token-value-ro {
-  font-size: 11px;
-  color: var(--text-muted);
-}
-
-.token-remove {
-  width: 18px;
-  height: 18px;
-  border: none;
-  background: none;
-  color: var(--text-muted);
-  font-size: 14px;
-  cursor: pointer;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  border-radius: 3px;
-}
-.token-remove:hover { color: #ef4444; background: rgba(239,68,68,0.1); }
-
-.no-preview-badge {
-  font-size: 8px;
-  color: var(--text-muted);
-  opacity: 0.6;
-  white-space: nowrap;
-}
-
-/* Color specific */
-.color-swatch-wrapper { flex-shrink: 0; }
-.color-swatch-inline {
-  width: 20px;
-  height: 20px;
-  border-radius: 4px;
-  border: 1px solid var(--border);
-  flex-shrink: 0;
-}
-
-/* Typography previews */
-.font-size-preview {
-  color: var(--text);
-  line-height: 1;
-  white-space: nowrap;
-}
-
-.weight-chips { display: flex; flex-wrap: wrap; gap: 4px; padding: 4px 0; }
-.weight-chip {
-  font-size: 10px;
-  padding: 2px 8px;
-  background: var(--surface-2);
-  border: 1px solid var(--border);
-  border-radius: 4px;
-  color: var(--text-muted);
-}
-
-/* Spacing preview */
-.spacing-preview {
-  width: 60px;
-  height: 12px;
-  background: var(--surface-2);
-  border-radius: 2px;
-  overflow: hidden;
-}
-.spacing-bar {
-  height: 100%;
-  background: var(--accent);
-  border-radius: 2px;
-  max-width: 100%;
-  transition: width 0.15s;
-}
-
-/* Radius preview */
-.radius-preview {
-  width: 24px;
-  height: 24px;
-  background: var(--accent);
-  transition: border-radius 0.15s;
-}
-
-/* Add token form */
-.add-token-btn {
-  padding: 6px;
-  margin-top: 4px;
-  font-size: 11px;
-  color: var(--text-muted);
-  background: none;
-  border: 1px dashed var(--border);
-  border-radius: 6px;
-  cursor: pointer;
-  transition: all 0.1s;
-}
-.add-token-btn:hover { color: var(--accent); border-color: var(--accent); }
-
-.add-token-form {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 8px;
-  margin-top: 4px;
-  background: var(--surface-2);
-  border: 1px solid var(--border);
-  border-radius: 6px;
-}
-.add-input {
-  padding: 4px 8px;
-  font-size: 11px;
-  background: var(--bg);
-  border: 1px solid var(--border);
-  border-radius: 4px;
-  color: var(--text);
-  outline: none;
-  font-family: inherit;
-}
-.add-input:focus { border-color: var(--accent); }
-.add-actions {
-  display: flex;
-  gap: 4px;
-  margin-top: 2px;
-}
-
-/* Library cards */
-.library-card {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 8px 10px;
-  background: var(--surface-2);
-  border: 1px solid var(--border);
-  border-radius: 6px;
-}
-.library-name { font-size: 12px; font-weight: 600; color: var(--text); }
-.library-version { font-size: 10px; color: var(--text-muted); }
-.styling-chip {
-  font-size: 9px;
-  padding: 1px 6px;
-  background: rgba(59,130,246,0.12);
-  color: #60a5fa;
-  border-radius: 3px;
-  font-weight: 600;
-}
-
-.library-components {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 4px;
-  padding: 6px 0;
-}
-.component-chip {
-  font-size: 10px;
-  padding: 2px 8px;
-  background: var(--surface-2);
-  border: 1px solid var(--border);
-  border-radius: 4px;
-  color: var(--text-muted);
-  font-family: monospace;
-}
+.theme-empty code { background: color-mix(in srgb, var(--accent) 15%, transparent); padding: 1px 6px; border-radius: 3px; font-weight: 600; color: var(--text-link); }
 </style>
diff --git a/src/shell/components/UsagePanel.vue b/src/shell/components/UsagePanel.vue
new file mode 100644
index 0000000..4104edb
--- /dev/null
+++ b/src/shell/components/UsagePanel.vue
@@ -0,0 +1,206 @@
+<script setup lang="ts">
+/**
+ * Usage & Metrics panel — scoped to one provider.
+ *
+ * Polls `/__annotask/api/usage` every 15s and shows the cumulative totals
+ * for the selected provider only (the `byProvider[providerId]` slice). The
+ * provider picker lives in the parent (SettingsOverlay's LLM Providers tab
+ * header); switching it flips the data shown here.
+ *
+ * When the backend has no rows for the selected provider yet, an empty
+ * state explains why instead of rendering a wall of zeros.
+ */
+import { ref, computed, onMounted, onBeforeUnmount } from 'vue'
+import type { ProviderId } from '../../embedded/provider-config'
+
+const props = defineProps<{ providerId: ProviderId }>()
+
+interface UsageTotals {
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheCreationTokens: number
+  turns: number
+}
+interface UsageSummary {
+  totals: UsageTotals
+  byScope: Record<'task' | 'init' | 'apply' | 'chat', UsageTotals>
+  byProvider: Record<string, UsageTotals>
+  firstAt: number | null
+  lastAt: number | null
+}
+
+const usageSummary = ref<UsageSummary | null>(null)
+let usagePollTimer: number | null = null
+
+async function refreshUsage() {
+  try {
+    const res = await fetch('/__annotask/api/usage')
+    if (!res.ok) return
+    usageSummary.value = await res.json()
+  } catch { /* offline — keep previous */ }
+}
+
+onMounted(() => {
+  void refreshUsage()
+  usagePollTimer = window.setInterval(refreshUsage, 15_000)
+})
+onBeforeUnmount(() => {
+  if (usagePollTimer !== null) { window.clearInterval(usagePollTimer); usagePollTimer = null }
+})
+
+function formatTokens(n: number): string {
+  if (n < 1000) return n.toString()
+  if (n < 1_000_000) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`
+  return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 2 : 1)}M`
+}
+
+function formatRelative(ts: number | null): string {
+  if (!ts) return '—'
+  const ms = Date.now() - ts
+  if (ms < 60_000) return 'just now'
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)}m ago`
+  if (ms < 86_400_000) return `${Math.round(ms / 3_600_000)}h ago`
+  return `${Math.round(ms / 86_400_000)}d ago`
+}
+
+/** This provider's totals, or null when no rows have been logged for it. */
+const providerTotals = computed<UsageTotals | null>(() => {
+  const row = usageSummary.value?.byProvider?.[props.providerId]
+  if (!row || row.turns === 0) return null
+  return row
+})
+
+/** Provider's share of overall project usage — informational. */
+const providerShare = computed<number | null>(() => {
+  const grand = usageSummary.value?.totals
+  if (!grand || grand.turns === 0) return null
+  const mine = providerTotals.value
+  if (!mine) return 0
+  const grandTokens = grand.inputTokens + grand.outputTokens
+  if (grandTokens === 0) return null
+  const mineTokens = mine.inputTokens + mine.outputTokens
+  return Math.round((mineTokens / grandTokens) * 1000) / 10
+})
+</script>
+
+<template>
+  <div class="usage-panel">
+    <p class="usage-lead">
+      Cumulative tokens <strong>{{ providerId }}</strong> has consumed in this
+      project — across initialization, task conversations, and apply runs.
+      Read from <code>.annotask/usage.jsonl</code>.
+    </p>
+
+    <div v-if="!providerTotals" class="usage-empty">
+      No usage recorded for <code>{{ providerId }}</code> yet. Start a
+      conversation on a task or run init with this provider selected.
+    </div>
+
+    <template v-else>
+      <div class="usage-grid" data-testid="usage-summary">
+        <div class="usage-card">
+          <div class="usage-card-label">Input</div>
+          <div class="usage-card-value">{{ formatTokens(providerTotals.inputTokens) }}</div>
+        </div>
+        <div class="usage-card">
+          <div class="usage-card-label">Output</div>
+          <div class="usage-card-value">{{ formatTokens(providerTotals.outputTokens) }}</div>
+        </div>
+        <div class="usage-card">
+          <div class="usage-card-label">Cache read</div>
+          <div class="usage-card-value">{{ formatTokens(providerTotals.cacheReadTokens) }}</div>
+        </div>
+        <div class="usage-card">
+          <div class="usage-card-label">Cache write</div>
+          <div class="usage-card-value">{{ formatTokens(providerTotals.cacheCreationTokens) }}</div>
+        </div>
+        <div class="usage-card">
+          <div class="usage-card-label">Turns</div>
+          <div class="usage-card-value">{{ providerTotals.turns.toLocaleString() }}</div>
+        </div>
+        <div class="usage-card">
+          <div class="usage-card-label">Last activity</div>
+          <div class="usage-card-value usage-card-value-small">{{ formatRelative(usageSummary?.lastAt ?? null) }}</div>
+        </div>
+      </div>
+
+      <p v-if="providerShare !== null" class="usage-share">
+        That's <strong>{{ providerShare }}%</strong> of total project usage
+        across all providers.
+      </p>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.usage-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+.usage-lead {
+  margin: 0;
+  font-size: 12px;
+  color: var(--text-muted);
+  line-height: 1.55;
+}
+.usage-lead code {
+  font-size: 11px;
+  padding: 1px 5px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 3px;
+  color: var(--text);
+}
+
+.usage-empty {
+  padding: 24px;
+  text-align: center;
+  font-size: 12.5px;
+  color: var(--text-muted);
+  border: 1px dashed var(--border);
+  border-radius: 8px;
+}
+
+.usage-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 10px;
+}
+.usage-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 12px 14px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+}
+.usage-card-label {
+  font-size: 10px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--text-muted);
+}
+.usage-card-value {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--text);
+  font-variant-numeric: tabular-nums;
+}
+.usage-card-value-small { font-size: 13px; font-weight: 500; }
+
+.usage-share {
+  margin: 0;
+  font-size: 12px;
+  color: var(--text-muted);
+  line-height: 1.5;
+}
+.usage-share strong {
+  font-weight: 600;
+  color: var(--text);
+  font-variant-numeric: tabular-nums;
+}
+</style>
diff --git a/src/shell/components/ViewportSelector.vue b/src/shell/components/ViewportSelector.vue
index 9d16e3d..a4fb094 100644
--- a/src/shell/components/ViewportSelector.vue
+++ b/src/shell/components/ViewportSelector.vue
@@ -143,7 +143,7 @@ onUnmounted(() => document.removeEventListener('click', onDocClick))
 .vp-item.active { background: var(--accent); color: var(--text-on-accent); }
 .vp-item-label { flex: 1; text-align: left; }
 .vp-item-dim { font-family: monospace; font-size: 10px; color: var(--text-muted); }
-.vp-item.active .vp-item-dim { color: rgba(255,255,255,0.7); }
+.vp-item.active .vp-item-dim { color: color-mix(in srgb, var(--text-on-accent) 70%, transparent); }
 
 .vp-custom { margin-top: 2px; border-top: 1px solid var(--border); padding-top: 4px; }
 .vp-custom-row { display: flex; align-items: center; gap: 4px; padding: 4px 8px; }
diff --git a/src/shell/components/WireframeBlockPopover.vue b/src/shell/components/WireframeBlockPopover.vue
new file mode 100644
index 0000000..485505f
--- /dev/null
+++ b/src/shell/components/WireframeBlockPopover.vue
@@ -0,0 +1,287 @@
+<script setup lang="ts">
+/**
+ * Inline config popover anchored to the selected palette block — the "configure
+ * on canvas" surface that replaced the right-docked generate panel. Editing a
+ * prop or binding mutates the block and live-regenerates its snapshot (debounced
+ * in the generator); the last-good snapshot stays visible with a shimmer until
+ * the new render lands. Selecting the block opens it; Escape / the close button
+ * dismisses it (which deselects the block).
+ *
+ * Anchoring mirrors the note/markdown editors: an absolute child of the selected
+ * .wf-block, below it by default, flipped above when the block sits near the
+ * bottom of the canvas. @pointerdown.stop keeps clicks from deselecting; the
+ * keydown handler stops propagation so typing/Backspace never reaches the
+ * canvas's block-delete shortcuts.
+ */
+import { computed, onMounted, ref } from 'vue'
+import Icon from './Icon.vue'
+import DataBindingPicker from './DataBindingPicker.vue'
+import PropWidgetRows from './PropWidgetRows.vue'
+import type { WidgetProp } from '../utils/propWidgets'
+import type { useComponentGenerator } from '../composables/useComponentGenerator'
+import type { WireframeBlock, WireframeDataBinding } from '../../shared/wireframe-types'
+import { WIREFRAME_DATA_BINDING_ENABLED } from '../wireframeFeatures'
+
+// Deferred this release (see wireframeFeatures.ts) — the Data section is gated.
+const dataBindingEnabled = WIREFRAME_DATA_BINDING_ENABLED
+
+const props = defineProps<{
+  block: WireframeBlock
+  generator: ReturnType<typeof useComponentGenerator>
+  /** This block's snapshot is rendering right now (drives the shimmer/label). */
+  generating: boolean
+  /** Captured document height (stage coords) — flips the popover above the
+   *  block when it would overflow the bottom. */
+  docHeight?: number
+}>()
+
+const emit = defineEmits<{ close: [] }>()
+
+const pickerOpen = ref(false)
+
+// Cold start (e.g. reopening a block after F5 without visiting Components): pull
+// the catalog so the prop rows upgrade from untyped keys to typed widgets.
+onMounted(() => props.generator.ensureCatalog())
+
+const meta = computed(() => props.generator.metaForBlock(props.block))
+
+/** Typed rows from catalog meta; fall back to the block's own prop keys as
+ *  untyped rows (honest degradation before/without a catalog). */
+const rows = computed<WidgetProp[]>(() => {
+  const m = meta.value
+  if (m && m.props.length > 0) return m.props
+  return Object.keys(props.block.component?.props ?? {}).map((name) => ({ name, type: null }))
+})
+
+const values = computed<Record<string, unknown>>(() => props.block.component?.props ?? {})
+const binding = computed<WireframeDataBinding | null>(() => props.block.data ?? null)
+const dataSuggested = computed(() => props.generator.datasourceSuggested(props.block))
+
+// Field→prop mapping + loop repeat (only meaningful once a binding exists).
+const boundFields = computed<string[]>(() => binding.value?.fields ?? [])
+const propMap = computed<Record<string, string>>(() => binding.value?.propMap ?? {})
+const isListBinding = computed(() => props.generator.isListPath(binding.value?.path))
+const repeatVal = computed(() => binding.value?.repeat ?? (isListBinding.value ? 3 : 1))
+
+const fidelityLabel = computed(() => {
+  const f = props.block.fidelity
+  if (!f || f === 'live') return null
+  return f === 'isolated-preview' ? 'isolated preview' : 'placeholder render'
+})
+
+/** Actionable explanation for a non-live render, shown under the header. */
+const fidelityNote = computed(() => {
+  const f = props.block.fidelity
+  if (f === 'isolated-preview') return 'Rendered outside the live app context — may differ from production.'
+  if (f === 'placeholder') return 'Couldn’t render live here — it may not be imported in the running app, or it needs required props.'
+  return null
+})
+
+const flipAbove = computed(() => {
+  const h = props.docHeight
+  if (!h) return false
+  return props.block.rect.y + props.block.rect.height + 300 > h
+})
+
+function onSet(name: string, value: unknown): void {
+  props.generator.setProp(props.block.id, name, value)
+}
+function onBindingSelect(b: WireframeDataBinding): void {
+  props.generator.setBinding(props.block.id, b)
+  pickerOpen.value = false
+}
+function onBindingClear(): void {
+  props.generator.setBinding(props.block.id, null)
+  pickerOpen.value = false
+}
+function onMapProp(prop: string, e: Event): void {
+  props.generator.setPropBinding(props.block.id, prop, (e.target as HTMLSelectElement).value || null)
+}
+function onRepeat(e: Event): void {
+  const n = Number((e.target as HTMLInputElement).value)
+  if (n >= 1) props.generator.setRepeat(props.block.id, n)
+}
+function onKeydown(e: KeyboardEvent): void {
+  // Stop here so Backspace/Delete/arrows inside the popover never trigger the
+  // canvas's block ops; Escape closes the popover.
+  e.stopPropagation()
+  if (e.key === 'Escape') emit('close')
+}
+</script>
+
+<template>
+  <div class="wf-popover" :class="{ above: flipAbove }" data-testid="wf-block-popover"
+    @pointerdown.stop @click.stop @keydown="onKeydown">
+    <div class="wf-pop-head">
+      <span class="wf-pop-title">{{ block.component?.componentName ?? block.component?.tag }}</span>
+      <span v-if="block.component?.library" class="wf-pop-lib">{{ block.component.library }}</span>
+      <span v-if="block.component?.mfe" class="wf-pop-mfe" :title="`renders &amp; imports from ${block.component.mfe}`">{{ block.component.mfe }}</span>
+      <span class="wf-pop-spacer" />
+      <span v-if="generating" class="wf-pop-rendering" data-testid="wf-pop-rendering">rendering…</span>
+      <span v-else-if="fidelityLabel" class="wf-pop-fidelity" :class="block.fidelity">{{ fidelityLabel }}</span>
+      <button class="wf-pop-close" title="Close (Esc)" data-testid="wf-pop-close" @click="emit('close')">
+        <Icon name="x" :size="13" />
+      </button>
+    </div>
+    <code v-if="block.component?.module" class="wf-pop-module">{{ block.component.module }}</code>
+
+    <div class="wf-pop-body">
+      <p v-if="!generating && fidelityNote" class="wf-pop-note" data-testid="wf-pop-fidelity-note">{{ fidelityNote }}</p>
+      <section class="wf-pop-section">
+        <h4>Props <em>— written into source</em></h4>
+        <p v-if="rows.length === 0" class="wf-pop-empty">No editable props detected.</p>
+        <PropWidgetRows v-else :rows="rows" :values="values" testid-prefix="wf-prop" @set="onSet" />
+      </section>
+
+      <section v-if="dataBindingEnabled" class="wf-pop-section">
+        <h4>Data <em v-if="dataSuggested">— looks data-driven</em></h4>
+        <div v-if="binding" class="wf-pop-binding" data-testid="wf-pop-binding">
+          <span class="wf-pop-binding-name">{{ binding.name }}</span>
+          <span v-if="binding.path" class="wf-pop-binding-path">{{ binding.path }}</span>
+          <span class="wf-pop-binding-tag" :class="binding.shape_source">{{ binding.shape_source }}</span>
+        </div>
+        <button class="wf-pop-btn" data-testid="wf-pop-bind" @click="pickerOpen = true">
+          {{ binding ? 'Change binding…' : 'Bind data…' }}
+        </button>
+
+        <!-- Map each prop to a bound field; list bindings sketch N loop rows. -->
+        <div v-if="binding && boundFields.length && rows.length" class="wf-pop-map" data-testid="wf-pop-map">
+          <div class="wf-pop-map-title">Map props → data{{ isListBinding ? ' (per item)' : '' }}</div>
+          <div v-for="p in rows" :key="`map-${p.name}`" class="wf-pop-map-row">
+            <code class="wf-pop-map-prop">{{ p.name }}</code>
+            <select class="wf-pop-map-select" :data-testid="`wf-pop-map-${p.name}`"
+              :value="propMap[p.name] ?? ''" @change="onMapProp(p.name, $event)">
+              <option value="">— literal —</option>
+              <option v-for="f in boundFields" :key="f" :value="f">{{ f }}</option>
+            </select>
+          </div>
+          <label v-if="isListBinding" class="wf-pop-repeat">
+            show
+            <input type="number" min="1" max="24" class="wf-pop-repeat-input" data-testid="wf-pop-repeat"
+              :value="repeatVal" @change="onRepeat($event)">
+            instances
+          </label>
+        </div>
+      </section>
+    </div>
+
+    <div v-if="dataBindingEnabled && pickerOpen" class="wf-pop-picker-overlay" @pointerdown.self="pickerOpen = false">
+      <DataBindingPicker :initial="binding" @select="onBindingSelect" @clear="onBindingClear" @cancel="pickerOpen = false" />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.wf-popover {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  width: 290px;
+  max-height: 360px;
+  display: flex;
+  flex-direction: column;
+  background: var(--surface-elevated);
+  border: 1px solid var(--border-strong);
+  border-radius: 8px;
+  box-shadow: 0 8px 24px var(--shadow);
+  color: var(--text);
+  font-size: 12px;
+  /* Above the resize handles (z ~1099) and block chrome. */
+  z-index: 1200;
+  cursor: default;
+}
+.wf-popover.above { top: auto; bottom: calc(100% + 4px); }
+.wf-pop-head { display: flex; align-items: center; gap: 6px; padding: 8px 10px 4px; }
+.wf-pop-title { font-weight: 600; font-size: 12px; }
+.wf-pop-lib {
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-size: 9px;
+  background: color-mix(in srgb, var(--accent) 18%, transparent);
+  color: var(--accent);
+}
+.wf-pop-mfe {
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-size: 9px;
+  background: color-mix(in srgb, var(--purple) 18%, transparent);
+  color: var(--purple);
+}
+.wf-pop-spacer { flex: 1; }
+.wf-pop-rendering { font-size: 9px; color: var(--text-muted); font-style: italic; }
+.wf-pop-fidelity {
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-size: 9px;
+  background: color-mix(in srgb, var(--warning) 85%, black);
+  color: #111;
+}
+.wf-pop-fidelity.placeholder { background: color-mix(in srgb, var(--text-muted) 85%, black); color: #eee; }
+.wf-pop-close { background: none; border: none; color: var(--text-muted); cursor: pointer; padding: 2px; display: flex; }
+.wf-pop-close:hover { color: var(--text); }
+.wf-pop-module { display: block; padding: 0 10px 6px; color: var(--text-muted); font-size: 10px; }
+.wf-pop-body { flex: 1; overflow-y: auto; padding: 0 10px 10px; display: flex; flex-direction: column; gap: 10px; }
+.wf-pop-section h4 { margin: 6px 0 6px; font-size: 11px; font-weight: 600; }
+.wf-pop-section h4 em { font-style: normal; font-weight: 400; color: var(--text-muted); }
+.wf-pop-empty { margin: 0; color: var(--text-muted); font-size: 11px; }
+.wf-pop-note {
+  margin: 8px 0 0;
+  padding: 6px 8px;
+  font-size: 10px;
+  line-height: 1.35;
+  color: var(--text-muted);
+  background: color-mix(in srgb, var(--warning) 12%, transparent);
+  border-radius: 4px;
+}
+.wf-pop-binding {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  margin-bottom: 6px;
+  padding: 3px 8px;
+  border-radius: 4px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+}
+.wf-pop-binding-name { font-weight: 600; }
+.wf-pop-binding-path { color: var(--text-muted); font-family: ui-monospace, monospace; font-size: 10px; }
+.wf-pop-binding-tag { padding: 0 5px; border-radius: 3px; font-size: 9px; }
+.wf-pop-binding-tag.api-schema { background: color-mix(in srgb, var(--success) 18%, transparent); color: var(--success); }
+.wf-pop-binding-tag.source-details { background: color-mix(in srgb, var(--warning) 18%, transparent); color: var(--warning); }
+.wf-pop-binding-tag.none { background: color-mix(in srgb, var(--text-muted) 18%, transparent); color: var(--text-muted); }
+.wf-pop-btn {
+  padding: 5px 10px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  color: var(--text);
+  cursor: pointer;
+  font-size: 12px;
+}
+.wf-pop-btn:hover { background: var(--surface-3); }
+.wf-pop-map { margin-top: 8px; padding-top: 8px; border-top: 1px solid var(--border); }
+.wf-pop-map-title { font-size: 10px; font-weight: 600; color: var(--text-muted); margin-bottom: 6px; }
+.wf-pop-map-row { display: flex; align-items: center; gap: 8px; margin-bottom: 4px; }
+.wf-pop-map-prop { min-width: 84px; font-size: 11px; color: var(--syntax-property); overflow: hidden; text-overflow: ellipsis; }
+.wf-pop-map-select {
+  flex: 1;
+  min-width: 0;
+  padding: 4px 6px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  color: var(--text);
+  font-size: 11px;
+}
+.wf-pop-repeat { display: flex; align-items: center; gap: 6px; margin-top: 6px; font-size: 11px; color: var(--text-muted); }
+.wf-pop-repeat-input { width: 52px; padding: 3px 6px; background: var(--surface); border: 1px solid var(--border); border-radius: 4px; color: var(--text); font-size: 11px; }
+.wf-pop-picker-overlay {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--overlay);
+  z-index: 80;
+}
+</style>
diff --git a/src/shell/components/WireframeCanvas.vue b/src/shell/components/WireframeCanvas.vue
new file mode 100644
index 0000000..e693d60
--- /dev/null
+++ b/src/shell/components/WireframeCanvas.vue
@@ -0,0 +1,1163 @@
+<script setup lang="ts">
+import { ref, computed, watch, nextTick } from 'vue'
+import ConfirmDialog from './ConfirmDialog.vue'
+import DataBindingPicker from './DataBindingPicker.vue'
+import WireframeBlockPopover from './WireframeBlockPopover.vue'
+import Icon from './Icon.vue'
+import { computeSnap, type SnapGuide } from '../utils/wireframeSnap'
+import { safeMd } from '../utils/safeMd'
+import { WIREFRAME_DATA_BINDING_ENABLED, WIREFRAME_EXPLODE_ENABLED } from '../wireframeFeatures'
+import type { useComponentGenerator } from '../composables/useComponentGenerator'
+import type { CanvasSelection } from '../composables/useCanvasSelection'
+import type { CanvasHistory } from '../composables/useCanvasHistory'
+import type { WireframeBlock, WireframeCanvasState, WireframeDataBinding } from '../../shared/wireframe-types'
+import type { WireframeCaptureProgress } from '../../shared/bridge-types'
+
+// Release-scope flags (deferred this release — see wireframeFeatures.ts).
+const dataBindingEnabled = WIREFRAME_DATA_BINDING_ENABLED
+const explodeEnabled = WIREFRAME_EXPLODE_ENABLED
+
+const props = defineProps<{
+  canvas: WireframeCanvasState | null
+  capturing: boolean
+  progress: WireframeCaptureProgress | null
+  error: string | null
+  /** Resolves a block's image (session dataUrl → sidecar file → null). */
+  imageSrc: (block: WireframeBlock) => string | null
+  deletedBlocks: WireframeBlock[]
+  /** Locked: a wireframe_apply task is implementing this sketch right now. */
+  building: boolean
+  implementing: boolean
+  /** Block selection (lifted to the mode so undo/redo can restore it). */
+  selection: CanvasSelection
+  /** Canvas undo/redo — the component brackets gestures; keys live in App. */
+  history: CanvasHistory
+  /** Place-first component config — drives the inline block popover. Null when
+   *  the host view doesn't offer the flow. */
+  generator?: ReturnType<typeof useComponentGenerator> | null
+  /** Block ids whose snapshot is rendering right now (drives the shimmer). */
+  generatingIds?: Set<string>
+}>()
+
+/** Is this block's snapshot currently rendering? */
+function isGenerating(b: WireframeBlock): boolean {
+  return props.generatingIds?.has(b.id) === true
+}
+
+/** Click-vs-drag threshold, min block dimension, duplicate offset, nudge step. */
+const DRAG_THRESHOLD_PX = 3
+const MIN_BLOCK_PX = 24
+const NUDGE_STEP_PX = 1
+const NUDGE_STEP_SHIFT_PX = 10
+const MARQUEE_MIN_PX = 6
+
+const emit = defineEmits<{
+  exit: []
+  recapture: []
+  implement: []
+  'undo-implementation': []
+  'explode-block': [id: string]
+  'update-rect': [id: string, rect: { x: number; y: number; width: number; height: number }]
+  'bring-to-front': [id: string]
+  'send-to-back': [id: string]
+  'bring-forward': [id: string]
+  'send-backward': [id: string]
+  'delete-block': [id: string]
+  'undelete-block': [id: string]
+  'duplicate-block': [id: string]
+  'set-note': [id: string, note: string]
+  'set-md': [id: string, md: string]
+  'set-data': [id: string, data: WireframeDataBinding | null]
+  'palette-drop': [at: { x: number; y: number }]
+  'add-placeholder': [rect: { x: number; y: number; width: number; height: number }, label: string]
+}>()
+
+const rootRef = ref<HTMLElement | null>(null)
+const stageRef = ref<HTMLElement | null>(null)
+const confirmRecapture = ref(false)
+const showDeleted = ref(false)
+
+const visibleBlocks = computed(() =>
+  (props.canvas?.blocks ?? [])
+    .filter((b) => !b.deleted)
+    .slice()
+    .sort((a, b) => a.z - b.z),
+)
+
+function blockLabel(b: WireframeBlock): string {
+  if (b.kind === 'placeholder') return b.label ?? 'placeholder'
+  if (b.kind === 'palette') return b.component?.componentName ?? b.component?.tag ?? 'component'
+  // Same priority as direction labels: class beats the shared page component.
+  return b.anchor?.cssClass || b.anchor?.sourceTag || b.anchor?.tag || b.anchor?.component || 'block'
+}
+
+function anchorChip(b: WireframeBlock): string | null {
+  if (b.kind !== 'captured' || !b.anchor?.file) return null
+  return `${b.anchor.file}:${b.anchor.line}`
+}
+
+/** Why a snapshot isn't a live render — shown as the fidelity pill's tooltip so
+ *  the state is actionable, not just labeled. */
+function fidelityReason(f: WireframeBlock['fidelity']): string {
+  if (f === 'isolated-preview') return 'Rendered outside the live app context (its providers/stores weren’t reachable) — may differ from production.'
+  if (f === 'placeholder') return 'Couldn’t render this component live here — it may not be imported in the running app, or it needs required props.'
+  return ''
+}
+
+// ── Selection (multi via shift-click / marquee) ───────────
+// State lives in the mode (props.selection) so undo/redo can restore it; the
+// component only adds editor-flag hygiene and focus on top.
+
+const selectedIds = computed(() => props.selection.selectedIds.value)
+const primaryBlock = computed(() => props.selection.primaryBlock.value)
+const isSelected = (id: string) => props.selection.isSelected(id)
+const selectedBlocks = () => props.selection.selectedBlocks()
+
+function select(id: string | null, additive = false): void {
+  closeEditors()
+  props.selection.select(id, additive)
+  if (id !== null) rootRef.value?.focus()
+}
+
+/** The note/markdown editors unmount with the selection — never leave a flag
+ *  set (it gates ALL canvas keys). Also called when undo/redo swaps selection
+ *  out from under an open editor. */
+function closeEditors(): void {
+  noteEditing.value = false
+  mdEditing.value = false
+}
+
+/** Focus the canvas root so keyboard shortcuts (Delete/Escape/arrow-nudge) work
+ *  immediately after a place-first drop/click — those go through
+ *  useWireframeMode.placeComponentBlock → selection.select directly, bypassing
+ *  the local select() wrapper (line below) that normally focuses on click. */
+function focusStage(): void {
+  rootRef.value?.focus()
+}
+defineExpose({ focusStage })
+
+// Undo/redo (and marquee) can change the primary block without going through
+// select() — close any open editor so a stale flag can't swallow keystrokes.
+watch(() => props.selection.primaryId.value, () => closeEditors())
+
+// ── Keyboard: delete / duplicate / Escape / arrow nudge ───
+
+function onKeydown(e: KeyboardEvent): void {
+  // Typing/picking — keys belong to the inputs, never to block ops. The
+  // target check covers inputs that bubble from INSIDE the canvas root (the
+  // inline config popover, its embedded picker) — without it, Backspace in a
+  // prop field deletes the selected block. The popover also stops its own
+  // keydowns, but this is the backstop for focused non-field controls.
+  const tag = (e.target as HTMLElement)?.tagName
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return
+  if (noteEditing.value || labelDraft.value !== null || mdEditing.value || dataPickerFor.value !== null) return
+  // Escape deselects, which closes the inline config popover (it's bound to the
+  // selection). The popover swallows its own Escape before it reaches here.
+  if (e.key === 'Escape') { select(null); drawMode.value = false; return }
+  if (props.building) return // sketch is locked while the agent implements it
+  const blocks = selectedBlocks()
+  if (blocks.length === 0) return
+  const mod = e.ctrlKey || e.metaKey
+  if (e.key === 'Delete' || e.key === 'Backspace') {
+    e.preventDefault()
+    // begin/end collapses the per-block deletes into ONE undo step.
+    props.history.begin()
+    for (const b of blocks) emit('delete-block', b.id)
+    props.history.end()
+    select(null)
+  } else if (mod && (e.key === 'd' || e.key === 'D')) {
+    e.preventDefault()
+    props.history.begin()
+    for (const b of blocks) emit('duplicate-block', b.id)
+    props.history.end()
+  } else if (e.key === '[' || e.key === ']') {
+    e.preventDefault()
+    nudgeZOrder(blocks, e.key === ']', mod)
+  } else if (e.key.startsWith('Arrow')) {
+    e.preventDefault()
+    // One coalesced entry per nudge burst (held/repeated keys merge); the
+    // rect updates themselves don't record.
+    props.history.record('nudge')
+    const step = e.shiftKey ? NUDGE_STEP_SHIFT_PX : NUDGE_STEP_PX
+    const dx = e.key === 'ArrowLeft' ? -step : e.key === 'ArrowRight' ? step : 0
+    const dy = e.key === 'ArrowUp' ? -step : e.key === 'ArrowDown' ? step : 0
+    for (const b of blocks) {
+      emit('update-rect', b.id, {
+        x: Math.max(0, b.rect.x + dx), y: Math.max(0, b.rect.y + dy),
+        width: b.rect.width, height: b.rect.height,
+      })
+    }
+  }
+}
+
+/** Z-order via keyboard: `]`/`[` step one layer, Ctrl/Cmd+`]`/`[` jump to
+ *  front/back. Processed in a z-order that preserves the group's relative
+ *  stacking; the whole batch is one undo step. */
+function nudgeZOrder(blocks: WireframeBlock[], forward: boolean, toEnd: boolean): void {
+  // front/back: stack so the originally-front block ends up front. forward/
+  // backward: step the trailing edge first so blocks don't leapfrog each other.
+  const ordered = [...blocks].sort((a, b) => (forward ? a.z - b.z : b.z - a.z))
+  props.history.begin()
+  for (const b of ordered) {
+    if (toEnd && forward) emit('bring-to-front', b.id)
+    else if (toEnd) emit('send-to-back', b.id)
+    else if (forward) emit('bring-forward', b.id)
+    else emit('send-backward', b.id)
+  }
+  props.history.end()
+}
+
+// ── Move / resize (window-level listeners) + snap guides ──
+
+const snapGuides = ref<SnapGuide[]>([])
+const dragState = ref<{
+  mode: 'move' | 'resize'
+  handle?: string
+  startX: number; startY: number
+  grabbedId: string
+  items: Array<{ id: string; origX: number; origY: number; origW: number; origH: number }>
+  moved: boolean
+} | null>(null)
+
+function beginDrag(e: PointerEvent, b: WireframeBlock, mode: 'move' | 'resize', handle?: string): void {
+  e.preventDefault()
+  e.stopPropagation()
+  select(b.id, e.shiftKey)
+  if (props.building) return // selection only — the sketch is locked
+  if (e.shiftKey) return // shift-click is selection surgery, never a drag
+  // bring-to-front is deferred to the first actual move (onDragMove): a plain
+  // click must not bump z, so it leaves no undo step behind.
+  const group = mode === 'move' ? selectedBlocks() : [b]
+  dragState.value = {
+    mode, handle,
+    startX: e.clientX, startY: e.clientY,
+    grabbedId: b.id,
+    items: group.map((g) => ({ id: g.id, origX: g.rect.x, origY: g.rect.y, origW: g.rect.width, origH: g.rect.height })),
+    moved: false,
+  }
+  window.addEventListener('pointermove', onDragMove)
+  window.addEventListener('pointerup', onDragUp)
+}
+
+function onDragMove(e: PointerEvent): void {
+  const d = dragState.value
+  if (!d) return
+  let dx = e.clientX - d.startX
+  let dy = e.clientY - d.startY
+  // Threshold separates click-to-select from an actual drag.
+  if (!d.moved && Math.abs(dx) + Math.abs(dy) < DRAG_THRESHOLD_PX) return
+  if (!d.moved) {
+    d.moved = true
+    // First real movement: open ONE history entry for the whole gesture, then
+    // raise the grabbed block (the z-bump rides inside this same undo step).
+    props.history.begin()
+    if (d.mode === 'move') emit('bring-to-front', d.grabbedId)
+  }
+
+  if (d.mode === 'move') {
+    // Snap by the GRABBED block against everything outside the moving group
+    // (Alt disables); the whole group follows the adjusted delta.
+    const grabbed = d.items.find((i) => i.id === d.grabbedId)!
+    const proposed = { x: grabbed.origX + dx, y: grabbed.origY + dy, width: grabbed.origW, height: grabbed.origH }
+    if (!e.altKey) {
+      const groupIds = new Set(d.items.map((i) => i.id))
+      const others = visibleBlocks.value.filter((b) => !groupIds.has(b.id)).map((b) => b.rect)
+      const snapped = computeSnap(proposed, others)
+      dx += snapped.x - proposed.x
+      dy += snapped.y - proposed.y
+      snapGuides.value = snapped.guides
+    } else {
+      snapGuides.value = []
+    }
+    for (const item of d.items) {
+      emit('update-rect', item.id, {
+        x: Math.max(0, item.origX + dx), y: Math.max(0, item.origY + dy),
+        width: item.origW, height: item.origH,
+      })
+    }
+    return
+  }
+
+  const item = d.items[0]
+  let x = item.origX, y = item.origY, w = item.origW, h = item.origH
+  const handle = d.handle || ''
+  if (handle.includes('e')) w = Math.max(MIN_BLOCK_PX, item.origW + dx)
+  if (handle.includes('s')) h = Math.max(MIN_BLOCK_PX, item.origH + dy)
+  if (handle.includes('w')) { w = Math.max(MIN_BLOCK_PX, item.origW - dx); x = item.origX + item.origW - w }
+  if (handle.includes('n')) { h = Math.max(MIN_BLOCK_PX, item.origH - dy); y = item.origY + item.origH - h }
+  emit('update-rect', item.id, { x: Math.max(0, x), y: Math.max(0, y), width: w, height: h })
+}
+
+function onDragUp(): void {
+  // Commit the gesture's single undo entry (no-op if it never moved).
+  if (dragState.value?.moved) props.history.end()
+  dragState.value = null
+  snapGuides.value = []
+  window.removeEventListener('pointermove', onDragMove)
+  window.removeEventListener('pointerup', onDragUp)
+}
+
+// ── Explode (double-click a captured block one level deeper) ──
+
+function onBlockDblClick(b: WireframeBlock): void {
+  if (!WIREFRAME_EXPLODE_ENABLED) return // deferred this release (see wireframeFeatures)
+  if (props.building || b.kind !== 'captured' || b.shell) return
+  emit('explode-block', b.id)
+}
+
+// ── Notes ─────────────────────────────────────────────────
+
+const noteEditing = ref(false)
+const noteDraft = ref('')
+const noteInputRef = ref<HTMLTextAreaElement | null>(null)
+
+function openNote(): void {
+  if (!primaryBlock.value) return
+  noteDraft.value = primaryBlock.value.note ?? ''
+  noteEditing.value = true
+  void nextTick(() => noteInputRef.value?.focus())
+}
+
+function commitNote(): void {
+  if (!noteEditing.value || !primaryBlock.value) return
+  emit('set-note', primaryBlock.value.id, noteDraft.value)
+  noteEditing.value = false
+}
+
+// ── Section markdown + data binding (drawn sections) ─────
+
+const mdEditing = ref(false)
+const mdDraft = ref('')
+const mdPreview = ref(false)
+const mdInputRef = ref<HTMLTextAreaElement | null>(null)
+/** Block id the binding picker is open for (null = closed). */
+const dataPickerFor = ref<string | null>(null)
+
+/** A placeholder with a markdown body or a binding IS a section — derived
+ *  affordance, not a new block kind. */
+function isSection(b: WireframeBlock): boolean {
+  return b.kind === 'placeholder' && (!!b.md || !!b.data)
+}
+
+function openMd(): void {
+  if (!primaryBlock.value) return
+  mdDraft.value = primaryBlock.value.md ?? ''
+  mdPreview.value = false
+  mdEditing.value = true
+  void nextTick(() => mdInputRef.value?.focus())
+}
+
+function commitMd(): void {
+  if (!mdEditing.value || !primaryBlock.value) return
+  emit('set-md', primaryBlock.value.id, mdDraft.value)
+  mdEditing.value = false
+}
+
+function cancelMd(): void {
+  mdEditing.value = false
+}
+
+function openDataPicker(id: string): void {
+  dataPickerFor.value = id
+}
+
+function onBindingSelect(binding: WireframeDataBinding): void {
+  if (dataPickerFor.value) emit('set-data', dataPickerFor.value, binding)
+  dataPickerFor.value = null
+}
+
+function onBindingClear(): void {
+  if (dataPickerFor.value) emit('set-data', dataPickerFor.value, null)
+  dataPickerFor.value = null
+}
+
+const pickerInitial = computed(() =>
+  dataPickerFor.value ? props.canvas?.blocks.find((b) => b.id === dataPickerFor.value)?.data ?? null : null)
+
+// ── Placeholder draw tool + marquee selection ─────────────
+
+const drawMode = ref(false)
+const drawRect = ref<{ x: number; y: number; width: number; height: number } | null>(null)
+const marqueeRect = ref<{ x: number; y: number; width: number; height: number } | null>(null)
+/** Non-null while the just-drawn placeholder waits for its label. */
+const labelDraft = ref<string | null>(null)
+const labelRect = ref<{ x: number; y: number; width: number; height: number } | null>(null)
+const labelInputRef = ref<HTMLInputElement | null>(null)
+let stageStart: { x: number; y: number } | null = null
+let stageGesture: 'draw' | 'marquee' | null = null
+let marqueeAdditive = false
+
+function stagePoint(e: PointerEvent | DragEvent): { x: number; y: number } {
+  const stage = stageRef.value
+  if (!stage) return { x: 0, y: 0 }
+  const r = stage.getBoundingClientRect()
+  return { x: e.clientX - r.left, y: e.clientY - r.top }
+}
+
+function onStagePointerDown(e: PointerEvent): void {
+  stageStart = stagePoint(e)
+  if (drawMode.value) {
+    stageGesture = 'draw'
+    drawRect.value = { ...stageStart, width: 0, height: 0 }
+  } else {
+    stageGesture = 'marquee'
+    marqueeAdditive = e.shiftKey
+    marqueeRect.value = { ...stageStart, width: 0, height: 0 }
+  }
+  window.addEventListener('pointermove', onStageMove)
+  window.addEventListener('pointerup', onStageUp)
+}
+
+function onStageMove(e: PointerEvent): void {
+  if (!stageStart) return
+  const p = stagePoint(e)
+  const rect = {
+    x: Math.min(stageStart.x, p.x),
+    y: Math.min(stageStart.y, p.y),
+    width: Math.abs(p.x - stageStart.x),
+    height: Math.abs(p.y - stageStart.y),
+  }
+  if (stageGesture === 'draw') drawRect.value = rect
+  else marqueeRect.value = rect
+}
+
+function onStageUp(): void {
+  window.removeEventListener('pointermove', onStageMove)
+  window.removeEventListener('pointerup', onStageUp)
+  const gesture = stageGesture
+  const draw = drawRect.value
+  const marquee = marqueeRect.value
+  stageStart = null
+  stageGesture = null
+  drawRect.value = null
+  marqueeRect.value = null
+
+  if (gesture === 'draw') {
+    drawMode.value = false
+    if (draw && draw.width >= MIN_BLOCK_PX && draw.height >= MIN_BLOCK_PX) {
+      labelRect.value = draw
+      labelDraft.value = ''
+      void nextTick(() => labelInputRef.value?.focus())
+    }
+    return
+  }
+
+  // Marquee: a real sweep selects every intersecting block; a click clears.
+  if (marquee && marquee.width + marquee.height > MARQUEE_MIN_PX) {
+    const hit = visibleBlocks.value.filter((b) =>
+      b.rect.x < marquee.x + marquee.width && b.rect.x + b.rect.width > marquee.x
+      && b.rect.y < marquee.y + marquee.height && b.rect.y + b.rect.height > marquee.y,
+    ).map((b) => b.id)
+    // Direct selection change — same editor-flag hygiene as select().
+    closeEditors()
+    props.selection.setSelection(marqueeAdditive ? [...new Set([...selectedIds.value, ...hit])] : hit)
+    if (hit.length) rootRef.value?.focus()
+  } else {
+    select(null)
+  }
+}
+
+function commitPlaceholder(): void {
+  if (labelDraft.value === null || !labelRect.value) return
+  const label = labelDraft.value.trim()
+  if (label) emit('add-placeholder', labelRect.value, label)
+  labelDraft.value = null
+  labelRect.value = null
+}
+
+function cancelPlaceholder(): void {
+  labelDraft.value = null
+  labelRect.value = null
+}
+
+// ── Palette drop (native HTML5 drag — no shield needed over the canvas) ──
+
+function onCanvasDrop(e: DragEvent): void {
+  e.preventDefault()
+  if (props.building) return
+  emit('palette-drop', stagePoint(e))
+}
+
+function onRecaptureConfirmed(): void {
+  confirmRecapture.value = false
+  emit('recapture')
+}
+</script>
+
+<template>
+  <div ref="rootRef" class="wireframe-canvas" data-testid="wireframe-canvas" tabindex="-1" @keydown="onKeydown">
+    <div class="wf-chrome">
+      <span class="wf-title">
+        <Icon name="frame" :size="12" />
+        Wireframe
+        <span class="wf-subtitle">sketch — rearranged images, not the live app</span>
+      </span>
+      <span v-if="canvas" class="wf-viewport" data-testid="wf-viewport"
+        title="Captured at this viewport — pick a device preset before capturing to wireframe mobile">{{ canvas.viewport.width }}×{{ canvas.viewport.height }} @{{ canvas.viewport.scale }}x</span>
+      <span v-if="capturing" class="wf-progress" data-testid="wf-progress">
+        Capturing{{ progress ? ` ${progress.index + 1}/${progress.total} — ${progress.label}` : '…' }}
+      </span>
+      <span v-else-if="error" class="wf-error">{{ error }}</span>
+      <span v-else-if="canvas?.truncated" class="wf-warn" title="Block discovery hit the 24-block cap — some page regions have no block">
+        capture truncated
+      </span>
+      <span v-if="building" class="wf-building" data-testid="wf-building">
+        Agent implementing — review the task in the Tasks panel
+      </span>
+      <span class="wf-spacer" />
+      <template v-if="building">
+        <button class="wf-btn" data-testid="wf-undo-implementation" @click="emit('undo-implementation')"
+          title="Delete the task and restore the pre-apply bytes — the sketch unlocks for editing">
+          <Icon name="rotate-ccw" :size="12" /> Undo this implementation
+        </button>
+      </template>
+      <button v-else class="wf-btn wf-implement" data-testid="wf-implement" :disabled="capturing || implementing"
+        @click="emit('implement')" title="Generate anchored directions + before/after screenshot and run the agent">
+        <Icon name="wand" :size="12" /> {{ implementing ? 'Implementing…' : 'Implement this wireframe' }}
+      </button>
+      <button v-if="!building" :class="['wf-btn', { 'wf-btn-active': drawMode }]" data-testid="wf-draw-placeholder" :disabled="capturing"
+        @click="drawMode = !drawMode" title="Draw a section — a labeled box, optionally with a markdown spec and a data binding">
+        <Icon name="square-plus" :size="12" /> Section
+      </button>
+      <div v-if="deletedBlocks.length" class="wf-deleted-wrap">
+        <button class="wf-btn" data-testid="wf-deleted-toggle" @click="showDeleted = !showDeleted"
+          :title="`${deletedBlocks.length} deleted block(s) — click to restore`">
+          <Icon name="trash" :size="12" /> {{ deletedBlocks.length }} deleted
+        </button>
+        <div v-if="showDeleted" class="wf-deleted-pop">
+          <div v-for="b in deletedBlocks" :key="b.id" class="wf-deleted-row">
+            <span>{{ blockLabel(b) }}</span>
+            <button class="wf-btn" :data-testid="`wf-undelete-${b.id}`" @click="emit('undelete-block', b.id)">restore</button>
+          </div>
+        </div>
+      </div>
+      <button class="wf-btn" data-testid="wf-recapture" :disabled="capturing || building" @click="confirmRecapture = true"
+        title="Discard this sketch and re-capture the live route">
+        <Icon name="refresh-cw" :size="12" /> Recapture
+      </button>
+      <button class="wf-btn wf-exit" data-testid="wf-exit" @click="emit('exit')"
+        title="Back to the live app (the sketch is kept)">
+        <Icon name="x" :size="12" /> Exit
+      </button>
+    </div>
+
+    <div v-if="capturing && !canvas" class="wf-empty">Capturing the page…</div>
+
+    <div v-else-if="canvas" class="wf-scroll"
+      @dragenter.prevent
+      @dragover.prevent
+      @drop="onCanvasDrop">
+      <div ref="stageRef" class="wf-stage" :class="{ drawing: drawMode }"
+        :style="{ width: canvas.viewport.docWidth + 'px', height: canvas.viewport.docHeight + 'px' }"
+        @pointerdown.self="onStagePointerDown">
+        <div v-for="b in visibleBlocks" :key="b.id"
+          class="wf-block"
+          :class="{ selected: isSelected(b.id), failed: !imageSrc(b) && b.kind === 'captured', placeholder: b.kind === 'placeholder', dragging: dragState?.moved && dragState.items.some((i) => i.id === b.id) }"
+          :data-block-id="b.id"
+          :style="{ left: b.rect.x + 'px', top: b.rect.y + 'px', width: b.rect.width + 'px', height: b.rect.height + 'px', zIndex: b.z }"
+          @pointerdown.stop="beginDrag($event, b, 'move')"
+          @dblclick.stop="onBlockDblClick(b)">
+          <img v-if="imageSrc(b)" :src="imageSrc(b)!" :alt="blockLabel(b)" draggable="false" />
+          <div v-else-if="b.kind === 'placeholder'" class="wf-placeholder-body" :class="{ section: isSection(b) }">
+            <span class="wf-placeholder-label">{{ b.label }}</span>
+            <span class="wf-placeholder-tag">{{ isSection(b) ? 'section' : 'placeholder' }}</span>
+            <!-- Sanitized markdown hint (clipped, non-interactive) — the
+                 verbatim body rides added.md; this is just the sketch view. -->
+            <div v-if="b.md" class="wf-md-hint" v-html="safeMd(b.md)" />
+          </div>
+          <!-- Palette block with no snapshot yet: honest placeholder while the
+               first render lands (place-first), or after a render produced no
+               pixels. Never a fabricated image. -->
+          <div v-else-if="b.kind === 'palette'" class="wf-palette-body">
+            <span class="wf-palette-label">{{ blockLabel(b) }}</span>
+            <span class="wf-palette-tag">{{ isGenerating(b) ? 'rendering…' : 'no render' }}</span>
+          </div>
+          <div v-else class="wf-block-failed">
+            <span>{{ b.captureError ? 'capture failed' : 'image missing' }}</span>
+            <span class="wf-failed-label">{{ blockLabel(b) }}</span>
+          </div>
+          <!-- Shimmer while this block's snapshot is rendering; the last-good
+               image (if any) stays visible underneath. -->
+          <div v-if="isGenerating(b)" class="wf-shimmer" data-testid="wf-shimmer" />
+          <div v-if="b.clipped" class="wf-clipped-note" title="Block was taller than the capture cap — only the top is shown">clipped</div>
+          <div v-if="b.note && primaryBlock?.id !== b.id" class="wf-note-chip" :title="b.note">
+            <Icon name="pencil" :size="9" /> note
+          </div>
+          <div v-if="b.kind === 'palette' && b.fidelity && b.fidelity !== 'live'" class="wf-fidelity-pill" :class="b.fidelity" :title="fidelityReason(b.fidelity)">
+            {{ b.fidelity === 'isolated-preview' ? 'isolated preview' : 'placeholder render' }}
+          </div>
+          <div v-if="b.data" class="wf-data-chip" :data-testid="`wf-data-chip-${b.id}`" :title="`bound to ${b.data.name}${b.data.path ? ' → ' + b.data.path : ''} [${b.data.shape_source}]`">
+            <Icon name="database" :size="9" /> {{ b.data.name }}<template v-if="b.data.path"> · {{ b.data.path }}</template><template v-if="b.data.repeat && b.data.repeat > 1"> · ×{{ b.data.repeat }}</template>
+          </div>
+
+          <template v-if="primaryBlock?.id === b.id && selectedIds.length === 1">
+            <div class="wf-block-header" @pointerdown.stop="beginDrag($event, b, 'move')">
+              <span class="wf-block-name">{{ blockLabel(b) }}</span>
+              <code v-if="anchorChip(b)" class="wf-anchor-chip" data-testid="wf-anchor-chip">{{ anchorChip(b) }}</code>
+              <span class="wf-header-spacer" />
+              <button v-if="explodeEnabled && b.kind === 'captured' && !b.shell" class="wf-hbtn" data-testid="wf-explode-btn" @pointerdown.stop @click.stop="onBlockDblClick(b)" title="Explode into child blocks (double-click)">
+                <Icon name="maximize-2" :size="10" />
+              </button>
+              <button class="wf-hbtn" data-testid="wf-note-btn" @pointerdown.stop @click.stop="openNote()" :title="b.note ? `Note: ${b.note}` : 'Add a note for the agent'">
+                <Icon name="pencil" :size="10" />
+              </button>
+              <button v-if="b.kind === 'placeholder'" class="wf-hbtn" data-testid="wf-md-btn" @pointerdown.stop @click.stop="openMd()" :title="b.md ? 'Edit the section\'s markdown spec' : 'Write a markdown spec for this section'">
+                <Icon name="file-text" :size="10" />
+              </button>
+              <button v-if="dataBindingEnabled && b.kind === 'placeholder'" class="wf-hbtn" data-testid="wf-data-btn" @pointerdown.stop @click.stop="openDataPicker(b.id)" :title="b.data ? `Bound to ${b.data.name} — change or clear` : 'Bind a data source'">
+                <Icon name="database" :size="10" />
+              </button>
+              <span class="wf-hbtn-sep" />
+              <button class="wf-hbtn" data-testid="wf-bring-to-front-btn" @pointerdown.stop @click.stop="emit('bring-to-front', b.id)" title="Bring to front (Ctrl+])">
+                <Icon name="bring-to-front" :size="10" />
+              </button>
+              <button class="wf-hbtn" data-testid="wf-bring-forward-btn" @pointerdown.stop @click.stop="emit('bring-forward', b.id)" title="Bring forward (])">
+                <Icon name="chevron-up" :size="10" />
+              </button>
+              <button class="wf-hbtn" data-testid="wf-send-backward-btn" @pointerdown.stop @click.stop="emit('send-backward', b.id)" title="Send backward ([)">
+                <Icon name="chevron-down" :size="10" />
+              </button>
+              <button class="wf-hbtn" data-testid="wf-send-to-back-btn" @pointerdown.stop @click.stop="emit('send-to-back', b.id)" title="Send to back (Ctrl+[)">
+                <Icon name="send-to-back" :size="10" />
+              </button>
+              <span class="wf-hbtn-sep" />
+              <button class="wf-hbtn" data-testid="wf-duplicate-btn" @pointerdown.stop @click.stop="emit('duplicate-block', b.id)" title="Duplicate (Ctrl+D)">
+                <Icon name="copy" :size="10" />
+              </button>
+              <button class="wf-hbtn wf-hbtn-danger" data-testid="wf-delete-btn" @pointerdown.stop @click.stop="emit('delete-block', b.id); select(null)" title="Delete (Del)">
+                <Icon name="trash" :size="10" />
+              </button>
+            </div>
+            <div v-if="noteEditing" class="wf-note-editor" @pointerdown.stop>
+              <textarea ref="noteInputRef" v-model="noteDraft" rows="2" data-testid="wf-note-input"
+                placeholder="Tell the agent about this block… (e.g. make this a carousel)"
+                @blur="commitNote" @keydown.enter.exact.prevent="commitNote" @keydown.escape.stop="noteEditing = false" />
+            </div>
+            <div v-if="mdEditing" class="wf-md-editor" @pointerdown.stop @click.stop>
+              <div class="wf-md-toolbar">
+                <button :class="['wf-md-tab', { active: !mdPreview }]" @click="mdPreview = false">Write</button>
+                <button :class="['wf-md-tab', { active: mdPreview }]" data-testid="wf-md-preview-toggle" @click="mdPreview = true">Preview</button>
+                <span class="wf-md-spacer" />
+                <button class="wf-md-tab" @click="cancelMd">Cancel</button>
+                <button class="wf-md-tab primary" data-testid="wf-md-save" @click="commitMd">Save</button>
+              </div>
+              <!-- Plain Enter = newline (multi-line markdown); Ctrl/Cmd+Enter commits. -->
+              <textarea v-if="!mdPreview" ref="mdInputRef" v-model="mdDraft" rows="7" data-testid="wf-md-input"
+                placeholder="Describe what you want here, in markdown… (## heading, - bullets)"
+                @keydown.enter.ctrl.prevent="commitMd" @keydown.enter.meta.prevent="commitMd" @keydown.escape.stop="cancelMd" />
+              <div v-else class="wf-md-preview" data-testid="wf-md-rendered" v-html="safeMd(mdDraft)" />
+            </div>
+            <!-- Inline config popover — "configure on canvas" for palette blocks.
+                 Opens with the selection; Escape / close deselects. -->
+            <WireframeBlockPopover v-if="b.kind === 'palette' && generator"
+              :block="b" :generator="generator" :generating="isGenerating(b)"
+              :doc-height="canvas?.viewport.docHeight"
+              @close="select(null)" />
+            <div class="resize-handle rh-n" @pointerdown.stop="beginDrag($event, b, 'resize', 'n')" />
+            <div class="resize-handle rh-s" @pointerdown.stop="beginDrag($event, b, 'resize', 's')" />
+            <div class="resize-handle rh-e" @pointerdown.stop="beginDrag($event, b, 'resize', 'e')" />
+            <div class="resize-handle rh-w" @pointerdown.stop="beginDrag($event, b, 'resize', 'w')" />
+            <div class="resize-handle rh-ne" @pointerdown.stop="beginDrag($event, b, 'resize', 'ne')" />
+            <div class="resize-handle rh-nw" @pointerdown.stop="beginDrag($event, b, 'resize', 'nw')" />
+            <div class="resize-handle rh-se" data-testid="wf-resize-se" @pointerdown.stop="beginDrag($event, b, 'resize', 'se')" />
+            <div class="resize-handle rh-sw" @pointerdown.stop="beginDrag($event, b, 'resize', 'sw')" />
+          </template>
+        </div>
+
+        <!-- Snap/align guide lines (visible mid-drag while a snap is active) -->
+        <template v-for="(g, i) in snapGuides" :key="`g${i}`">
+          <div v-if="g.axis === 'x'" class="wf-guide wf-guide-v" :style="{ left: g.at + 'px' }" />
+          <div v-else class="wf-guide wf-guide-h" :style="{ top: g.at + 'px' }" />
+        </template>
+
+        <!-- Marquee selection preview -->
+        <div v-if="marqueeRect && marqueeRect.width + marqueeRect.height > 6" class="wf-marquee"
+          :style="{ left: marqueeRect.x + 'px', top: marqueeRect.y + 'px', width: marqueeRect.width + 'px', height: marqueeRect.height + 'px' }" />
+
+        <!-- Placeholder drawing preview + label input -->
+        <div v-if="drawRect && drawRect.width > 4 && drawRect.height > 4" class="wf-draw-preview"
+          :style="{ left: drawRect.x + 'px', top: drawRect.y + 'px', width: drawRect.width + 'px', height: drawRect.height + 'px' }" />
+        <div v-if="labelDraft !== null && labelRect" class="wf-label-input"
+          :style="{ left: labelRect.x + 'px', top: labelRect.y + 'px', width: labelRect.width + 'px', height: labelRect.height + 'px' }">
+          <input ref="labelInputRef" v-model="labelDraft" data-testid="wf-placeholder-label"
+            placeholder="Label this placeholder… (e.g. pagination here)"
+            @keydown.enter.prevent="commitPlaceholder" @keydown.escape="cancelPlaceholder" @blur="commitPlaceholder" />
+        </div>
+
+      </div>
+    </div>
+
+    <div v-if="dataPickerFor" class="wf-picker-overlay" @pointerdown.self="dataPickerFor = null">
+      <DataBindingPicker :initial="pickerInitial" @select="onBindingSelect" @clear="onBindingClear" @cancel="dataPickerFor = null" />
+    </div>
+
+    <ConfirmDialog v-if="confirmRecapture"
+      message="Discard this sketch and re-capture the live route? Your rearrangement on this canvas will be lost."
+      confirmLabel="Recapture"
+      @confirm="onRecaptureConfirmed"
+      @cancel="confirmRecapture = false" />
+  </div>
+</template>
+
+<style scoped>
+.wireframe-canvas {
+  position: absolute;
+  inset: 0;
+  z-index: 60; /* above iframe + shields + overlays, below modals */
+  display: flex;
+  flex-direction: column;
+  background: var(--bg);
+  outline: none;
+}
+
+.wf-chrome {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+  font-size: 11px;
+  flex: 0 0 auto;
+}
+.wf-title {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-weight: 600;
+  color: var(--text);
+}
+.wf-subtitle { color: var(--text-muted); font-weight: 400; }
+.wf-viewport {
+  font-family: ui-monospace, monospace;
+  font-size: 10px;
+  color: var(--text-muted);
+  border: 1px solid var(--border);
+  border-radius: 3px;
+  padding: 1px 5px;
+}
+.wf-progress { color: var(--info); }
+.wf-error { color: var(--danger); }
+.wf-warn { color: var(--warning); }
+.wf-building { color: var(--status-in-progress, var(--info)); font-weight: 600; }
+.wf-implement {
+  background: var(--accent);
+  color: var(--text-on-accent);
+  border-color: var(--accent);
+}
+.wf-implement:hover:not(:disabled) { background: var(--accent-hover); }
+.wf-spacer { flex: 1; }
+.wf-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 11px;
+  padding: 3px 8px;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: var(--surface-2);
+  color: var(--text);
+  cursor: pointer;
+}
+.wf-btn:hover { border-color: var(--border-strong); }
+.wf-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+.wf-btn-active { border-color: var(--accent); color: var(--accent); }
+.wf-exit { background: color-mix(in srgb, var(--accent) 12%, transparent); }
+
+.wf-deleted-wrap { position: relative; }
+.wf-deleted-pop {
+  position: absolute;
+  top: calc(100% + 4px);
+  right: 0;
+  z-index: 10;
+  min-width: 180px;
+  background: var(--surface-elevated);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  padding: 6px;
+  box-shadow: 0 4px 16px var(--shadow);
+}
+.wf-deleted-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 2px 4px;
+  font-size: 11px;
+  color: var(--text);
+}
+
+.wf-empty {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--text-muted);
+  font-size: 12px;
+}
+
+.wf-scroll { flex: 1; overflow: auto; }
+.wf-stage {
+  position: relative;
+  /* The sketch keeps the capture's document coordinate space. */
+  background:
+    repeating-linear-gradient(0deg, transparent 0 23px, color-mix(in srgb, var(--border) 35%, transparent) 23px 24px),
+    repeating-linear-gradient(90deg, transparent 0 23px, color-mix(in srgb, var(--border) 35%, transparent) 23px 24px);
+}
+.wf-stage.drawing { cursor: crosshair; }
+
+.wf-block {
+  position: absolute;
+  box-sizing: border-box;
+  border: 1px solid transparent;
+  background: var(--surface);
+  overflow: hidden;
+  cursor: grab;
+}
+.wf-block.dragging { cursor: grabbing; opacity: 0.92; }
+.wf-block:hover { border-color: color-mix(in srgb, var(--accent) 50%, transparent); }
+.wf-block.selected { border-color: var(--accent); box-shadow: 0 0 0 1px var(--accent); overflow: visible; }
+.wf-block img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: fill;
+  user-select: none;
+  -webkit-user-drag: none;
+  pointer-events: none;
+}
+
+.wf-block.failed {
+  border: 1px dashed var(--border-strong);
+  background: repeating-linear-gradient(45deg, var(--surface) 0 8px, color-mix(in srgb, var(--border) 40%, transparent) 8px 16px);
+}
+.wf-block-failed {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  gap: 4px;
+  color: var(--text-muted);
+  font-size: 11px;
+}
+.wf-failed-label { font-size: 10px; opacity: 0.8; }
+
+.wf-block.placeholder {
+  border: 2px dashed color-mix(in srgb, var(--accent) 60%, transparent);
+  background: repeating-linear-gradient(45deg, transparent 0 10px, color-mix(in srgb, var(--accent) 8%, transparent) 10px 20px);
+}
+.wf-placeholder-body {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  gap: 4px;
+}
+.wf-placeholder-label { font-size: 12px; font-weight: 600; color: var(--text); }
+.wf-placeholder-tag {
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-muted);
+}
+/* Section affordance: a placeholder carrying a markdown spec or a binding. */
+.wf-placeholder-body.section { justify-content: flex-start; padding: 8px 10px 18px; align-items: flex-start; }
+.wf-placeholder-body.section .wf-placeholder-tag { color: var(--accent); }
+.wf-md-hint {
+  width: 100%;
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+  pointer-events: none;
+  font-size: 10px;
+  color: var(--text-muted);
+  text-align: left;
+}
+.wf-md-hint :deep(h1), .wf-md-hint :deep(h2), .wf-md-hint :deep(h3) { font-size: 11px; margin: 2px 0; color: var(--text); }
+.wf-md-hint :deep(p), .wf-md-hint :deep(ul) { margin: 2px 0; }
+.wf-md-hint :deep(ul) { padding-left: 14px; }
+
+.wf-clipped-note {
+  position: absolute;
+  bottom: 2px;
+  right: 4px;
+  font-size: 9px;
+  color: var(--warning);
+  background: color-mix(in srgb, var(--bg) 80%, transparent);
+  padding: 0 4px;
+  border-radius: 3px;
+}
+
+.wf-note-chip {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  font-size: 9px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: color-mix(in srgb, var(--warning) 25%, var(--bg));
+  color: var(--text);
+  pointer-events: none;
+}
+
+.wf-fidelity-pill {
+  position: absolute;
+  bottom: 4px;
+  left: 4px;
+  font-size: 9px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: color-mix(in srgb, var(--warning) 30%, var(--bg));
+  color: var(--text);
+  pointer-events: none;
+}
+
+.wf-data-chip {
+  position: absolute;
+  bottom: 4px;
+  right: 4px;
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  font-size: 9px;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: color-mix(in srgb, var(--info) 25%, var(--bg));
+  color: var(--text);
+  pointer-events: none;
+  max-width: 80%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Palette block awaiting (or lacking) a snapshot — honest, never a fake image. */
+.wf-palette-body {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  gap: 4px;
+  border: 1px dashed var(--border-strong);
+  border-radius: 4px;
+  background: var(--surface-2);
+}
+.wf-palette-label { font-size: 12px; font-weight: 600; color: var(--text); }
+.wf-palette-tag {
+  font-size: 9px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-muted);
+}
+
+/* Rendering shimmer — overlays the block (last-good image stays visible). */
+.wf-shimmer {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  border-radius: 2px;
+  background: linear-gradient(
+    100deg,
+    transparent 30%,
+    color-mix(in srgb, var(--accent) 22%, transparent) 50%,
+    transparent 70%
+  );
+  background-size: 220% 100%;
+  animation: wf-shimmer-slide 1.1s ease-in-out infinite;
+}
+@keyframes wf-shimmer-slide {
+  from { background-position: 180% 0; }
+  to { background-position: -80% 0; }
+}
+
+.wf-block-header {
+  position: absolute;
+  top: -22px;
+  left: -1px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 2px 6px;
+  height: 18px;
+  font-size: 10px;
+  white-space: nowrap;
+  background: var(--accent);
+  color: var(--text-on-accent);
+  border-radius: 4px 4px 0 0;
+  cursor: grab;
+  user-select: none;
+}
+.wf-block-name { font-weight: 600; }
+.wf-anchor-chip {
+  font-family: ui-monospace, monospace;
+  font-size: 9px;
+  opacity: 0.9;
+}
+.wf-header-spacer { width: 6px; }
+.wf-hbtn {
+  display: inline-flex;
+  align-items: center;
+  border: none;
+  background: transparent;
+  color: var(--text-on-accent);
+  cursor: pointer;
+  padding: 1px 2px;
+  opacity: 0.85;
+}
+.wf-hbtn:hover { opacity: 1; }
+.wf-hbtn-danger:hover { color: var(--danger); }
+.wf-hbtn-sep {
+  width: 1px;
+  align-self: stretch;
+  margin: 2px 3px;
+  background: color-mix(in srgb, var(--text-on-accent) 30%, transparent);
+}
+
+.wf-note-editor {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  width: min(280px, 100%);
+  z-index: 5;
+}
+.wf-note-editor textarea {
+  width: 100%;
+  box-sizing: border-box;
+  background: var(--surface-elevated);
+  border: 1px solid var(--accent);
+  border-radius: 4px;
+  color: var(--text);
+  font-size: 11px;
+  padding: 6px 8px;
+  resize: vertical;
+}
+
+/* Section markdown editor — same anchored-popover pattern as the note
+   editor but wider and multi-line, with a Write/Preview toggle. */
+.wf-md-editor {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  width: min(440px, 90vw);
+  z-index: 6;
+  background: var(--surface-elevated);
+  border: 1px solid var(--accent);
+  border-radius: 6px;
+  box-shadow: 0 8px 24px var(--shadow);
+  overflow: hidden;
+}
+.wf-md-toolbar {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 4px 6px;
+  border-bottom: 1px solid var(--border);
+}
+.wf-md-spacer { flex: 1; }
+.wf-md-tab {
+  padding: 2px 8px;
+  background: none;
+  border: 1px solid transparent;
+  border-radius: 4px;
+  color: var(--text-muted);
+  cursor: pointer;
+  font-size: 11px;
+}
+.wf-md-tab:hover { color: var(--text); }
+.wf-md-tab.active { background: var(--surface-2); color: var(--text); border-color: var(--border); }
+.wf-md-tab.primary { background: var(--accent); color: var(--text-on-accent); }
+.wf-md-editor textarea {
+  display: block;
+  width: 100%;
+  box-sizing: border-box;
+  background: var(--surface);
+  border: none;
+  color: var(--text);
+  font-size: 11px;
+  font-family: ui-monospace, monospace;
+  padding: 8px;
+  resize: vertical;
+  outline: none;
+}
+.wf-md-preview {
+  padding: 8px 10px;
+  font-size: 11px;
+  color: var(--text);
+  max-height: 220px;
+  overflow-y: auto;
+  cursor: text;
+}
+
+.wf-picker-overlay {
+  position: fixed;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--overlay);
+  z-index: 90;
+}
+
+.wf-guide {
+  position: absolute;
+  background: var(--accent);
+  opacity: 0.7;
+  pointer-events: none;
+  z-index: 9999;
+}
+.wf-guide-v { top: 0; bottom: 0; width: 1px; }
+.wf-guide-h { left: 0; right: 0; height: 1px; }
+
+.wf-marquee {
+  position: absolute;
+  border: 1px solid var(--accent);
+  background: color-mix(in srgb, var(--accent) 10%, transparent);
+  pointer-events: none;
+  z-index: 9999;
+}
+
+.wf-draw-preview {
+  position: absolute;
+  border: 2px dashed var(--accent);
+  background: color-mix(in srgb, var(--accent) 8%, transparent);
+  pointer-events: none;
+}
+.wf-label-input {
+  position: absolute;
+  border: 2px dashed color-mix(in srgb, var(--accent) 60%, transparent);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.wf-label-input input {
+  width: 90%;
+  background: var(--surface-elevated);
+  border: 1px solid var(--accent);
+  border-radius: 4px;
+  color: var(--text);
+  font-size: 11px;
+  padding: 4px 8px;
+}
+
+/* ── Resize handles (8-handle pattern) ── */
+.resize-handle { position: absolute; z-index: 6; }
+.rh-n  { top: -4px; left: 8px; right: 8px; height: 8px; cursor: n-resize; }
+.rh-s  { bottom: -4px; left: 8px; right: 8px; height: 8px; cursor: s-resize; }
+.rh-e  { right: -4px; top: 8px; bottom: 8px; width: 8px; cursor: e-resize; }
+.rh-w  { left: -4px; top: 8px; bottom: 8px; width: 8px; cursor: w-resize; }
+.rh-nw, .rh-ne, .rh-sw, .rh-se {
+  width: 10px; height: 10px;
+  background: var(--accent); border: 1.5px solid var(--text-on-accent);
+  border-radius: 2px;
+}
+.rh-nw { top: -5px; left: -5px; cursor: nw-resize; }
+.rh-ne { top: -5px; right: -5px; cursor: ne-resize; }
+.rh-sw { bottom: -5px; left: -5px; cursor: sw-resize; }
+.rh-se { bottom: -5px; right: -5px; cursor: se-resize; }
+</style>
diff --git a/src/shell/composables/__tests__/useAgentMode.test.ts b/src/shell/composables/__tests__/useAgentMode.test.ts
new file mode 100644
index 0000000..92376ea
--- /dev/null
+++ b/src/shell/composables/__tests__/useAgentMode.test.ts
@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest'
+import { requestAutoRun, consumeAutoRun, useAgentMode } from '../useAgentMode'
+
+describe('useAgentMode', () => {
+  it('enqueues a task id', () => {
+    const id = `task-${Math.random().toString(36).slice(2)}`
+    requestAutoRun(id)
+    expect(useAgentMode().pendingAutoRun.value.has(id)).toBe(true)
+  })
+
+  it('consumeAutoRun returns true once then false', () => {
+    const id = `task-${Math.random().toString(36).slice(2)}`
+    requestAutoRun(id)
+    expect(consumeAutoRun(id)).toBe(true)
+    expect(consumeAutoRun(id)).toBe(false)
+    expect(useAgentMode().pendingAutoRun.value.has(id)).toBe(false)
+  })
+
+  it('ignores empty ids', () => {
+    const before = useAgentMode().pendingAutoRun.value.size
+    requestAutoRun('')
+    expect(useAgentMode().pendingAutoRun.value.size).toBe(before)
+  })
+
+  it('is idempotent on duplicate enqueue', () => {
+    const id = `task-${Math.random().toString(36).slice(2)}`
+    requestAutoRun(id)
+    const sizeAfterFirst = useAgentMode().pendingAutoRun.value.size
+    requestAutoRun(id)
+    expect(useAgentMode().pendingAutoRun.value.size).toBe(sizeAfterFirst)
+    expect(consumeAutoRun(id)).toBe(true)
+  })
+
+  it('defaults to auto source', () => {
+    const id = `task-${Math.random().toString(36).slice(2)}`
+    requestAutoRun(id)
+    expect(useAgentMode().pendingAutoRun.value.get(id)).toBe('auto')
+    consumeAutoRun(id)
+  })
+
+  it('stores manual source', () => {
+    const id = `task-${Math.random().toString(36).slice(2)}`
+    requestAutoRun(id, 'manual')
+    expect(useAgentMode().pendingAutoRun.value.get(id)).toBe('manual')
+    consumeAutoRun(id)
+  })
+
+  it('consumeAutoRun respects allowedSources filter', () => {
+    const id = `task-${Math.random().toString(36).slice(2)}`
+    requestAutoRun(id, 'manual')
+    // The headless driver filters to 'auto' only — manual should be rejected
+    expect(consumeAutoRun(id, ['auto'])).toBe(false)
+    // The item is still in the queue
+    expect(useAgentMode().pendingAutoRun.value.has(id)).toBe(true)
+    // The Conversation tab consumes without filter — succeeds
+    expect(consumeAutoRun(id)).toBe(true)
+    expect(useAgentMode().pendingAutoRun.value.has(id)).toBe(false)
+  })
+
+  it('headless driver can consume auto-sourced items', () => {
+    const id = `task-${Math.random().toString(36).slice(2)}`
+    requestAutoRun(id, 'auto')
+    expect(consumeAutoRun(id, ['auto'])).toBe(true)
+    expect(useAgentMode().pendingAutoRun.value.has(id)).toBe(false)
+  })
+})
diff --git a/src/shell/composables/__tests__/useAgentModels.test.ts b/src/shell/composables/__tests__/useAgentModels.test.ts
new file mode 100644
index 0000000..a197d4c
--- /dev/null
+++ b/src/shell/composables/__tests__/useAgentModels.test.ts
@@ -0,0 +1,170 @@
+// @vitest-environment jsdom
+/**
+ * useAgentModels singleton composable — caching, dedup, refresh.
+ *
+ * The fetch boundary is mocked so we can verify:
+ *   - identical concurrent ensure() calls collapse to a single network call
+ *   - the localStorage cache survives a "page reload" (composable reset)
+ *   - refresh() bypasses the in-memory cache and issues a new fetch
+ *   - fetch failures surface as an `error` field with an Auto-only catalog,
+ *     so the UI can block selection of a specific model id (no curated
+ *     guesses — see src/server/agent-models.ts for the rationale).
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { useAgentModels, __resetAgentModelsCache } from '../useAgentModels'
+
+type MockFetch = ReturnType<typeof vi.fn> & {
+  responses: Array<() => Promise<Response>>
+}
+
+function makeMockFetch(): MockFetch {
+  const mock = vi.fn(async (input: RequestInfo) => {
+    const url = typeof input === 'string' ? input : input.toString()
+    const next = (mock as MockFetch).responses.shift()
+    if (!next) throw new Error(`Unexpected fetch: ${url}`)
+    return next()
+  }) as MockFetch
+  mock.responses = []
+  return mock
+}
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  }) as Response
+}
+
+beforeEach(() => {
+  __resetAgentModelsCache()
+  window.localStorage.clear()
+})
+
+describe('useAgentModels', () => {
+  it('returns an Auto-only catalog before any fetch lands', () => {
+    const m = useAgentModels()
+    const cat = m.catalogFor('opencode-local').value
+    expect(cat.models).toHaveLength(1)
+    expect(cat.models[0].id).toBe('') // Auto option only — no curated guesses
+    expect(cat.discovered).toBe(false)
+  })
+
+  it('dedupes concurrent ensure() calls into a single fetch', async () => {
+    const fetchMock = makeMockFetch()
+    fetchMock.responses.push(async () =>
+      jsonResponse({
+        cli: 'opencode-local',
+        discovered: true,
+        models: [
+          { id: '', label: 'Auto', source: 'auto' },
+          { id: 'openai/gpt-5.4', label: 'GPT-5.4', source: 'discovered' },
+        ],
+        cachedAt: Date.now(),
+      }),
+    )
+    vi.stubGlobal('fetch', fetchMock)
+    const m = useAgentModels()
+
+    const [a, b, c] = await Promise.all([
+      m.ensure('opencode-local'),
+      m.ensure('opencode-local'),
+      m.ensure('opencode-local'),
+    ])
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    expect(a.models.map(x => x.id)).toContain('openai/gpt-5.4')
+    expect(b).toBe(a)
+    expect(c).toBe(a)
+  })
+
+  it('refresh() bypasses the cache and re-fetches', async () => {
+    const fetchMock = makeMockFetch()
+    fetchMock.responses.push(
+      async () => jsonResponse({
+        cli: 'codex-local',
+        discovered: true,
+        models: [{ id: 'gpt-5.4', label: 'GPT-5.4', source: 'discovered' }],
+        cachedAt: Date.now(),
+      }),
+      async () => jsonResponse({
+        cli: 'codex-local',
+        discovered: true,
+        models: [{ id: 'gpt-5.5', label: 'GPT-5.5', source: 'discovered' }],
+        cachedAt: Date.now(),
+      }),
+    )
+    vi.stubGlobal('fetch', fetchMock)
+    const m = useAgentModels()
+
+    const first = await m.ensure('codex-local')
+    expect(first.models[0].id).toBe('gpt-5.4')
+    // Second ensure without refresh hits the cache — no new fetch.
+    await m.ensure('codex-local')
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    // refresh forces a new fetch and updates the catalog.
+    const refreshed = await m.refresh('codex-local')
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+    expect(refreshed.models[0].id).toBe('gpt-5.5')
+    // refresh URL carries ?refresh=1
+    const calls = (fetchMock as unknown as { mock: { calls: unknown[][] } }).mock.calls
+    expect(String(calls[1][0])).toContain('refresh=1')
+  })
+
+  it('survives a "page reload" via localStorage', async () => {
+    const fetchMock = makeMockFetch()
+    fetchMock.responses.push(async () => jsonResponse({
+      cli: 'opencode-local',
+      discovered: true,
+      models: [{ id: 'cached/model', label: 'cached/model', source: 'discovered' }],
+      cachedAt: Date.now(),
+    }))
+    vi.stubGlobal('fetch', fetchMock)
+    const m = useAgentModels()
+    await m.ensure('opencode-local')
+
+    // Simulate a fresh shell mount: blow away in-memory state, keep storage.
+    __resetAgentModelsCache.call(null) // also clears storage — undo that
+    // Re-seed storage from what we just learned (mirrors what persistToStorage does)
+    window.localStorage.setItem('annotask:agent:modelCatalog', JSON.stringify({
+      'opencode-local': {
+        cli: 'opencode-local',
+        discovered: true,
+        models: [{ id: 'cached/model', label: 'cached/model', source: 'discovered' }],
+        cachedAt: Date.now(),
+      },
+    }))
+
+    const m2 = useAgentModels()
+    const cat = m2.catalogFor('opencode-local').value
+    expect(cat.models.some(x => x.id === 'cached/model')).toBe(true)
+  })
+
+  it('blocks the picker (Auto-only + error) when the server returns an error', async () => {
+    const fetchMock = makeMockFetch()
+    fetchMock.responses.push(async () => new Response('boom', { status: 500 }) as Response)
+    vi.stubGlobal('fetch', fetchMock)
+    const m = useAgentModels()
+    const cat = await m.ensure('opencode-local')
+    expect(cat.models).toHaveLength(1)
+    expect(cat.models[0].id).toBe('') // Auto only — no curated fallback
+    expect(cat.discovered).toBe(false)
+    expect(m.state.errors['opencode-local']).toBeDefined()
+  })
+
+  it('surfaces the server `error` field when the probe returns Auto-only', async () => {
+    const fetchMock = makeMockFetch()
+    fetchMock.responses.push(async () => jsonResponse({
+      cli: 'copilot-local',
+      discovered: false,
+      models: [{ id: '', label: 'Auto (CLI default)', source: 'auto' }],
+      cachedAt: Date.now(),
+      error: 'copilot-local: no models returned by the live probe.',
+    }))
+    vi.stubGlobal('fetch', fetchMock)
+    const m = useAgentModels()
+    const cat = await m.ensure('copilot-local')
+    expect(cat.discovered).toBe(false)
+    expect(cat.error).toMatch(/no models returned/i)
+    expect(m.state.errors['copilot-local']).toBe(cat.error)
+  })
+})
diff --git a/src/shell/composables/__tests__/useAutoRunDriver.test.ts b/src/shell/composables/__tests__/useAutoRunDriver.test.ts
new file mode 100644
index 0000000..24c2666
--- /dev/null
+++ b/src/shell/composables/__tests__/useAutoRunDriver.test.ts
@@ -0,0 +1,87 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { ref } from 'vue'
+
+// drain() consults provider settings before touching the queue — force
+// embedded mode on so the regression tests exercise the queue loop itself
+// rather than the early-exit guard.
+vi.mock('../useProviderSettings', async () => {
+  const { ref } = await import('vue')
+  return {
+    useProviderSettings: () => ({
+      settings: ref({ embeddedAgentEnabled: true }),
+      ready: ref(true),
+    }),
+  }
+})
+
+import { requestAutoRunCancel, resetAutoRunDriverForTests, drainForTests } from '../useAutoRunDriver'
+import { useAgentMode, requestAutoRun, consumeAutoRun } from '../useAgentMode'
+
+function fakeTaskSystem() {
+  // drain only reads tasks.value.find — an empty list sends consumed ids
+  // down the "not in tasks.value — dropping" path, so no headless run spawns.
+  return { tasks: ref([]) } as unknown as Parameters<typeof drainForTests>[0]
+}
+
+describe('useAutoRunDriver cancel registry', () => {
+  beforeEach(() => {
+    resetAutoRunDriverForTests()
+  })
+
+  it('requestAutoRunCancel is a harmless no-op when no headless run is registered', () => {
+    // ConversationTab.cancelRun() always calls this alongside agent.abort();
+    // when the run is a local (non-headless) one or nothing is running, it
+    // must report false and do nothing rather than throw.
+    expect(requestAutoRunCancel('task-not-running')).toBe(false)
+  })
+
+  it('reset clears the registry so a stale hook never fires for a reused id', () => {
+    expect(requestAutoRunCancel('task-1')).toBe(false)
+    resetAutoRunDriverForTests()
+    expect(requestAutoRunCancel('task-1')).toBe(false)
+  })
+})
+
+describe('useAutoRunDriver drain', () => {
+  beforeEach(() => {
+    resetAutoRunDriverForTests()
+    // The auto-run queue is a module singleton — flush leftovers so each
+    // test starts from an empty queue.
+    const { pendingAutoRun } = useAgentMode()
+    for (const id of [...pendingAutoRun.value.keys()]) consumeAutoRun(id)
+    vi.restoreAllMocks()
+  })
+
+  it('returns instead of busy-looping when the only queued item is a manual run', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    requestAutoRun('task-manual', 'manual')
+
+    // Regression: consumeAutoRun(id, ['auto']) refuses manual items WITHOUT
+    // removing them. Before the skip-set fix, drain re-read the same queue
+    // head and `continue`d with no await — a tight synchronous loop that
+    // froze the tab whenever "Run with agent" enqueued a manual item before
+    // ConversationTab could mount and claim it. This await never resolved.
+    await drainForTests(fakeTaskSystem())
+
+    // The manual item must stay queued for the Conversation tab to claim…
+    expect(useAgentMode().pendingAutoRun.value.get('task-manual')).toBe('manual')
+    // …and drain must have skipped it exactly once, not spun on it.
+    const manualWarns = warnSpy.mock.calls.filter((c) => String(c[0]).includes('task-manual'))
+    expect(manualWarns).toHaveLength(1)
+  })
+
+  it('skips past a manual head and still processes a later auto item', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    requestAutoRun('task-manual', 'manual')
+    requestAutoRun('task-auto', 'auto')
+
+    await drainForTests(fakeTaskSystem())
+
+    const queue = useAgentMode().pendingAutoRun.value
+    // The auto item behind the manual head was consumed (then dropped —
+    // its task isn't in tasks.value)…
+    expect(queue.has('task-auto')).toBe(false)
+    // …while the manual one survived for the Conversation tab.
+    expect(queue.get('task-manual')).toBe('manual')
+  })
+})
diff --git a/src/shell/composables/__tests__/useCanvasHistory.test.ts b/src/shell/composables/__tests__/useCanvasHistory.test.ts
new file mode 100644
index 0000000..b6b0d5f
--- /dev/null
+++ b/src/shell/composables/__tests__/useCanvasHistory.test.ts
@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { useCanvasHistory } from '../useCanvasHistory'
+
+/** Minimal document the history snapshots: a value + a selection list. */
+interface Doc { value: number; sel: string[] }
+
+function harness(initial: Doc = { value: 0, sel: [] }) {
+  let state: Doc = JSON.parse(JSON.stringify(initial))
+  const history = useCanvasHistory<Doc>(
+    () => state,
+    (s) => { state = s },
+  )
+  return {
+    history,
+    get: () => state,
+    set: (d: Doc) => { state = d },
+  }
+}
+
+describe('useCanvasHistory', () => {
+  it('record() captures the pre-mutation state; undo restores it, redo re-applies', () => {
+    const h = harness({ value: 1, sel: ['a'] })
+    h.history.record()
+    h.set({ value: 2, sel: ['b'] })
+
+    expect(h.history.canUndo.value).toBe(true)
+    expect(h.history.canRedo.value).toBe(false)
+
+    h.history.undo()
+    expect(h.get()).toEqual({ value: 1, sel: ['a'] })
+    expect(h.history.canRedo.value).toBe(true)
+
+    h.history.redo()
+    expect(h.get()).toEqual({ value: 2, sel: ['b'] })
+  })
+
+  it('restores the selection alongside the value (one snapshot covers both)', () => {
+    const h = harness({ value: 0, sel: ['x', 'y'] })
+    h.history.record()
+    h.set({ value: 5, sel: ['z'] })
+    h.history.undo()
+    expect(h.get().sel).toEqual(['x', 'y'])
+  })
+
+  it('a new record() after undo clears the redo stack (no branching)', () => {
+    const h = harness({ value: 0, sel: [] })
+    h.history.record(); h.set({ value: 1, sel: [] })
+    h.history.undo()
+    expect(h.history.canRedo.value).toBe(true)
+    h.history.record(); h.set({ value: 9, sel: [] })
+    expect(h.history.canRedo.value).toBe(false)
+  })
+
+  it('begin()/end() collapse a multi-step gesture into ONE undo entry', () => {
+    const h = harness({ value: 0, sel: [] })
+    h.history.begin()
+    // Several mutations inside the gesture; inner record() calls no-op.
+    h.set({ value: 1, sel: [] }); h.history.record('rect')
+    h.set({ value: 2, sel: [] }); h.history.record('rect')
+    h.set({ value: 3, sel: [] })
+    h.history.end()
+
+    h.history.undo()
+    expect(h.get().value).toBe(0)        // one step back to the pre-gesture state
+    expect(h.history.canUndo.value).toBe(false)
+  })
+
+  it('end() drops a no-op gesture (a click that never moved)', () => {
+    const h = harness({ value: 7, sel: ['a'] })
+    h.history.begin()
+    h.history.end()                       // nothing changed
+    expect(h.history.canUndo.value).toBe(false)
+  })
+
+  describe('coalescing (rapid same-key records merge into one entry)', () => {
+    beforeEach(() => vi.useFakeTimers())
+    afterEach(() => vi.useRealTimers())
+
+    it('merges same-key records within the time window, splits after it', () => {
+      const h = harness({ value: 0, sel: [] })
+      h.history.record('nudge'); h.set({ value: 1, sel: [] })
+      vi.advanceTimersByTime(100)
+      h.history.record('nudge'); h.set({ value: 2, sel: [] }) // coalesced — no new entry
+      vi.advanceTimersByTime(100)
+      h.history.record('nudge'); h.set({ value: 3, sel: [] }) // still coalesced
+
+      h.history.undo()
+      expect(h.get().value).toBe(0)        // single entry back to the start
+      expect(h.history.canUndo.value).toBe(false)
+
+      // After the window elapses, a fresh entry is cut.
+      h.set({ value: 3, sel: [] })
+      h.history.record('nudge'); h.set({ value: 4, sel: [] })
+      vi.advanceTimersByTime(1000)
+      h.history.record('nudge'); h.set({ value: 5, sel: [] })
+      h.history.undo()
+      expect(h.get().value).toBe(4)        // only the last burst undone
+    })
+
+    it('different keys never coalesce', () => {
+      const h = harness({ value: 0, sel: [] })
+      h.history.record('a'); h.set({ value: 1, sel: [] })
+      h.history.record('b'); h.set({ value: 2, sel: [] })
+      h.history.undo(); expect(h.get().value).toBe(1)
+      h.history.undo(); expect(h.get().value).toBe(0)
+    })
+  })
+
+  it('caps the undo stack at the configured limit (drops the oldest)', () => {
+    let state = { value: 0, sel: [] as string[] }
+    const history = useCanvasHistory<typeof state>(() => state, (s) => { state = s }, { limit: 3 })
+    for (let i = 1; i <= 5; i++) { history.record(); state = { value: i, sel: [] } }
+    // 5 records, limit 3 → only the 3 newest pasts remain.
+    let undos = 0
+    while (history.canUndo.value) { history.undo(); undos++ }
+    expect(undos).toBe(3)
+    expect(state.value).toBe(2)            // oldest reachable state (0 and 1 dropped)
+  })
+
+  it('clear() empties both stacks', () => {
+    const h = harness()
+    h.history.record(); h.set({ value: 1, sel: [] })
+    h.history.clear()
+    expect(h.history.canUndo.value).toBe(false)
+    expect(h.history.canRedo.value).toBe(false)
+  })
+})
diff --git a/src/shell/composables/__tests__/useCanvasSelection.test.ts b/src/shell/composables/__tests__/useCanvasSelection.test.ts
new file mode 100644
index 0000000..66284cf
--- /dev/null
+++ b/src/shell/composables/__tests__/useCanvasSelection.test.ts
@@ -0,0 +1,90 @@
+import { describe, it, expect } from 'vitest'
+import { ref } from 'vue'
+import { useCanvasSelection } from '../useCanvasSelection'
+import type { WireframeBlock, WireframeCanvasState } from '../../../shared/wireframe-types'
+
+/** Minimal block — selection only cares about id + deleted. */
+function blk(id: string, deleted = false): WireframeBlock {
+  return { id, kind: 'placeholder', rect: { x: 0, y: 0, width: 10, height: 10 }, z: 0, createdAt: 1, ...(deleted ? { deleted: true } : {}) }
+}
+
+function canvasOf(...blocks: WireframeBlock[]) {
+  return ref<WireframeCanvasState | null>({
+    capturedAt: 1,
+    viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 1 },
+    blocks,
+  })
+}
+
+describe('useCanvasSelection', () => {
+  it('single select replaces; primary is the (only) selected id', () => {
+    const sel = useCanvasSelection(canvasOf(blk('a'), blk('b')))
+    sel.select('a')
+    expect(sel.selectedIds.value).toEqual(['a'])
+    expect(sel.primaryId.value).toBe('a')
+    expect(sel.primaryBlock.value?.id).toBe('a')
+
+    sel.select('b')
+    expect(sel.selectedIds.value).toEqual(['b'])
+    expect(sel.isSelected('a')).toBe(false)
+  })
+
+  it('additive select toggles membership and keeps primary = last-selected', () => {
+    const sel = useCanvasSelection(canvasOf(blk('a'), blk('b'), blk('c')))
+    sel.select('a')
+    sel.select('b', true)
+    sel.select('c', true)
+    expect(sel.selectedIds.value).toEqual(['a', 'b', 'c'])
+    expect(sel.primaryId.value).toBe('c')
+
+    // Additive re-click REMOVES (toggle off).
+    sel.select('b', true)
+    expect(sel.selectedIds.value).toEqual(['a', 'c'])
+    expect(sel.isSelected('b')).toBe(false)
+  })
+
+  it('re-clicking inside a multi-selection keeps the group and promotes to primary (no collapse)', () => {
+    const sel = useCanvasSelection(canvasOf(blk('a'), blk('b'), blk('c')))
+    sel.setSelection(['a', 'b', 'c'])
+    expect(sel.primaryId.value).toBe('c')
+
+    // Plain (non-additive) click on an already-selected member must NOT collapse
+    // to a single selection — it promotes that member to primary.
+    sel.select('a')
+    expect(sel.selectedIds.value).toEqual(['b', 'c', 'a'])
+    expect(sel.primaryId.value).toBe('a')
+  })
+
+  it('select(null) and clear() empty the selection', () => {
+    const sel = useCanvasSelection(canvasOf(blk('a')))
+    sel.select('a')
+    sel.select(null)
+    expect(sel.selectedIds.value).toEqual([])
+    sel.setSelection(['a'])
+    sel.clear()
+    expect(sel.selectedIds.value).toEqual([])
+    expect(sel.primaryId.value).toBeNull()
+    expect(sel.primaryBlock.value).toBeNull()
+  })
+
+  it('setSelection prunes ids that no longer resolve to a live block', () => {
+    const sel = useCanvasSelection(canvasOf(blk('a'), blk('b'), blk('gone-deleted', true)))
+    // 'ghost' was removed entirely; 'gone-deleted' is soft-deleted — both pruned.
+    sel.setSelection(['a', 'ghost', 'gone-deleted', 'b'])
+    expect(sel.selectedIds.value).toEqual(['a', 'b'])
+  })
+
+  it('primaryBlock and selectedBlocks exclude soft-deleted blocks', () => {
+    const canvas = canvasOf(blk('a'), blk('b'))
+    const sel = useCanvasSelection(canvas)
+    sel.setSelection(['a', 'b'])
+    expect(sel.selectedBlocks().map((b) => b.id)).toEqual(['a', 'b'])
+
+    // 'b' gets soft-deleted after selection — it drops out of selectedBlocks,
+    // and a primary pointing at it resolves to null (the live-block lookup skips it).
+    canvas.value!.blocks = [blk('a'), blk('b', true)]
+    expect(sel.selectedBlocks().map((b) => b.id)).toEqual(['a'])
+    expect(sel.primaryId.value).toBe('b')      // id is still tracked…
+    expect(sel.primaryBlock.value).toBeNull()  // …but it no longer resolves to a live block
+  })
+})
diff --git a/src/shell/composables/__tests__/useComponentGenerator.test.ts b/src/shell/composables/__tests__/useComponentGenerator.test.ts
new file mode 100644
index 0000000..4f1e014
--- /dev/null
+++ b/src/shell/composables/__tests__/useComponentGenerator.test.ts
@@ -0,0 +1,380 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { computed, reactive, ref } from 'vue'
+
+// useComponentGenerator pulls in useComponentLibrary, whose module state
+// subscribes to the shared WebSocket client — stub it like the other tests.
+vi.mock('../../services/wsClient', () => ({
+  on: () => () => {},
+  send: () => {},
+  isConnected: () => true,
+}))
+
+import { useComponentGenerator, type ComponentGeneratorDeps } from '../useComponentGenerator'
+import type { PaletteDragItem } from '../usePaletteDrag'
+import type { WireframeBlock, WireframePaletteRef, WireframeDataBinding } from '../../../shared/wireframe-types'
+import type { PaletteSnapshot } from '../useWireframeMode'
+
+const SNAPSHOT = { mounted: true, fidelity: 'isolated-preview', dataUrl: 'data:image/png;base64,xx', width: 320, height: 100 }
+
+/** A manually-resolvable promise — lets a test hold a previewComponent call
+ *  in-flight to exercise supersession / mid-flight deletion. */
+function deferred<T>() {
+  let resolve!: (v: T) => void
+  const promise = new Promise<T>((r) => { resolve = r })
+  return { promise, resolve }
+}
+
+/** Drain the microtask queue (the runGenerate async chain) — independent of the
+ *  fake timer clock, which only governs the debounce setTimeout. */
+async function flush(times = 6): Promise<void> {
+  for (let i = 0; i < times; i++) await Promise.resolve()
+}
+
+function makeDeps(surfaceMfe?: () => string | null) {
+  const buildingFlag = ref(false)
+  const blocks = new Map<string, WireframeBlock>()
+  let counter = 0
+
+  const previewComponent = vi.fn<ComponentGeneratorDeps['iframe']['previewComponent']>(async () => ({ ...SNAPSHOT }))
+  const placeComponentBlock = vi.fn((componentRef: WireframePaletteRef, at: { x: number; y: number }) => {
+    const id = `wfb-${++counter}`
+    blocks.set(id, {
+      id,
+      kind: 'palette',
+      rect: { x: at.x, y: at.y, width: 320, height: 120 },
+      z: 1,
+      createdAt: 1,
+      component: JSON.parse(JSON.stringify(componentRef)) as WireframePaletteRef,
+      fidelity: 'placeholder',
+    })
+    return id
+  })
+  const updatePaletteBlock = vi.fn(async (
+    id: string,
+    patch: { props?: Record<string, unknown>; previewProps?: Record<string, unknown>; data?: WireframeDataBinding | null; snapshot?: PaletteSnapshot },
+    _opts?: { recordHistory?: boolean },
+  ) => {
+    const b = blocks.get(id)
+    if (!b || !b.component) return
+    if (patch.props !== undefined) {
+      if (Object.keys(patch.props).length > 0) b.component.props = JSON.parse(JSON.stringify(patch.props))
+      else delete b.component.props
+    }
+    if (patch.previewProps !== undefined) b.component.previewProps = JSON.parse(JSON.stringify(patch.previewProps))
+    if (patch.data !== undefined) { if (patch.data) b.data = JSON.parse(JSON.stringify(patch.data)); else delete b.data }
+    if (patch.snapshot) {
+      b.fidelity = patch.snapshot.fidelity ?? (patch.snapshot.mounted ? 'isolated-preview' : 'placeholder')
+      if (patch.snapshot.dataUrl) b.image = `${id}.png`
+    }
+  })
+  const findBlock = vi.fn((id: string) => blocks.get(id) ?? null)
+  const setGenerating = vi.fn((_id: string, _on: boolean) => {})
+
+  const deps: ComponentGeneratorDeps = {
+    iframe: { previewComponent },
+    wireframe: { placeComponentBlock, updatePaletteBlock, findBlock, building: computed(() => buildingFlag.value), setGenerating },
+    ...(surfaceMfe ? { surfaceMfe } : {}),
+  }
+  return { deps, buildingFlag, blocks, previewComponent, placeComponentBlock, updatePaletteBlock, findBlock, setGenerating }
+}
+
+function item(extra: Partial<PaletteDragItem> = {}): PaletteDragItem {
+  return {
+    kind: 'component',
+    componentName: 'PlanetCard',
+    tag: 'planetcard',
+    label: 'PlanetCard',
+    library: 'Project',
+    module: './src/components/PlanetCard.vue',
+    previewProps: { name: 'Mercury' },
+    ...extra,
+  }
+}
+
+const BINDING: WireframeDataBinding = {
+  kind: 'composable',
+  name: 'usePlanets',
+  module: 'src/composables/usePlanets.ts',
+  path: 'planets[]',
+  fields: ['name', 'type'],
+  shape_source: 'api-schema',
+}
+
+describe('useComponentGenerator (place-first)', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+    // Catalog fetches from useComponentLibrary.load() — keep them inert.
+    vi.stubGlobal('fetch', vi.fn(async () => ({ ok: false, json: async () => ({}) })))
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  it('placeComponent mints the block immediately and fills its snapshot', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 40, y: 60 })
+    expect(id).toBe('wfb-1')
+    // Block minted synchronously at the drop point, imageless placeholder.
+    const [refArg, atArg] = d.placeComponentBlock.mock.calls[0]
+    expect(refArg).toMatchObject({ componentName: 'PlanetCard', module: './src/components/PlanetCard.vue', previewProps: { name: 'Mercury' } })
+    expect(atArg).toEqual({ x: 40, y: 60 })
+    // Background fill renders and writes the snapshot WITHOUT recording history.
+    await flush()
+    expect(d.previewComponent).toHaveBeenCalledTimes(1)
+    const [, props, module, width] = d.previewComponent.mock.calls[0]
+    expect(props).toEqual({ name: 'Mercury' })
+    expect(module).toBe('./src/components/PlanetCard.vue')
+    expect(width).toBe(320)
+    const [fid, patch, opts] = d.updatePaletteBlock.mock.calls[0]
+    expect(fid).toBe(id)
+    expect(patch.snapshot).toMatchObject({ dataUrl: SNAPSHOT.dataUrl, fidelity: 'isolated-preview' })
+    expect(opts).toEqual({ recordHistory: false })
+    expect(d.blocks.get(id!)?.fidelity).toBe('isolated-preview')
+  })
+
+  it('stamps the surface MFE on the placed block when the item has none', () => {
+    const d = makeDeps(() => 'checkout')
+    const gen = useComponentGenerator(d.deps)
+    gen.placeComponent(item(), { x: 0, y: 0 })
+    expect(d.placeComponentBlock.mock.calls[0][0]).toMatchObject({ mfe: 'checkout' })
+  })
+
+  it("prefers the item's own MFE over the surface MFE", () => {
+    const d = makeDeps(() => 'checkout')
+    const gen = useComponentGenerator(d.deps)
+    gen.placeComponent(item({ mfe: 'admin' }), { x: 0, y: 0 })
+    expect(d.placeComponentBlock.mock.calls[0][0]).toMatchObject({ mfe: 'admin' })
+  })
+
+  it('does not place while the sketch is locked to a task', () => {
+    const d = makeDeps()
+    d.buildingFlag.value = true
+    const gen = useComponentGenerator(d.deps)
+    expect(gen.placeComponent(item(), { x: 0, y: 0 })).toBeNull()
+    expect(d.placeComponentBlock).not.toHaveBeenCalled()
+  })
+
+  it('strips reactive proxies before the previewComponent boundary', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const reactiveItem = reactive(item({ previewProps: { name: 'Mercury' } })) as PaletteDragItem
+    gen.placeComponent(reactiveItem, { x: 0, y: 0 })
+    await flush()
+    const props = d.previewComponent.mock.calls[0][1]
+    expect(props).toEqual({ name: 'Mercury' })
+    expect(props).not.toBe(reactiveItem.previewProps)
+  })
+
+  it('setProp merges samples + real (real wins) and regenerates after the debounce', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    d.previewComponent.mockClear()
+
+    gen.setProp(id, 'name', 'Venus')
+    // Prop mutation is synchronous + recorded (recordHistory not false).
+    const propCall = d.updatePaletteBlock.mock.calls.find((c) => c[1].props)!
+    expect(propCall[1].props).toEqual({ name: 'Venus' })
+    expect(propCall[2]?.recordHistory).not.toBe(false)
+    // No render yet — it's debounced.
+    expect(d.previewComponent).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(375)
+    await flush()
+    expect(d.previewComponent).toHaveBeenCalledTimes(1)
+    expect(d.previewComponent.mock.calls[0][1]).toEqual({ name: 'Venus' }) // real over the Mercury sample
+  })
+
+  it('setBinding writes the binding and regenerates', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    d.previewComponent.mockClear()
+
+    gen.setBinding(id, BINDING)
+    expect(d.blocks.get(id)?.data).toEqual(BINDING)
+    vi.advanceTimersByTime(375)
+    await flush()
+    expect(d.previewComponent).toHaveBeenCalledTimes(1)
+  })
+
+  it('drops a superseded in-flight render (only the latest snapshot lands)', async () => {
+    const d = makeDeps()
+    const defs: Array<ReturnType<typeof deferred<typeof SNAPSHOT>>> = []
+    d.previewComponent.mockImplementation(() => {
+      const def = deferred<typeof SNAPSHOT>()
+      defs.push(def)
+      return def.promise
+    })
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })! // first fill → render A (pending)
+    await flush()
+    gen.setProp(id, 'name', 'Venus')
+    vi.advanceTimersByTime(375)
+    await flush() // regen → render B (pending)
+    expect(defs.length).toBe(2)
+
+    // Resolve the NEWER render first, then the stale one.
+    defs[1].resolve({ ...SNAPSHOT, dataUrl: 'data:image/png;base64,B' })
+    await flush()
+    defs[0].resolve({ ...SNAPSHOT, dataUrl: 'data:image/png;base64,A' })
+    await flush()
+
+    const snapshotWrites = d.updatePaletteBlock.mock.calls.filter((c) => c[1].snapshot)
+    expect(snapshotWrites.length).toBe(1) // the stale render A was dropped
+    expect(snapshotWrites[0][1].snapshot?.dataUrl).toBe('data:image/png;base64,B')
+  })
+
+  it('no-ops a render whose block was deleted mid-flight', async () => {
+    const d = makeDeps()
+    const def = deferred<typeof SNAPSHOT>()
+    d.previewComponent.mockImplementation(() => def.promise)
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    d.blocks.delete(id) // user undid the drop before the render returned
+    def.resolve({ ...SNAPSHOT })
+    await flush()
+    const snapshotWrites = d.updatePaletteBlock.mock.calls.filter((c) => c[1].snapshot)
+    expect(snapshotWrites.length).toBe(0)
+  })
+
+  it('degrades honestly to placeholder fidelity when a render has no pixels', async () => {
+    const d = makeDeps()
+    d.previewComponent.mockResolvedValue({ mounted: false, fidelity: 'placeholder', error: 'no-runtime' } as never)
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    const snap = d.updatePaletteBlock.mock.calls.find((c) => c[1].snapshot)![1].snapshot
+    expect(snap?.fidelity).toBe('placeholder')
+    expect(d.blocks.get(id)?.fidelity).toBe('placeholder')
+  })
+
+  it('cancel() clears a pending regen so it never fires', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    d.previewComponent.mockClear()
+    gen.setProp(id, 'name', 'Venus')
+    gen.cancel()
+    vi.advanceTimersByTime(375)
+    await flush()
+    expect(d.previewComponent).not.toHaveBeenCalled()
+  })
+
+  it('setProp is inert while the sketch is locked', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    d.updatePaletteBlock.mockClear()
+    d.buildingFlag.value = true
+    gen.setProp(id, 'name', 'Venus')
+    expect(d.updatePaletteBlock).not.toHaveBeenCalled()
+  })
+
+  const LIST_BINDING: WireframeDataBinding = {
+    kind: 'composable', name: 'usePlanets', module: 'src/composables/usePlanets.ts',
+    path: 'planets[]', fields: ['name'], shape_source: 'api-schema',
+  }
+
+  it('renders a list binding as N instances with REAL example values', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    gen.setBinding(id, { ...LIST_BINDING, repeat: 3, sample: [{ name: 'Mercury' }, { name: 'Venus' }, { name: 'Earth' }] })
+    gen.setPropBinding(id, 'label', 'name')
+    d.previewComponent.mockClear()
+    vi.advanceTimersByTime(375)
+    await flush()
+    const opts = d.previewComponent.mock.calls[0][4]
+    expect(opts?.repeat).toBe(3)
+    expect(opts?.instanceProps).toEqual([{ label: 'Mercury' }, { label: 'Venus' }, { label: 'Earth' }])
+  })
+
+  it('falls back to {field} tokens when the contract has no example', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    gen.setBinding(id, { ...LIST_BINDING }) // no sample, no repeat
+    gen.setPropBinding(id, 'label', 'name')
+    d.previewComponent.mockClear()
+    vi.advanceTimersByTime(375)
+    await flush()
+    const opts = d.previewComponent.mock.calls[0][4]
+    expect(opts?.repeat).toBe(3) // list path defaults to 3 instances
+    expect(opts?.instanceProps).toEqual([{ label: '{name}' }, { label: '{name}' }, { label: '{name}' }])
+  })
+
+  it('setPropBinding sets then clears a field→prop mapping', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    gen.setBinding(id, { ...LIST_BINDING })
+    gen.setPropBinding(id, 'label', 'name')
+    expect(d.blocks.get(id)!.data!.propMap).toEqual({ label: 'name' })
+    gen.setPropBinding(id, 'label', null)
+    expect(d.blocks.get(id)!.data!.propMap).toBeUndefined()
+  })
+
+  it('produces a structured-clone-safe instanceProps payload for nested-object sample values', async () => {
+    // Regression: a mapped field value can be a nested object/array (legit for
+    // api-schema bindings). Read off the REACTIVE block, each such value is a
+    // Vue proxy — structuredClone (postMessage) throws DataCloneError on it,
+    // silently degrading the block's preview to a permanent placeholder. The
+    // payload crossing the bridge must be plain JSON.
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+
+    gen.setBinding(id, {
+      ...LIST_BINDING,
+      repeat: 2,
+      // A nested object + array per row — the api-schema case that proxies.
+      sample: [
+        { name: 'Mercury', meta: { moons: 0, tags: ['rocky'] } },
+        { name: 'Venus', meta: { moons: 0, tags: ['rocky', 'hot'] } },
+      ],
+    })
+    gen.setPropBinding(id, 'detail', 'meta')
+
+    // Force the block (and its sample rows) to be a live reactive proxy, as it
+    // is in the running app — so `row[field]` yields a proxied nested object.
+    const block = d.blocks.get(id)!
+    block.data = reactive(block.data!) as typeof block.data
+
+    d.previewComponent.mockClear()
+    vi.advanceTimersByTime(375)
+    await flush()
+
+    const opts = d.previewComponent.mock.calls[0][4]
+    expect(opts?.instanceProps).toEqual([
+      { detail: { moons: 0, tags: ['rocky'] } },
+      { detail: { moons: 0, tags: ['rocky', 'hot'] } },
+    ])
+    // The whole options payload must survive the postMessage clone boundary.
+    expect(() => structuredClone(opts)).not.toThrow()
+  })
+
+  it('setRepeat clamps to [1,24]', async () => {
+    const d = makeDeps()
+    const gen = useComponentGenerator(d.deps)
+    const id = gen.placeComponent(item(), { x: 0, y: 0 })!
+    await flush()
+    gen.setBinding(id, { ...LIST_BINDING })
+    gen.setRepeat(id, 100)
+    expect(d.blocks.get(id)!.data!.repeat).toBe(24)
+    gen.setRepeat(id, 2)
+    expect(d.blocks.get(id)!.data!.repeat).toBe(2)
+  })
+})
diff --git a/src/shell/composables/__tests__/useDesignSession.test.ts b/src/shell/composables/__tests__/useDesignSession.test.ts
new file mode 100644
index 0000000..5d2bb51
--- /dev/null
+++ b/src/shell/composables/__tests__/useDesignSession.test.ts
@@ -0,0 +1,452 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { useDesignSession } from '../useDesignSession'
+import { useStyleEditor } from '../useStyleEditor'
+import type { InsertChangeRecord } from '../useStyleEditor'
+
+function emptyServerDoc(rev?: number) {
+  return { version: '1.0', sessionId: 'ds-server', startedAt: 0, updatedAt: 0, ...(rev !== undefined ? { rev } : {}), entries: [] }
+}
+
+function jsonResponse(status: number, body: unknown) {
+  return { ok: status >= 200 && status < 300, status, json: async () => body }
+}
+
+const meta = { file: 'src/App.vue', line: '10', component: 'App' }
+
+function placementInput(instanceId: string, overrides: Partial<Parameters<ReturnType<typeof useDesignSession>['record']>[0]> = {}) {
+  const change: InsertChangeRecord = {
+    id: `wf-${instanceId}`,
+    type: 'component_insert',
+    description: 'Place <PlanetCard> append div',
+    file: 'src/pages/PlanetsPage.vue',
+    section: 'template',
+    line: 9,
+    component: 'PlanetsPage',
+    insert_position: 'append',
+    inserted: { tag: 'planetcard' },
+  }
+  return {
+    change,
+    anchor: { file: 'src/pages/PlanetsPage.vue', line: 9, position: 'append' as const },
+    route: '/planets',
+    eid: `container-${instanceId}`,
+    instanceId,
+    ...overrides,
+  }
+}
+
+describe('useDesignSession journal', () => {
+  let session: ReturnType<typeof useDesignSession>
+  let editor: ReturnType<typeof useStyleEditor>
+
+  beforeEach(() => {
+    session = useDesignSession()
+    session.clear()
+    session.sessionRoute.value = '/planets'
+    session.activeBreakpointId.value = null
+    editor = useStyleEditor()
+  })
+
+  describe('append-or-amend', () => {
+    it('amends the journal entry during a continuous gesture (slider drag = one entry)', () => {
+      editor.applyStyle('e-1', 'color', 'red', '', meta)
+      editor.applyStyle('e-1', 'color', 'blue', '', meta)
+      editor.applyStyle('e-1', 'color', 'green', '', meta)
+
+      expect(session.entries.value).toHaveLength(1)
+      const c = session.entries.value[0].change
+      expect(c.type).toBe('style_update')
+      if (c.type === 'style_update') {
+        expect(c.before).toBe('') // preserved from first touch
+        expect(c.after).toBe('green')
+      }
+    })
+
+    it('appends on a non-adjacent re-edit so ordered undo steps back through actions', () => {
+      editor.applyStyle('e-1', 'color', 'red', '', meta)
+      editor.applyStyle('e-1', 'padding', '10px', '0px', meta)
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+
+      // Journal: 3 ordered entries; projection: 2 collapsed records.
+      expect(session.entries.value).toHaveLength(3)
+      expect(editor.changes.value).toHaveLength(2)
+      const color = editor.changes.value[0]
+      if (color.type === 'style_update') {
+        expect(color.before).toBe('') // first touch
+        expect(color.after).toBe('blue') // latest value
+      }
+
+      // Undo reverts ONLY the latest action (blue → red), not the whole group.
+      const undoInfo = editor.undo()
+      expect(undoInfo).toEqual({ type: 'style', eid: 'e-1', property: 'color', value: 'red' })
+      const colorAfterUndo = editor.changes.value[0]
+      if (colorAfterUndo.type === 'style_update') expect(colorAfterUndo.after).toBe('red')
+    })
+
+    it('amends per-eid during a group-selection gesture instead of appending per tick', () => {
+      // Tick 1: applyToGroup loops both eids; tick 2 repeats with a new value.
+      editor.applyStyle('e-1', 'color', 'red', '', meta)
+      editor.applyStyle('e-2', 'color', 'red', '', meta)
+      editor.applyStyle('e-1', 'color', 'blue', '', meta)
+      editor.applyStyle('e-2', 'color', 'blue', '', meta)
+
+      expect(session.entries.value).toHaveLength(2)
+      expect(editor.changes.value).toHaveLength(2)
+    })
+
+    it('splits collapse keys by breakpoint', () => {
+      editor.applyStyle('e-1', 'padding', '20px', '10px', meta)
+      session.activeBreakpointId.value = 'iphone-se'
+      editor.applyStyle('e-1', 'padding', '8px', '20px', meta)
+
+      expect(session.entries.value).toHaveLength(2)
+      expect(session.entries.value[0].breakpointId).toBeNull()
+      expect(session.entries.value[1].breakpointId).toBe('iphone-se')
+      expect(editor.changes.value).toHaveLength(2)
+    })
+
+    it('does not amend an entry that was snapshotted into a task or already applied', () => {
+      editor.applyStyle('e-1', 'color', 'red', '', meta)
+      const entry = session.entries.value[0]
+      session.setLiveState(entry.id, { status: 'written', applyBatchId: 'ab-1' })
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+
+      expect(session.entries.value).toHaveLength(2)
+      expect(session.entries.value[0].live.status).toBe('written')
+      expect(session.entries.value[1].live.status).toBe('pending')
+    })
+  })
+
+  describe('placements in the journal', () => {
+    it('interleaves placement-create with style edits in one ordered undo stack', () => {
+      editor.applyStyle('e-1', 'color', 'red', '', meta)
+      session.record(placementInput('wfi-1'))
+      editor.applyStyle('e-1', 'padding', '10px', '0px', meta)
+
+      // Undo 1: the padding edit.
+      expect(editor.undo()).toEqual({ type: 'style', eid: 'e-1', property: 'padding', value: '0px' })
+      // Undo 2: the placement — returns the delete descriptor for doUndo.
+      expect(editor.undo()).toEqual({ type: 'placement_delete', instanceId: 'wfi-1' })
+      // Undo 3: the first style edit.
+      expect(editor.undo()).toEqual({ type: 'style', eid: 'e-1', property: 'color', value: '' })
+      expect(editor.undo()).toBeNull()
+    })
+
+    it('keeps placement entries out of the changes/report projection', () => {
+      session.record(placementInput('wfi-1'))
+      expect(editor.changes.value).toHaveLength(0)
+      expect(editor.report.value).toBeNull()
+    })
+
+    it('keeps placement entries through clearChanges/removeChangesFor (wireframe lifecycle owns them)', () => {
+      session.record(placementInput('wfi-1'))
+      editor.applyStyle('e-1', 'color', 'red', '', { ...meta, file: 'src/pages/PlanetsPage.vue', line: '9' })
+
+      editor.removeChangesFor('src/pages/PlanetsPage.vue', 9)
+      expect(session.entries.value).toHaveLength(1)
+      expect(session.entries.value[0].instanceId).toBe('wfi-1')
+
+      editor.clearChanges()
+      expect(session.entries.value).toHaveLength(1)
+    })
+
+    it('removeByInstanceId drops the placement entry (deletePlacement path)', () => {
+      session.record(placementInput('wfi-1'))
+      session.record(placementInput('wfi-2'))
+      session.removeByInstanceId('wfi-1')
+      expect(session.entries.value).toHaveLength(1)
+      expect(session.entries.value[0].instanceId).toBe('wfi-2')
+    })
+  })
+
+  describe('live-state projection', () => {
+    it('excludes written/applying entries from changes and report (no double-apply)', () => {
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+      editor.applyStyle('e-1', 'padding', '10px', '0px', meta)
+      const [colorEntry, paddingEntry] = session.entries.value
+
+      session.setLiveState(colorEntry.id, { status: 'written', applyBatchId: 'ab-1', writtenAt: 1 })
+      expect(editor.changes.value).toHaveLength(1)
+      expect(editor.report.value!.changes).toHaveLength(1)
+
+      session.setLiveState(paddingEntry.id, { status: 'applying', applyBatchId: 'ab-2' })
+      expect(editor.changes.value).toHaveLength(0)
+      expect(editor.report.value).toBeNull()
+    })
+
+    it('keeps failed entries visible (they are pending work again)', () => {
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+      session.setLiveState(session.entries.value[0].id, { status: 'failed', error: 'not found in source' })
+      expect(editor.changes.value).toHaveLength(1)
+    })
+  })
+
+  describe('persistence (debounced CAS PUT)', () => {
+    let fetchMock: ReturnType<typeof vi.fn>
+
+    beforeEach(async () => {
+      fetchMock = vi.fn(async () => jsonResponse(200, emptyServerDoc()))
+      vi.stubGlobal('fetch', fetchMock)
+      session.readOnly.value = false
+      session.syncError.value = null
+      // Drain any flush queued by the outer clear(), then reset module rev
+      // state by adopting a fresh empty server doc.
+      await session.queueFlushNow()
+      await session.load()
+      fetchMock.mockClear()
+      vi.useFakeTimers()
+    })
+
+    afterEach(async () => {
+      await vi.runAllTimersAsync()
+      vi.useRealTimers()
+      vi.unstubAllGlobals()
+    })
+
+    it('debounces mutations into one single-flight PUT of the whole journal', async () => {
+      fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+        if (init?.method === 'PUT') {
+          const body = JSON.parse(init.body as string)
+          return jsonResponse(200, { ...body, rev: (body.rev ?? 0) + 1 })
+        }
+        return jsonResponse(200, emptyServerDoc())
+      })
+
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+      editor.applyStyle('e-1', 'color', 'green', 'red', meta) // amends within the window
+      expect(fetchMock).not.toHaveBeenCalled()
+
+      await vi.advanceTimersByTimeAsync(350)
+      const puts = fetchMock.mock.calls.filter((c) => (c[1] as RequestInit | undefined)?.method === 'PUT')
+      expect(puts).toHaveLength(1)
+      const body = JSON.parse((puts[0][1] as RequestInit).body as string)
+      expect(body.version).toBe('1.0')
+      expect(body.entries).toHaveLength(1)
+      expect(body.entries[0].change.after).toBe('green')
+
+      // The stamped rev round-trips on the next flush.
+      editor.applyStyle('e-1', 'padding', '10px', '0px', meta)
+      await vi.advanceTimersByTimeAsync(350)
+      const puts2 = fetchMock.mock.calls.filter((c) => (c[1] as RequestInit | undefined)?.method === 'PUT')
+      expect(puts2).toHaveLength(2)
+      expect(JSON.parse((puts2[1][1] as RequestInit).body as string).rev).toBe(1)
+    })
+
+    it('merges on 409 (server wins live/taskId, local wins presence) and retries once', async () => {
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+      const localEntry = session.entries.value[0]
+      const serverDoc = {
+        version: '1.0', sessionId: 'ds-server', startedAt: 5, updatedAt: 6, rev: 7,
+        entries: [
+          { ...JSON.parse(JSON.stringify(localEntry)), live: { status: 'written', applyBatchId: 'ab-1' }, taskId: 'task-9' },
+          { id: 'se-99', ordinal: 99, ts: 9, route: '/planets', change: { id: 'c-99', type: 'style_update', description: 'x', file: 'b.vue', section: 'style', line: 1, element: 'p', property: 'color', before: 'a', after: 'b' }, anchor: { file: 'b.vue', line: 1 }, live: { status: 'pending' } },
+        ],
+      }
+      let putCount = 0
+      fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+        if (init?.method === 'PUT') {
+          putCount++
+          if (putCount === 1) return jsonResponse(409, { error: { code: 'conflict', message: 'stale' } })
+          const body = JSON.parse(init.body as string)
+          return jsonResponse(200, { ...body, rev: (body.rev ?? 0) + 1 })
+        }
+        return jsonResponse(200, serverDoc)
+      })
+
+      await vi.advanceTimersByTimeAsync(350)
+      expect(putCount).toBe(2)
+      expect(session.readOnly.value).toBe(false)
+      // Server's live/taskId adopted on our entry; foreign entry appended.
+      expect(localEntry.live.status).toBe('written')
+      expect(localEntry.taskId).toBe('task-9')
+      expect(session.entries.value.map((e) => e.id)).toContain('se-99')
+    })
+
+    it('goes read-only with a banner after two conflicts in a row', async () => {
+      fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+        if (init?.method === 'PUT') return jsonResponse(409, { error: { code: 'conflict', message: 'stale' } })
+        return jsonResponse(200, emptyServerDoc(7))
+      })
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+      await vi.advanceTimersByTimeAsync(350)
+      expect(session.readOnly.value).toBe(true)
+      expect(session.syncError.value).toMatch(/another tab/)
+    })
+
+    it('load() adopts the persisted journal and reseeds counters', async () => {
+      const persisted = {
+        version: '1.0', sessionId: 'ds-restored', startedAt: 5, updatedAt: 6, rev: 3,
+        entries: [
+          { id: 'se-7', ordinal: 7, ts: 1, route: '/planets', change: { id: 'c-7', type: 'style_update', description: 'x', file: 'a.vue', section: 'style', line: 9, element: 'h1', property: 'color', before: 'red', after: 'blue' }, anchor: { file: 'a.vue', line: 9 }, live: { status: 'pending' } },
+        ],
+      }
+      fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+        if (init?.method === 'PUT') {
+          const body = JSON.parse(init.body as string)
+          return jsonResponse(200, { ...body, rev: (body.rev ?? 0) + 1 })
+        }
+        return jsonResponse(200, persisted)
+      })
+
+      await session.load()
+      expect(session.entries.value).toHaveLength(1)
+
+      editor.applyStyle('e-1', 'padding', '10px', '0px', meta)
+      const fresh = session.entries.value[1]
+      expect(fresh.id).toBe('se-8')
+      expect(fresh.ordinal).toBe(8)
+    })
+  })
+
+  describe('reload restore (reapplyPreviews)', () => {
+    it('replays single-element style/class previews, re-stamps eids, and marks loop anchors stale', async () => {
+      editor.applyStyle('e-old', 'color', 'blue', 'red', { file: 'a.vue', line: '5', component: 'A' })
+      editor.recordClassChange('e-old2', 'x', 'y', { file: 'a.vue', line: '6', component: 'A' })
+      const [styleEntry, classEntry] = session.entries.value
+
+      const iframe = {
+        findTemplateGroup: vi.fn(async (_file: string, line: string) =>
+          line === '5' ? { eids: ['e-new'] } : { eids: ['a', 'b'] }),
+        applyStyleVia: vi.fn(async () => 'before'),
+        setClass: vi.fn(async () => 'before'),
+      }
+
+      await session.reapplyPreviews('/planets', iframe, { force: true })
+      expect(iframe.applyStyleVia).toHaveBeenCalledWith('e-new', 'color', 'blue')
+      expect(styleEntry.eid).toBe('e-new')
+      // The class edit's anchor resolved to a 2-element loop group — replaying
+      // one element's edit onto all N would be a silent fake → stale badge.
+      expect(iframe.setClass).not.toHaveBeenCalled()
+      expect(session.staleEntryIds.value).toContain(classEntry.id)
+      expect(session.staleEntryIds.value).not.toContain(styleEntry.id)
+
+      // De-dup: same route without force is a no-op.
+      await session.reapplyPreviews('/planets', iframe)
+      expect(iframe.applyStyleVia).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('agent-apply client ops', () => {
+    let fetchMock: ReturnType<typeof vi.fn>
+
+    beforeEach(async () => {
+      fetchMock = vi.fn(async () => jsonResponse(200, emptyServerDoc()))
+      vi.stubGlobal('fetch', fetchMock)
+      session.readOnly.value = false
+      session.lastError.value = null
+      session.snapshotState.value = { files: {}, batches: [] }
+      await session.queueFlushNow()
+      await session.load()
+      fetchMock.mockClear()
+    })
+
+    afterEach(() => {
+      vi.unstubAllGlobals()
+    })
+
+    it('applyNow flushes, POSTs the route, and returns the minted task/batch', async () => {
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+      session.sessionRoute.value = '/planets'
+      fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+        if (String(url).endsWith('/design-session/apply')) {
+          expect(JSON.parse(init!.body as string)).toEqual({ route: '/planets' })
+          return jsonResponse(200, { taskId: 'task-9', batchId: 'ab-1', entryIds: ['se-1'], instanceIds: [] })
+        }
+        if (String(url).endsWith('/design-session/snapshots')) {
+          return jsonResponse(200, { files: { 'src/App.vue': { baseHash: 'x', status: 'clean' } }, batches: [{ id: 'ab-1', taskId: 'task-9', files: ['src/App.vue'], startedAt: 1, status: 'running' }] })
+        }
+        if (init?.method === 'PUT') {
+          const body = JSON.parse(init.body as string)
+          return jsonResponse(200, { ...body, rev: (body.rev ?? 0) + 1 })
+        }
+        return jsonResponse(200, emptyServerDoc(2))
+      })
+
+      const result = await session.applyNow()
+      expect(result).toEqual({ taskId: 'task-9', batchId: 'ab-1' })
+      expect(session.lastError.value).toBeNull()
+      expect(session.snapshotState.value.batches.map((b) => b.id)).toEqual(['ab-1'])
+      // The journal was flushed BEFORE the apply POST.
+      const calls = fetchMock.mock.calls.map((c) => `${(c[1] as RequestInit | undefined)?.method ?? 'GET'} ${c[0]}`)
+      const putIdx = calls.findIndex((c) => c.startsWith('PUT'))
+      const applyIdx = calls.findIndex((c) => c.includes('/apply'))
+      expect(putIdx).toBeGreaterThanOrEqual(0)
+      expect(putIdx).toBeLessThan(applyIdx)
+    })
+
+    it('applyNow surfaces server refusals in lastError', async () => {
+      fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+        if (String(url).endsWith('/design-session/apply')) {
+          return jsonResponse(400, { error: { code: 'invalid_body', message: 'nothing to apply' } })
+        }
+        if (init?.method === 'PUT') {
+          const body = JSON.parse(init.body as string)
+          return jsonResponse(200, { ...body, rev: (body.rev ?? 0) + 1 })
+        }
+        return jsonResponse(200, emptyServerDoc())
+      })
+      expect(await session.applyNow()).toBeNull()
+      expect(session.lastError.value).toMatch(/nothing to apply/)
+    })
+
+    it('undoLastBatch POSTs the newest batch id and reports unrestorable files', async () => {
+      session.snapshotState.value = {
+        files: { 'src/App.vue': { baseHash: 'x', status: 'clean' } },
+        batches: [
+          { id: 'ab-1', taskId: 't1', files: ['src/App.vue'], startedAt: 1, status: 'done' },
+          { id: 'ab-2', taskId: 't2', files: ['src/App.vue'], startedAt: 2, status: 'done' },
+        ],
+      }
+      fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+        if (String(url).endsWith('/design-session/undo-batch')) {
+          expect(JSON.parse(init!.body as string)).toEqual({ batchId: 'ab-2' })
+          return jsonResponse(200, { reverted: [], skipped: ['src/App.vue'] })
+        }
+        if (String(url).endsWith('/design-session/snapshots')) return jsonResponse(200, { files: {}, batches: [] })
+        return jsonResponse(200, emptyServerDoc())
+      })
+      const result = await session.undoLastBatch()
+      expect(result).toEqual({ reverted: [], skipped: ['src/App.vue'] })
+      expect(session.lastError.value).toMatch(/outside Annotask/)
+    })
+
+    it('journal undo refuses to pop written/applying tails (batch undo owns them)', async () => {
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+      session.setLiveState(session.entries.value[0].id, { status: 'written', applyBatchId: 'ab-1' })
+      expect(editor.undo()).toBeNull()
+      expect(session.entries.value).toHaveLength(1)
+    })
+
+    it('discardSession DELETEs and resets local state', async () => {
+      editor.applyStyle('e-1', 'color', 'blue', 'red', meta)
+      fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+        if (init?.method === 'DELETE') {
+          return jsonResponse(200, { revertedFiles: ['src/App.vue'], failedFiles: [], removedInstances: 1 })
+        }
+        if (String(url).endsWith('/design-session/snapshots')) return jsonResponse(200, { files: {}, batches: [] })
+        if (init?.method === 'PUT') {
+          const body = JSON.parse(init.body as string)
+          return jsonResponse(200, { ...body, rev: (body.rev ?? 0) + 1 })
+        }
+        return jsonResponse(200, emptyServerDoc(9))
+      })
+      const result = await session.discardSession()
+      expect(result).toMatchObject({ revertedFiles: ['src/App.vue'], removedInstances: 1 })
+      expect(session.entries.value).toHaveLength(0)
+    })
+  })
+
+  describe('envelope', () => {
+    it('stamps route, eid, ordinal, and anchor on recorded entries', () => {
+      session.sessionRoute.value = '/moons'
+      editor.applyStyle('e-9', 'color', 'blue', 'red', meta)
+      const e = session.entries.value[0]
+      expect(e.route).toBe('/moons')
+      expect(e.eid).toBe('e-9')
+      expect(e.ordinal).toBeGreaterThan(0)
+      expect(e.anchor).toMatchObject({ file: 'src/App.vue', line: 10, component: 'App' })
+      expect(e.live).toEqual({ status: 'pending' })
+    })
+  })
+})
diff --git a/src/shell/composables/__tests__/useEmbeddedAgent.test.ts b/src/shell/composables/__tests__/useEmbeddedAgent.test.ts
new file mode 100644
index 0000000..542ebd8
--- /dev/null
+++ b/src/shell/composables/__tests__/useEmbeddedAgent.test.ts
@@ -0,0 +1,464 @@
+/**
+ * Tests for the embedded-agent composable's work-stream + queue behaviour
+ * plus the seed-run lifecycle transitions (pending→in_progress→review).
+ *
+ * Provider streaming + the real task system are mocked so we exercise the
+ * composable's branching logic directly. End-to-end coverage (claude CLI
+ * actually flipping a task to review) lives in the Playwright suite.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { ref, shallowRef } from 'vue'
+
+// Mock useTasks BEFORE importing the composable under test so the
+// composable picks up the stub. The typed signature lets `.mock.calls`
+// expose the arguments as a real 4-tuple rather than `unknown[]`.
+type UpdateTaskStatusFn = (
+  id: string,
+  status: string,
+  feedback?: string | undefined,
+  extra?: Record<string, unknown> | undefined,
+) => Promise<unknown>
+const updateTaskStatusMock = vi.fn<UpdateTaskStatusFn>().mockResolvedValue({ ok: true })
+const tasksRef = ref<Array<Record<string, unknown>>>([])
+vi.mock('../useTasks', () => ({
+  useTasks: () => ({
+    tasks: tasksRef,
+    updateTaskStatus: updateTaskStatusMock,
+  }),
+}))
+
+// Mock the provider factory so `runOne()` doesn't try to hit a real API.
+// We return a provider that emits a single text block then `done` — enough
+// for the seed-run lifecycle assertions.
+// The real provider stream is a `type`-tagged event union (text | tool_call |
+// tool_result | usage | error | done) — type the double openly so individual
+// tests can yield any variant (e.g. a `usage` event) without fighting inference.
+const providerStreamMock = vi.fn(async function* (
+  _messages?: unknown,
+  _tools?: unknown,
+  _options?: { signal?: AbortSignal },
+): AsyncGenerator<{ type: string; [k: string]: unknown }> {
+  yield { type: 'text', text: 'All set.' }
+  yield { type: 'done', stopReason: 'end_turn' }
+})
+const abortRunMock = vi.fn()
+// Indirection so individual tests can make provider construction itself
+// throw (the missing-API-key path) via mockImplementationOnce — the factory
+// mock defers to this fn per call.
+const makeProviderMock = vi.fn(() => ({ name: 'mock', stream: providerStreamMock, abortRun: abortRunMock }))
+vi.mock('../../../embedded/provider-factory.js', () => ({
+  makeProvider: () => makeProviderMock(),
+}))
+
+import { useEmbeddedAgent } from '../useEmbeddedAgent'
+import { useAgentMode } from '../useAgentMode'
+import { resetProviderSettingsForTests, useProviderSettings } from '../useProviderSettings'
+import type { UseTaskThread, ThreadMessage } from '../useTaskThread'
+
+/** Minimal stub thread that records appends and lets tests preload messages. */
+function makeStubThread(initial: ThreadMessage[] = []): UseTaskThread & {
+  appended: Array<Parameters<UseTaskThread['append']>[0]>
+} {
+  const messages = shallowRef<ThreadMessage[]>([...initial])
+  const appended: Array<Parameters<UseTaskThread['append']>[0]> = []
+  return {
+    taskId: ref('task-test'),
+    messages,
+    status: ref<'idle' | 'loading' | 'live' | 'error' | 'reconnecting'>('live'),
+    error: ref<string | null>(null),
+    lastId: ref<string | null>(null),
+    open: vi.fn().mockResolvedValue(undefined),
+    close: vi.fn(),
+    append: vi.fn(async (input) => {
+      appended.push(input)
+      const stored: ThreadMessage = {
+        id: `m-${appended.length}`,
+        ts: Date.now(),
+        role: input.role,
+        content: input.content,
+        providerId: input.providerId,
+        model: input.model,
+        usage: input.usage,
+        blocks: input.blocks,
+      }
+      messages.value = [...messages.value, stored]
+      return stored
+    }),
+    update: vi.fn(async (id, patch) => {
+      const idx = messages.value.findIndex((m) => m.id === id)
+      const base: ThreadMessage = idx >= 0
+        ? messages.value[idx]
+        : { id, ts: Date.now(), role: 'assistant', content: '' }
+      const merged: ThreadMessage = { ...base, ...patch }
+      const next = messages.value.slice()
+      if (idx >= 0) next[idx] = merged
+      else next.push(merged)
+      messages.value = next
+      return merged
+    }),
+    appended,
+  }
+}
+
+beforeEach(() => {
+  resetProviderSettingsForTests()
+  // Default to OpenRouter so makeProvider doesn't bail on missing creds.
+  const store = useProviderSettings()
+  store.setActiveProvider('openrouter')
+  store.setProviderConfig({
+    id: 'openrouter',
+    apiKey: 'sk-or-test',
+    baseUrl: '',
+    model: 'openai/gpt-4o-mini',
+    effort: 'auto',
+  })
+  // Reset mocks between cases — vi.fn instances retain call history.
+  updateTaskStatusMock.mockClear()
+  providerStreamMock.mockClear()
+  abortRunMock.mockClear()
+  makeProviderMock.mockClear()
+  tasksRef.value = []
+})
+
+describe('useEmbeddedAgent — queue', () => {
+  it('starts with an empty queue', () => {
+    const agent = useEmbeddedAgent(makeStubThread())
+    expect(agent.queuedMessages.value).toEqual([])
+    expect(agent.running.value).toBe(false)
+  })
+
+  it('cancelQueued removes the entry at the given index', () => {
+    const agent = useEmbeddedAgent(makeStubThread())
+    // Push directly into the ref to simulate a running turn.
+    agent.queuedMessages.value = ['a', 'b', 'c']
+    agent.cancelQueued(1)
+    expect(agent.queuedMessages.value).toEqual(['a', 'c'])
+  })
+
+  it('cancelQueued is a no-op for out-of-range indices', () => {
+    const agent = useEmbeddedAgent(makeStubThread())
+    agent.queuedMessages.value = ['a']
+    agent.cancelQueued(-1)
+    agent.cancelQueued(5)
+    expect(agent.queuedMessages.value).toEqual(['a'])
+  })
+
+  it('send() while not running fires immediately; while running queues', async () => {
+    const agent = useEmbeddedAgent(makeStubThread())
+
+    // Empty/whitespace strings are ignored — neither fired nor queued.
+    await agent.send('   ')
+    expect(agent.queuedMessages.value).toEqual([])
+
+    // Simulate a turn in flight by flipping status directly.
+    agent.status.value = 'running'
+    await agent.send('hello there')
+    expect(agent.queuedMessages.value).toEqual(['hello there'])
+  })
+})
+
+describe('useEmbeddedAgent — surfaces', () => {
+  it('exposes currentBlocks as a reactive shallow ref', () => {
+    const agent = useEmbeddedAgent(makeStubThread())
+    expect(Array.isArray(agent.currentBlocks.value)).toBe(true)
+    expect(agent.currentBlocks.value.length).toBe(0)
+  })
+
+  it('exposes informational usage totals', () => {
+    const agent = useEmbeddedAgent(makeStubThread())
+    expect(agent.usage.value).toEqual({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0 })
+  })
+})
+
+describe('useEmbeddedAgent — redaction wiring', () => {
+  it('scrubs secrets from outgoing history before the provider sees them', async () => {
+    const secret = `sk-ant-${'A'.repeat(40)}`
+    const thread = makeStubThread([
+      { id: 'u0', ts: 1, role: 'user', content: `my key is ${secret}` },
+    ])
+    const agent = useEmbeddedAgent(thread)
+
+    // Non-seed turn on the (HTTP) openrouter provider still streams; redaction
+    // is on by default. The raw secret must not reach the provider.
+    await agent.send('continue please')
+
+    expect(providerStreamMock).toHaveBeenCalled()
+    const passedMessages = providerStreamMock.mock.calls[0]?.[0]
+    expect(JSON.stringify(passedMessages)).not.toContain(secret)
+  })
+})
+
+describe('useEmbeddedAgent — abort', () => {
+  it('abort() aborts the run signal and asks the provider to kill the subprocess', async () => {
+    let sawAbort = false
+    providerStreamMock.mockImplementationOnce(async function* (
+      _m?: unknown, _t?: unknown, options?: { signal?: AbortSignal },
+    ) {
+      yield { type: 'text', text: 'working…' }
+      await new Promise<void>((resolve) => {
+        if (options?.signal?.aborted) { sawAbort = true; resolve(); return }
+        options?.signal?.addEventListener('abort', () => { sawAbort = true; resolve() })
+      })
+      yield { type: 'done', stopReason: 'aborted' }
+    })
+
+    const agent = useEmbeddedAgent(makeStubThread())
+    const run = agent.send('go')
+    // Let the run reach the in-flight await before aborting.
+    await new Promise((r) => setTimeout(r, 0))
+    agent.abort()
+    await run
+
+    expect(sawAbort).toBe(true)
+    expect(abortRunMock).toHaveBeenCalled()
+  })
+})
+
+describe('useEmbeddedAgent — seed run lifecycle', () => {
+  it('flips pending → in_progress at start and in_progress → review at end on isSeed', async () => {
+    tasksRef.value = [{ id: 'task-test', status: 'pending', description: 'Do the thing.' }]
+    const agent = useEmbeddedAgent(makeStubThread())
+
+    await agent.send('Do the thing.', { isSeed: true })
+
+    // Two transitions in order. The mock task ref isn't actually mutated by
+    // the mock updateTaskStatus, but the second call still fires because the
+    // composable consulted `tasks.value` BEFORE calling updateTaskStatus —
+    // we have to update the ref in between to simulate that.
+    expect(updateTaskStatusMock.mock.calls.length).toBeGreaterThanOrEqual(1)
+    expect(updateTaskStatusMock.mock.calls[0]).toEqual(['task-test', 'in_progress'])
+  })
+
+  it('skips the review flip when the task drifted out of in_progress mid-run', async () => {
+    // Simulate: start state is pending, lock flips it to in_progress (mock
+    // doesn't update the ref), then mid-run something else drifted the task
+    // to needs_info. The review flip checks the *current* status from the
+    // task ref, which we set to needs_info before the run ends.
+    tasksRef.value = [{ id: 'task-test', status: 'needs_info', description: 'x' }]
+    const agent = useEmbeddedAgent(makeStubThread())
+
+    await agent.send('x', { isSeed: true })
+
+    // Lock step: pending|denied only. Since status is already needs_info
+    // when we read it, lockTaskOnStart skips.
+    // End step: review flip requires current status === 'in_progress', which
+    // it isn't here, so no review call either.
+    expect(updateTaskStatusMock).not.toHaveBeenCalled()
+  })
+
+  it('does NOT touch task.status when isSeed is false', async () => {
+    tasksRef.value = [{ id: 'task-test', status: 'pending', description: 'x' }]
+    const agent = useEmbeddedAgent(makeStubThread())
+
+    await agent.send('free-form follow-up', /* isSeed omitted */)
+
+    expect(updateTaskStatusMock).not.toHaveBeenCalled()
+  })
+
+  it('uses the agent\'s last text block as the resolution', async () => {
+    tasksRef.value = [{ id: 'task-test', status: 'in_progress', description: 'x' }]
+    // Mid-run, replace the mock so the end-of-run sees status: in_progress.
+    const agent = useEmbeddedAgent(makeStubThread())
+    await agent.send('Make the change.', { isSeed: true })
+
+    const reviewCall = updateTaskStatusMock.mock.calls.find((c) => c[1] === 'review')
+    expect(reviewCall).toBeDefined()
+    if (reviewCall) {
+      // Signature: (id, status, feedback, extra)
+      expect(reviewCall[0]).toBe('task-test')
+      expect(reviewCall[3]).toMatchObject({ resolution: 'All set.' })
+    }
+  })
+})
+
+describe('useEmbeddedAgent — seed run error paths', () => {
+  // Each case presets the task at `in_progress` (the post-lock state — the
+  // mock updateTaskStatus doesn't mutate tasksRef, so we start where the
+  // lock would have landed) and asserts the failed run releases the lock
+  // back to `pending` and clears the live-run indicator.
+
+  it('provider stream throwing reverts the task to pending + clears the run indicator', async () => {
+    tasksRef.value = [{ id: 'task-test', status: 'in_progress', description: 'x' }]
+    let activeDuringRun = false
+    providerStreamMock.mockImplementationOnce(async function* () {
+      activeDuringRun = useAgentMode().activeRuns.value.has('task-test')
+      yield { type: 'text', text: 'partial output…' }
+      throw new Error('boom')
+    })
+    const thread = makeStubThread()
+    const agent = useEmbeddedAgent(thread)
+
+    await agent.send('Do the thing.', { isSeed: true })
+
+    expect(agent.status.value).toBe('error')
+    expect(activeDuringRun).toBe(true)
+    expect(useAgentMode().activeRuns.value.has('task-test')).toBe(false)
+    expect(updateTaskStatusMock).toHaveBeenCalledWith('task-test', 'pending')
+    // The failure is persisted as a system message so every observer (other
+    // tabs, MCP tail-readers) sees why the run ended — same as the watchdog.
+    expect(thread.appended.some((m) => m.role === 'system' && m.content.includes('boom'))).toBe(true)
+  })
+
+  it('makeProvider throwing (missing API key) reverts the task to pending', async () => {
+    tasksRef.value = [{ id: 'task-test', status: 'in_progress', description: 'x' }]
+    makeProviderMock.mockImplementationOnce(() => { throw new Error('no API key configured') })
+    const thread = makeStubThread()
+    const agent = useEmbeddedAgent(thread)
+
+    await agent.send('Do the thing.', { isSeed: true })
+
+    expect(agent.status.value).toBe('error')
+    expect(useAgentMode().activeRuns.value.has('task-test')).toBe(false)
+    expect(updateTaskStatusMock).toHaveBeenCalledWith('task-test', 'pending')
+    expect(thread.appended.some((m) => m.role === 'system' && m.content.includes('no API key configured'))).toBe(true)
+  })
+
+  it('user-message append failure reverts the task to pending', async () => {
+    tasksRef.value = [{ id: 'task-test', status: 'in_progress', description: 'x' }]
+    const thread = makeStubThread()
+    vi.mocked(thread.append).mockRejectedValueOnce(new Error('disk full'))
+    const agent = useEmbeddedAgent(thread)
+
+    await agent.send('Do the thing.', { isSeed: true })
+
+    expect(agent.status.value).toBe('error')
+    expect(useAgentMode().activeRuns.value.has('task-test')).toBe(false)
+    expect(updateTaskStatusMock).toHaveBeenCalledWith('task-test', 'pending')
+  })
+
+  it('chat-turn (non-seed) errors never touch task.status but still clear the indicator', async () => {
+    tasksRef.value = [{ id: 'task-test', status: 'in_progress', description: 'x' }]
+    providerStreamMock.mockImplementationOnce(async function* () {
+      yield { type: 'text', text: 'hmm' }
+      throw new Error('boom')
+    })
+    const thread = makeStubThread()
+    const agent = useEmbeddedAgent(thread)
+
+    await agent.send('free-form follow-up')
+
+    expect(agent.status.value).toBe('error')
+    expect(updateTaskStatusMock).not.toHaveBeenCalled()
+    expect(useAgentMode().activeRuns.value.has('task-test')).toBe(false)
+    // No system message either — the error strip is enough for a chat turn.
+    expect(thread.appended.some((m) => m.role === 'system')).toBe(false)
+  })
+})
+
+describe('useEmbeddedAgent — seed run abort', () => {
+  it('reverts the task to pending when a seed run is aborted (Stop / requestAutoRunCancel)', async () => {
+    // Regression: a deliberate abort ends the stream as `done`/'aborted' with
+    // no watchdogReason. Before the fix this fell through every terminal
+    // branch, leaving the task stranded in_progress for the server to
+    // mislabel "tab was likely closed". It must now release the lock to
+    // pending — same recovery as the error path.
+    tasksRef.value = [{ id: 'task-test', status: 'in_progress', description: 'x' }]
+    providerStreamMock.mockImplementationOnce(async function* (
+      _m?: unknown, _t?: unknown, options?: { signal?: AbortSignal },
+    ) {
+      yield { type: 'text', text: 'working…' }
+      await new Promise<void>((resolve) => {
+        if (options?.signal?.aborted) { resolve(); return }
+        options?.signal?.addEventListener('abort', () => resolve())
+      })
+      // Local CLI providers normalize an aborted run to a clean done/'aborted'
+      // event (they don't throw) — mirror that so we exercise the gap.
+      yield { type: 'done', stopReason: 'aborted' }
+    })
+    const agent = useEmbeddedAgent(makeStubThread())
+
+    const run = agent.send('Do the thing.', { isSeed: true })
+    await new Promise((r) => setTimeout(r, 0))
+    agent.abort()
+    await run
+
+    expect(agent.status.value).toBe('aborted')
+    expect(abortRunMock).toHaveBeenCalled()
+    expect(updateTaskStatusMock).toHaveBeenCalledWith('task-test', 'pending')
+    expect(useAgentMode().activeRuns.value.has('task-test')).toBe(false)
+  })
+})
+
+describe('useEmbeddedAgent — usage accounting (no double-count across turns)', () => {
+  it('keeps usage per-turn so a 2-turn conversation sums to the true total, not 2x', async () => {
+    // Each turn emits its OWN usage event. Before the fix, `usage` accumulated
+    // across every turn and was never reset, so turn 2's persisted message
+    // carried turn-1+turn-2 tokens AND the live accumulator still held the
+    // running total — the header (persisted-message sum + live accumulator)
+    // showed ~2x. The invariant: each persisted message holds exactly its own
+    // turn, and the live accumulator is zeroed once the turn is persisted.
+    providerStreamMock.mockImplementation(async function* () {
+      yield { type: 'text', text: 'turn output' }
+      yield { type: 'usage', inputTokens: 100, outputTokens: 30 }
+      yield { type: 'done', stopReason: 'end_turn' }
+    })
+    const thread = makeStubThread()
+    const agent = useEmbeddedAgent(thread)
+
+    await agent.send('first turn')
+    // After the turn persists, the live accumulator is cleared (so the idle
+    // gap between turns can't double-count it against the persisted message).
+    expect(agent.usage.value).toEqual({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0 })
+
+    await agent.send('second turn')
+    expect(agent.usage.value).toEqual({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0 })
+
+    // Each assistant turn's persisted message carries exactly its OWN turn's
+    // tokens — never the running cumulative — so the header summing them lands
+    // on the true total (200 in / 60 out), not 2x turn-1.
+    const usages = thread.messages.value
+      .filter((m) => m.role === 'assistant' && m.usage)
+      .map((m) => m.usage!)
+    expect(usages).toHaveLength(2)
+    for (const u of usages) {
+      expect(u.inputTokens).toBe(100)
+      expect(u.outputTokens).toBe(30)
+    }
+    const totalIn = usages.reduce((s, u) => s + (u.inputTokens || 0), 0) + agent.usage.value.input
+    const totalOut = usages.reduce((s, u) => s + (u.outputTokens || 0), 0) + agent.usage.value.output
+    expect(totalIn).toBe(200)
+    expect(totalOut).toBe(60)
+
+    // Restore the suite default — this test installed a persistent
+    // implementation (both turns needed it); `mockClear()` in beforeEach only
+    // resets call history, not the implementation.
+    providerStreamMock.mockImplementation(async function* () {
+      yield { type: 'text', text: 'All set.' }
+      yield { type: 'done', stopReason: 'end_turn' }
+    })
+  })
+})
+
+describe('useEmbeddedAgent — seed gate lists all four local CLIs', () => {
+  it('refusal message names claude/codex/opencode/copilot and never locks the task', async () => {
+    // Pin the task type to a custom persona on an HTTP provider so the
+    // "local CLIs only" apply gate actually fires.
+    const store = useProviderSettings()
+    store.upsertPersona({
+      id: 'custom:http-tester',
+      name: 'HTTP Tester',
+      description: '',
+      taskTypes: [],
+      providerId: 'openrouter',
+      model: '',
+      effort: 'auto',
+      roleDirections: '',
+      systemPromptExtras: '',
+      isCustom: true,
+    })
+    store.setPersonaOverride('annotation', 'custom:http-tester')
+    tasksRef.value = [{ id: 'task-test', status: 'pending', description: 'x', type: 'annotation' }]
+    const agent = useEmbeddedAgent(makeStubThread())
+
+    await agent.send('x', { isSeed: true })
+
+    expect(agent.status.value).toBe('error')
+    for (const cli of ['claude-local', 'codex-local', 'opencode-local', 'copilot-local']) {
+      expect(agent.errorMessage.value).toContain(cli)
+    }
+    // The gate fires before the lock — the task stays pending and the
+    // live-run indicator doesn't leak.
+    expect(updateTaskStatusMock).not.toHaveBeenCalled()
+    expect(useAgentMode().activeRuns.value.has('task-test')).toBe(false)
+  })
+})
diff --git a/src/shell/composables/__tests__/useErrorMonitor.test.ts b/src/shell/composables/__tests__/useErrorMonitor.test.ts
new file mode 100644
index 0000000..dfc4106
--- /dev/null
+++ b/src/shell/composables/__tests__/useErrorMonitor.test.ts
@@ -0,0 +1,81 @@
+import { describe, it, expect, vi } from 'vitest'
+import { ref } from 'vue'
+import { normalizeStackFile, useErrorMonitor, type ErrorEntry } from '../useErrorMonitor'
+import type { useIframeManager } from '../useIframeManager'
+import type { useTasks } from '../useTasks'
+
+describe('normalizeStackFile', () => {
+  // [stack-derived file reference, expected repo-relative path]
+  const cases: Array<[string, string]> = [
+    // Dev-server URLs (with port) lose scheme://host:port/
+    ['http://localhost:5173/src/App.vue', 'src/App.vue'],
+    ['https://localhost:8443/src/pages/OverviewPage.vue', 'src/pages/OverviewPage.vue'],
+    // Vite cache-buster / HMR query strings are stripped
+    ['http://localhost:5173/src/components/Pill.vue?t=1717171717123', 'src/components/Pill.vue'],
+    ['src/main.ts?import&t=123', 'src/main.ts'],
+    // /@fs/ imports point at absolute filesystem paths — no anchor possible
+    ['/@fs/home/kurt/code/app/src/App.vue', ''],
+    ['http://localhost:5173/@fs/home/kurt/code/app/src/App.vue', ''],
+    // Plain repo-relative paths pass through; leading ./ and / are stripped
+    ['src/App.vue', 'src/App.vue'],
+    ['/src/App.vue', 'src/App.vue'],
+    ['./src/App.vue', 'src/App.vue'],
+    // webpack-internal:/// frames resolve to project-relative paths
+    ['webpack-internal:///./src/App.vue', 'src/App.vue'],
+    // Garbage that would 400 against SafeSourceFile drops to ''
+    ['node:internal/process/task_queues.js', ''],
+    ['data:text/javascript;base64,abc.js', ''],
+    ['C:\\Users\\kurt\\src\\App.vue', ''],
+    ['', ''],
+  ]
+
+  it.each(cases)('normalizes %j → %j', (input, expected) => {
+    expect(normalizeStackFile(input)).toBe(expected)
+  })
+})
+
+describe('useErrorMonitor.createErrorTask', () => {
+  function makeMonitor() {
+    const createTask = vi.fn(async (t: Record<string, unknown>) => ({ id: 't1', ...t }))
+    const iframe = {
+      onBridgeEvent: vi.fn(),
+      getColorScheme: vi.fn(async () => null),
+      getComponentChain: vi.fn(async () => null),
+    } as unknown as ReturnType<typeof useIframeManager>
+    const taskSystem = { tasks: ref([]), createTask } as unknown as ReturnType<typeof useTasks>
+    const monitor = useErrorMonitor(iframe, taskSystem, ref('/'))
+    return { monitor, createTask }
+  }
+
+  function entryWithStack(stack: string): ErrorEntry {
+    return {
+      id: 'e1', level: 'error', message: 'boom', stack,
+      count: 1, firstSeen: 1, lastSeen: 1,
+    }
+  }
+
+  it('normalizes dev-server URLs from the stack into repo-relative file anchors', async () => {
+    const { monitor, createTask } = makeMonitor()
+    await monitor.createErrorTask(entryWithStack(
+      'Error: boom\n    at setup (http://localhost:5173/src/App.vue:42:10)',
+    ))
+    expect(createTask).toHaveBeenCalledTimes(1)
+    const payload = createTask.mock.calls[0][0] as Record<string, unknown>
+    // Before the fix this POSTed file="http://localhost:5173/src/App.vue",
+    // which SafeSourceFile rejects with a 400 — silently.
+    expect(payload.file).toBe('src/App.vue')
+    expect(payload.line).toBe(42)
+  })
+
+  it('drops the anchor (file="", line=0) when the frame cannot be made repo-relative', async () => {
+    const { monitor, createTask } = makeMonitor()
+    await monitor.createErrorTask(entryWithStack(
+      'Error: boom\n    at run (/@fs/home/kurt/code/app/src/App.vue:7:3)',
+    ))
+    const payload = createTask.mock.calls[0][0] as Record<string, unknown>
+    // The task is still creatable — just without a source anchor.
+    expect(payload.file).toBe('')
+    expect(payload.line).toBe(0)
+    expect(payload.type).toBe('error_fix')
+  })
+})
diff --git a/src/shell/composables/__tests__/useProjectComponents.test.ts b/src/shell/composables/__tests__/useProjectComponents.test.ts
new file mode 100644
index 0000000..982546f
--- /dev/null
+++ b/src/shell/composables/__tests__/useProjectComponents.test.ts
@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+// useComponentLibrary subscribes to the shared WebSocket client on first use.
+vi.mock('../../services/wsClient', () => ({
+  on: () => () => {},
+  send: () => {},
+  isConnected: () => true,
+}))
+
+import { useComponentLibrary, type LibraryComponent } from '../useProjectComponents'
+import { useWorkspace, type WorkspaceInfo } from '../useWorkspace'
+
+function comp(name: string, sourceFile?: string | null): LibraryComponent {
+  return { name, props: [], ...(sourceFile !== undefined ? { sourceFile } : {}) }
+}
+
+const TWO_MFE: WorkspaceInfo = {
+  root: '/r',
+  isWorkspace: true,
+  currentDir: 'packages/checkout',
+  packages: [
+    { name: 'checkout', dir: 'packages/checkout', mfe: 'checkout' },
+    { name: 'admin', dir: 'packages/admin', mfe: 'admin' },
+  ],
+}
+
+describe('surfaceRenderInfo (MFE-aware palette)', () => {
+  const ws = useWorkspace()
+  const cl = useComponentLibrary()
+
+  beforeEach(() => { ws.info.value = null })
+  afterEach(() => { vi.restoreAllMocks() })
+
+  it('single-MFE / non-workspace: everything renderable, no owning MFE', () => {
+    ws.info.value = { root: '/r', isWorkspace: false, packages: [], currentDir: '' }
+    expect(cl.surfaceRenderInfo('Project', comp('Foo', 'src/Foo.vue'))).toEqual({ renderable: true, owningMfe: null })
+  })
+
+  it('a Project component from ANOTHER MFE is not renderable on this surface', () => {
+    ws.info.value = TWO_MFE
+    expect(cl.surfaceRenderInfo('Project', comp('AdminNav', 'packages/admin/src/AdminNav.vue')))
+      .toEqual({ renderable: false, owningMfe: 'admin' })
+  })
+
+  it('a Project component on the CURRENT surface is renderable', () => {
+    ws.info.value = TWO_MFE
+    expect(cl.surfaceRenderInfo('Project', comp('CartButton', 'packages/checkout/src/CartButton.vue')))
+      .toEqual({ renderable: true, owningMfe: 'checkout' })
+  })
+
+  it('an unattributed Project component (shared/no MFE source) defaults to renderable', () => {
+    ws.info.value = TWO_MFE
+    expect(cl.surfaceRenderInfo('Project', comp('Shared', 'packages/design-system/src/Shared.vue')))
+      .toEqual({ renderable: true, owningMfe: null })
+  })
+
+  it('third-party libraries are never gated (the registry is the real arbiter)', () => {
+    ws.info.value = TWO_MFE
+    // Even with a cross-MFE-looking source, an installed library stays draggable
+    // and is stamped with the current surface MFE.
+    expect(cl.surfaceRenderInfo('primevue', comp('Button', 'packages/admin/src/whatever')))
+      .toEqual({ renderable: true, owningMfe: 'checkout' })
+  })
+})
diff --git a/src/shell/composables/__tests__/useProviderSettings.test.ts b/src/shell/composables/__tests__/useProviderSettings.test.ts
new file mode 100644
index 0000000..351f664
--- /dev/null
+++ b/src/shell/composables/__tests__/useProviderSettings.test.ts
@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest'
+import { createProviderSettingsForTests } from '../useProviderSettings'
+
+describe('useProviderSettings', () => {
+  it('starts with the documented defaults when storage is empty', () => {
+    const s = createProviderSettingsForTests(null)
+    // Local-first default: paperclip-style, prefer whatever CLI the user has
+    // logged into. The composer's empty state steers them if no CLI is found.
+    expect(s.settings.value.activeProvider).toBe('claude-local')
+    expect(s.settings.value.agentMode).toBe('auto')
+    expect(s.settings.value.onboardingDismissed).toBe(false)
+    expect(s.settings.value.redactionEnabled).toBe(true)
+    expect(s.settings.value.eventLogEnabled).toBe(true)
+    expect(s.ready.value).toBe(false)
+  })
+
+  it('flips ready=true once the active provider has credentials', () => {
+    const s = createProviderSettingsForTests(null)
+    // Switch to the BYOK Anthropic branch so this test exercises a credential
+    // path (local-CLI readiness is gated on the agent-detect probe, not creds).
+    s.setActiveProvider('anthropic')
+    s.setProviderConfig({
+      id: 'anthropic',
+      apiKey: 'sk-ant-abc',
+      model: 'claude-sonnet-4-5',
+      effort: 'auto',
+    })
+    expect(s.ready.value).toBe(true)
+  })
+
+  it('switches active provider without losing other branches', () => {
+    const s = createProviderSettingsForTests(null)
+    s.setProviderConfig({
+      id: 'anthropic',
+      apiKey: 'sk-ant-abc',
+      model: 'claude-sonnet-4-5',
+      effort: 'auto',
+    })
+    s.setActiveProvider('openai')
+    expect(s.activeProvider.value).toBe('openai')
+    expect(s.settings.value.providers.anthropic.apiKey).toBe('sk-ant-abc')
+    expect(s.ready.value).toBe(false) // openai still has no key
+    s.setProviderConfig({
+      id: 'openai',
+      apiKey: 'sk-test',
+      organization: '',
+      model: 'gpt-5',
+      effort: 'auto',
+    })
+    expect(s.ready.value).toBe(true)
+  })
+
+  it('agentMode tri-state persists', () => {
+    const s = createProviderSettingsForTests(null)
+    expect(s.settings.value.agentMode).toBe('auto')
+    s.setAgentMode('manual')
+    expect(s.settings.value.agentMode).toBe('manual')
+    s.setAgentMode('off')
+    expect(s.settings.value.agentMode).toBe('off')
+  })
+
+  it('persists changes through the injected sink', () => {
+    let stored: unknown = null
+    const persistence = {
+      load: () => stored,
+      save: (v: unknown) => {
+        stored = typeof v === 'string' ? v : JSON.stringify(v)
+      },
+    }
+    const s1 = createProviderSettingsForTests(stored)
+    s1.setActiveProvider('openai')
+    const persisted = JSON.stringify(s1.settings.value)
+    const s2 = createProviderSettingsForTests(persisted)
+    expect(s2.activeProvider.value).toBe('openai')
+    void persistence
+  })
+})
diff --git a/src/shell/composables/__tests__/useTaskThread.test.ts b/src/shell/composables/__tests__/useTaskThread.test.ts
new file mode 100644
index 0000000..50ddec9
--- /dev/null
+++ b/src/shell/composables/__tests__/useTaskThread.test.ts
@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { useTaskThread, type ThreadMessage } from '../useTaskThread'
+
+/**
+ * Minimal EventSource stub — jsdom doesn't implement it, and `open()` only
+ * needs construction to succeed (we drive messages directly via append/update).
+ */
+class FakeEventSource {
+  url: string
+  constructor(url: string) { this.url = url }
+  addEventListener() { /* no-op */ }
+  close() { /* no-op */ }
+}
+
+function jsonResponse(body: unknown): Response {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response
+}
+
+describe('useTaskThread', () => {
+  let fetchMock: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    vi.stubGlobal('EventSource', FakeEventSource)
+    fetchMock = vi.fn()
+    vi.stubGlobal('fetch', fetchMock)
+  })
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  async function openWithSnapshot(snapshot: ThreadMessage[]) {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ taskId: 'task-x', messages: snapshot }))
+    const thread = useTaskThread()
+    await thread.open('task-x')
+    return thread
+  }
+
+  it('upserts by id: update() replaces the message in place instead of duplicating', async () => {
+    const partial: ThreadMessage = { id: 'm1', ts: 1, role: 'assistant', content: '', isPartial: true }
+    const thread = await openWithSnapshot([partial])
+    expect(thread.messages.value).toHaveLength(1)
+
+    // PATCH returns the merged record with the same id.
+    fetchMock.mockResolvedValueOnce(jsonResponse({
+      ...partial, content: 'streaming…', isPartial: true, lastEventAt: 5,
+    }))
+    await thread.update('m1', { content: 'streaming…', lastEventAt: 5 })
+
+    expect(thread.messages.value).toHaveLength(1) // not duplicated
+    expect(thread.messages.value[0].content).toBe('streaming…')
+    expect(thread.messages.value[0].lastEventAt).toBe(5)
+
+    // Final flush clears isPartial — still one entry, same id.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ ...partial, content: 'done', isPartial: false }))
+    await thread.update('m1', { content: 'done', isPartial: false })
+    expect(thread.messages.value).toHaveLength(1)
+    expect(thread.messages.value[0].isPartial).toBe(false)
+    expect(thread.messages.value[0].content).toBe('done')
+  })
+
+  it('append() adds a new entry but dedupes a repeat of the same id', async () => {
+    const thread = await openWithSnapshot([])
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'u1', ts: 2, role: 'user', content: 'hi' }))
+    await thread.append({ role: 'user', content: 'hi' })
+    expect(thread.messages.value).toHaveLength(1)
+
+    // A second append echoing the same id (e.g. SSE replay) must not duplicate.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'u1', ts: 2, role: 'user', content: 'hi' }))
+    await thread.append({ role: 'user', content: 'hi' })
+    expect(thread.messages.value).toHaveLength(1)
+  })
+
+  it('gives up after repeated reconnect failures and surfaces an actionable error', async () => {
+    // Controllable EventSource so we can drive `error` events deterministically.
+    const listeners: Record<string, Array<(ev?: unknown) => void>> = {}
+    let closed = false
+    class ControllableES {
+      url: string
+      constructor(url: string) { this.url = url }
+      addEventListener(type: string, fn: (ev?: unknown) => void) { (listeners[type] ??= []).push(fn) }
+      close() { closed = true }
+    }
+    vi.stubGlobal('EventSource', ControllableES)
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ taskId: 'task-x', messages: [] }))
+    const thread = useTaskThread()
+    await thread.open('task-x')
+
+    const fireError = () => listeners.error?.forEach((fn) => fn())
+
+    // First 5 failures: still trying, not given up.
+    for (let i = 0; i < 5; i++) fireError()
+    expect(thread.status.value).toBe('reconnecting')
+    expect(closed).toBe(false)
+
+    // 6th consecutive failure → give up with an actionable error.
+    fireError()
+    expect(thread.status.value).toBe('error')
+    expect(thread.error.value).toMatch(/Lost connection/)
+    expect(closed).toBe(true)
+  })
+
+  it('resets the reconnect counter on a successful (re)connect', async () => {
+    const listeners: Record<string, Array<(ev?: unknown) => void>> = {}
+    class ControllableES {
+      url: string
+      constructor(url: string) { this.url = url }
+      addEventListener(type: string, fn: (ev?: unknown) => void) { (listeners[type] ??= []).push(fn) }
+      close() { /* no-op */ }
+    }
+    vi.stubGlobal('EventSource', ControllableES)
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ taskId: 'task-x', messages: [] }))
+    const thread = useTaskThread()
+    await thread.open('task-x')
+
+    const fireError = () => listeners.error?.forEach((fn) => fn())
+    const fireOpen = () => listeners.open?.forEach((fn) => fn())
+
+    for (let i = 0; i < 5; i++) fireError()
+    fireOpen() // recovered — counter resets
+    expect(thread.status.value).toBe('live')
+    for (let i = 0; i < 5; i++) fireError() // 5 more shouldn't trip the give-up
+    expect(thread.status.value).toBe('reconnecting')
+  })
+})
diff --git a/src/shell/composables/__tests__/useTasks.test.ts b/src/shell/composables/__tests__/useTasks.test.ts
new file mode 100644
index 0000000..a02e086
--- /dev/null
+++ b/src/shell/composables/__tests__/useTasks.test.ts
@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+// Replace the shared WebSocket client so importing useTasks neither opens a
+// real socket nor races reconnect timers. `__emit` is a test-only hook that
+// fires synthetic events at subscribers (used for the `reconnected` resync).
+vi.mock('../../services/wsClient', () => {
+  const listeners = new Map<string, Set<(d?: unknown) => void>>()
+  return {
+    on: (event: string, handler: (d?: unknown) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set())
+      listeners.get(event)!.add(handler)
+      return () => { listeners.get(event)?.delete(handler) }
+    },
+    send: () => { /* no-op */ },
+    isConnected: () => true,
+    __emit: (event: string, data?: unknown) => {
+      listeners.get(event)?.forEach((h) => h(data))
+    },
+  }
+})
+
+import * as wsClient from '../../services/wsClient'
+import { useTasks } from '../useTasks'
+
+const emitWs = (wsClient as unknown as { __emit: (event: string, data?: unknown) => void }).__emit
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  } as unknown as Response
+}
+
+describe('useTasks error handling', () => {
+  let fetchMock: ReturnType<typeof vi.fn>
+  let errorSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    fetchMock = vi.fn().mockResolvedValue(jsonResponse({ tasks: [] }))
+    vi.stubGlobal('fetch', fetchMock)
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+  })
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  it('createTask returns the created task and clears lastError on success', async () => {
+    const ts = useTasks()
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: 't1', description: 'x' })) // POST
+    const created = await ts.createTask({ type: 'annotation', description: 'x' })
+    expect(created).toMatchObject({ id: 't1' })
+    expect(ts.lastError.value).toBeNull()
+  })
+
+  it('createTask returns null and surfaces the server error body on a 400', async () => {
+    const ts = useTasks()
+    // The exact failure from the error_fix chain: SafeSourceFile rejecting a
+    // dev-server URL as `file`. The old code returned this body as if it
+    // were the created task, so /tasks/undefined sidecar POSTs followed.
+    fetchMock.mockResolvedValueOnce(jsonResponse(
+      { error: { code: 'validation_failed', message: 'URL-style paths are not allowed' } },
+      400,
+    ))
+    const created = await ts.createTask({ type: 'error_fix', description: 'boom', file: 'http://localhost:5173/src/App.vue' })
+    expect(created).toBeNull()
+    expect(ts.lastError.value).toEqual({ code: 'validation_failed', message: 'URL-style paths are not allowed' })
+    expect(errorSpy).toHaveBeenCalled()
+  })
+
+  it('createTask falls back to an http_error code when the failure body is not JSON', async () => {
+    const ts = useTasks()
+    fetchMock.mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+      json: async () => { throw new Error('not json') },
+    } as unknown as Response)
+    const created = await ts.createTask({ type: 'annotation', description: 'x' })
+    expect(created).toBeNull()
+    expect(ts.lastError.value).toEqual({ code: 'http_error', message: 'HTTP 500' })
+  })
+
+  it('createTask reports network failures as network_error', async () => {
+    const ts = useTasks()
+    fetchMock.mockRejectedValueOnce(new Error('ECONNREFUSED'))
+    const created = await ts.createTask({ type: 'annotation', description: 'x' })
+    expect(created).toBeNull()
+    expect(ts.lastError.value?.code).toBe('network_error')
+  })
+
+  it('updateTask returns false + lastError on a rejected PATCH, true on success', async () => {
+    const ts = useTasks()
+    fetchMock.mockResolvedValueOnce(jsonResponse(
+      { error: { code: 'validation_failed', message: 'Unknown field' } },
+      400,
+    ))
+    expect(await ts.updateTask('t1', { status: 'review' })).toBe(false)
+    expect(ts.lastError.value?.code).toBe('validation_failed')
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ ok: true })) // PATCH
+    expect(await ts.updateTask('t1', { status: 'review' })).toBe(true)
+    expect(ts.lastError.value).toBeNull()
+  })
+
+  it('deleteTask returns false + lastError on a rejected DELETE', async () => {
+    const ts = useTasks()
+    fetchMock.mockResolvedValueOnce(jsonResponse(
+      { error: { code: 'not_found', message: 'Not found' } },
+      404,
+    ))
+    expect(await ts.deleteTask('missing')).toBe(false)
+    expect(ts.lastError.value).toEqual({ code: 'not_found', message: 'Not found' })
+  })
+
+  it('refetches the task list when the WebSocket reconnects after a drop', async () => {
+    useTasks() // ensure subscriptions are registered
+    fetchMock.mockClear()
+    emitWs('reconnected')
+    // fetchTasks is fire-and-forget — flush the microtask queue.
+    await Promise.resolve()
+    expect(fetchMock).toHaveBeenCalledWith('/__annotask/api/tasks')
+  })
+})
diff --git a/src/shell/composables/__tests__/useWireframeCanvas.test.ts b/src/shell/composables/__tests__/useWireframeCanvas.test.ts
new file mode 100644
index 0000000..f1d7557
--- /dev/null
+++ b/src/shell/composables/__tests__/useWireframeCanvas.test.ts
@@ -0,0 +1,170 @@
+import { describe, it, expect, beforeEach, afterEach, vi, type Mock } from 'vitest'
+import { ref } from 'vue'
+
+// useWireframeCanvas pulls in the useWireframeDoc singleton, which subscribes
+// to the shared WebSocket client — stub it out like the other composable tests.
+vi.mock('../../services/wsClient', () => {
+  const listeners = new Map<string, Set<(d?: unknown) => void>>()
+  return {
+    on: (event: string, handler: (d?: unknown) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set())
+      listeners.get(event)!.add(handler)
+      return () => { listeners.get(event)?.delete(handler) }
+    },
+    send: () => { /* no-op */ },
+    isConnected: () => true,
+  }
+})
+
+import { useWireframeCanvas, type WireframeCanvasIframe } from '../useWireframeCanvas'
+import type { WireframeDocument, WireframeInstance } from '../../../shared/wireframe-types'
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  } as unknown as Response
+}
+
+function instance(id: string, extra: Partial<WireframeInstance> = {}): WireframeInstance {
+  return {
+    id,
+    kind: 'component',
+    anchor: { file: 'PlanetsPage.vue', line: 9, position: 'append', component: 'PlanetsPage', targetTag: 'section' },
+    inserted: { tag: 'planetcard', componentName: 'PlanetCard' },
+    fidelity: 'live',
+    mounted: true,
+    createdAt: 1,
+    ...extra,
+  }
+}
+
+function docWith(instances: WireframeInstance[]): WireframeDocument {
+  return { version: '1.0', updatedAt: 0, rev: 1, routes: [{ route: '/r', instances }] }
+}
+
+function makeIframe(): WireframeCanvasIframe {
+  return {
+    currentRoute: ref('/r'),
+    bridgeReady: ref(false), // watchers stay quiet — these tests drive Build directly
+    resolveElementAt: vi.fn(async () => null),
+    findTemplateGroup: vi.fn(async () => ({ eids: ['target-1'] })),
+    insertComponent: vi.fn(async () => ({ eid: 'mounted-1', mounted: true })),
+    insertPlaceholder: vi.fn(async () => 'mounted-1'),
+    removePlaceholder: vi.fn(async () => undefined),
+  }
+}
+
+describe('useWireframeCanvas — Build collector', () => {
+  let fetchMock: ReturnType<typeof vi.fn>
+  let createRouteTask: Mock<(data: Record<string, unknown>) => Promise<{ id: string } | null>>
+  /** Deep snapshot of the createRouteTask payload at call time — Build stamps
+   *  the same instance objects 'building' right after, so a live reference
+   *  would show post-mutation state. */
+  let capturedPayloads: Array<Record<string, unknown>>
+  let canvas: ReturnType<typeof useWireframeCanvas>
+
+  beforeEach(async () => {
+    capturedPayloads = []
+    fetchMock = vi.fn().mockImplementation(async (_url: string, init?: RequestInit) => {
+      if (init?.method === 'PUT') {
+        const sent = JSON.parse(init.body as string) as WireframeDocument
+        return jsonResponse({ ...sent, rev: (sent.rev ?? 0) + 1 })
+      }
+      return jsonResponse(docWith([]))
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    createRouteTask = vi.fn(async (data: Record<string, unknown>) => {
+      capturedPayloads.push(JSON.parse(JSON.stringify(data)))
+      return { id: 'task-9' }
+    })
+    canvas = useWireframeCanvas({
+      iframe: makeIframe(),
+      createRouteTask,
+    })
+    // Let the doc singleton's initial load settle before seeding the doc, so a
+    // late response can't clobber the fixture.
+    await Promise.resolve()
+    await Promise.resolve()
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  it('batches ONLY placed instances (with previewProps) into one wireframe_apply task and stamps them building', async () => {
+    canvas.wireframeDoc.doc.value = docWith([
+      instance('wfi-1', { status: 'placed', previewProps: { label: 'Hello' } }),
+      instance('wfi-2'), // legacy-undefined counts as placed
+      instance('wfi-3', { status: 'building', taskId: 'task-old' }),
+    ])
+    expect(canvas.placedCount.value).toBe(2)
+
+    await canvas.buildWireframeRoute()
+
+    expect(createRouteTask).toHaveBeenCalledTimes(1)
+    const payload = capturedPayloads[0]
+    expect(payload.type).toBe('wireframe_apply')
+    const wireframe = (payload.context as { wireframe: { route: string; instances: WireframeInstance[] } }).wireframe
+    expect(wireframe.route).toBe('/r')
+    expect(wireframe.instances.map((i) => i.id)).toEqual(['wfi-1', 'wfi-2'])
+    expect(wireframe.instances[0].previewProps).toEqual({ label: 'Hello' })
+
+    const byId = Object.fromEntries(canvas.wireframeDoc.instancesForRoute('/r').map((i) => [i.id, i]))
+    expect(byId['wfi-1'].status).toBe('building')
+    expect(byId['wfi-1'].taskId).toBe('task-9')
+    expect(byId['wfi-2'].status).toBe('building')
+    expect(byId['wfi-3'].taskId).toBe('task-old') // untouched
+    expect(canvas.placedCount.value).toBe(0)
+  })
+
+  it('a second Build with nothing placed creates no task', async () => {
+    canvas.wireframeDoc.doc.value = docWith([instance('wfi-1', { status: 'placed' })])
+    await canvas.buildWireframeRoute()
+    expect(createRouteTask).toHaveBeenCalledTimes(1)
+    await canvas.buildWireframeRoute()
+    expect(createRouteTask).toHaveBeenCalledTimes(1)
+  })
+
+  it('a double-click cannot emit a duplicate task (re-entrancy guard)', async () => {
+    canvas.wireframeDoc.doc.value = docWith([instance('wfi-1', { status: 'placed' })])
+    // Hold task creation open so the second click lands mid-build.
+    let release!: (v: { id: string }) => void
+    createRouteTask.mockImplementationOnce(async (data: Record<string, unknown>) => {
+      capturedPayloads.push(JSON.parse(JSON.stringify(data)))
+      return new Promise((resolve) => { release = resolve })
+    })
+    const first = canvas.buildWireframeRoute()
+    const second = canvas.buildWireframeRoute()
+    release({ id: 'task-9' })
+    await Promise.all([first, second])
+    expect(createRouteTask).toHaveBeenCalledTimes(1)
+  })
+
+  it('a failed task creation leaves the batch placed so Build can retry', async () => {
+    canvas.wireframeDoc.doc.value = docWith([instance('wfi-1', { status: 'placed' })])
+    createRouteTask.mockResolvedValueOnce(null) // POST rejected / server down
+    await canvas.buildWireframeRoute()
+    expect(canvas.wireframeDoc.instancesForRoute('/r')[0].status).toBe('placed')
+    expect(canvas.placedCount.value).toBe(1)
+    await canvas.buildWireframeRoute()
+    expect(createRouteTask).toHaveBeenCalledTimes(2)
+  })
+
+  it('deletePlacement unmounts the live node and removes the instance from the doc', async () => {
+    canvas.wireframeDoc.doc.value = docWith([instance('wfi-1'), instance('wfi-2')])
+    canvas.registerContainer('wfi-1', 'container-eid-1')
+    const iframe = makeIframe()
+    // Re-create the canvas against this iframe so removePlaceholder is observable.
+    const localCanvas = useWireframeCanvas({
+      iframe,
+      createRouteTask,
+    })
+    localCanvas.registerContainer('wfi-1', 'container-eid-1')
+    await localCanvas.deletePlacement('wfi-1')
+    expect(iframe.removePlaceholder).toHaveBeenCalledWith('container-eid-1')
+    expect(localCanvas.wireframeDoc.instancesForRoute('/r').map((i) => i.id)).toEqual(['wfi-2'])
+  })
+})
diff --git a/src/shell/composables/__tests__/useWireframeDoc.test.ts b/src/shell/composables/__tests__/useWireframeDoc.test.ts
new file mode 100644
index 0000000..f6dfefb
--- /dev/null
+++ b/src/shell/composables/__tests__/useWireframeDoc.test.ts
@@ -0,0 +1,278 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+// Replace the shared WebSocket client so importing useWireframeDoc neither
+// opens a real socket nor races reconnect timers (same pattern as useTasks).
+vi.mock('../../services/wsClient', () => {
+  const listeners = new Map<string, Set<(d?: unknown) => void>>()
+  return {
+    on: (event: string, handler: (d?: unknown) => void) => {
+      if (!listeners.has(event)) listeners.set(event, new Set())
+      listeners.get(event)!.add(handler)
+      return () => { listeners.get(event)?.delete(handler) }
+    },
+    send: () => { /* no-op */ },
+    isConnected: () => true,
+  }
+})
+
+import { useWireframeDoc, type WireframeIframe } from '../useWireframeDoc'
+import type { WireframeDocument, WireframeInstance } from '../../../shared/wireframe-types'
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  } as unknown as Response
+}
+
+function instance(id: string, extra: Partial<WireframeInstance> = {}): WireframeInstance {
+  return {
+    id,
+    kind: 'component',
+    anchor: { file: 'PlanetsPage.vue', line: 9, position: 'append', targetTag: 'section' },
+    inserted: { tag: 'planetcard', componentName: 'PlanetCard', props: { real: true } },
+    fidelity: 'live',
+    mounted: true,
+    createdAt: 1,
+    ...extra,
+  }
+}
+
+function docWith(instances: WireframeInstance[], route = '/r'): WireframeDocument {
+  return { version: '1.0', updatedAt: 0, rev: 1, routes: [{ route, instances }] }
+}
+
+function makeIframe(overrides: Partial<WireframeIframe> = {}): WireframeIframe {
+  return {
+    findTemplateGroup: vi.fn(async () => ({ eids: ['target-1'] })),
+    insertComponent: vi.fn(async () => ({ eid: 'mounted-1' })),
+    insertPlaceholder: vi.fn(async () => 'mounted-1'),
+    ...overrides,
+  }
+}
+
+describe('useWireframeDoc', () => {
+  let fetchMock: ReturnType<typeof vi.fn>
+  let warnSpy: ReturnType<typeof vi.spyOn>
+  let wf: ReturnType<typeof useWireframeDoc>
+
+  beforeEach(async () => {
+    fetchMock = vi.fn().mockResolvedValue(jsonResponse(docWith([])))
+    vi.stubGlobal('fetch', fetchMock)
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    wf = useWireframeDoc()
+    // The singleton's first useWireframeDoc() fires load(); let it settle so a
+    // late response can't clobber the doc a test seeds below.
+    await Promise.resolve()
+    await Promise.resolve()
+    wf.resetApplied()
+    wf.staleIds.value = []
+    wf.failedIds.value = []
+    wf.loadError.value = null
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  describe('reapply', () => {
+    it('mounts only placed (or legacy-undefined) instances — never building/applied', async () => {
+      wf.doc.value = docWith([
+        instance('wfi-placed', { status: 'placed' }),
+        instance('wfi-legacy'), // no status field == placed
+        instance('wfi-building', { status: 'building', taskId: 'task-1' }),
+        instance('wfi-applied', { status: 'applied', taskId: 'task-1' }),
+      ])
+      const iframe = makeIframe()
+      await wf.reapply('/r', iframe)
+      const mountedIds = vi.mocked(iframe.insertComponent).mock.calls.map((c) => c[5])
+      expect(mountedIds).toEqual(['wfi-placed', 'wfi-legacy'])
+    })
+
+    it('mounts components with previewProps when captured, falling back to inserted.props', async () => {
+      wf.doc.value = docWith([
+        instance('wfi-sampled', { previewProps: { label: 'Hello' } }),
+        instance('wfi-plain'),
+      ])
+      const iframe = makeIframe()
+      await wf.reapply('/r', iframe)
+      expect(iframe.insertComponent).toHaveBeenNthCalledWith(1, 'target-1', 'append', 'PlanetCard', { label: 'Hello' }, undefined, 'wfi-sampled')
+      expect(iframe.insertComponent).toHaveBeenNthCalledWith(2, 'target-1', 'append', 'PlanetCard', { real: true }, undefined, 'wfi-plain')
+    })
+
+    it('isolates per-instance failures — a throwing insert does not stop the next', async () => {
+      wf.doc.value = docWith([instance('wfi-boom'), instance('wfi-ok')])
+      const iframe = makeIframe({
+        insertComponent: vi.fn(async (...args: unknown[]) => {
+          if (args[5] === 'wfi-boom') throw new Error('mount failed')
+          return { eid: 'mounted-ok' }
+        }),
+      })
+      await wf.reapply('/r', iframe)
+      expect(iframe.insertComponent).toHaveBeenCalledTimes(2)
+      expect(wf.failedIds.value).toEqual(['wfi-boom'])
+      expect(warnSpy).toHaveBeenCalled()
+    })
+
+    it('records a stale anchor (empty template group) in staleIds instead of mounting', async () => {
+      wf.doc.value = docWith([instance('wfi-stale'), instance('wfi-live')])
+      const iframe = makeIframe({
+        findTemplateGroup: vi.fn(async (file: string, line: string) =>
+          line === '9' ? { eids: [] } : { eids: ['target-1'] }),
+      })
+      // Drift only the first instance's anchor resolution.
+      wf.doc.value.routes[0].instances[1].anchor.line = 22
+      await wf.reapply('/r', iframe)
+      expect(wf.staleIds.value).toEqual(['wfi-stale'])
+      expect(vi.mocked(iframe.insertComponent).mock.calls.map((c) => c[5])).toEqual(['wfi-live'])
+
+      // A later pass that resolves again clears the badge (no force needed —
+      // stale instances were never marked applied).
+      iframe.findTemplateGroup = vi.fn(async () => ({ eids: ['target-1'] }))
+      await wf.reapply('/r', iframe)
+      expect(wf.staleIds.value).toEqual([])
+    })
+
+    it('skips an instance whose stamped node is already in the iframe DOM', async () => {
+      wf.doc.value = docWith([instance('wfi-already'), instance('wfi-fresh')])
+      const iframe = makeIframe({
+        resolveBySelectors: vi.fn(async (selectors: string[]) => selectors.map((selector) => ({
+          selector,
+          eid: selector.includes('wfi-already') ? 'existing-eid' : null,
+        }))),
+      })
+      await wf.reapply('/r', iframe)
+      expect(iframe.resolveBySelectors).toHaveBeenCalledWith([
+        '[data-annotask-instance="wfi-already"]',
+        '[data-annotask-instance="wfi-fresh"]',
+      ])
+      expect(vi.mocked(iframe.insertComponent).mock.calls.map((c) => c[5])).toEqual(['wfi-fresh'])
+    })
+
+    it('does not re-mount an instance twice for the same route (appliedIds de-dup)', async () => {
+      wf.doc.value = docWith([instance('wfi-once')])
+      const iframe = makeIframe()
+      await wf.reapply('/r', iframe)
+      await wf.reapply('/r', iframe)
+      expect(iframe.insertComponent).toHaveBeenCalledTimes(1)
+      await wf.reapply('/r', iframe, { force: true })
+      expect(iframe.insertComponent).toHaveBeenCalledTimes(2)
+    })
+  })
+
+  describe('persist (rev round-trip)', () => {
+    it('sends the current rev and adopts the server-stamped doc on success', async () => {
+      wf.doc.value = docWith([])
+      fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+        const sent = JSON.parse(init!.body as string) as WireframeDocument
+        expect(sent.rev).toBe(1)
+        return jsonResponse({ ...sent, rev: 2 })
+      })
+      await wf.saveInstance('/r', instance('wfi-new'))
+      expect(wf.doc.value.rev).toBe(2)
+      expect(wf.loadError.value).toBeNull()
+    })
+
+    it('on 409 it reloads the doc, surfaces a conflict message, and does not retry the write', async () => {
+      wf.doc.value = docWith([instance('wfi-mine')])
+      const serverDoc = { ...docWith([instance('wfi-theirs')]), rev: 5 }
+      fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+        if (init?.method === 'PUT') return jsonResponse({ error: { code: 'conflict', message: 'stale' } }, 409)
+        return jsonResponse(serverDoc) // the reload GET
+      })
+      await wf.saveInstance('/r', instance('wfi-another'))
+      const puts = fetchMock.mock.calls.filter((c) => (c[1] as RequestInit | undefined)?.method === 'PUT')
+      expect(puts).toHaveLength(1)
+      expect(wf.doc.value.rev).toBe(5)
+      expect(wf.instancesForRoute('/r').map((i) => i.id)).toEqual(['wfi-theirs'])
+      expect(wf.loadError.value).toContain('changed in another tab')
+    })
+  })
+
+  describe('markInstancesBuilding / deleteInstance', () => {
+    beforeEach(() => {
+      // Echo PUTs back with a bumped rev so doc.value stays coherent.
+      fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+        if (init?.method === 'PUT') {
+          const sent = JSON.parse(init.body as string) as WireframeDocument
+          return jsonResponse({ ...sent, rev: (sent.rev ?? 0) + 1 })
+        }
+        return jsonResponse(docWith([]))
+      })
+    })
+
+    it('stamps the batch building with the owning task id in ONE persist', async () => {
+      wf.doc.value = docWith([instance('wfi-a'), instance('wfi-b'), instance('wfi-c')])
+      await wf.markInstancesBuilding('/r', ['wfi-a', 'wfi-c'], 'task-7')
+      const byId = Object.fromEntries(wf.instancesForRoute('/r').map((i) => [i.id, i]))
+      expect(byId['wfi-a'].status).toBe('building')
+      expect(byId['wfi-a'].taskId).toBe('task-7')
+      expect(byId['wfi-c'].status).toBe('building')
+      expect(byId['wfi-b'].status).toBeUndefined()
+      const puts = fetchMock.mock.calls.filter((c) => (c[1] as RequestInit | undefined)?.method === 'PUT')
+      expect(puts).toHaveLength(1)
+    })
+
+    it('deleteInstance drops the instance and its stale/failed bookkeeping', async () => {
+      wf.doc.value = docWith([instance('wfi-dead'), instance('wfi-kept')])
+      wf.staleIds.value = ['wfi-dead']
+      wf.failedIds.value = ['wfi-dead']
+      await wf.deleteInstance('/r', 'wfi-dead')
+      expect(wf.instancesForRoute('/r').map((i) => i.id)).toEqual(['wfi-kept'])
+      expect(wf.staleIds.value).toEqual([])
+      expect(wf.failedIds.value).toEqual([])
+    })
+  })
+
+  describe('snapshot-wireframe canvas', () => {
+    const canvas = {
+      capturedAt: 9,
+      viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+      blocks: [{
+        id: 'wfb-1', kind: 'captured' as const,
+        rect: { x: 0, y: 80, width: 800, height: 240 }, z: 1, createdAt: 1,
+        anchor: { file: 'src/pages/PlanetsPage.vue', line: 12 },
+        originalRect: { x: 0, y: 80, width: 800, height: 240 },
+        image: 'wfb-1.png',
+      }],
+    }
+
+    it('saveCanvas creates the route entry when absent and persists once', async () => {
+      wf.doc.value = { version: '1.0', updatedAt: 0, rev: 1, routes: [] }
+      // Echo the PUT body back like the real server (rev stamped).
+      fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+        if (init?.method === 'PUT') return jsonResponse({ ...JSON.parse(init.body as string), rev: 2 })
+        return jsonResponse(docWith([]))
+      })
+      await wf.saveCanvas('/planets', canvas)
+      expect(wf.canvasForRoute('/planets')?.blocks).toHaveLength(1)
+      const puts = fetchMock.mock.calls.filter((c) => (c[1] as RequestInit | undefined)?.method === 'PUT')
+      expect(puts).toHaveLength(1)
+      const sent = JSON.parse(puts[0][1].body as string)
+      expect(sent.routes[0].canvas.blocks[0].id).toBe('wfb-1')
+    })
+
+    it('canvasForRoute returns null when the route has no canvas', () => {
+      wf.doc.value = docWith([instance('wfi-1')])
+      expect(wf.canvasForRoute('/r')).toBeNull()
+      expect(wf.canvasForRoute('/elsewhere')).toBeNull()
+    })
+
+    it('clearCanvas removes the canvas and persists; no-ops without one', async () => {
+      wf.doc.value = { version: '1.0', updatedAt: 0, rev: 1, routes: [{ route: '/planets', instances: [], canvas }] }
+      fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+        if (init?.method === 'PUT') return jsonResponse({ ...JSON.parse(init.body as string), rev: 2 })
+        return jsonResponse(docWith([]))
+      })
+      await wf.clearCanvas('/planets')
+      expect(wf.canvasForRoute('/planets')).toBeNull()
+      const putsAfterClear = fetchMock.mock.calls.filter((c) => (c[1] as RequestInit | undefined)?.method === 'PUT').length
+      expect(putsAfterClear).toBe(1)
+      await wf.clearCanvas('/planets') // already gone — must not PUT again
+      const putsAfterNoop = fetchMock.mock.calls.filter((c) => (c[1] as RequestInit | undefined)?.method === 'PUT').length
+      expect(putsAfterNoop).toBe(1)
+    })
+  })
+})
diff --git a/src/shell/composables/__tests__/useWireframeMode.test.ts b/src/shell/composables/__tests__/useWireframeMode.test.ts
new file mode 100644
index 0000000..07185dc
--- /dev/null
+++ b/src/shell/composables/__tests__/useWireframeMode.test.ts
@@ -0,0 +1,513 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import { ref, nextTick } from 'vue'
+
+vi.mock('../../services/wsClient', () => ({
+  on: () => () => { /* no-op */ },
+  send: () => { /* no-op */ },
+  isConnected: () => true,
+}))
+
+import { useWireframeMode, type WireframeModeIframe } from '../useWireframeMode'
+import { useWireframeDoc } from '../useWireframeDoc'
+import type { WireframeCaptureResult } from '../../../shared/bridge-types'
+import type { InteractionMode } from '../useInteractionMode'
+
+const CAPTURE_OK: WireframeCaptureResult = {
+  viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+  fullDataUrl: 'data:image/png;base64,FULL',
+  blocks: [
+    {
+      eid: 'e1', file: 'src/pages/PlanetsPage.vue', line: '12', component: 'PlanetsPage',
+      source_tag: 'header', tag: 'header', cls: 'page-header', role: 'header',
+      rect: { x: 0, y: 0, width: 1280, height: 80 }, dataUrl: 'data:image/png;base64,A',
+    },
+    {
+      eid: 'e2', file: 'src/pages/PlanetsPage.vue', line: '30', component: 'PlanetsPage',
+      source_tag: 'div', tag: 'div', cls: 'toolbar', role: 'content',
+      rect: { x: 0, y: 80, width: 1280, height: 600 }, dataUrl: 'data:image/png;base64,B',
+    },
+    {
+      eid: 'e3', file: '', line: '', component: '', source_tag: '', tag: 'section', cls: '', role: 'content',
+      rect: { x: 0, y: 680, width: 1280, height: 200 }, dataUrl: null, error: 'capture failed',
+    },
+  ],
+}
+
+function makeIframe(result: WireframeCaptureResult = CAPTURE_OK): WireframeModeIframe & { currentRoute: ReturnType<typeof ref<string>> } {
+  return {
+    currentRoute: ref('/planets'),
+    bridgeReady: ref(true),
+    captureWireframe: vi.fn(async () => result),
+    previewComponent: vi.fn(async () => ({ mounted: true, fidelity: 'isolated-preview', dataUrl: 'data:image/png;base64,P', width: 320, height: 140 })),
+    findTemplateGroup: vi.fn(async () => ({ eids: ['live-1'] })),
+    onBridgeEvent: vi.fn(),
+  } as never
+}
+
+describe('useWireframeMode', () => {
+  let fetchMock: ReturnType<typeof vi.fn>
+  let wf: ReturnType<typeof useWireframeDoc>
+
+  beforeEach(async () => {
+    localStorage.removeItem('annotask:wireframe')
+    fetchMock = vi.fn().mockImplementation(async (url: string, init?: RequestInit) => {
+      if (String(url).includes('wireframe-snapshots') && init?.method === 'POST') {
+        const body = JSON.parse(init.body as string) as { id: string }
+        return { ok: true, status: 200, json: async () => ({ filename: `${body.id}.png` }) } as unknown as Response
+      }
+      if (init?.method === 'PUT') {
+        return { ok: true, status: 200, json: async () => ({ ...JSON.parse(init.body as string), rev: 2 }) } as unknown as Response
+      }
+      if (init?.method === 'DELETE') {
+        return { ok: true, status: 200, json: async () => ({}) } as unknown as Response
+      }
+      return { ok: true, status: 200, json: async () => ({ version: '1.0', updatedAt: 0, rev: 1, routes: [] }) } as unknown as Response
+    })
+    vi.stubGlobal('fetch', fetchMock)
+    wf = useWireframeDoc()
+    await Promise.resolve()
+    await Promise.resolve()
+    wf.doc.value = { version: '1.0', updatedAt: 0, rev: 1, routes: [] }
+    wf.loadError.value = null
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+    localStorage.removeItem('annotask:wireframe')
+  })
+
+  function makeMode(iframe = makeIframe()) {
+    const interactionMode = ref<InteractionMode>('interact')
+    const shellView = ref('design')
+    const mode = useWireframeMode({ iframe, interactionMode, shellView })
+    return { mode, iframe, interactionMode, shellView }
+  }
+
+  it('enter() captures, anchors blocks, uploads PNGs, persists, and activates', async () => {
+    const { mode, interactionMode } = makeMode()
+    await mode.enter()
+
+    expect(mode.active.value).toBe(true)
+    expect(interactionMode.value).toBe('select')
+    expect(localStorage.getItem('annotask:wireframe')).toBe('1')
+
+    const canvas = mode.canvas.value!
+    expect(canvas.blocks).toHaveLength(3)
+    expect(canvas.viewport.docHeight).toBe(2400)
+    // Anchors survive the bridge → block translation.
+    expect(canvas.blocks[0].anchor).toMatchObject({ file: 'src/pages/PlanetsPage.vue', line: 12, role: 'header' })
+    expect(canvas.blocks[0].originalRect).toEqual(canvas.blocks[0].rect)
+    // The unstamped failing block stays honest: no image, captureError set.
+    expect(canvas.blocks[2].captureError).toBe('capture failed')
+    expect(canvas.blocks[2].image).toBeUndefined()
+    expect(mode.imageSrc(canvas.blocks[2])).toBeNull()
+
+    // Uploads: 2 block PNGs + 1 full page; canvas persisted with filenames.
+    const posts = fetchMock.mock.calls.filter((c) => String(c[0]).includes('wireframe-snapshots') && (c[1] as RequestInit)?.method === 'POST')
+    expect(posts).toHaveLength(3)
+    expect(canvas.blocks[0].image).toMatch(/^wfb-.+\.png$/)
+    expect(canvas.fullImage).toMatch(/^wf-full-.+\.png$/)
+    // In-session render uses the dataUrl, not the uploaded file.
+    expect(mode.imageSrc(canvas.blocks[0])).toBe('data:image/png;base64,A')
+    expect(wf.canvasForRoute('/planets')?.blocks).toHaveLength(3)
+  })
+
+  it('enter() reuses a persisted canvas without capturing; images come from the sidecar route', async () => {
+    const persisted = {
+      capturedAt: 5,
+      viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+      blocks: [{
+        id: 'wfb-old', kind: 'captured' as const,
+        rect: { x: 0, y: 0, width: 100, height: 50 }, z: 1, createdAt: 1,
+        anchor: { file: 'a.vue', line: 1 }, originalRect: { x: 0, y: 0, width: 100, height: 50 },
+        image: 'wfb-old.png',
+      }],
+    }
+    wf.doc.value = { version: '1.0', updatedAt: 0, rev: 1, routes: [{ route: '/planets', instances: [], canvas: persisted }] }
+    const { mode, iframe } = makeMode()
+    await mode.enter()
+    expect(mode.active.value).toBe(true)
+    expect(iframe.captureWireframe).not.toHaveBeenCalled()
+    expect(mode.imageSrc(mode.canvas.value!.blocks[0])).toBe('/__annotask/wireframe-snapshots/wfb-old.png')
+  })
+
+  it('a failed capture surfaces the error and stays in live view', async () => {
+    const { mode } = makeMode(makeIframe({ error: 'failed to load html2canvas' }))
+    await mode.enter()
+    expect(mode.active.value).toBe(false)
+    expect(mode.error.value).toBe('failed to load html2canvas')
+    expect(localStorage.getItem('annotask:wireframe')).toBeNull()
+  })
+
+  it('exit() is lossless bookkeeping: flag cleared, canvas stays persisted', async () => {
+    const { mode } = makeMode()
+    await mode.enter()
+    mode.exit()
+    expect(mode.active.value).toBe(false)
+    expect(localStorage.getItem('annotask:wireframe')).toBeNull()
+    expect(wf.canvasForRoute('/planets')).not.toBeNull()
+  })
+
+  it('route change and leaving the design view exit the mode', async () => {
+    const { mode, iframe, shellView } = makeMode()
+    await mode.enter()
+    iframe.currentRoute.value = '/moons'
+    await nextTick()
+    expect(mode.active.value).toBe(false)
+
+    iframe.currentRoute.value = '/planets'
+    await nextTick() // route watcher settles before the user re-toggles
+    await mode.enter() // canvas persisted → instant re-entry
+    expect(mode.active.value).toBe(true)
+    shellView.value = 'editor'
+    await nextTick()
+    expect(mode.active.value).toBe(false)
+  })
+
+  it('recapture() discards the old canvas + snapshot files and captures fresh', async () => {
+    const { mode } = makeMode()
+    await mode.enter()
+    const oldFirstId = mode.canvas.value!.blocks[0].id
+    await mode.recapture()
+    expect(mode.active.value).toBe(true)
+    expect(mode.canvas.value!.blocks[0].id).not.toBe(oldFirstId)
+    const deletes = fetchMock.mock.calls.filter((c) => String(c[0]).includes('wireframe-snapshots/') && (c[1] as RequestInit)?.method === 'DELETE')
+    expect(deletes.length).toBeGreaterThanOrEqual(3) // 2 block files + full page
+  })
+
+  describe('block operations (W2)', () => {
+    it('updateBlockRect / bringToFront / setNote mutate the working canvas', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const [a, b] = mode.canvas.value!.blocks
+      mode.updateBlockRect(a.id, { x: 10, y: 20, width: 300, height: 150 })
+      expect(a.rect).toEqual({ x: 10, y: 20, width: 300, height: 150 })
+      expect(a.originalRect).toEqual({ x: 0, y: 0, width: 1280, height: 80 }) // diff baseline untouched
+
+      mode.bringToFront(a.id)
+      expect(a.z).toBeGreaterThan(b.z)
+
+      mode.setNote(a.id, '  make this a carousel  ')
+      expect(a.note).toBe('make this a carousel')
+      mode.setNote(a.id, '   ')
+      expect(a.note).toBeUndefined()
+    })
+
+    it('captured blocks soft-delete (diff fact) and can be restored; sketch blocks remove outright', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const captured = mode.canvas.value!.blocks[0]
+      mode.deleteBlock(captured.id)
+      expect(captured.deleted).toBe(true)
+      expect(mode.canvas.value!.blocks).toHaveLength(3) // still in the doc
+      expect(mode.deletedBlocks.value.map((b) => b.id)).toEqual([captured.id])
+      mode.undeleteBlock(captured.id)
+      expect(captured.deleted).toBeUndefined()
+
+      const phId = mode.addPlaceholderBlock({ x: 5, y: 5, width: 100, height: 50 }, 'pagination here')!
+      mode.deleteBlock(phId)
+      expect(mode.canvas.value!.blocks.find((b) => b.id === phId)).toBeUndefined()
+    })
+
+    it('duplicateBlock offsets +16/+16, tops z, shares the image, and roots duplicateOf', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const src = mode.canvas.value!.blocks[0]
+      const copyId = mode.duplicateBlock(src.id)!
+      const copy = mode.canvas.value!.blocks.find((b) => b.id === copyId)!
+      expect(copy.rect.x).toBe(src.rect.x + 16)
+      expect(copy.rect.y).toBe(src.rect.y + 16)
+      expect(copy.z).toBeGreaterThan(src.z)
+      expect(copy.duplicateOf).toBe(src.id)
+      expect(copy.image).toBe(src.image)
+      // The session dataUrl resolves through the duplicate chain.
+      expect(mode.imageSrc(copy)).toBe('data:image/png;base64,A')
+      // A duplicate of the duplicate still roots at the original.
+      const grandId = mode.duplicateBlock(copyId)!
+      expect(mode.canvas.value!.blocks.find((b) => b.id === grandId)!.duplicateOf).toBe(src.id)
+    })
+
+    it('deleting one of two blocks sharing an image keeps the file; the last one drops it', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      // Palette block (hard-delete path) + its duplicate share one file.
+      await mode.addPaletteBlock(
+        { tag: 'planetcard', componentName: 'PlanetCard', module: './components/PlanetCard.vue' },
+        { dataUrl: 'data:image/png;base64,P', width: 320, height: 140, fidelity: 'isolated-preview', mounted: true },
+        { x: 40, y: 40 },
+      )
+      const palette = mode.canvas.value!.blocks.find((b) => b.kind === 'palette')!
+      const dupId = mode.duplicateBlock(palette.id)!
+      const fileDeletes = () => fetchMock.mock.calls.filter((c) => String(c[0]).includes(`wireframe-snapshots/${palette.image}`) && (c[1] as RequestInit)?.method === 'DELETE').length
+
+      mode.deleteBlock(palette.id)
+      expect(fileDeletes()).toBe(0) // duplicate still references the file
+      mode.deleteBlock(dupId)
+      expect(fileDeletes()).toBe(1)
+    })
+
+    it('placeComponentBlock mints an imageless, selected block as ONE undo entry', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const id = mode.placeComponentBlock(
+        { tag: 'planetcard', componentName: 'PlanetCard', module: './components/PlanetCard.vue', props: { real: true }, mfe: 'planets' },
+        { x: 100, y: 200 },
+      )!
+      const block = mode.findBlock(id)!
+      // Honest from the first frame: no fabricated image, placeholder fidelity.
+      expect(block.kind).toBe('palette')
+      expect(block.fidelity).toBe('placeholder')
+      expect(block.image).toBeUndefined()
+      expect(mode.imageSrc(block)).toBeNull()
+      expect(block.rect).toMatchObject({ x: 100, y: 200, width: 320, height: 120 })
+      expect(block.component).toMatchObject({ componentName: 'PlanetCard', props: { real: true }, mfe: 'planets' })
+      // Auto-selected + shimmering.
+      expect(mode.selection.selectedIds.value).toEqual([id])
+      expect(mode.generatingIds.value.has(id)).toBe(true)
+
+      // The background fill folds into the drop's single undo entry.
+      await mode.updatePaletteBlock(
+        id,
+        { previewProps: {}, snapshot: { dataUrl: 'data:image/png;base64,P', width: 320, height: 140, fidelity: 'isolated-preview', mounted: true } },
+        { recordHistory: false },
+      )
+      expect(mode.findBlock(id)!.fidelity).toBe('isolated-preview')
+      expect(mode.findBlock(id)!.image).toMatch(/\.png$/)
+      expect(mode.history.canUndo.value).toBe(true)
+      mode.history.undo()
+      expect(mode.findBlock(id)).toBeNull() // one undo removes the whole block (place + fill)
+      expect(mode.history.canUndo.value).toBe(false)
+    })
+
+    it('a place-first block is honest before its snapshot fills (client-only shimmer)', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const id = mode.placeComponentBlock({ tag: 'planetcard', componentName: 'PlanetCard' }, { x: 10, y: 20 })!
+      const block = mode.findBlock(id)!
+      // The PERSISTED block is honest: no 'generating' fidelity, no image.
+      expect(block.fidelity).toBe('placeholder')
+      expect(block.image).toBeUndefined()
+      expect(mode.imageSrc(block)).toBeNull()
+      // The shimmer is client-only state, not on the block — a reload (fresh
+      // mode reading the same doc) starts with no shimmer and an honest block.
+      expect(mode.generatingIds.value.has(id)).toBe(true)
+      const fresh = makeMode().mode
+      expect(fresh.generatingIds.value.has(id)).toBe(false)
+    })
+
+    it('dropPaletteItem turns catalog items into labeled placeholders', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      await mode.dropPaletteItem({ kind: 'layout-preset', tag: 'div', category: 'flex row' }, { x: 0, y: 0 })
+      const ph = mode.canvas.value!.blocks.filter((b) => b.kind === 'placeholder')
+      expect(ph).toHaveLength(1)
+      expect(ph[0].label).toBe('flex row')
+    })
+  })
+
+  describe('explode (W4)', () => {
+    const CHILD_CAPTURE: WireframeCaptureResult = {
+      viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+      shellDataUrl: 'data:image/png;base64,SHELL',
+      blocks: [
+        {
+          eid: 'c1', file: 'src/pages/PlanetsPage.vue', line: '31', component: 'PlanetsPage',
+          source_tag: 'div', tag: 'div', cls: 'search-row', role: 'content',
+          rect: { x: 0, y: 90, width: 600, height: 40 }, dataUrl: 'data:image/png;base64,C1',
+        },
+        {
+          eid: 'c2', file: 'src/pages/PlanetsPage.vue', line: '35', component: 'PlanetsPage',
+          source_tag: 'div', tag: 'div', cls: 'sort-row', role: 'content',
+          rect: { x: 620, y: 90, width: 600, height: 40 }, dataUrl: 'data:image/png;base64,C2',
+        },
+      ],
+    }
+
+    it('keeps the parent as a SHELL backdrop and adds translated children with their own anchors', async () => {
+      const { mode, iframe } = makeMode()
+      await mode.enter()
+      const parent = mode.canvas.value!.blocks[1] // div.toolbar, y 80
+      const parentImage = parent.image
+      // The user moved the parent +0/+30 before exploding — children follow.
+      mode.updateBlockRect(parent.id, { ...parent.rect, y: parent.rect.y + 30 })
+
+      vi.mocked(iframe.captureWireframe).mockResolvedValueOnce(CHILD_CAPTURE)
+      const ok = await mode.explodeBlock(parent.id)
+      expect(ok).toBe(true)
+      expect(iframe.findTemplateGroup).toHaveBeenCalledWith('src/pages/PlanetsPage.vue', '30', 'div')
+      expect(iframe.captureWireframe).toHaveBeenLastCalledWith({ rootEid: 'live-1' })
+
+      const blocks = mode.canvas.value!.blocks
+      // The parent survives as the container shell — its surface styling stays
+      // visible under the children (this was the "double-click removes the
+      // styling" bug).
+      const shell = blocks.find((b) => b.id === parent.id)!
+      expect(shell.shell).toBe(true)
+      expect(shell.image).toBe(`${parent.id}-shell.png`)
+      expect(mode.imageSrc(shell)).toBe('data:image/png;base64,SHELL')
+      // A second explode of the shell is refused.
+      expect(await mode.explodeBlock(parent.id)).toBe(false)
+      expect(mode.error.value).toContain('Already exploded')
+
+      const children = blocks.filter((b) => b.anchor?.cssClass === 'search-row' || b.anchor?.cssClass === 'sort-row')
+      expect(children).toHaveLength(2)
+      // Canvas rects ride the parent's move delta; the diff baseline stays live.
+      expect(children[0].rect.y).toBe(120)
+      expect(children[0].originalRect!.y).toBe(90)
+      expect(children[0].anchor).toMatchObject({ file: 'src/pages/PlanetsPage.vue', line: 31 })
+      expect(children[0].image).toMatch(/\.png$/)
+      // Children stack above the shell.
+      expect(Math.min(...children.map((b) => b.z))).toBeGreaterThan(shell.z)
+      // The parent's ORIGINAL snapshot file was dropped (nothing references it).
+      const deletes = fetchMock.mock.calls.filter((c) => String(c[0]).includes(`wireframe-snapshots/${parentImage}`) && (c[1] as RequestInit)?.method === 'DELETE')
+      expect(deletes).toHaveLength(1)
+    })
+
+    it('falls back to removing the parent when no shell could be captured (a stale image would ghost the children)', async () => {
+      const { mode, iframe } = makeMode()
+      await mode.enter()
+      const parent = mode.canvas.value!.blocks[1]
+      vi.mocked(iframe.captureWireframe).mockResolvedValueOnce({ ...CHILD_CAPTURE, shellDataUrl: undefined })
+      expect(await mode.explodeBlock(parent.id)).toBe(true)
+      expect(mode.canvas.value!.blocks.find((b) => b.id === parent.id)).toBeUndefined()
+    })
+
+    it('an unresolvable anchor keeps the block and surfaces an error', async () => {
+      const { mode, iframe } = makeMode()
+      await mode.enter()
+      vi.mocked(iframe.findTemplateGroup).mockResolvedValueOnce({ eids: [] })
+      const parent = mode.canvas.value!.blocks[0]
+      expect(await mode.explodeBlock(parent.id)).toBe(false)
+      expect(mode.error.value).toContain('Could not find this block')
+      expect(mode.canvas.value!.blocks.find((b) => b.id === parent.id)).toBeDefined()
+    })
+
+    it('a block with no separable children stays intact', async () => {
+      const { mode, iframe } = makeMode()
+      await mode.enter()
+      const parent = mode.canvas.value!.blocks[0]
+      vi.mocked(iframe.captureWireframe).mockResolvedValueOnce({
+        viewport: CAPTURE_OK.viewport,
+        blocks: [{
+          eid: 'live-1', file: 'src/pages/PlanetsPage.vue', line: '12', component: 'PlanetsPage',
+          source_tag: 'header', tag: 'header', cls: 'page-header', role: 'header',
+          rect: { x: 0, y: 0, width: 1280, height: 80 }, dataUrl: 'data:image/png;base64,A',
+        }],
+      })
+      expect(await mode.explodeBlock(parent.id)).toBe(false)
+      expect(mode.error.value).toContain('no separable children')
+      expect(mode.canvas.value!.blocks.find((b) => b.id === parent.id)).toBeDefined()
+    })
+  })
+
+  it('boot restore re-enters only with both the flag and a persisted canvas', async () => {
+    localStorage.setItem('annotask:wireframe', '1')
+    // No canvas persisted → flag is cleared, mode stays off.
+    const first = makeMode()
+    await nextTick()
+    expect(first.mode.active.value).toBe(false)
+    expect(localStorage.getItem('annotask:wireframe')).toBeNull()
+
+    // With a persisted canvas → boots straight into the sketch.
+    localStorage.setItem('annotask:wireframe', '1')
+    wf.doc.value = {
+      version: '1.0', updatedAt: 0, rev: 1,
+      routes: [{
+        route: '/planets', instances: [],
+        canvas: {
+          capturedAt: 5,
+          viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+          blocks: [],
+        },
+      }],
+    }
+    const second = makeMode()
+    await nextTick()
+    expect(second.mode.active.value).toBe(true)
+  })
+
+  describe('z-order + undo/redo', () => {
+    it('bringToFront / sendToBack / forward / backward reorder z', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const [b0, b1, b2] = mode.canvas.value!.blocks
+      expect([b0.z, b1.z, b2.z]).toEqual([1, 2, 3])
+
+      mode.sendToBack(b2.id)
+      expect(b2.z).toBeLessThan(b0.z)
+
+      mode.bringToFront(b0.id)
+      expect(b0.z).toBeGreaterThan(b1.z)
+      expect(b0.z).toBeGreaterThan(b2.z)
+
+      // forward/backward swap with the nearest neighbour in z order.
+      const beforeFwd = b1.z
+      mode.bringForward(b1.id)
+      expect(b1.z).toBeGreaterThan(beforeFwd)
+    })
+
+    it('undo reverts a z change and restores the prior selection; redo re-applies', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const b0 = mode.canvas.value!.blocks[0]
+      const z0 = b0.z
+      mode.selection.select(b0.id)
+
+      mode.bringToFront(b0.id)
+      const raised = mode.canvas.value!.blocks.find((b) => b.id === b0.id)!.z
+      expect(raised).toBeGreaterThan(z0)
+
+      // Selection moves elsewhere; undo must bring it back to where the edit was.
+      mode.selection.clear()
+      mode.undo()
+      expect(mode.canvas.value!.blocks.find((b) => b.id === b0.id)!.z).toBe(z0)
+      expect(mode.selection.selectedIds.value).toEqual([b0.id])
+
+      mode.redo()
+      expect(mode.canvas.value!.blocks.find((b) => b.id === b0.id)!.z).toBe(raised)
+    })
+
+    it('a begin/end-bracketed move is one undo step', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const b0 = mode.canvas.value!.blocks[0]
+      const orig = { ...b0.rect }
+
+      // Simulate a drag gesture: one entry, several rect updates.
+      mode.history.begin()
+      mode.updateBlockRect(b0.id, { ...orig, x: orig.x + 10 })
+      mode.updateBlockRect(b0.id, { ...orig, x: orig.x + 40 })
+      mode.history.end()
+      expect(mode.canvas.value!.blocks[0].rect.x).toBe(orig.x + 40)
+
+      mode.undo()
+      expect(mode.canvas.value!.blocks[0].rect.x).toBe(orig.x)
+      expect(mode.history.canUndo.value).toBe(false)
+    })
+
+    it('undo restores a soft-deleted captured block', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const b0 = mode.canvas.value!.blocks[0]
+      mode.deleteBlock(b0.id)
+      expect(mode.canvas.value!.blocks.find((b) => b.id === b0.id)!.deleted).toBe(true)
+
+      mode.undo()
+      expect(mode.canvas.value!.blocks.find((b) => b.id === b0.id)!.deleted).toBeUndefined()
+    })
+
+    it('undo/redo are no-ops while the sketch is building (locked)', async () => {
+      const { mode } = makeMode()
+      await mode.enter()
+      const b0 = mode.canvas.value!.blocks[0]
+      mode.bringToFront(b0.id)
+      const raised = mode.canvas.value!.blocks.find((b) => b.id === b0.id)!.z
+
+      mode.canvas.value!.status = 'building'
+      mode.undo() // locked — must not roll back
+      expect(mode.canvas.value!.blocks.find((b) => b.id === b0.id)!.z).toBe(raised)
+    })
+  })
+})
diff --git a/src/shell/composables/__tests__/wsClient.test.ts b/src/shell/composables/__tests__/wsClient.test.ts
new file mode 100644
index 0000000..82e9e3f
--- /dev/null
+++ b/src/shell/composables/__tests__/wsClient.test.ts
@@ -0,0 +1,96 @@
+// @vitest-environment jsdom
+// wsClient dereferences `window.location` at import time (auto-connect), so
+// this suite needs a DOM-flavored global — the rest of the composable tests
+// run fine under node.
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest'
+
+/**
+ * Controllable WebSocket stub — jsdom's implementation actually tries to
+ * connect, and we need to drive open/close transitions deterministically.
+ * Statics mirror the readyState constants wsClient reads off the global.
+ */
+class FakeWebSocket {
+  static instances: FakeWebSocket[] = []
+  static CONNECTING = 0
+  static OPEN = 1
+  static CLOSING = 2
+  static CLOSED = 3
+  url: string
+  readyState = FakeWebSocket.CONNECTING
+  onopen: (() => void) | null = null
+  onclose: (() => void) | null = null
+  onerror: (() => void) | null = null
+  onmessage: ((e: { data: string }) => void) | null = null
+  constructor(url: string) {
+    this.url = url
+    FakeWebSocket.instances.push(this)
+  }
+  send(): void { /* no-op */ }
+  close(): void { /* no-op */ }
+}
+
+describe('wsClient reconnected event', () => {
+  let on: typeof import('../../services/wsClient')['on']
+
+  beforeAll(async () => {
+    vi.useFakeTimers()
+    vi.stubGlobal('WebSocket', FakeWebSocket)
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+    // Import AFTER stubbing — the module auto-connects at import time.
+    ;({ on } = await import('../../services/wsClient'))
+  })
+  afterAll(() => {
+    vi.unstubAllGlobals()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('fires only on a re-open after a drop, never on the initial connect', () => {
+    let reconnects = 0
+    on('reconnected', () => { reconnects++ })
+
+    const first = FakeWebSocket.instances[0]
+    expect(first).toBeDefined()
+
+    // Initial open: consumers fetch on init, so no resync signal.
+    first.readyState = FakeWebSocket.OPEN
+    first.onopen?.()
+    expect(reconnects).toBe(0)
+
+    // Drop → backoff timer → re-open: resync signal fires exactly once.
+    first.readyState = FakeWebSocket.CLOSED
+    first.onclose?.()
+    vi.advanceTimersByTime(1000) // first backoff step (1000 * 2^0)
+    const second = FakeWebSocket.instances[1]
+    expect(second).toBeDefined()
+    second.readyState = FakeWebSocket.OPEN
+    second.onopen?.()
+    expect(reconnects).toBe(1)
+
+    // A second drop/re-open cycle fires again — the flag is "ever
+    // connected", not a one-shot.
+    second.readyState = FakeWebSocket.CLOSED
+    second.onclose?.()
+    vi.advanceTimersByTime(1000)
+    const third = FakeWebSocket.instances[2]
+    expect(third).toBeDefined()
+    third.readyState = FakeWebSocket.OPEN
+    third.onopen?.()
+    expect(reconnects).toBe(2)
+  })
+
+  it('keeps the on/off contract: unsubscribing stops reconnected delivery', () => {
+    let seen = 0
+    const off = on('reconnected', () => { seen++ })
+    off()
+
+    const current = FakeWebSocket.instances[FakeWebSocket.instances.length - 1]
+    current.readyState = FakeWebSocket.CLOSED
+    current.onclose?.()
+    vi.advanceTimersByTime(1000)
+    const next = FakeWebSocket.instances[FakeWebSocket.instances.length - 1]
+    next.readyState = FakeWebSocket.OPEN
+    next.onopen?.()
+    expect(seen).toBe(0)
+  })
+})
diff --git a/src/shell/composables/useA11yHighlights.ts b/src/shell/composables/useA11yHighlights.ts
index fdbc6aa..ff26ee5 100644
--- a/src/shell/composables/useA11yHighlights.ts
+++ b/src/shell/composables/useA11yHighlights.ts
@@ -8,12 +8,15 @@
  * overlays inherit the active shell theme. When `focusedRule` is set, that
  * rule's overlays are visually emphasized and the rest are dimmed.
  *
- * Patterned after useDataHighlights.ts — same RECT_CAP, same loop shape.
+ * Shares the rAF lifecycle + re-entrancy/visibility guards with the Data view
+ * via `useOverlayLoop` (useOverlayEngine.ts); this file only owns the
+ * selector/eid resolve and the per-violation rect shape.
  */
-import { ref, watch, type Ref } from 'vue'
+import { ref, type Ref } from 'vue'
 import type { BridgeRect } from '../../shared/bridge-types'
 import type { useIframeManager } from './useIframeManager'
 import type { A11yViolation } from './useA11yScanner'
+import { useOverlayLoop, OVERLAY_RECT_CAP } from './useOverlayEngine'
 
 export interface A11yHighlightRect {
   ruleId: string
@@ -23,8 +26,6 @@ export interface A11yHighlightRect {
   rect: BridgeRect
 }
 
-const RECT_CAP = 400
-
 export function useA11yHighlights(deps: {
   iframe: ReturnType<typeof useIframeManager>
   violations: Ref<A11yViolation[]>
@@ -39,13 +40,8 @@ export function useA11yHighlights(deps: {
 
   const rects = ref<A11yHighlightRect[]>([])
 
-  let loopRunning = false
-  let refreshInFlight = false
-
   async function refreshRects(): Promise<void> {
-    if (refreshInFlight) return
-    refreshInFlight = true
-    try {
+    {
       if (!active.value || violations.value.length === 0) {
         if (rects.value.length) rects.value = []
         return
@@ -61,10 +57,10 @@ export function useA11yHighlights(deps: {
         if (!v.elements) continue
         for (const el of v.elements) {
           if (!el.target && !el.eid) continue
-          if (items.length >= RECT_CAP) break
+          if (items.length >= OVERLAY_RECT_CAP) break
           items.push({ ruleId: v.id, impact: v.impact || 'minor', selector: el.target, eid: el.eid })
         }
-        if (items.length >= RECT_CAP) break
+        if (items.length >= OVERLAY_RECT_CAP) break
       }
 
       if (items.length === 0) {
@@ -105,48 +101,19 @@ export function useA11yHighlights(deps: {
         }
       }
       rects.value = out
-    } finally {
-      refreshInFlight = false
-    }
-  }
-
-  function startLoop(): void {
-    if (loopRunning) return
-    if (!active.value) return
-    loopRunning = true
-    const tick = () => {
-      if (!active.value || violations.value.length === 0) {
-        loopRunning = false
-        return
-      }
-      if (typeof document !== 'undefined' && document.hidden) {
-        requestAnimationFrame(tick)
-        return
-      }
-      refreshRects()
-      requestAnimationFrame(tick)
     }
-    requestAnimationFrame(tick)
   }
 
-  watch(active, (v, old) => {
-    if (v && !old) {
-      // Re-entering the A11y view — refresh rects now instead of waiting for
-      // the next rAF tick so the user sees outlines immediately without
-      // needing to scroll or rescan.
-      refreshRects()
-      startLoop()
-    } else if (!v && old) rects.value = []
+  // Shared overlay loop owns the rAF lifecycle + re-entrancy/visibility guards;
+  // this composable supplies the refresh body and what "idle" means.
+  useOverlayLoop({
+    active,
+    refresh: refreshRects,
+    inputs: () => violations.value,
+    isIdle: () => violations.value.length === 0,
+    onDeactivate: () => { rects.value = [] },
   })
 
-  watch(violations, () => {
-    if (active.value) {
-      refreshRects()
-      startLoop()
-    }
-    if (violations.value.length === 0) rects.value = []
-  }, { deep: false })
-
   function classFor(rect: A11yHighlightRect): string {
     if (focusedRule.value) {
       return rect.ruleId === focusedRule.value ? 'focused' : 'dimmed'
diff --git a/src/shell/composables/useAgentConfigs.ts b/src/shell/composables/useAgentConfigs.ts
new file mode 100644
index 0000000..1f2507b
--- /dev/null
+++ b/src/shell/composables/useAgentConfigs.ts
@@ -0,0 +1,76 @@
+import { ref, type Ref } from 'vue'
+import type { ProviderId, EffortLevel } from '../../embedded/provider-config'
+import { on as wsOn } from '../services/wsClient'
+
+export interface AgentConfigEntry {
+  projectDirections: string
+  providerId?: ProviderId
+  model?: string
+  effort?: EffortLevel
+}
+
+export interface AgentConfigs {
+  version: number
+  agents: Record<string, AgentConfigEntry>
+}
+
+const BASE = '/__annotask/api'
+
+let singleton: ReturnType<typeof create> | null = null
+
+function create() {
+  const configs: Ref<Record<string, AgentConfigEntry>> = ref({})
+  const loading = ref(false)
+  const error: Ref<string | null> = ref(null)
+
+  async function refresh() {
+    loading.value = true
+    error.value = null
+    try {
+      const res = await fetch(`${BASE}/agent-configs`)
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const data: AgentConfigs = await res.json()
+      configs.value = data.agents ?? {}
+    } catch (e) {
+      error.value = (e as Error)?.message ?? 'Failed to load agent configs'
+    } finally {
+      loading.value = false
+    }
+  }
+
+  async function save(personaId: string, patch: Partial<AgentConfigEntry>): Promise<boolean> {
+    try {
+      const res = await fetch(`${BASE}/agent-configs/${encodeURIComponent(personaId)}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(patch),
+      })
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const data: AgentConfigs = await res.json()
+      configs.value = data.agents ?? {}
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  refresh()
+
+  // Re-fetch when init finishes (or any sub-step completes), since the
+  // agent-configs step writes/rewrites .annotask/agents.json on disk and
+  // the panel's cached snapshot would otherwise show empty / stale data.
+  wsOn('init:progress', (data: any) => {
+    const steps = Array.isArray(data?.steps) ? data.steps : []
+    const ac = steps.find((s: any) => s?.id === 'agent-configs')
+    if (ac && (ac.status === 'success' || ac.status === 'error')) {
+      void refresh()
+    }
+  })
+
+  return { configs, loading, error, save, refresh }
+}
+
+export function useAgentConfigs() {
+  if (!singleton) singleton = create()
+  return singleton
+}
diff --git a/src/shell/composables/useAgentMode.ts b/src/shell/composables/useAgentMode.ts
new file mode 100644
index 0000000..f752ee1
--- /dev/null
+++ b/src/shell/composables/useAgentMode.ts
@@ -0,0 +1,96 @@
+/**
+ * Agent-mode auto-run queue.
+ *
+ * When the user creates a task with `agentMode` enabled and a ready
+ * provider, `useTaskWorkflows` enqueues the task id here. App.vue watches
+ * the queue and opens the task detail modal at the Conversation tab. The
+ * Conversation tab itself drains the queue on mount and fires the first
+ * `send()` with the task description, so the user sees the agent start
+ * working as soon as the modal opens.
+ *
+ * Singleton — the queue is process-global within the shell. Drained once
+ * per task id (consume returns true once and then forgets it).
+ *
+ * Why a queue rather than a single ref: two creation flows could race
+ * (e.g. a stylesheet change that mints multiple tasks). One id at a time
+ * is the dominant case, but the Map handles overlap without cross-talk.
+ *
+ * Run sources:
+ *   - `auto`   — task auto-enqueued on creation (taskWorkflows). The
+ *     headless driver AND the Conversation tab can claim these.
+ *   - `manual` — user clicked "Run with agent" in the task detail. Only
+ *     the Conversation tab should claim these so the user sees the live
+ *     work-stream they asked to watch.
+ */
+
+import { ref } from 'vue'
+
+export type RunSource = 'manual' | 'auto'
+
+const pendingAutoRun = ref<Map<string, RunSource>>(new Map())
+
+/**
+ * Task ids that currently have an in-flight agent turn. Different from
+ * `task.status === 'in_progress'` — the agent doesn't always update the
+ * task's status field, especially in chat-only flows. TaskCard reads this
+ * set to render the live-activity dot independently of status.
+ */
+const activeRuns = ref<Set<string>>(new Set())
+
+/** Mark a task as having an active agent run. Idempotent. */
+export function markRunStarted(taskId: string): void {
+  if (!taskId) return
+  if (activeRuns.value.has(taskId)) return
+  const next = new Set(activeRuns.value)
+  next.add(taskId)
+  activeRuns.value = next
+}
+
+/** Clear the active-run flag. Safe to call multiple times. */
+export function markRunFinished(taskId: string): void {
+  if (!activeRuns.value.has(taskId)) return
+  const next = new Set(activeRuns.value)
+  next.delete(taskId)
+  activeRuns.value = next
+}
+
+/** Schedule a task for auto-run. Idempotent. */
+export function requestAutoRun(taskId: string, source: RunSource = 'auto'): void {
+  if (!taskId) return
+  if (pendingAutoRun.value.has(taskId)) return
+  const next = new Map(pendingAutoRun.value)
+  next.set(taskId, source)
+  pendingAutoRun.value = next
+}
+
+/**
+ * Atomically check-and-clear. Returns true if the task was queued (and the
+ * caller now owns running it). Subsequent calls for the same id return false.
+ *
+ * When `allowedSources` is provided, only items with a matching source are
+ * consumed. Non-matching items are left in the queue for a different consumer.
+ */
+export function consumeAutoRun(taskId: string, allowedSources?: RunSource[]): boolean {
+  const source = pendingAutoRun.value.get(taskId)
+  if (source === undefined) return false
+  if (allowedSources && !allowedSources.includes(source)) return false
+  const next = new Map(pendingAutoRun.value)
+  next.delete(taskId)
+  pendingAutoRun.value = next
+  return true
+}
+
+/**
+ * Reactive accessors. The auto-run queue feeds the silent driver; the
+ * activeRuns set feeds the live-activity dot on task cards.
+ */
+export function useAgentMode() {
+  return {
+    pendingAutoRun,
+    requestAutoRun,
+    consumeAutoRun,
+    activeRuns,
+    markRunStarted,
+    markRunFinished,
+  }
+}
diff --git a/src/shell/composables/useAgentModels.ts b/src/shell/composables/useAgentModels.ts
new file mode 100644
index 0000000..933a1b9
--- /dev/null
+++ b/src/shell/composables/useAgentModels.ts
@@ -0,0 +1,227 @@
+/**
+ * Singleton model-catalog cache for every place in the shell that picks a
+ * provider model — Settings → Providers, the InitWizard agent step, and the
+ * per-persona AgentDirectionsPanel.
+ *
+ * Why a single composable:
+ * - Three components were each issuing their own `/__annotask/api/agent/models`
+ *   fetch on mount. Switching tabs re-ran the probe and the opencode /
+ *   Copilot calls (5s budget each) sometimes raced or stalled, leaving
+ *   dropdowns stuck on "Auto" only.
+ * - With one cache, the first opener pays the cost and every subsequent
+ *   consumer gets the result reactively. `preload()` lets App.vue warm the
+ *   cache at shell startup so the user never sees a half-loaded list.
+ *
+ * Caching strategy:
+ * - In-memory reactive `Record<ProviderId, AgentModelCatalog | null>`.
+ * - Persisted to localStorage with TTL (matches the 5-min server cache).
+ * - In-flight promises are deduped by provider so concurrent ensure()
+ *   calls from different components issue a single network call.
+ *
+ * Failure posture: no curated fallback list. If the probe fails or returns
+ * nothing, the catalog comes back with only "Auto (CLI default)" plus an
+ * `error` string from the server. Consumers must surface that error and
+ * block selection of a specific model id — guessing causes runtime "model
+ * not found" errors from the underlying CLI.
+ */
+
+import { computed, reactive, readonly } from 'vue'
+import { PROVIDER_IDS, type ProviderId } from '../../embedded/provider-config'
+
+export interface ModelOption {
+  id: string
+  label: string
+  /** Mirror of the server-side ModelOption.source union — see
+   *  src/server/agent-models.ts for what each value means. */
+  source: 'auto' | 'discovered' | 'static'
+}
+
+export interface AgentModelCatalog {
+  cli: ProviderId
+  models: ModelOption[]
+  /** true when the catalog includes live-discovered entries (vs Auto-only). */
+  discovered: boolean
+  /** ms since epoch the entry was fetched. */
+  cachedAt: number
+  /** Non-empty when the live probe couldn't return a real model list. */
+  error?: string
+}
+
+const AUTO_OPTION: ModelOption = { id: '', label: 'Auto (CLI default)', source: 'auto' }
+
+const STORAGE_KEY = 'annotask:agent:modelCatalog'
+const TTL_MS = 5 * 60_000
+const PROVIDER_IDS_SET = new Set<ProviderId>(PROVIDER_IDS)
+
+interface CatalogStore {
+  catalogs: Partial<Record<ProviderId, AgentModelCatalog>>
+  loading: Partial<Record<ProviderId, boolean>>
+  errors: Partial<Record<ProviderId, string>>
+}
+
+const state = reactive<CatalogStore>({
+  catalogs: {},
+  loading: {},
+  errors: {},
+})
+
+// In-flight fetches deduped by provider id. Lives outside reactive state so
+// concurrent callers reuse the same Promise without triggering renders.
+const inflight = new Map<ProviderId, Promise<AgentModelCatalog | null>>()
+
+let hydrated = false
+
+function hydrateFromStorage() {
+  if (hydrated || typeof window === 'undefined') return
+  hydrated = true
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY)
+    if (!raw) return
+    const parsed = JSON.parse(raw) as Record<string, AgentModelCatalog>
+    for (const [id, entry] of Object.entries(parsed)) {
+      if (!PROVIDER_IDS_SET.has(id as ProviderId)) continue
+      if (!entry || !Array.isArray(entry.models)) continue
+      state.catalogs[id as ProviderId] = entry
+    }
+  } catch {
+    // Storage may be unavailable (private mode, quota) — fall through to
+    // network fetches. Never throw out of init.
+  }
+}
+
+function persistToStorage() {
+  if (typeof window === 'undefined') return
+  try {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(state.catalogs))
+  } catch {
+    // Quota exceeded or storage disabled. Cache stays in memory; nothing else
+    // to do.
+  }
+}
+
+/**
+ * Catalog shown before any fetch has resolved. Holds only "Auto (CLI
+ * default)" — there is intentionally no curated model list. Consumers must
+ * treat `error` as a blocking condition; the empty list isn't a "loading
+ * skeleton", it's the truth until the probe says otherwise.
+ */
+function emptyCatalog(cli: ProviderId, error?: string): AgentModelCatalog {
+  return {
+    cli,
+    models: [AUTO_OPTION],
+    discovered: false,
+    cachedAt: 0, // 0 marks "never fetched" — always considered stale.
+    error,
+  }
+}
+
+function isFresh(entry: AgentModelCatalog | undefined, now: number): boolean {
+  if (!entry) return false
+  return now - entry.cachedAt < TTL_MS
+}
+
+async function fetchCatalog(cli: ProviderId, opts: { refresh?: boolean } = {}): Promise<AgentModelCatalog | null> {
+  state.loading[cli] = true
+  state.errors[cli] = undefined
+  try {
+    const url = `/__annotask/api/agent/models?cli=${encodeURIComponent(cli)}${opts.refresh ? '&refresh=1' : ''}`
+    const res = await fetch(url)
+    if (!res.ok) {
+      state.errors[cli] = `HTTP ${res.status}`
+      return null
+    }
+    const data = (await res.json()) as Partial<AgentModelCatalog>
+    if (!data || !Array.isArray(data.models)) {
+      state.errors[cli] = 'malformed response from /api/agent/models'
+      return null
+    }
+    // An "empty" list (just Auto, plus an error from the server) is a valid
+    // response now — it tells the UI to block model selection rather than
+    // serve a curated guess. Persist it like any other catalog.
+    const fresh: AgentModelCatalog = {
+      cli,
+      models: data.models,
+      discovered: !!data.discovered,
+      cachedAt: Date.now(),
+      error: typeof data.error === 'string' && data.error.length > 0 ? data.error : undefined,
+    }
+    state.catalogs[cli] = fresh
+    if (fresh.error) state.errors[cli] = fresh.error
+    persistToStorage()
+    return fresh
+  } catch (err) {
+    state.errors[cli] = (err as Error).message
+    return null
+  } finally {
+    state.loading[cli] = false
+  }
+}
+
+async function ensure(cli: ProviderId, opts: { refresh?: boolean } = {}): Promise<AgentModelCatalog> {
+  hydrateFromStorage()
+  const existing = state.catalogs[cli]
+  const now = Date.now()
+
+  // Fresh cache → return immediately.
+  if (!opts.refresh && isFresh(existing, now)) return existing as AgentModelCatalog
+
+  // Deduplicate concurrent fetches for the same provider.
+  let pending = inflight.get(cli)
+  if (!pending) {
+    pending = fetchCatalog(cli, opts).finally(() => inflight.delete(cli))
+    inflight.set(cli, pending)
+  }
+  const fetched = await pending
+
+  if (fetched) return fetched
+  if (existing) return existing
+  return emptyCatalog(cli, state.errors[cli])
+}
+
+function getCatalog(cli: ProviderId): AgentModelCatalog {
+  hydrateFromStorage()
+  return state.catalogs[cli] ?? emptyCatalog(cli, state.errors[cli])
+}
+
+function isLoading(cli: ProviderId): boolean {
+  return !!state.loading[cli]
+}
+
+function lastError(cli: ProviderId): string | undefined {
+  return state.errors[cli]
+}
+
+async function preload(ids: ProviderId[]): Promise<void> {
+  // Fire all probes in parallel; ensure() handles dedup + cache.
+  await Promise.all(ids.map((id) => ensure(id).catch(() => null)))
+}
+
+async function refresh(cli: ProviderId): Promise<AgentModelCatalog> {
+  return ensure(cli, { refresh: true })
+}
+
+export function useAgentModels() {
+  hydrateFromStorage()
+  return {
+    state: readonly(state),
+    catalogFor: (cli: ProviderId) => computed(() => getCatalog(cli)),
+    modelsFor: (cli: ProviderId) => computed(() => getCatalog(cli).models),
+    isLoading: (cli: ProviderId) => computed(() => isLoading(cli)),
+    lastError: (cli: ProviderId) => computed(() => lastError(cli)),
+    ensure,
+    refresh,
+    preload,
+  }
+}
+
+// Test hook — never used by production code.
+export function __resetAgentModelsCache() {
+  state.catalogs = {}
+  state.loading = {}
+  state.errors = {}
+  inflight.clear()
+  hydrated = false
+  if (typeof window !== 'undefined') {
+    try { window.localStorage.removeItem(STORAGE_KEY) } catch { /* ignore */ }
+  }
+}
diff --git a/src/shell/composables/useAnnotationRects.ts b/src/shell/composables/useAnnotationRects.ts
index 3bdc66d..53e7eb5 100644
--- a/src/shell/composables/useAnnotationRects.ts
+++ b/src/shell/composables/useAnnotationRects.ts
@@ -38,9 +38,6 @@ export function useAnnotationRects(deps: {
       for (const h of annotations.highlights.value) {
         if (h.eid) addEid(h.eid, { type: 'highlight', id: h.id, field: 'rect' })
       }
-      for (const s of annotations.drawnSections.value) {
-        if (s.nearEid) addEid(s.nearEid, { type: 'section', id: s.id, field: 'near' })
-      }
       const currentRoute = annotations.activeRoute.value
       for (const t of taskSystem.tasks.value) {
         const v = t.visual as any
@@ -101,30 +98,56 @@ export function useAnnotationRects(deps: {
               // per-line rects (which describe text runs, not the element box) by
               // the same delta. Don't overwrite hl.rect with the element rect.
               const prev = (hl as any)._anchorRect as typeof rect | undefined
-              if (prev) {
-                const dx = rect.x - prev.x
-                const dy = rect.y - prev.y
-                if (Math.abs(dx) > 0.5 || Math.abs(dy) > 0.5) {
-                  hl.rects = hl.rects.map(r => ({ x: r.x + dx, y: r.y + dy, width: r.width, height: r.height }))
-                  if (hl.rect) hl.rect = { x: hl.rect.x + dx, y: hl.rect.y + dy, width: hl.rect.width, height: hl.rect.height }
+              if (!prev) {
+                ;(hl as any)._anchorRect = rect
+              } else {
+                const sizeChanged = Math.abs(rect.width - prev.width) > 0.5 || Math.abs(rect.height - prev.height) > 0.5
+                if (sizeChanged) {
+                  // Element resized — text likely reflowed, so line breaks may
+                  // have shifted. Re-measure the actual Range from the iframe;
+                  // delta translation can't track reflow. Fire-and-forget so the
+                  // rAF tick stays cheap.
+                  const targetEid = eids[i]
+                  const hlId = hl.id
+                  const fallbackPrev = prev
+                  iframe.getTextRangeRects(targetEid, hl.selectedText).then(fresh => {
+                    const h2 = annotations.highlights.value.find(x => x.id === hlId)
+                    if (!h2 || h2.eid !== targetEid) return
+                    if (fresh && fresh.length) {
+                      h2.rects = fresh.map(r => ({ x: r.x, y: r.y, width: r.width, height: r.height }))
+                      let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity
+                      for (const r of fresh) {
+                        if (r.x < minX) minX = r.x
+                        if (r.y < minY) minY = r.y
+                        if (r.x + r.width > maxX) maxX = r.x + r.width
+                        if (r.y + r.height > maxY) maxY = r.y + r.height
+                      }
+                      h2.rect = { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
+                    } else {
+                      // Re-measure failed (text moved out of the anchor or
+                      // mismatched after reflow) — fall back to translation so
+                      // the overlay at least follows the element.
+                      const dx = rect.x - fallbackPrev.x, dy = rect.y - fallbackPrev.y
+                      if (Math.abs(dx) > 0.5 || Math.abs(dy) > 0.5) {
+                        h2.rects = h2.rects!.map(r => ({ x: r.x + dx, y: r.y + dy, width: r.width, height: r.height }))
+                        if (h2.rect) h2.rect = { x: h2.rect.x + dx, y: h2.rect.y + dy, width: h2.rect.width, height: h2.rect.height }
+                      }
+                    }
+                  })
                   ;(hl as any)._anchorRect = rect
+                } else {
+                  const dx = rect.x - prev.x
+                  const dy = rect.y - prev.y
+                  if (Math.abs(dx) > 0.5 || Math.abs(dy) > 0.5) {
+                    hl.rects = hl.rects.map(r => ({ x: r.x + dx, y: r.y + dy, width: r.width, height: r.height }))
+                    if (hl.rect) hl.rect = { x: hl.rect.x + dx, y: hl.rect.y + dy, width: hl.rect.width, height: hl.rect.height }
+                    ;(hl as any)._anchorRect = rect
+                  }
                 }
-              } else {
-                ;(hl as any)._anchorRect = rect
               }
             } else {
               hl.rect = rect
             }
-          } else if (entry.type === 'section') {
-            const section = annotations.drawnSections.value.find(s => s.id === entry.id)
-            if (!section) continue
-            const prevRect = (section as any)._nearRect as typeof rect | undefined
-            if (prevRect) {
-              const dx = rect.x - prevRect.x, dy = rect.y - prevRect.y
-              if (Math.abs(dx) > 0.5 || Math.abs(dy) > 0.5) {
-                section.x += dx; section.y += dy; (section as any)._nearRect = rect
-              }
-            } else { (section as any)._nearRect = rect }
           } else if (entry.type === 'task') {
             newTaskRects.push({ taskId: entry.id, rect })
           }
@@ -142,7 +165,6 @@ export function useAnnotationRects(deps: {
     function tick() {
       const hasWork = annotations.arrows.value.some(a => a.fromEid || a.toEid)
         || annotations.highlights.value.some(h => h.eid)
-        || annotations.drawnSections.value.some(s => s.nearEid)
         || taskSystem.tasks.value.some(t => { const v = t.visual as any; return v?.kind === 'select' && (v.eids?.length || v.eid) && t.status !== 'accepted' })
       if (!hasWork) { loopRunning = false; return }
       // Skip work while the tab is hidden — the browser still fires rAF at reduced rate,
@@ -158,7 +180,7 @@ export function useAnnotationRects(deps: {
   }
 
   // Start annotation loop when annotations or tasks exist
-  watch([annotations.arrows, annotations.highlights, annotations.drawnSections, taskSystem.tasks], () => {
+  watch([annotations.arrows, annotations.highlights, taskSystem.tasks], () => {
     startAnnotationLoop()
   }, { deep: true })
 
diff --git a/src/shell/composables/useAnnotations.ts b/src/shell/composables/useAnnotations.ts
index 5f82e9e..98ff47f 100644
--- a/src/shell/composables/useAnnotations.ts
+++ b/src/shell/composables/useAnnotations.ts
@@ -53,23 +53,6 @@ export interface Arrow {
   timestamp: number
 }
 
-export interface DrawnSection {
-  id: string
-  number: number
-  x: number
-  y: number
-  width: number
-  height: number
-  prompt: string
-  nearEid?: string
-  nearFile?: string
-  nearLine?: number
-  nearComponent?: string
-  placement?: 'above' | 'below' | 'left' | 'right'
-  route: string
-  timestamp: number
-}
-
 export interface TextHighlight {
   id: string
   number: number
@@ -90,7 +73,6 @@ export interface TextHighlight {
 const pins = ref<Pin[]>([])
 const stickyNotes = ref<StickyNote[]>([])
 const arrows = ref<Arrow[]>([])
-const drawnSections = ref<DrawnSection[]>([])
 const highlights = ref<TextHighlight[]>([])
 const activeRoute = ref('/')
 
@@ -103,7 +85,6 @@ function normalizeRoute(path: string): string {
 const selectedPinId = ref<string | null>(null)
 const selectedStickyId = ref<string | null>(null)
 const selectedArrowId = ref<string | null>(null)
-const selectedSectionId = ref<string | null>(null)
 let counter = 0
 
 export function useAnnotations() {
@@ -112,7 +93,6 @@ export function useAnnotations() {
   // Route-filtered views
   const routePins = computed(() => pins.value.filter(p => normalizeRoute(p.route) === activeRoute.value))
   const routeArrows = computed(() => arrows.value.filter(a => normalizeRoute(a.route) === activeRoute.value))
-  const routeSections = computed(() => drawnSections.value.filter(s => normalizeRoute(s.route) === activeRoute.value))
   const routeHighlights = computed(() => highlights.value.filter(h => normalizeRoute(h.route) === activeRoute.value))
 
   // ── Pins ──
@@ -209,29 +189,6 @@ export function useAnnotations() {
     if (arrow) Object.assign(arrow, updates)
   }
 
-  // ── Drawn Sections ──
-  function addDrawnSection(x: number, y: number, width: number, height: number): DrawnSection {
-    counter++
-    const section: DrawnSection = {
-      id: `section-${counter}`, number: counter,
-      x, y, width, height,
-      prompt: '', route: activeRoute.value, timestamp: Date.now(),
-    }
-    drawnSections.value.push(section)
-    selectedSectionId.value = section.id
-    return section
-  }
-
-  function removeDrawnSection(id: string) {
-    drawnSections.value = drawnSections.value.filter(s => s.id !== id)
-    if (selectedSectionId.value === id) selectedSectionId.value = null
-  }
-
-  function updateDrawnSection(id: string, updates: Partial<DrawnSection>) {
-    const section = drawnSections.value.find(s => s.id === id)
-    if (section) Object.assign(section, updates)
-  }
-
   // ── Text Highlights ──
   const selectedHighlightId = ref<string | null>(null)
 
@@ -272,26 +229,23 @@ export function useAnnotations() {
     pins.value = []
     stickyNotes.value = []
     arrows.value = []
-    drawnSections.value = []
     highlights.value = []
     selectedPinId.value = null
     selectedStickyId.value = null
     selectedArrowId.value = null
-    selectedSectionId.value = null
     selectedHighlightId.value = null
   }
 
   return {
-    pins, stickyNotes, arrows, drawnSections, highlights,
-    routePins, routeArrows, routeSections, routeHighlights,
+    pins, stickyNotes, arrows, highlights,
+    routePins, routeArrows, routeHighlights,
     activeRoute, setRoute,
-    selectedPinId, selectedStickyId, selectedArrowId, selectedSectionId, selectedHighlightId,
+    selectedPinId, selectedStickyId, selectedArrowId, selectedHighlightId,
     selectedPin,
     reclaimLastCounter,
     addPin, removePin, updatePinNote, setPinAction, getPinsForElement,
     addStickyNote, removeStickyNote, updateStickyNote,
     addArrow, removeArrow, updateArrow,
-    addDrawnSection, removeDrawnSection, updateDrawnSection,
     addHighlight, removeHighlight, updateHighlight,
     clearAll,
   }
diff --git a/src/shell/composables/useAutoRunDriver.ts b/src/shell/composables/useAutoRunDriver.ts
new file mode 100644
index 0000000..a00b65c
--- /dev/null
+++ b/src/shell/composables/useAutoRunDriver.ts
@@ -0,0 +1,168 @@
+/**
+ * Silent auto-run driver.
+ *
+ * Mounted once at the app root. Watches `useAgentMode().pendingAutoRun` and,
+ * whenever a task id appears, runs the embedded agent against it without
+ * opening any modal. The driver owns its own headless `useTaskThread` +
+ * `useEmbeddedAgent` pair per task — the user's open Conversation tab (if
+ * any) subscribes to the same persisted thread via SSE, so they see the
+ * work-stream live without being interrupted.
+ *
+ * Concurrency cap: 1. Local CLIs (claude/codex/opencode) consume real CPU
+ * and may grab file locks; serializing keeps cross-task chaos out of v1.
+ * Queued ids run FIFO.
+ *
+ * Drains policy: the driver claims an id by calling `consumeAutoRun(id)` —
+ * if a Conversation tab is already mounted for that task, it raced us and
+ * we skip. Otherwise we run headlessly. The tab can attach later mid-run
+ * and observe via the live SSE stream.
+ */
+
+import { watch } from 'vue'
+import { useAgentMode, consumeAutoRun } from './useAgentMode'
+import { useTaskThread } from './useTaskThread'
+import { useEmbeddedAgent } from './useEmbeddedAgent'
+import { useTasks } from './useTasks'
+import { useProviderSettings } from './useProviderSettings'
+
+let started = false
+let runningId: string | null = null
+// Cancel hooks for in-flight headless runs, keyed by task id. A Conversation
+// tab observing a headless run can't reach that run's local `aborter` (the
+// driver owns a separate agent instance), so it routes a cancel through here.
+const cancelHooks = new Map<string, () => void>()
+
+export function startAutoRunDriver(): void {
+  if (started) return
+  started = true
+
+  const agentMode = useAgentMode()
+  const taskSystem = useTasks()
+
+  watch(
+    agentMode.pendingAutoRun,
+    () => { void drain(taskSystem) },
+    { immediate: true },
+  )
+}
+
+async function drain(taskSystem: ReturnType<typeof useTasks>): Promise<void> {
+  if (runningId) return // already busy; we'll re-enter when this turn finishes
+
+  // Skip the entire drain when the user is in skill/MCP mode. Tasks may
+  // still enqueue (older code paths, tests), but the driver should not
+  // spawn anything embedded. The queue stays put so flipping the toggle
+  // back on doesn't lose work.
+  const providerSettings = useProviderSettings()
+  if (providerSettings.settings.value.embeddedAgentEnabled !== true) {
+    // eslint-disable-next-line no-console
+    console.warn('[annotask:autorun] drain skipped: embeddedAgentEnabled is not true')
+    return
+  }
+
+  // Ids that refused consumption this drain pass — manual runs owned by the
+  // Conversation tab, or ids another consumer raced us for. They stay in the
+  // queue (the tab consumes manual items on mount), but we must iterate past
+  // them: re-reading the head after a failed consume was a tight synchronous
+  // loop with no await, freezing the tab whenever "Run with agent" enqueued
+  // a manual item before ConversationTab could mount and claim it.
+  const skipped = new Set<string>()
+
+  while (true) {
+    const queue = useAgentMode().pendingAutoRun.value
+
+    // FIFO among entries we haven't already skipped this pass.
+    let id: string | null = null
+    for (const x of queue.keys()) {
+      if (!skipped.has(x)) { id = x; break }
+    }
+    // Nothing consumable left — either the queue is empty or every remaining
+    // item belongs to a different consumer. Exit; manual items are the
+    // Conversation tab's to drain.
+    if (!id) return
+
+    if (!consumeAutoRun(id, ['auto'])) {
+      // Either another consumer already claimed this id, or it's a manual
+      // run destined for the Conversation tab. Skip it for the rest of this
+      // pass and move on to the next queued id.
+      // eslint-disable-next-line no-console
+      console.warn(`[annotask:autorun] ${id} consumed by another consumer (likely manual run)`)
+      skipped.add(id)
+      continue
+    }
+
+    const task = taskSystem.tasks.value.find((t) => t.id === id)
+    if (!task) {
+      // Task vanished before we could run it (deleted?). Drop and continue.
+      // eslint-disable-next-line no-console
+      console.warn(`[annotask:autorun] ${id} not in tasks.value — dropping`)
+      continue
+    }
+
+    const description = (task.description ?? '').trim()
+    if (!description) {
+      // eslint-disable-next-line no-console
+      console.warn(`[annotask:autorun] ${id} has empty description — dropping`)
+      continue
+    }
+
+    runningId = id
+    // eslint-disable-next-line no-console
+    console.log(`[annotask:autorun] starting ${id}`)
+    try {
+      await runHeadless(id, description)
+      // eslint-disable-next-line no-console
+      console.log(`[annotask:autorun] finished ${id}`)
+    } catch (err) {
+      // Without this catch, errors bubble through the `void drain(...)`
+      // call in the watcher and vanish into unhandled-promise-rejection
+      // limbo — leaving the user with a task stuck "running" and no UI
+      // indication that anything went wrong.
+      // eslint-disable-next-line no-console
+      console.error(`[annotask:autorun] ${id} failed:`, err)
+    } finally {
+      runningId = null
+    }
+  }
+}
+
+async function runHeadless(taskId: string, prompt: string): Promise<void> {
+  // Fresh thread + agent instance per run. The composables don't use
+  // lifecycle hooks so they're safe to construct outside a component.
+  const thread = useTaskThread()
+  try {
+    await thread.open(taskId)
+    const agent = useEmbeddedAgent(thread)
+    // Register a cancel hook so an observer tab can abort this headless run.
+    cancelHooks.set(taskId, () => agent.abort())
+    // Seed run — agent treats this prompt as its objective. On clean
+    // completion the composable flips the task to `review`.
+    await agent.send(prompt, { isSeed: true })
+  } finally {
+    cancelHooks.delete(taskId)
+    thread.close()
+  }
+}
+
+/**
+ * Cancel an in-flight headless auto-run for a task. Returns true if a run was
+ * found and asked to abort. Safe to call when nothing is running (no-op).
+ */
+export function requestAutoRunCancel(taskId: string): boolean {
+  const hook = cancelHooks.get(taskId)
+  if (!hook) return false
+  hook()
+  return true
+}
+
+/** Test seam — resets the singleton so unit tests can re-arm the driver. */
+export function resetAutoRunDriverForTests(): void {
+  started = false
+  runningId = null
+  cancelHooks.clear()
+}
+
+/** Test seam — drives one drain pass directly, bypassing the watcher. */
+export function drainForTests(taskSystem: ReturnType<typeof useTasks>): Promise<void> {
+  return drain(taskSystem)
+}
diff --git a/src/shell/composables/useBridgeEventHandlers.ts b/src/shell/composables/useBridgeEventHandlers.ts
index dce1bfc..098fb30 100644
--- a/src/shell/composables/useBridgeEventHandlers.ts
+++ b/src/shell/composables/useBridgeEventHandlers.ts
@@ -161,10 +161,16 @@ export function useBridgeEventHandlers(deps: BridgeEventHandlerDeps) {
         }
       }
     } else {
-      primarySelection.value = { file, line, component, mfe: mfe || '', tagName, classes, eid, text, ...(source_tag ? { sourceTag: source_tag } : {}), ...(parent_component ? { parentComponent: parent_component } : {}) }
+      primarySelection.value = { file, line, component, mfe: mfe || '', tagName, classes, eid, text, ...(source_tag ? { sourceTag: source_tag } : {}), ...(parent_component ? { parentComponent: parent_component } : {}), ...(data.instance_id ? { instanceId: data.instance_id } : {}) }
       selectedEids.value = [eid]
-      const group = await iframe.findTemplateGroup(file, line, tagName)
-      templateGroupEids.value = group.eids
+      if (data.instance_id) {
+        // A placement has no source anchor — there is no template group to
+        // resolve and group fan-out would target unrelated elements.
+        templateGroupEids.value = []
+      } else {
+        const group = await iframe.findTemplateGroup(file, line, tagName)
+        templateGroupEids.value = group.eids
+      }
       // Default: a single click selects exactly one element. Shift+click adds
       // more. The template-group is still tracked so the style editor's
       // "apply to all instances" toggle can opt into fan-out when useful.
diff --git a/src/shell/composables/useCanvasDrawing.ts b/src/shell/composables/useCanvasDrawing.ts
index d8baa89..d2c7055 100644
--- a/src/shell/composables/useCanvasDrawing.ts
+++ b/src/shell/composables/useCanvasDrawing.ts
@@ -27,7 +27,6 @@ export function useCanvasDrawing(
     fromTag?: string; fromComponent?: string
     toTag?: string; toComponent?: string
   } | null>(null)
-  const drawingRect = ref<{ x: number; y: number; width: number; height: number } | null>(null)
   const hoverElement = ref<HoverElement>(null)
   let drawStart: { x: number; y: number } | null = null
 
@@ -52,9 +51,6 @@ export function useCanvasDrawing(
           fromRect: fromCtx.rect, fromTag: fromCtx.tag, fromComponent: fromCtx.component,
         }
       }
-    } else if (mode === 'draw') {
-      drawStart = { x: e.clientX, y: e.clientY }
-      drawingRect.value = { x: e.clientX, y: e.clientY, width: 0, height: 0 }
     }
   }
 
@@ -91,12 +87,6 @@ export function useCanvasDrawing(
           }
         }
       }, 50)
-    } else if (mode === 'draw' && drawingRect.value) {
-      const x = Math.min(drawStart.x, e.clientX)
-      const y = Math.min(drawStart.y, e.clientY)
-      const w = Math.abs(e.clientX - drawStart.x)
-      const h = Math.abs(e.clientY - drawStart.y)
-      drawingRect.value = { x, y, width: w, height: h }
     }
   }
 
@@ -127,31 +117,12 @@ export function useCanvasDrawing(
         onArrowCreated?.(arrow.id, fromCtx, toCtx)
       }
       drawingArrow.value = null
-    } else if (mode === 'draw' && drawingRect.value) {
-      const r = drawingRect.value
-      if (r.width > 30 && r.height > 30) {
-        onBeforeAnnotation?.()
-        const nearCtx = await resolveElementAt(r.x + r.width / 2, r.y)
-        const section = annotations.addDrawnSection(r.x, r.y, r.width, r.height)
-        if (nearCtx) {
-          const placement = r.y > (drawStart?.y || 0) ? 'below' : 'above'
-          annotations.updateDrawnSection(section.id, {
-            nearEid: nearCtx.eid,
-            nearFile: nearCtx.file,
-            nearLine: parseInt(nearCtx.line) || 0,
-            nearComponent: nearCtx.component,
-            placement: placement as 'above' | 'below',
-          })
-        }
-      }
-      drawingRect.value = null
     }
     drawStart = null
   }
 
   return {
     drawingArrow,
-    drawingRect,
     hoverElement,
     onCanvasPointerDown,
     onCanvasPointerMove,
diff --git a/src/shell/composables/useCanvasHistory.ts b/src/shell/composables/useCanvasHistory.ts
new file mode 100644
index 0000000..95ed0de
--- /dev/null
+++ b/src/shell/composables/useCanvasHistory.ts
@@ -0,0 +1,123 @@
+import { ref, computed, type Ref } from 'vue'
+
+/**
+ * Snapshot-stack undo/redo for a single plain-data document.
+ *
+ * The wireframe canvas is small, JSON-serializable state (a few dozen blocks
+ * plus the current selection), so a structural-clone snapshot stack is the
+ * simplest thing that covers EVERY mutation uniformly — move, resize, delete,
+ * duplicate, note, binding, z-order, palette-drop, explode. No per-op inverse
+ * commands to keep in sync.
+ *
+ * Recording model:
+ *  - `record(key?)` — a discrete op snapshots the CURRENT (pre-mutation) state.
+ *    Call it BEFORE mutating. `key` + a short time window coalesces rapid
+ *    repeats (e.g. a burst of arrow-key nudges) into one entry.
+ *  - `begin()` / `end()` — bracket a multi-step gesture (a drag, or a loop over
+ *    several selected blocks). `begin()` captures one baseline; `record()` calls
+ *    in between no-op; `end()` commits a single entry (or drops it if nothing
+ *    actually changed). Gestures collapse what would otherwise be N entries.
+ */
+export interface CanvasHistory {
+  canUndo: Ref<boolean>
+  canRedo: Ref<boolean>
+  begin(): void
+  end(): void
+  record(coalesceKey?: string): void
+  undo(): boolean
+  redo(): boolean
+  clear(): void
+}
+
+const COALESCE_MS = 600
+
+export function useCanvasHistory<S>(
+  getState: () => S,
+  setState: (s: S) => void,
+  opts: { limit?: number; clone?: (s: S) => S } = {},
+): CanvasHistory {
+  const limit = opts.limit ?? 50
+  const clone = opts.clone ?? ((s: S) => JSON.parse(JSON.stringify(s)) as S)
+
+  const past = ref<S[]>([]) as Ref<S[]>
+  const future = ref<S[]>([]) as Ref<S[]>
+  const canUndo = computed(() => past.value.length > 0)
+  const canRedo = computed(() => future.value.length > 0)
+
+  let gestureActive = false
+  let gestureBaseline: S | null = null
+  let lastCoalesceKey: string | null = null
+  let lastRecordAt = 0
+  // Module-local clock so coalescing never depends on a passed-in timestamp.
+  const now = () => Date.now()
+
+  function pushPast(snapshot: S): void {
+    past.value.push(snapshot)
+    if (past.value.length > limit) past.value.shift()
+  }
+
+  function commit(snapshot: S): void {
+    pushPast(snapshot)
+    future.value = []
+  }
+
+  function begin(): void {
+    if (gestureActive) return
+    gestureActive = true
+    gestureBaseline = clone(getState())
+  }
+
+  function end(): void {
+    if (!gestureActive) return
+    gestureActive = false
+    const baseline = gestureBaseline
+    gestureBaseline = null
+    if (baseline == null) return
+    // Drop no-op gestures (a click that never moved, a drag back to origin).
+    if (JSON.stringify(baseline) === JSON.stringify(getState())) return
+    commit(baseline)
+    lastCoalesceKey = null
+  }
+
+  function record(coalesceKey?: string): void {
+    if (gestureActive) return
+    const ts = now()
+    if (coalesceKey && coalesceKey === lastCoalesceKey && ts - lastRecordAt < COALESCE_MS) {
+      // Same gesture continuing — fold into the entry already on the stack.
+      lastRecordAt = ts
+      return
+    }
+    commit(clone(getState()))
+    lastCoalesceKey = coalesceKey ?? null
+    lastRecordAt = ts
+  }
+
+  function undo(): boolean {
+    if (!past.value.length) return false
+    const prev = past.value.pop() as S
+    future.value.push(clone(getState()))
+    setState(clone(prev))
+    lastCoalesceKey = null
+    return true
+  }
+
+  function redo(): boolean {
+    if (!future.value.length) return false
+    const next = future.value.pop() as S
+    pushPast(clone(getState()))
+    setState(clone(next))
+    lastCoalesceKey = null
+    return true
+  }
+
+  function clear(): void {
+    past.value = []
+    future.value = []
+    gestureActive = false
+    gestureBaseline = null
+    lastCoalesceKey = null
+    lastRecordAt = 0
+  }
+
+  return { canUndo, canRedo, begin, end, record, undo, redo, clear }
+}
diff --git a/src/shell/composables/useCanvasSelection.ts b/src/shell/composables/useCanvasSelection.ts
new file mode 100644
index 0000000..45dfc94
--- /dev/null
+++ b/src/shell/composables/useCanvasSelection.ts
@@ -0,0 +1,66 @@
+import { ref, computed, type Ref, type ComputedRef } from 'vue'
+import type { WireframeBlock, WireframeCanvasState } from '../../shared/wireframe-types'
+
+/**
+ * Canvas block selection (multi via shift-click / marquee), lifted out of
+ * WireframeCanvas.vue so undo/redo can snapshot and restore it alongside the
+ * blocks: an undone move re-selects whatever was selected when it was made.
+ *
+ * `selectedIds` is ordered by selection recency — the LAST id is primary (it
+ * drives the per-block detail/edit affordances).
+ */
+export interface CanvasSelection {
+  selectedIds: Ref<string[]>
+  primaryId: ComputedRef<string | null>
+  primaryBlock: ComputedRef<WireframeBlock | null>
+  isSelected: (id: string) => boolean
+  select: (id: string | null, additive?: boolean) => void
+  setSelection: (ids: string[]) => void
+  clear: () => void
+  selectedBlocks: () => WireframeBlock[]
+}
+
+export function useCanvasSelection(canvas: Ref<WireframeCanvasState | null>): CanvasSelection {
+  const selectedIds = ref<string[]>([])
+
+  const primaryId = computed(() => selectedIds.value[selectedIds.value.length - 1] ?? null)
+  const primaryBlock = computed(() =>
+    canvas.value?.blocks.find((b) => b.id === primaryId.value && !b.deleted) ?? null)
+
+  const isSelected = (id: string) => selectedIds.value.includes(id)
+
+  function select(id: string | null, additive = false): void {
+    if (id === null) {
+      selectedIds.value = []
+      return
+    }
+    if (additive) {
+      selectedIds.value = isSelected(id)
+        ? selectedIds.value.filter((x) => x !== id)
+        : [...selectedIds.value, id]
+    } else if (!isSelected(id)) {
+      selectedIds.value = [id]
+    } else {
+      // Re-click inside a multi-selection keeps the group; promote to primary.
+      selectedIds.value = [...selectedIds.value.filter((x) => x !== id), id]
+    }
+  }
+
+  /** Replace the selection wholesale (marquee, undo/redo restore). Prunes ids
+   *  that no longer resolve to a live block so a restored selection can't point
+   *  at a deleted/removed block. */
+  function setSelection(ids: string[]): void {
+    const valid = new Set((canvas.value?.blocks ?? []).filter((b) => !b.deleted).map((b) => b.id))
+    selectedIds.value = ids.filter((id) => valid.has(id))
+  }
+
+  function clear(): void {
+    selectedIds.value = []
+  }
+
+  function selectedBlocks(): WireframeBlock[] {
+    return (canvas.value?.blocks ?? []).filter((b) => isSelected(b.id) && !b.deleted)
+  }
+
+  return { selectedIds, primaryId, primaryBlock, isSelected, select, setSelection, clear, selectedBlocks }
+}
diff --git a/src/shell/composables/useChangeHistory.ts b/src/shell/composables/useChangeHistory.ts
index 76ccb2f..f261644 100644
--- a/src/shell/composables/useChangeHistory.ts
+++ b/src/shell/composables/useChangeHistory.ts
@@ -23,6 +23,9 @@ export function useChangeHistory(deps: {
   shellView: Ref<ShellView>
   readLiveStyles: () => Promise<void>
   createRouteTask: (data: Record<string, unknown>) => Promise<unknown>
+  /** Wireframe deletePlacement (useWireframeCanvas) — executes undo of a
+   *  placement-create journal entry. Optional so older wiring keeps compiling. */
+  deletePlacement?: (instanceId: string) => Promise<void> | void
 }) {
   const { styleEditor, iframe, primarySelection, selectedEids, templateGroupEids, selectedElementRole, shellView, readLiveStyles, createRouteTask } = deps
   const { changes } = styleEditor
@@ -44,6 +47,9 @@ export function useChangeHistory(deps: {
       await iframe.undoClass(undoInfo.eid, undoInfo.classes || '')
     } else if (undoInfo.type === 'insert_remove' && undoInfo.eid) {
       await iframe.removePlaceholder(undoInfo.eid)
+    } else if (undoInfo.type === 'placement_delete' && undoInfo.instanceId) {
+      // Undo of a wireframe placement-create: remove the instance (doc + live node).
+      await deps.deletePlacement?.(undoInfo.instanceId)
     }
     await readLiveStyles()
   }
diff --git a/src/shell/composables/useComponentGenerator.ts b/src/shell/composables/useComponentGenerator.ts
new file mode 100644
index 0000000..f7fbac1
--- /dev/null
+++ b/src/shell/composables/useComponentGenerator.ts
@@ -0,0 +1,325 @@
+import { useComponentLibrary, type LibraryComponent } from './useProjectComponents'
+import { parseDefault } from '../utils/propWidgets'
+import type { PaletteDragItem } from './usePaletteDrag'
+import type { useWireframeMode, PaletteSnapshot, WireframeModeIframe } from './useWireframeMode'
+import type { WireframeBlock, WireframeDataBinding, WireframePaletteRef } from '../../shared/wireframe-types'
+
+/**
+ * Place-first component flow for the wireframe canvas.
+ *
+ * A palette drop mints the block IMMEDIATELY (imageless, honest 'placeholder'
+ * fidelity) and auto-selects it; the snapshot fills in the background. The user
+ * then configures the block IN PLACE via the inline popover — editing a prop or
+ * binding live-regenerates the snapshot (debounced) and updates the block. There
+ * is no separate generate/place step and no per-drop session: the config target
+ * is simply the selected block, and the snapshot lives on the block.
+ *
+ * Clone discipline: every payload that crosses postMessage (previewComponent) or
+ * lands in the persisted block (placeComponentBlock / updatePaletteBlock) is
+ * JSON-round-tripped at the boundary — reactive proxies throw DataCloneError in
+ * postMessage and must never reach wireframe.json.
+ *
+ * Undo: the drop records one entry; the first fill folds into it
+ * (recordHistory:false). A prop/binding edit records once (coalesce-keyed) and
+ * its regen folds in too, so a config burst is a single undo.
+ *
+ * Supersession: a per-block monotonic token is captured before the
+ * previewComponent await and re-checked after it — a stale in-flight render is
+ * dropped so a newer edit always wins.
+ */
+
+/** Debounce before a live config edit regenerates the snapshot. Kept strictly
+ *  below useCanvasHistory's COALESCE_MS (600) so an edit burst folds into one
+ *  undo entry. */
+const REGEN_DEBOUNCE_MS = 375
+/** Offscreen preview mount width (matches the legacy generate flow). */
+const PREVIEW_WIDTH = 320
+/** How many loop instances to sketch for a list binding by default. */
+const DEFAULT_REPEAT = 3
+
+export interface ComponentGeneratorDeps {
+  iframe: Pick<WireframeModeIframe, 'previewComponent'>
+  wireframe: Pick<
+    ReturnType<typeof useWireframeMode>,
+    'placeComponentBlock' | 'updatePaletteBlock' | 'findBlock' | 'building' | 'setGenerating'
+  >
+  /** The current iframe surface's MFE id, for stamping placed blocks. Null in
+   *  single-MFE / non-workspace projects (no stamp then). */
+  surfaceMfe?: () => string | null
+}
+
+function plain<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T
+}
+
+function definedEntries(obj: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined && v !== null && v !== '') out[k] = v
+  }
+  return out
+}
+
+export function useComponentGenerator(deps: ComponentGeneratorDeps) {
+  const cl = useComponentLibrary()
+  // Per-block monotonic generation token — only the latest regen of a block may
+  // write its snapshot; a superseded in-flight previewComponent is dropped.
+  const tokens = new Map<string, number>()
+  // Per-block debounce timers for live config edits.
+  const timers = new Map<string, ReturnType<typeof setTimeout>>()
+
+  /** Ensure the component catalog is loaded so the popover can show typed prop
+   *  widgets and previewProps can seed from meta defaults. Lazy + idempotent. */
+  function ensureCatalog(): void {
+    if (cl.libraries.value.length === 0) void cl.load()
+  }
+
+  /** Catalog metadata for a component — library-scoped first, any-library
+   *  fallback. Reads `cl.libraries` reactively so a computed wrapper re-resolves
+   *  when the catalog lands after a cold start. */
+  function resolveMeta(componentName: string | undefined, library?: string): LibraryComponent | null {
+    if (!componentName) return null
+    const libs = cl.libraries.value
+    const scoped = library ? libs.find((l) => l.name === library) : undefined
+    const inScope = scoped?.components.find((c) => c.name === componentName)
+    if (inScope) return inScope
+    for (const lib of libs) {
+      const hit = lib.components.find((c) => c.name === componentName)
+      if (hit) return hit
+    }
+    return null
+  }
+
+  /** Catalog meta for a placed block — drives the popover's typed widgets. */
+  function metaForBlock(block: WireframeBlock): LibraryComponent | null {
+    return resolveMeta(block.component?.componentName, block.component?.library)
+  }
+
+  function seedFromMeta(meta: LibraryComponent | null): Record<string, unknown> {
+    const out: Record<string, unknown> = {}
+    for (const p of meta?.props ?? []) {
+      const parsed = parseDefault(p.default, p.type)
+      if (parsed !== undefined) out[p.name] = parsed
+    }
+    return out
+  }
+
+  /** Build the persisted component ref from a palette item — stamps the MFE so
+   *  apply-time codegen imports from the right package, and seeds previewProps
+   *  (display samples) from the item or meta defaults. */
+  function componentRefFromItem(item: PaletteDragItem): WireframePaletteRef {
+    const meta = resolveMeta(item.componentName, item.library)
+    const props = item.props ? plain(item.props) : undefined
+    const seeded = seedFromMeta(meta)
+    const previewProps = item.previewProps
+      ? plain(item.previewProps)
+      : (Object.keys(seeded).length > 0 ? seeded : undefined)
+    const mfe = item.mfe ?? deps.surfaceMfe?.() ?? undefined
+    return {
+      tag: item.tag,
+      componentName: item.componentName,
+      ...(item.library ? { library: item.library } : {}),
+      ...(item.module ? { module: item.module } : {}),
+      ...(props ? { props } : {}),
+      ...(previewProps ? { previewProps } : {}),
+      ...(mfe ? { mfe } : {}),
+    }
+  }
+
+  /** Real props win over display samples — the merged set is what the user sees
+   *  rendered and what becomes the block's previewProps. */
+  function mergedProps(block: WireframeBlock): Record<string, unknown> {
+    const real = definedEntries(block.component?.props ?? {})
+    const samples = block.component?.previewProps ?? {}
+    return plain({ ...samples, ...real })
+  }
+
+  /** A binding whose path drills into an array is a list/loop. */
+  function isListPath(path?: string): boolean {
+    return !!path && path.includes('[]')
+  }
+
+  /** Resolve a block's data binding into a repeat count + per-instance prop
+   *  overlays for the preview. A bound prop shows the contract's REAL example
+   *  value when present (`sample`), else an honest `{field}` token — never
+   *  synthesized. Unbound blocks render once with no overlay. */
+  function bindingPreview(block: WireframeBlock): { repeat: number; instanceProps?: Record<string, unknown>[] } {
+    const data = block.data
+    if (!data) return { repeat: 1 }
+    const repeat = Math.max(1, data.repeat ?? (isListPath(data.path) ? DEFAULT_REPEAT : 1))
+    const map = data.propMap
+    if (!map || Object.keys(map).length === 0) return { repeat }
+    const sample = data.sample ?? []
+    const instanceProps: Record<string, unknown>[] = []
+    for (let i = 0; i < repeat; i++) {
+      const row = sample[i] ?? sample[0]
+      const overlay: Record<string, unknown> = {}
+      for (const [prop, field] of Object.entries(map)) {
+        const v = row?.[field]
+        overlay[prop] = (v !== undefined && v !== null) ? v : `{${field}}`
+      }
+      instanceProps.push(overlay)
+    }
+    // A mapped field value can be a nested object/array (legitimate for
+    // api-schema bindings), and `row` comes from the reactive `block.data.sample`
+    // — so each value here is a Vue reactive proxy. structuredClone throws
+    // DataCloneError on proxies, which would silently degrade the preview to a
+    // placeholder. plain() at this boundary guarantees only JSON crosses
+    // previewComponent's postMessage.
+    return { repeat, instanceProps: plain(instanceProps) }
+  }
+
+  /** Render the block's component offscreen and write the honest snapshot back.
+   *  Token-guarded so only the latest regen of a block wins. */
+  async function runGenerate(id: string): Promise<void> {
+    const block = deps.wireframe.findBlock(id)
+    if (!block || block.kind !== 'palette' || !block.component?.componentName) {
+      deps.wireframe.setGenerating(id, false)
+      return
+    }
+    if (deps.wireframe.building.value) {
+      deps.wireframe.setGenerating(id, false)
+      return
+    }
+    const token = (tokens.get(id) ?? 0) + 1
+    tokens.set(id, token)
+    deps.wireframe.setGenerating(id, true)
+    const merged = mergedProps(block)
+    const { repeat, instanceProps } = bindingPreview(block)
+    try {
+      const res = await deps.iframe.previewComponent(
+        block.component.componentName,
+        merged,
+        block.component.module,
+        PREVIEW_WIDTH,
+        { repeat, instanceProps },
+      )
+      if (tokens.get(id) !== token) return // superseded by a newer edit
+      if (!deps.wireframe.findBlock(id)) return // block deleted mid-flight
+      const snapshot: PaletteSnapshot = {
+        dataUrl: res.dataUrl,
+        width: res.width,
+        height: res.height,
+        fidelity: (res.fidelity as PaletteSnapshot['fidelity']) ?? (res.mounted ? 'isolated-preview' : 'placeholder'),
+        mounted: res.mounted,
+      }
+      // Honest degradation: no pixels → the block stays a placeholder render.
+      if (!res.dataUrl) snapshot.fidelity = 'placeholder'
+      await deps.wireframe.updatePaletteBlock(id, { previewProps: merged, snapshot }, { recordHistory: false })
+    } catch {
+      if (tokens.get(id) === token && deps.wireframe.findBlock(id)) {
+        await deps.wireframe.updatePaletteBlock(
+          id,
+          { snapshot: { fidelity: 'placeholder', mounted: false } },
+          { recordHistory: false },
+        )
+      }
+    } finally {
+      if (tokens.get(id) === token) deps.wireframe.setGenerating(id, false)
+    }
+  }
+
+  /** Debounced live regen for a config edit. Shows the shimmer immediately
+   *  (keeping the last-good snapshot visible) and renders after the pause. */
+  function scheduleRegen(id: string): void {
+    if (deps.wireframe.building.value) return
+    deps.wireframe.setGenerating(id, true)
+    const existing = timers.get(id)
+    if (existing) clearTimeout(existing)
+    timers.set(id, setTimeout(() => {
+      timers.delete(id)
+      void runGenerate(id)
+    }, REGEN_DEBOUNCE_MS))
+  }
+
+  /** Place-first drop: mint the block now, fill its snapshot immediately. */
+  function placeComponent(item: PaletteDragItem, at: { x: number; y: number }): string | null {
+    if (deps.wireframe.building.value) return null
+    const plainItem = plain(item)
+    ensureCatalog()
+    const id = deps.wireframe.placeComponentBlock(componentRefFromItem(plainItem), at)
+    if (id) void runGenerate(id)
+    return id
+  }
+
+  /** Set one REAL prop on a placed block (codegen value) and live-regenerate.
+   *  Records once per edit burst (coalesce-keyed via updatePaletteBlock). */
+  function setProp(id: string, name: string, value: unknown): void {
+    const block = deps.wireframe.findBlock(id)
+    if (!block || block.kind !== 'palette' || deps.wireframe.building.value) return
+    const props = { ...(block.component?.props ?? {}) }
+    if (value === undefined || value === null || value === '') delete props[name]
+    else props[name] = value
+    void deps.wireframe.updatePaletteBlock(id, { props }, { recordHistory: true })
+    scheduleRegen(id)
+  }
+
+  /** Bind (or clear) the block's data source and live-regenerate. */
+  function setBinding(id: string, binding: WireframeDataBinding | null): void {
+    if (deps.wireframe.building.value) return
+    void deps.wireframe.updatePaletteBlock(id, { data: binding ? plain(binding) : null }, { recordHistory: true })
+    scheduleRegen(id)
+  }
+
+  /** Map a component prop to a bound data field (or clear it with field=null),
+   *  then live-regenerate so the preview shows the bound value. No-op without a
+   *  binding on the block. */
+  function setPropBinding(id: string, prop: string, field: string | null): void {
+    const block = deps.wireframe.findBlock(id)
+    if (!block || block.kind !== 'palette' || !block.data || deps.wireframe.building.value) return
+    const data = plain(block.data)
+    const map = { ...(data.propMap ?? {}) }
+    if (field) map[prop] = field
+    else delete map[prop]
+    data.propMap = Object.keys(map).length > 0 ? map : undefined
+    void deps.wireframe.updatePaletteBlock(id, { data }, { recordHistory: true })
+    scheduleRegen(id)
+  }
+
+  /** Set how many loop instances a list binding sketches, then regenerate. */
+  function setRepeat(id: string, n: number): void {
+    const block = deps.wireframe.findBlock(id)
+    if (!block || block.kind !== 'palette' || !block.data || deps.wireframe.building.value) return
+    const data = plain(block.data)
+    data.repeat = Math.max(1, Math.min(Math.round(n) || 1, 24))
+    void deps.wireframe.updatePaletteBlock(id, { data }, { recordHistory: true })
+    scheduleRegen(id)
+  }
+
+  /** Cancel every pending live regen — called before "Implement this wireframe"
+   *  locks the sketch so an in-flight render can't mutate it mid-implement. */
+  function cancel(): void {
+    for (const t of timers.values()) clearTimeout(t)
+    timers.clear()
+  }
+
+  /** The datasource step is OFFERED (not required) when the component looks
+   *  data-driven — any prop infers as json (objects/arrays) or names an
+   *  array-ish type. An explicit "Bind data…" affordance always exists. */
+  function datasourceSuggested(block: WireframeBlock): boolean {
+    const meta = metaForBlock(block)
+    if (!meta) return false
+    return meta.props.some((p) => {
+      const t = (p.type ?? '').toLowerCase()
+      return (
+        t.includes('[]') ||
+        t.includes('array') ||
+        (!!p.type && !/^(string|number|boolean|bool|int|float)\b/.test(t) && !/^(['"])/.test(p.type ?? ''))
+      )
+    })
+  }
+
+  return {
+    placeComponent,
+    setProp,
+    setBinding,
+    setPropBinding,
+    setRepeat,
+    isListPath,
+    regenerate: scheduleRegen,
+    metaForBlock,
+    ensureCatalog,
+    datasourceSuggested,
+    cancel,
+  }
+}
diff --git a/src/shell/composables/useDataHighlights.ts b/src/shell/composables/useDataHighlights.ts
index 69adc1e..326e3ff 100644
--- a/src/shell/composables/useDataHighlights.ts
+++ b/src/shell/composables/useDataHighlights.ts
@@ -10,11 +10,12 @@
  *
  * Colors come from the annotation palette so they follow the active theme.
  */
-import { ref, watch, type Ref } from 'vue'
+import { ref, type Ref } from 'vue'
 import type { BridgeRect } from '../../shared/bridge-types'
 import type { DataSource } from '../../schema'
 import type { useIframeManager } from './useIframeManager'
 import { useWorkspace } from './useWorkspace'
+import { useOverlayLoop, OVERLAY_RECT_CAP } from './useOverlayEngine'
 
 export type HighlightConfidence = 'precise' | 'fallback' | 'runtime-only'
 
@@ -58,6 +59,12 @@ export interface DataHighlightSource {
    *  with no static binding, else `'precise'`. UI shows a badge when this is
    *  not precise. Defaults to `'precise'`. */
   confidence?: HighlightConfidence
+  /** How this source's COLOR should be read. `'identity'` (default) — color
+   *  distinguishes one source from another (library/positional palette).
+   *  `'latency'` — color encodes a measured latency bucket (the Network tab).
+   *  The overlay paints latency rects with a distinct border so an orange
+   *  "slow endpoint" can never be misread as an orange "2nd source". */
+  encoding?: 'identity' | 'latency'
   /** Short diagnostic string shown in row tooltips — "Astro analyzer
    *  missing", etc. Only surfaced when `confidence !== 'precise'`. */
   partialNote?: string
@@ -84,6 +91,10 @@ export interface DataHighlightRect {
    *  source when the site didn't set one). Drives fallback/precise overlay
    *  styling in `_highlights.css`. Defaults to `'precise'`. */
   confidence?: HighlightConfidence
+  /** Inherited from the owning source — `'latency'` makes the overlay draw a
+   *  distinct (solid) border so latency color isn't confused with identity
+   *  color. Defaults to `'identity'`. */
+  encoding?: 'identity' | 'latency'
   /** Every source that resolved to this DOM element. `sourceName` is the
    *  primary (first) owner for back-compat with existing callers; multi-
    *  source elements list every contributor here so the overlay can show a
@@ -153,8 +164,6 @@ export function colorForSource(name: string): string {
   return DATA_PALETTE[idx]
 }
 
-const RECT_CAP = 400
-
 export function useDataHighlights(deps: {
   iframe: ReturnType<typeof useIframeManager>
   /** True when the shell is on a view that should show data-source highlights
@@ -173,9 +182,10 @@ export function useDataHighlights(deps: {
   const focusedEid = ref<string | null>(null)
   const rects = ref<DataHighlightRect[]>([])
   const truncated = ref(false)
-
-  let loopRunning = false
-  let refreshInFlight = false
+  /** Total DOM matches the iframe resolved this pass (before the rect cap).
+   *  `rects.length` is what's drawn; this is the real count so the UI can say
+   *  "showing 400 of 1,237" instead of silently hiding the overflow. */
+  const totalResolved = ref(0)
 
   function setSources(list: DataHighlightSource[]): void {
     sources.value = list
@@ -186,13 +196,9 @@ export function useDataHighlights(deps: {
     if (focusedName.value && !list.find(s => s.name === focusedName.value)) {
       focusedName.value = null
     }
-    if (active.value) {
-      // Kick a refresh now so switching tools (Data → Components etc.) paints
-      // within the same frame instead of waiting for the next rAF tick. The
-      // rAF loop handles ongoing sync; this call just removes the startup gap.
-      refreshRects()
-      startLoop()
-    }
+    // Paint now so switching tools (Data → Components etc.) lands within the
+    // same frame; the shared loop handles ongoing sync.
+    if (active.value) loop.kick()
   }
 
   function setFocus(name: string | null, eid: string | null = null): void {
@@ -206,12 +212,11 @@ export function useDataHighlights(deps: {
     focusedEid.value = null
     rects.value = []
     truncated.value = false
+    totalResolved.value = 0
   }
 
   async function refreshRects(): Promise<void> {
-    if (refreshInFlight) return
-    refreshInFlight = true
-    try {
+    {
       if (!active.value || sources.value.length === 0) {
         if (rects.value.length) rects.value = []
         if (truncated.value) truncated.value = false
@@ -225,15 +230,23 @@ export function useDataHighlights(deps: {
       // location key itself so the bridge's match deduplicates across owners
       // before we even round-trip.
       const locations: Array<{ ref: string; file: string; line: number; tag?: string; mfe?: string; module?: string }> = []
-      interface OwnerMeta { sourceName: string; color: string; label: string; tag?: string; module?: string; confidence: HighlightConfidence }
+      interface OwnerMeta { sourceName: string; color: string; label: string; tag?: string; module?: string; confidence: HighlightConfidence; encoding: 'identity' | 'latency' }
       const siteOwners = new Map<string, OwnerMeta[]>()
 
-      // Workspace-aware path translation: catalogs store workspace-relative
-      // paths, but the iframe DOM carries MFE-local `data-annotask-file`
-      // values tagged with `data-annotask-mfe`. Convert each workspace path
-      // back to `(mfe-local, mfe)` so the bridge selector lines up.
+      // Workspace-aware path translation: catalogs/binding graphs store
+      // workspace-relative paths (e.g. `playgrounds/simple/vue-vite/src/App.vue`),
+      // but the iframe DOM carries `data-annotask-file` values that Vite stamps
+      // relative to ITS root = the running package (e.g. `src/App.vue`). Convert
+      // each workspace path back to that package-local form so the bridge
+      // selector lines up. MFE files strip the MFE package dir (and carry its id);
+      // every other file strips the running package's own dir (`currentDir`).
+      // Without the `currentDir` strip, a non-MFE app nested under the workspace
+      // root never matches and no data-source rects ever render — the same
+      // translation `useProjectComponents` already applies in the reverse
+      // direction (it *prefixes* currentDir onto bridge-reported files).
       const ws = useWorkspace()
       const mfePkgs = (ws.info.value?.packages ?? []).filter(p => !!p.mfe && !!p.dir)
+      const currentDir = ws.info.value?.currentDir ?? ''
 
       function toBridgeLoc(file: string): { file: string; mfe?: string } {
         // Longest-matching dir wins so nested packages beat their parent.
@@ -250,6 +263,12 @@ export function useDataHighlights(deps: {
         if (bestMfe) {
           return { file: file === bestDir ? '' : file.slice(bestDir.length + 1), mfe: bestMfe }
         }
+        // Non-MFE: strip the running package's dir so the path is package-local.
+        // `currentDir` is '' when the running package *is* the workspace root, in
+        // which case the path is already package-local and needs no change.
+        if (currentDir && (file === currentDir || file.startsWith(currentDir + '/'))) {
+          return { file: file === currentDir ? '' : file.slice(currentDir.length + 1) }
+        }
         return { file }
       }
 
@@ -269,7 +288,7 @@ export function useDataHighlights(deps: {
             site.confidence
             ?? src.confidence
             ?? (site.line === 0 ? 'fallback' : 'precise')
-          const entry: OwnerMeta = { sourceName: src.name, color, label, tag: site.tag, module: site.module, confidence }
+          const entry: OwnerMeta = { sourceName: src.name, color, label, tag: site.tag, module: site.module, confidence, encoding: src.encoding ?? 'identity' }
           const existing = siteOwners.get(key)
           if (existing) {
             // Same (file, line, tag) already has an owner — stack this source
@@ -299,6 +318,9 @@ export function useDataHighlights(deps: {
       // merge those into a single rect with an `ownerSources` list so the
       // UI can show both owners instead of drawing two stacked overlays.
       const byEid = new Map<string, DataHighlightRect>()
+      // Unique elements past the rect cap — counted (not stored) so the UI can
+      // report the true total ("showing 400 of N") instead of silently hiding them.
+      const overflowEids = new Set<string>()
       const confidenceRank: Record<HighlightConfidence, number> = {
         precise: 2,
         fallback: 1,
@@ -326,7 +348,7 @@ export function useDataHighlights(deps: {
           }
           continue
         }
-        if (byEid.size >= RECT_CAP) continue
+        if (byEid.size >= OVERLAY_RECT_CAP) { overflowEids.add(m.eid); continue }
         byEid.set(m.eid, {
           sourceName: primary.sourceName,
           file: m.file,
@@ -338,66 +360,43 @@ export function useDataHighlights(deps: {
           tag: primary.tag,
           module: primary.module,
           confidence: primary.confidence,
+          encoding: primary.encoding,
           ownerSources: owners.map(o => o.sourceName),
           ownerLabels: owners.map(o => o.label),
         })
       }
       rects.value = [...byEid.values()]
-      truncated.value = wasTruncated || matches.length > RECT_CAP
-    } finally {
-      refreshInFlight = false
-    }
-  }
-
-  function startLoop(): void {
-    if (loopRunning) return
-    if (!active.value) return
-    loopRunning = true
-    const tick = () => {
-      if (!active.value || sources.value.length === 0) {
-        loopRunning = false
-        return
-      }
-      if (typeof document !== 'undefined' && document.hidden) {
-        requestAnimationFrame(tick)
-        return
-      }
-      refreshRects()
-      requestAnimationFrame(tick)
+      totalResolved.value = byEid.size + overflowEids.size
+      truncated.value = wasTruncated || overflowEids.size > 0
     }
-    requestAnimationFrame(tick)
   }
 
-  watch(active, (v, old) => {
-    if (v && !old) {
-      // Entering a highlight-showing view (Data / Components / etc.) — push a
-      // refresh immediately so already-set sources paint without waiting for
-      // the next setSources call. Fixes the case where a user switches to
-      // Components on an unchanged iframe route and expects the overlays to
-      // appear without them having to navigate the iframe first.
-      refreshRects()
-      startLoop()
-    } else if (!v && old) {
-      // Leaving a highlight view — clear both rects and sources so the next
-      // entry starts from a clean slate. Without this, switching
-      // Data → Annotate → Components would briefly paint the stale Data
-      // sources until Components' own load() pushed its list.
+  // The shared overlay loop owns the rAF lifecycle + re-entrancy/visibility
+  // guards; this composable only supplies the refresh body and what "idle"
+  // means. Leaving the view clears sources/focus/rects so the next entry
+  // starts clean (prevents a stale Data → Components flash).
+  const loop = useOverlayLoop({
+    active,
+    refresh: refreshRects,
+    inputs: () => sources.value,
+    isIdle: () => sources.value.length === 0,
+    onDeactivate: () => {
       sources.value = []
       focusedName.value = null
       focusedEid.value = null
       rects.value = []
       truncated.value = false
-    }
+      totalResolved.value = 0
+    },
   })
 
-  watch(sources, () => { if (active.value) startLoop() }, { deep: true })
-
   return {
     sources,
     focusedName,
     focusedEid,
     rects,
     truncated,
+    totalResolved,
     setSources,
     setFocus,
     clear,
diff --git a/src/shell/composables/useDataSources.ts b/src/shell/composables/useDataSources.ts
index 72e64f7..c2e4578 100644
--- a/src/shell/composables/useDataSources.ts
+++ b/src/shell/composables/useDataSources.ts
@@ -1,7 +1,6 @@
 /**
  * State + fetching for the Data view: project data sources, discovered API
- * schemas, and per-source definition details. Creates `api_update` tasks for
- * in-repo data sources; external sources are exposed but non-editable.
+ * schemas, and per-source definition details.
  */
 import { ref, computed } from 'vue'
 import { on as wsOn } from '../services/wsClient'
@@ -351,6 +350,9 @@ function buildNetworkHighlightSources(): DataHighlightSource[] {
       sites,
       defaultLabel: label,
       color,
+      // Network color is a latency bucket, not an identity hue — tag it so the
+      // overlay draws a distinct (solid) border and the legend can say so.
+      encoding: 'latency',
     })
   }
   return out
@@ -437,8 +439,12 @@ function buildApiHighlightSources(): DataHighlightSource[] {
     try { return new URL(raw).origin } catch { return null }
   }
   const pathOf = (raw: string): string => {
-    if (!raw.startsWith('http://') && !raw.startsWith('https://')) return raw
-    try { return new URL(raw).pathname } catch { return raw }
+    if (raw.startsWith('http://') || raw.startsWith('https://')) {
+      try { return new URL(raw).pathname } catch { return raw }
+    }
+    // Relative path — strip the query string / fragment so an endpoint like
+    // `/api/solar/planets?sort_by=x` still matches the schema op `/api/solar/planets`.
+    return raw.split(/[?#]/)[0]
   }
   // An entry's origin comes from its resolved_endpoint (proxy-aware) first,
   // falling back to a literal absolute URL in `endpoint`. We also pre-compute
@@ -456,14 +462,19 @@ function buildApiHighlightSources(): DataHighlightSource[] {
     const seen = new Set<string>()
     for (const entry of cat.project_entries) {
       if (!entry.endpoint) continue
-      const entryUrl = entry.resolved_endpoint ?? entry.endpoint
-      const entryOrigin = originOf(entryUrl)
-      // Strict origin match when both sides know their origin.
+      // Use the ORIGINAL endpoint for the origin. A relative endpoint
+      // (`/api/...`) is a same-origin (often Vite-proxied) call — match it by
+      // PATH against any schema. resolved_endpoint's proxy-target host
+      // (e.g. :8888) is a server-side detail; gating on it dropped every proxied
+      // entry from the schema (whose origin is the browser-visible dev-server
+      // origin), so the APIs tab highlighted nothing.
+      const entryOrigin = entry.endpoint.startsWith('/') ? null : originOf(entry.endpoint)
+      // Strict origin match only when the entry itself is an absolute URL.
       if (schemaOrigin && entryOrigin && schemaOrigin !== entryOrigin) continue
-      // When the entry has a known origin but this schema doesn't, skip if
-      // another schema covers the entry's origin — that's the right owner.
+      // When the entry has a known (absolute) origin but this schema doesn't,
+      // skip if another schema covers that origin — that's the right owner.
       if (!schemaOrigin && entryOrigin && schemaOrigins.has(entryOrigin)) continue
-      const entryPath = pathOf(entryUrl)
+      const entryPath = pathOf(entry.endpoint)
       const match = schema.operations.find(op => matchesOpPath(op.path, entryPath))
       if (!match) continue
       const graph = bindingsByName.value.get(entryBindingKey(entry))
@@ -640,7 +651,7 @@ async function loadLibraryUsages(lib: DataSourceLibrary): Promise<void> {
 /**
  * Find the API schema that most likely backs a data-source, by matching on
  * endpoint / path heuristics. Used to expose `schema_in_repo` on the detail
- * pane and wire the `Create API Update Task` button.
+ * pane.
  */
 function matchSchemaForEntry(entry: ProjectDataEntry, all: ApiSchema[]): { schema: ApiSchema; operation?: ApiSchema['operations'][number] } | null {
   if (!entry.endpoint) return null
@@ -649,8 +660,12 @@ function matchSchemaForEntry(entry: ProjectDataEntry, all: ApiSchema[]): { schem
     try { return new URL(raw).origin } catch { return null }
   }
   const pathOf = (raw: string): string => {
-    if (!raw.startsWith('http://') && !raw.startsWith('https://')) return raw
-    try { return new URL(raw).pathname } catch { return raw }
+    if (raw.startsWith('http://') || raw.startsWith('https://')) {
+      try { return new URL(raw).pathname } catch { return raw }
+    }
+    // Relative path — strip the query string / fragment so an endpoint like
+    // `/api/solar/planets?sort_by=x` still matches the schema op `/api/solar/planets`.
+    return raw.split(/[?#]/)[0]
   }
   const entryOrigin = originOf(entry.endpoint)
   const entryPath = pathOf(entry.endpoint)
@@ -836,7 +851,7 @@ const selectedItem = computed<DataListItem | null>(() => {
 /**
  * For the currently selected data-source, find the matching schema (if any)
  * and return `{ schema_in_repo, schema, operation }` so the detail pane can
- * decide whether to show the "Create API Update Task" button.
+ * surface in-repo / external badges.
  */
 const selectedSchemaLink = computed<
   { schema_in_repo: boolean; schema: ApiSchema; operation?: ApiSchema['operations'][number] } | null
@@ -884,54 +899,6 @@ function clearSelection(): void {
   highlightsAdapter?.setFocus(null)
 }
 
-async function createApiUpdateTask(args: {
-  description: string
-  desired_change: string
-  rationale?: string
-}): Promise<{ ok: true; id: string } | { ok: false; error: string }> {
-  const item = selectedItem.value
-  if (!item || item.kind !== 'data-source') {
-    return { ok: false, error: 'No data source selected' }
-  }
-  const link = selectedSchemaLink.value
-  if (!link || !link.schema_in_repo) {
-    return { ok: false, error: 'Selected source is not backed by an in-repo schema' }
-  }
-  const context: Record<string, unknown> = {
-    data_source_name: item.name,
-    data_source_kind: item.dataKind,
-    schema_location: link.schema.location,
-    schema_kind: link.schema.kind,
-    desired_change: args.desired_change,
-  }
-  if (item.endpoint) context.endpoint = item.endpoint
-  if (link.operation) {
-    context.operation = { method: link.operation.method, path: link.operation.path }
-  }
-  if (args.rationale) context.rationale = args.rationale
-  try {
-    const res = await fetch('/__annotask/api/tasks', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        type: 'api_update',
-        description: args.description,
-        file: item.file,
-        line: item.line ?? 1,
-        context,
-      }),
-    })
-    if (!res.ok) {
-      const data = await res.json().catch(() => ({}))
-      return { ok: false, error: data?.error?.message ?? `HTTP ${res.status}` }
-    }
-    const created = await res.json()
-    return { ok: true, id: created.id }
-  } catch (err) {
-    return { ok: false, error: (err as Error).message ?? 'Network error' }
-  }
-}
-
 let initialized = false
 
 /**
@@ -989,7 +956,6 @@ export function useDataSources() {
     select,
     clearSelection,
     reload: loadAll,
-    createApiUpdateTask,
     colorForEntry,
     colorForSchema,
     bindingConfidenceFor,
diff --git a/src/shell/composables/useDesignSession.ts b/src/shell/composables/useDesignSession.ts
new file mode 100644
index 0000000..edddf88
--- /dev/null
+++ b/src/shell/composables/useDesignSession.ts
@@ -0,0 +1,592 @@
+import { ref, computed } from 'vue'
+import { on as wsOn } from '../services/wsClient'
+import type { DesignSessionDocument, SessionAnchor, EditEvidence, LiveWriteState, ApplyBatch } from '../../shared/design-session-types'
+// Type-only import — runtime dependency points the other way (useStyleEditor
+// records into this journal), so this cycle is erased at compile time.
+import type { ChangeRecord } from './useStyleEditor'
+
+/**
+ * Shell-side session entry. Mirrors the persisted `SessionEntry`
+ * (shared/design-session-types.ts) but carries the legacy `ChangeRecord`
+ * runtime payload — the report/task shapes are projected from it by
+ * useStyleEditor.shapeChange, exactly as before. Serialization to the server
+ * document (and the agent-facing `context.session`) strips the non-schema
+ * fields at that boundary.
+ */
+export interface ShellSessionEntry {
+  id: string
+  /** Monotonic within the session — the undo order. */
+  ordinal: number
+  ts: number
+  /** Normalized iframe route at record time. */
+  route: string
+  change: ChangeRecord
+  anchor: SessionAnchor
+  evidence?: EditEvidence
+  live: LiveWriteState
+  /** Cross-reference to a WireframeInstance for placement entries. The
+   *  instance payload is never copied — wireframe.json stays canonical. */
+  instanceId?: string
+  /** Volatile bridge element id — never trusted across HMR. */
+  eid?: string
+  /** Set when the entry was snapshotted into a wireframe_apply task. */
+  taskId?: string
+  breakpointId?: string | null
+  /** Collapse identity (includes eid) — entries sharing it project to ONE
+   *  report record and amend during a continuous gesture. Absent = never grouped. */
+  amendKey?: string
+  /** Gesture identity (amendKey minus eid). Lets a group-selection slider drag
+   *  (N eids per tick) amend its N entries instead of appending N per tick. */
+  gestureKey?: string
+}
+
+export interface RecordEntryInput {
+  change: ChangeRecord
+  anchor: SessionAnchor
+  route?: string
+  eid?: string
+  instanceId?: string
+  evidence?: EditEvidence
+  amendKey?: string
+  gestureKey?: string
+  /** Applied to the latest pending same-key entry instead of appending, when
+   *  the entries recorded since it all belong to the same gesture. Must update
+   *  `after`/description only — `before` is preserved from first touch. */
+  amendTop?: (top: ChangeRecord) => void
+}
+
+/** The iframe surface the reload-restore preview pass needs — structural so
+ *  tests can pass a small mock; useIframeManager satisfies it. */
+export interface SessionPreviewIframe {
+  findTemplateGroup: (file: string, line: string, tagName: string) => Promise<{ eids: string[] }>
+  applyStyleVia?: (eid: string, property: string, value: string) => Promise<string>
+  setClass?: (eid: string, classes: string) => Promise<string>
+}
+
+// Module-level singleton state — same pattern as useStyleEditor's change
+// buffer and useWireframeDoc: every caller shares one session.
+const entries = ref<ShellSessionEntry[]>([])
+const redoBuffer: ShellSessionEntry[] = []
+/** Normalized iframe route, wired from useIframeManager by App.vue. */
+const sessionRoute = ref('')
+/** Active viewport scope for new entries (M6); null = base viewport. Included
+ *  in collapse keys from day one so retrofitting can't corrupt undo grouping. */
+const activeBreakpointId = ref<string | null>(null)
+/** Last sync problem worth surfacing ('session active in another tab', …). */
+const syncError = ref<string | null>(null)
+/** Set when a second 409 in a row proves another tab owns the session. */
+const readOnly = ref(false)
+/** Entries whose anchors no longer resolve in the live DOM after a reload —
+ *  the preview can't honestly claim them, so they get a badge instead. */
+const staleEntryIds = ref<string[]>([])
+/** Snapshot-engine state (touched files + apply batches) for the panel. */
+const snapshotState = ref<{ files: Record<string, { baseHash: string; lastAppliedHash?: string; status: 'clean' | 'diverged' }>; batches: ApplyBatch[] }>({ files: {}, batches: [] })
+/** An apply POST is in flight (just the request — see applyInFlight for the run). */
+const applying = ref(false)
+/** Loud-failure surface for apply/undo/discard operations. */
+const lastError = ref<string | null>(null)
+
+/**
+ * True while an apply run is unsettled: the POST is in flight, or a batch is
+ * still 'running' (its agent is mid-write, or crashed before sealing). Undo/
+ * Discard MUST be inert here — reverting an unsealed batch clobbers the agent's
+ * in-progress bytes with no hash guard. The BATCH status is authoritative: it
+ * is sealed on every terminal transition (review verify, or an abandon/orphan
+ * seal 'failed'), so a lingering 'applying' entry — e.g. an agent paused at
+ * needs_info — no longer falsely pins this true and disables undo forever. The
+ * server's revertBatch/revertAll still hard-refuse a 'running' batch, so a
+ * stale client view can never clobber a live run regardless.
+ */
+const applyInFlight = computed(() =>
+  applying.value
+  || snapshotState.value.batches.some((b) => (b.status ?? 'running') === 'running'),
+)
+
+let ordinalCounter = 0
+let entryCounter = 0
+let sessionId = ''
+let startedAt = 0
+let lastRev: number | undefined
+let initialized = false
+// Reload-restore de-dup: which route's previews were replayed into the
+// current iframe document (reset when bridgeReady refires).
+let previewAppliedRoute: string | null = null
+
+// ── Persistence: debounced single-flight CAS PUT ──
+let flushTimer: ReturnType<typeof setTimeout> | null = null
+let flushing = false
+let dirty = false
+
+function setStale(id: string, present: boolean): void {
+  const has = staleEntryIds.value.includes(id)
+  if (present && !has) staleEntryIds.value = [...staleEntryIds.value, id]
+  else if (!present && has) staleEntryIds.value = staleEntryIds.value.filter((x) => x !== id)
+}
+
+function ensureSessionIdentity(): void {
+  if (!sessionId) {
+    sessionId = `ds-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`
+    startedAt = Date.now()
+  }
+}
+
+function serializeEntry(e: ShellSessionEntry): Record<string, unknown> {
+  // placeholderEl (a DOM node) must never reach JSON.stringify; everything
+  // else on the records is plain data.
+  const { placeholderEl: _el, ...change } = e.change as ChangeRecord & { placeholderEl?: Element }
+  return { ...e, change }
+}
+
+function buildDoc(): Record<string, unknown> {
+  ensureSessionIdentity()
+  return {
+    version: '1.0',
+    sessionId,
+    startedAt,
+    updatedAt: Date.now(),
+    ...(lastRev !== undefined ? { rev: lastRev } : {}),
+    entries: entries.value.map(serializeEntry),
+  }
+}
+
+function reseedCounters(): void {
+  ordinalCounter = entries.value.reduce((m, e) => Math.max(m, e.ordinal), 0)
+  entryCounter = entries.value.reduce((m, e) => {
+    const n = /^se-(\d+)$/.exec(e.id)
+    return n ? Math.max(m, parseInt(n[1], 10)) : m
+  }, 0)
+}
+
+function adoptDocument(doc: DesignSessionDocument): void {
+  entries.value = doc.entries as unknown as ShellSessionEntry[]
+  sessionId = doc.sessionId
+  startedAt = doc.startedAt
+  lastRev = doc.rev
+  redoBuffer.length = 0
+  reseedCounters()
+}
+
+/** Server wins `live`/`taskId` per entry id; the local list wins on entry
+ *  presence and change payloads (the two sides mutate disjoint fields). Other
+ *  tabs' new entries are appended in ordinal order. */
+function mergeFromServer(server: DesignSessionDocument): void {
+  const serverById = new Map(server.entries.map((e) => [e.id, e]))
+  for (const local of entries.value) {
+    const remote = serverById.get(local.id)
+    if (remote) {
+      local.live = remote.live as LiveWriteState
+      if (remote.taskId !== undefined) local.taskId = remote.taskId
+    }
+  }
+  const localIds = new Set(entries.value.map((e) => e.id))
+  const foreign = server.entries.filter((e) => !localIds.has(e.id)) as unknown as ShellSessionEntry[]
+  if (foreign.length > 0) {
+    entries.value = [...entries.value, ...foreign].sort((a, b) => a.ordinal - b.ordinal)
+  }
+  sessionId = server.sessionId
+  startedAt = server.startedAt
+  lastRev = server.rev
+  reseedCounters()
+}
+
+async function flushNow(): Promise<void> {
+  if (flushing) { dirty = true; return }
+  if (readOnly.value) return
+  flushing = true
+  dirty = false
+  try {
+    const res = await fetch('/__annotask/api/design-session', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(buildDoc()),
+    })
+    if (res.status === 409) {
+      // Another writer (tab, or a server lifecycle hook) committed first.
+      // Merge their truth in, then retry exactly once — a second conflict
+      // means a genuinely concurrent editor, so go read-only instead of
+      // ping-ponging writes.
+      const server = (await (await fetch('/__annotask/api/design-session')).json()) as unknown
+      if (!looksLikeSessionDoc(server)) throw new Error('unexpected design-session payload')
+      mergeFromServer(server)
+      const retry = await fetch('/__annotask/api/design-session', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(buildDoc()),
+      })
+      if (retry.status === 409) {
+        readOnly.value = true
+        syncError.value = 'Design session is active in another tab — this tab is read-only.'
+        return
+      }
+      if (!retry.ok) throw new Error(`HTTP ${retry.status}`)
+      const saved = (await retry.json()) as DesignSessionDocument
+      lastRev = saved.rev
+      syncError.value = null
+      return
+    }
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const saved = (await res.json()) as DesignSessionDocument
+    lastRev = saved.rev
+    syncError.value = null
+  } catch (err) {
+    syncError.value = (err as Error).message ?? 'Failed to save design session'
+  } finally {
+    flushing = false
+    if (dirty) queueFlush()
+  }
+}
+
+function queueFlush(): void {
+  dirty = true
+  if (flushTimer) clearTimeout(flushTimer)
+  flushTimer = setTimeout(() => { flushTimer = null; void flushNow() }, 300)
+}
+
+function looksLikeSessionDoc(v: unknown): v is DesignSessionDocument {
+  return !!v && typeof v === 'object'
+    && typeof (v as DesignSessionDocument).sessionId === 'string'
+    && Array.isArray((v as DesignSessionDocument).entries)
+}
+
+async function load(): Promise<void> {
+  try {
+    const res = await fetch('/__annotask/api/design-session')
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const doc = (await res.json()) as unknown
+    // Never clobber the in-memory journal with something that isn't a session
+    // document (misrouted proxy, stale server build).
+    if (!looksLikeSessionDoc(doc)) throw new Error('unexpected design-session payload')
+    adoptDocument(doc)
+    syncError.value = null
+  } catch (err) {
+    syncError.value = (err as Error).message ?? 'Failed to load design session'
+  }
+}
+
+function findAmendTarget(amendKey: string, gestureKey: string | undefined): ShellSessionEntry | null {
+  for (let i = entries.value.length - 1; i >= 0; i--) {
+    const e = entries.value[i]
+    if (e.amendKey === amendKey) {
+      // Amendable only while untouched by apply/snapshot.
+      if (e.live.status !== 'pending' || e.taskId) return null
+      return e
+    }
+    // An intervening entry from a DIFFERENT gesture breaks the run — the
+    // re-edit is a new user action and must append (ordered undo).
+    if (!gestureKey || e.gestureKey !== gestureKey) return null
+  }
+  return null
+}
+
+export function useDesignSession() {
+  if (!initialized) {
+    initialized = true
+    void load()
+    void refreshSnapshots()
+    wsOn('session:updated', (payload: unknown) => {
+      const doc = payload as DesignSessionDocument | null
+      // The snapshot view (touched files, batches, divergence) can change on
+      // any server-side session mutation — keep the panel fresh.
+      void refreshSnapshots()
+      // Our own PUT echoes back with the rev we just adopted — ignore it.
+      if (doc && typeof doc.rev === 'number' && doc.rev === lastRev) return
+      // Unflushed local work: let the flush's 409-merge reconcile instead of
+      // clobbering the in-memory journal with a lagging disk state.
+      if (dirty || flushing) return
+      if (looksLikeSessionDoc(doc)) {
+        adoptDocument(doc)
+      } else {
+        void load()
+      }
+    })
+  }
+
+  /** Append a new entry, or amend the latest same-key entry recorded within
+   *  the current gesture run. Returns the live entry either way. */
+  function record(input: RecordEntryInput): ShellSessionEntry {
+    redoBuffer.length = 0
+    ensureSessionIdentity()
+    if (input.amendKey && input.amendTop) {
+      const target = findAmendTarget(input.amendKey, input.gestureKey)
+      if (target) {
+        input.amendTop(target.change)
+        target.ts = Date.now()
+        if (input.eid) target.eid = input.eid
+        if (input.evidence) target.evidence = input.evidence
+        queueFlush()
+        return target
+      }
+    }
+    entryCounter++
+    const entry: ShellSessionEntry = {
+      id: `se-${entryCounter}`,
+      ordinal: ++ordinalCounter,
+      ts: Date.now(),
+      route: input.route ?? sessionRoute.value,
+      change: input.change,
+      anchor: input.anchor,
+      ...(input.evidence ? { evidence: input.evidence } : {}),
+      live: { status: 'pending' },
+      ...(input.instanceId ? { instanceId: input.instanceId } : {}),
+      ...(input.eid ? { eid: input.eid } : {}),
+      breakpointId: activeBreakpointId.value,
+      ...(input.amendKey ? { amendKey: input.amendKey } : {}),
+      ...(input.gestureKey ? { gestureKey: input.gestureKey } : {}),
+    }
+    entries.value.push(entry)
+    queueFlush()
+    return entry
+  }
+
+  /** Pop the journal tail into the redo buffer — the session-wide undo unit.
+   *  Written/applying entries are NOT poppable here: agent-authored source
+   *  can't be un-written per entry (the tool didn't author it) — the panel's
+   *  "Undo last apply" restores that batch's snapshots instead. */
+  function popForUndo(): ShellSessionEntry | null {
+    const last = entries.value[entries.value.length - 1]
+    if (!last) return null
+    if (last.live.status === 'written' || last.live.status === 'applying') return null
+    entries.value.pop()
+    redoBuffer.push(last)
+    setStale(last.id, false)
+    queueFlush()
+    return last
+  }
+
+  function setLiveState(entryId: string, live: LiveWriteState): void {
+    const e = entries.value.find((x) => x.id === entryId)
+    if (!e) return
+    e.live = live
+    queueFlush()
+  }
+
+  function findByChangeId(changeId: string): ShellSessionEntry | undefined {
+    return entries.value.find((e) => e.change.id === changeId)
+  }
+
+  /** Remove entries matching the predicate; returns the removed entries. */
+  function removeWhere(pred: (e: ShellSessionEntry) => boolean): ShellSessionEntry[] {
+    const removed: ShellSessionEntry[] = []
+    entries.value = entries.value.filter((e) => {
+      if (pred(e)) { removed.push(e); return false }
+      return true
+    })
+    if (removed.length > 0) {
+      for (const e of removed) setStale(e.id, false)
+      queueFlush()
+    }
+    return removed
+  }
+
+  function removeByInstanceId(instanceId: string): ShellSessionEntry[] {
+    return removeWhere((e) => e.instanceId === instanceId)
+  }
+
+  /** Clear the whole journal; returns the removed entries. */
+  function clear(): ShellSessionEntry[] {
+    const removed = entries.value
+    entries.value = []
+    redoBuffer.length = 0
+    staleEntryIds.value = []
+    if (removed.length > 0) queueFlush()
+    return removed
+  }
+
+  /**
+   * Reload-restore: replay this route's pending style/class previews onto the
+   * fresh iframe DOM, so a persisted session never claims edits the preview
+   * doesn't show. Anchors re-resolve via the durable (file, line, targetTag)
+   * triple; an anchor that resolves to MULTIPLE elements (a loop) is marked
+   * stale instead of replayed — applying one element's edit to all N would
+   * silently fake what the user did. Precision over recall.
+   */
+  async function reapplyPreviews(route: string, iframe: SessionPreviewIframe, opts?: { force?: boolean }): Promise<void> {
+    if (!opts?.force && route === previewAppliedRoute) return
+    previewAppliedRoute = route
+    const candidates = entries.value.filter(
+      (e) => !e.instanceId
+        && e.route === route
+        && (e.live.status === 'pending' || e.live.status === 'failed')
+        && (e.change.type === 'style_update' || e.change.type === 'class_update'),
+    )
+    for (const e of candidates) {
+      try {
+        const group = await iframe.findTemplateGroup(e.anchor.file, String(e.anchor.line), e.anchor.targetTag ?? '')
+        if (group.eids.length !== 1) {
+          setStale(e.id, true)
+          continue
+        }
+        const eid = group.eids[0]
+        if (e.change.type === 'style_update' && iframe.applyStyleVia) {
+          await iframe.applyStyleVia(eid, e.change.property, e.change.after)
+        } else if (e.change.type === 'class_update' && iframe.setClass) {
+          await iframe.setClass(eid, e.change.after.classes)
+        }
+        // Re-stamp the volatile eid so undo targets the live node again.
+        e.eid = eid
+        setStale(e.id, false)
+      } catch {
+        setStale(e.id, true)
+      }
+    }
+  }
+
+  /** Drop the preview-replay de-dup (a fresh iframe DOM means nothing is applied). */
+  function resetPreviewApplied(): void {
+    previewAppliedRoute = null
+  }
+
+  /** Test hook + pre-snapshot barrier: run the debounced flush immediately. */
+  async function queueFlushNow(): Promise<void> {
+    if (flushTimer) { clearTimeout(flushTimer); flushTimer = null }
+    await flushNow()
+  }
+
+  async function refreshSnapshots(): Promise<void> {
+    try {
+      const res = await fetch('/__annotask/api/design-session/snapshots')
+      if (!res.ok) return
+      const state = (await res.json()) as typeof snapshotState.value
+      if (state && state.files && Array.isArray(state.batches)) snapshotState.value = state
+    } catch { /* panel state is best-effort */ }
+  }
+
+  /**
+   * "Apply now": flush the journal, then ask the server to snapshot the
+   * touched files and mint ONE wireframe_apply task (placements + panel
+   * edits). The caller hands the returned taskId to the embedded-agent
+   * auto-run (or leaves it for an external agent).
+   */
+  async function applyNow(opts?: { route?: string; screenshot?: string }): Promise<{ taskId: string; batchId: string } | null> {
+    lastError.value = null
+    applying.value = true
+    try {
+      await queueFlushNow()
+      const res = await fetch('/__annotask/api/design-session/apply', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          route: opts?.route ?? (sessionRoute.value || '/'),
+          ...(opts?.screenshot ? { screenshot: opts.screenshot } : {}),
+        }),
+      })
+      const body = await res.json().catch(() => null) as { taskId?: string; batchId?: string; error?: { message?: string } } | null
+      if (!res.ok || !body?.taskId || !body?.batchId) {
+        lastError.value = body?.error?.message ?? `apply failed (HTTP ${res.status})`
+        return null
+      }
+      await load()
+      await refreshSnapshots()
+      return { taskId: body.taskId, batchId: body.batchId }
+    } catch (err) {
+      lastError.value = (err as Error).message ?? 'apply failed'
+      return null
+    } finally {
+      applying.value = false
+    }
+  }
+
+  /** Restore the newest apply batch's pre-apply bytes; its entries return to pending. */
+  async function undoLastBatch(): Promise<{ reverted: string[]; skipped: string[] } | null> {
+    if (applyInFlight.value) {
+      lastError.value = 'An apply is still running — wait for it to finish before undoing.'
+      return null
+    }
+    const batch = snapshotState.value.batches[snapshotState.value.batches.length - 1]
+    if (!batch) return null
+    lastError.value = null
+    try {
+      const res = await fetch('/__annotask/api/design-session/undo-batch', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ batchId: batch.id }),
+      })
+      const body = await res.json().catch(() => null) as { reverted?: string[]; skipped?: string[]; error?: { message?: string } } | null
+      if (!res.ok) {
+        lastError.value = body?.error?.message ?? `undo failed (HTTP ${res.status})`
+        return null
+      }
+      await load()
+      await refreshSnapshots()
+      if (body?.skipped?.length) {
+        lastError.value = `Could not restore ${body.skipped.join(', ')} — edited outside Annotask (detach to keep the current bytes)`
+      }
+      return { reverted: body?.reverted ?? [], skipped: body?.skipped ?? [] }
+    } catch (err) {
+      lastError.value = (err as Error).message ?? 'undo failed'
+      return null
+    }
+  }
+
+  /** Discard the whole session: server restores every snapshot-tracked file to
+   *  its session base and removes the session's placements. */
+  async function discardSession(): Promise<{ revertedFiles: string[]; failedFiles: string[]; removedInstances: number } | null> {
+    if (applyInFlight.value) {
+      lastError.value = 'An apply is still running — wait for it to finish before discarding.'
+      return null
+    }
+    lastError.value = null
+    try {
+      const res = await fetch('/__annotask/api/design-session', { method: 'DELETE' })
+      const body = await res.json().catch(() => null) as { revertedFiles?: string[]; failedFiles?: string[]; removedInstances?: number } | null
+      if (!res.ok) {
+        lastError.value = `discard failed (HTTP ${res.status})`
+        return null
+      }
+      clear()
+      await load()
+      await refreshSnapshots()
+      if (body?.failedFiles?.length) {
+        lastError.value = `Could not restore ${body.failedFiles.join(', ')} — edited outside Annotask`
+      }
+      return { revertedFiles: body?.revertedFiles ?? [], failedFiles: body?.failedFiles ?? [], removedInstances: body?.removedInstances ?? 0 }
+    } catch (err) {
+      lastError.value = (err as Error).message ?? 'discard failed'
+      return null
+    }
+  }
+
+  /** Diverged-file resolution: keep the disk bytes, forget the file. */
+  async function detachFile(file: string): Promise<void> {
+    try {
+      const res = await fetch('/__annotask/api/design-session/detach-file', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ file }),
+      })
+      if (res.ok) {
+        const state = (await res.json()) as typeof snapshotState.value
+        if (state && state.files) snapshotState.value = state
+      }
+    } catch { /* best effort */ }
+  }
+
+  return {
+    entries,
+    sessionRoute,
+    activeBreakpointId,
+    syncError,
+    readOnly,
+    staleEntryIds,
+    snapshotState,
+    applying,
+    applyInFlight,
+    lastError,
+    record,
+    popForUndo,
+    setLiveState,
+    findByChangeId,
+    removeWhere,
+    removeByInstanceId,
+    clear,
+    load,
+    reapplyPreviews,
+    resetPreviewApplied,
+    queueFlushNow,
+    refreshSnapshots,
+    applyNow,
+    undoLastBatch,
+    discardSession,
+    detachFile,
+  }
+}
diff --git a/src/shell/composables/useElementClassification.ts b/src/shell/composables/useElementClassification.ts
index 27be26e..410e17c 100644
--- a/src/shell/composables/useElementClassification.ts
+++ b/src/shell/composables/useElementClassification.ts
@@ -1,4 +1,6 @@
-export type ElementRole = 'container' | 'content' | 'component'
+/** 'placement' is assigned by the selection model (never by DOM classification):
+ *  an annotask-mounted wireframe placement selected via its container. */
+export type ElementRole = 'container' | 'content' | 'component' | 'placement'
 
 export interface ElementClassification {
   role: ElementRole
diff --git a/src/shell/composables/useEmbeddedAgent.ts b/src/shell/composables/useEmbeddedAgent.ts
new file mode 100644
index 0000000..0edf025
--- /dev/null
+++ b/src/shell/composables/useEmbeddedAgent.ts
@@ -0,0 +1,978 @@
+/**
+ * Embedded agent runner for the per-task Conversation work-stream.
+ *
+ * One instance per Conversation tab. Drives the active provider, captures
+ * the full work-stream timeline (text + tool calls + tool results), and
+ * persists each assistant turn as a single `ThreadMessage` with a `blocks`
+ * timeline.
+ *
+ * Flow per turn:
+ *   1. Composer calls `send(userText)`.
+ *   2. User message appended to thread (HTTP POST → SSE broadcast → all
+ *      subscribers, including MCP, see it before the provider does).
+ *   3. Provider instantiated via factory.
+ *   4. for-await over `provider.stream(...)`. Each event grows
+ *      `currentBlocks.value` reactively:
+ *        - `text`        → grow the last text block, or push a new one
+ *        - `tool_call`   → push a new tool_call block (summary via toolSummary)
+ *        - `tool_result` → push a new tool_result block (summary + raw)
+ *        - `usage`       → accumulate token totals
+ *   5. On `done`, persist a single ThreadMessage with `content` = text-only
+ *      rollup and `blocks` = the full timeline. Then drain any queued user
+ *      messages — they fire as the next turn.
+ *
+ * Steering policy:
+ *   - User submits while idle → fires `send()` directly.
+ *   - User submits while a turn is running → queued for next turn. The
+ *     composer surfaces this with a muted "queued" strip.
+ *   - User submits while task.status === 'needs_info' → routed through the
+ *     answer-mode path (TaskAgentFeedback). The composable does NOT
+ *     intercept; the Conversation tab handles answer mode by swapping the
+ *     composer.
+ */
+
+import { ref, computed, shallowRef, type Ref, type ShallowRef } from 'vue'
+import { useProviderSettings } from './useProviderSettings'
+import { useAgentConfigs } from './useAgentConfigs'
+import { markRunStarted, markRunFinished } from './useAgentMode'
+import { useTasks } from './useTasks'
+import { makeProvider } from '../../embedded/provider-factory.js'
+import { resolveEffectivePermissionMode } from '../../embedded/permission-mode.js'
+import { permissionModeSystemPromptPrefix, normalizeHeadlessMode, type InitCliBin } from '../../embedded/permission-mode-flags.js'
+import { redactString, redactValue } from '../../embedded/redaction.js'
+import type { ProviderMessage, ProviderEvent, ProviderContentBlock } from '../../embedded/provider.js'
+import type { PermissionMode } from '../../schema'
+import type { WorkStreamBlock } from '../../shared/work-stream'
+import { summarizeToolCall, summarizeToolResult } from '../utils/toolSummary'
+import { fetchMcpToolCatalog } from '../services/mcpClient'
+import type { ThreadMessage, UseTaskThread } from './useTaskThread'
+
+export type RunStatus = 'idle' | 'running' | 'completed' | 'aborted' | 'error'
+
+interface UsageTotals {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+}
+
+export interface UseEmbeddedAgent {
+  status: Ref<RunStatus>
+  /** Live work-stream timeline for the in-flight turn. Empty between turns. */
+  currentBlocks: ShallowRef<WorkStreamBlock[]>
+  /** Cumulative usage across the conversation (informational). */
+  usage: Ref<UsageTotals>
+  /** Most recent error message. */
+  errorMessage: Ref<string | null>
+  /** True iff a turn is currently streaming. */
+  running: Ref<boolean>
+  /** Messages submitted while running, waiting to fire after the current turn. */
+  queuedMessages: Ref<string[]>
+  /**
+   * Send a user message. Fires immediately if idle, else queues for next turn.
+   *
+   * `isSeed: true` flags the turn as the agent's primary "do this task" run
+   * (the prompt is the task description). The composable then apes the
+   * canonical annotask flow on the task: lock-on-start (pending|denied →
+   * in_progress) and flip-to-review with a resolution on clean completion.
+   * Free-form chat turns omit the flag and never touch task.status.
+   */
+  send(userText: string, opts?: { isSeed?: boolean }): Promise<void>
+  /** Remove a queued message by index without firing it. */
+  cancelQueued(index: number): void
+  abort(): void
+}
+
+const SYSTEM_PROMPT_PLACEHOLDER =
+  'You are the embedded chat agent inside Annotask. Help the user iterate on the current task. Be concise.'
+
+/** Providers whose spawn pathway can actually apply file edits today. HTTP
+ *  API providers (anthropic/openai/openrouter/copilot/paperclip) don't have
+ *  a browser-side file-write tool loop yet — seed runs on those providers
+ *  get refused with an actionable error. See Phase 3 of the embedded-first
+ *  refactor plan. */
+const LOCAL_CLI_PROVIDERS = new Set(['claude-local', 'codex-local', 'opencode-local', 'copilot-local'])
+
+function isLocalCliProvider(id: string): boolean {
+  return LOCAL_CLI_PROVIDERS.has(id)
+}
+
+/**
+ * Redact secrets from provider messages before they leave the machine.
+ *
+ * Applied when `redactionEnabled` is true. Catches provider API keys, PEM
+ * private keys, JWTs, bearer tokens, and common env-var secrets — see
+ * `redaction.ts` for the full pattern set.
+ *
+ * Limitation: local CLIs can independently read project files via their
+ * tool loop, so redaction here covers only what the shell explicitly sends
+ * (system prompt, conversation messages). It is defense-in-depth, not airtight.
+ */
+function redactMessages(messages: ProviderMessage[]): ProviderMessage[] {
+  return messages.map((msg) => {
+    if (typeof msg.content === 'string') {
+      return { ...msg, content: redactString(msg.content) }
+    }
+    const blocks: ProviderContentBlock[] = msg.content.map((block) => {
+      if (block.type === 'text') return { ...block, text: redactString(block.text) }
+      if (block.type === 'tool_result') return { ...block, content: redactString(block.content) }
+      // tool_use carries structured `input` (tool arguments) that can contain a
+      // secret the model echoed back; walk it with the recursive redactor.
+      if (block.type === 'tool_use') return { ...block, input: redactValue(block.input) }
+      return block
+    })
+    return { ...msg, content: blocks }
+  })
+}
+
+/**
+ * Compose the seed prompt sent to the local CLI.
+ *
+ * Two things go in: the task id (canonical handle) and the description
+ * (rendered as a blockquote). Everything else — file, line, component, theme,
+ * selected element, screenshot, interaction history, type-specific context —
+ * lives behind `annotask_get_task` and the agent fetches what it needs.
+ *
+ * Why this shape:
+ *   - The id is the only field the agent strictly needs; MCP carries the rest.
+ *   - The description is decorative for the agent (it'll get a richer copy via
+ *     MCP) but **load-bearing for the human** reading the Conversation tab —
+ *     without it, the chat thread is just opaque task IDs.
+ *   - Also serves as a graceful-degrade fallback when MCP isn't configured:
+ *     the agent still has the user's request as plain text.
+ *
+ * The runner handles status transitions (lock-on-start, mark-review-on-clean-
+ * exit), so the agent does NOT need to call `annotask_update_task`.
+ */
+interface SeedFeedbackEntry {
+  questions?: Array<{ id?: string; text?: string }>
+  answers?: Array<{ id?: string; value?: string }>
+  answered_at?: number
+}
+
+/** Render answered needs_info exchanges as an inline Q&A block. The resume
+ *  path (respondToAgent → in_progress → auto-run re-seed) re-runs the WHOLE
+ *  seed; without the answers in the prompt, a no-MCP agent never sees them and
+ *  asks the same question again — an infinite needs_info loop. MCP agents also
+ *  benefit (no extra round-trip). Only ANSWERED exchanges are surfaced. */
+function answeredFeedbackBlock(feedback: SeedFeedbackEntry[] | undefined): string {
+  if (!Array.isArray(feedback)) return ''
+  const lines: string[] = []
+  for (const ex of feedback) {
+    if (!ex || !ex.answered_at || !Array.isArray(ex.questions) || !Array.isArray(ex.answers)) continue
+    const byId = new Map((ex.answers ?? []).map((a) => [a.id, (a.value ?? '').trim()]))
+    for (const q of ex.questions) {
+      const a = byId.get(q.id) ?? ''
+      if (!a) continue
+      lines.push(`> Q: ${(q.text ?? '').trim()}`)
+      lines.push(`> A: ${a}`)
+    }
+  }
+  if (lines.length === 0) return ''
+  return [
+    '',
+    '**Clarifications you previously requested — the user has now answered.** Continue applying the task using these answers; do NOT ask again unless something new is genuinely unresolved.',
+    '',
+    ...lines,
+  ].join('\n')
+}
+
+function buildSeedPrompt(
+  task: { id?: string; status?: string; feedback?: string; resolution?: string; agent_feedback?: SeedFeedbackEntry[] },
+  description: string,
+): string {
+  const id = task.id ?? '<unknown>'
+  const quoted = description
+    .trim()
+    .split('\n')
+    .map(line => `> ${line}`)
+    .join('\n')
+  // Retry context: when the task is being re-run after a deny, surface the
+  // previous attempt's resolution + the user's deny feedback inline so the
+  // agent doesn't need to round-trip through `annotask_get_task` to learn
+  // what was rejected and why. Same shape for plain `description` blocks
+  // (`>` quoted) so the model parses it consistently.
+  const isRetry = task.status === 'denied' && (task.feedback ?? '').trim().length > 0
+  const retryBlock = isRetry
+    ? [
+        '',
+        '**This is a retry.** Your previous attempt was denied by the user.',
+        '',
+        'Previous attempt resolution:',
+        (task.resolution ?? '(no resolution recorded)').trim().split('\n').map(l => `> ${l}`).join('\n'),
+        '',
+        'User feedback on the denial:',
+        (task.feedback ?? '').trim().split('\n').map(l => `> ${l}`).join('\n'),
+        '',
+        'Address the feedback specifically — do not repeat the previous approach unless the feedback explicitly asks for a small tweak on top of it.',
+      ].join('\n')
+    : ''
+  return [
+    `Apply Annotask task \`${id}\`:`,
+    '',
+    quoted,
+    retryBlock,
+    answeredFeedbackBlock(task.agent_feedback),
+    '',
+    `Use \`annotask_get_task\` with this id for full context if you need it.`,
+    `Annotask handles the status transitions for you — exit cleanly when done, or reply with a short explanation if you can't apply the change.`,
+  ].filter(Boolean).join('\n')
+}
+
+/**
+ * Fetch the task-type-aware system prompt from the dev server. Composes the
+ * base `annotask-apply` skill body with the matching task-type companion
+ * (A11Y_RULES.md, THEME_UPDATE.md, etc.) so the embedded runner sees the
+ * same prompt the MCP `initialize.instructions` payload ships to external
+ * editors, plus per-type guidance.
+ *
+ * Falls back to the built-in placeholder when the bundled skills are missing
+ * (older annotask install, dev-mode without skills built) or the endpoint
+ * is unreachable — the run still works, it just lacks the apply playbook.
+ */
+async function fetchSystemPrompt(taskType: string | undefined): Promise<string> {
+  try {
+    const qs = taskType ? `?task_type=${encodeURIComponent(taskType)}` : ''
+    const res = await fetch(`/__annotask/api/system-prompt${qs}`)
+    if (!res.ok) return SYSTEM_PROMPT_PLACEHOLDER
+    const payload = await res.json() as { prompt?: string }
+    const prompt = typeof payload.prompt === 'string' ? payload.prompt.trim() : ''
+    return prompt.length > 0 ? prompt : SYSTEM_PROMPT_PLACEHOLDER
+  } catch {
+    return SYSTEM_PROMPT_PLACEHOLDER
+  }
+}
+
+/**
+ * Task ids this tab currently holds an `in_progress` lock for via a live seed
+ * run. If the tab is closed mid-run, the run's normal finalization never gets
+ * to execute — so on `pagehide` we relinquish each lock back to `pending` with
+ * a keepalive PATCH. That reconciles the task *before* the server's
+ * orphan-finalizer has to guess, so a closed tab leaves a retryable `pending`
+ * task instead of a stranded one (and never the misleading "tab was likely
+ * closed" blocked state). Module-scoped so the single listener covers both the
+ * headless auto-run driver and any open Conversation tab.
+ */
+const lockedSeedTasks = new Set<string>()
+let pagehideArmed = false
+function armPagehideFlush(): void {
+  if (pagehideArmed || typeof window === 'undefined') return
+  pagehideArmed = true
+  window.addEventListener('pagehide', () => {
+    for (const id of lockedSeedTasks) {
+      try {
+        // keepalive lets the request outlive the unloading document.
+        void fetch(`/__annotask/api/tasks/${encodeURIComponent(id)}`, {
+          method: 'PATCH',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ status: 'pending' }),
+          keepalive: true,
+        }).catch(() => { /* best-effort */ })
+      } catch { /* ignore */ }
+    }
+  })
+}
+
+export function useEmbeddedAgent(thread: UseTaskThread): UseEmbeddedAgent {
+  const providerSettings = useProviderSettings()
+  const agentConfigs = useAgentConfigs()
+  const status = ref<RunStatus>('idle')
+  const currentBlocks = shallowRef<WorkStreamBlock[]>([])
+  const errorMessage = ref<string | null>(null)
+  const usage = ref<UsageTotals>({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0 })
+  const queuedMessages = ref<string[]>([])
+
+  const running = computed(() => status.value === 'running')
+
+  let aborter: AbortController | null = null
+  let currentProvider: import('../../embedded/provider.js').LLMProvider | null = null
+
+  function reset() {
+    currentBlocks.value = []
+    errorMessage.value = null
+    // `usage` is the live accumulator for the CURRENT (not-yet-persisted) turn
+    // only — each completed turn's tokens land on its persisted ThreadMessage
+    // (via flushPartial's final write), and the header sums those. Resetting
+    // here keeps `agent.usage` from carrying prior turns' tokens forward, which
+    // would otherwise be double-counted on top of the persisted-message sum.
+    usage.value = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+  }
+
+  /**
+   * Grow the last `text` block, or push a new one. Tool calls and results
+   * break the run; any text that arrives after a tool starts a fresh block
+   * so the UI renders the natural sequence.
+   */
+  function pushText(delta: string): void {
+    const list = currentBlocks.value
+    const last = list[list.length - 1]
+    if (last && last.kind === 'text') {
+      const updated: WorkStreamBlock = { kind: 'text', text: last.text + delta }
+      currentBlocks.value = [...list.slice(0, -1), updated]
+      return
+    }
+    currentBlocks.value = [...list, { kind: 'text', text: delta }]
+  }
+
+  function pushToolCall(id: string, name: string, input: unknown): void {
+    currentBlocks.value = [
+      ...currentBlocks.value,
+      { kind: 'tool_call', id, name, input, summary: summarizeToolCall(name, input) },
+    ]
+  }
+
+  function pushToolResult(toolUseId: string, content: string, isError?: boolean): void {
+    currentBlocks.value = [
+      ...currentBlocks.value,
+      {
+        kind: 'tool_result',
+        toolUseId,
+        summary: summarizeToolResult(content, isError),
+        raw: content,
+        isError,
+      },
+    ]
+  }
+
+  function applyEvent(ev: ProviderEvent): void {
+    switch (ev.type) {
+      case 'text':
+        pushText(ev.text)
+        return
+      case 'tool_call':
+        pushToolCall(ev.id, ev.name, ev.input)
+        return
+      case 'tool_result':
+        pushToolResult(ev.toolUseId, ev.content, ev.isError)
+        return
+      case 'usage':
+        usage.value = {
+          input: usage.value.input + ev.inputTokens,
+          output: usage.value.output + ev.outputTokens,
+          cacheRead: usage.value.cacheRead + (ev.cacheReadTokens ?? 0),
+          cacheWrite: usage.value.cacheWrite + (ev.cacheCreationTokens ?? 0),
+        }
+        return
+      // done + error are handled in send() so they affect status/control flow.
+      default:
+        return
+    }
+  }
+
+  /**
+   * Flatten the blocks into a single text rollup for the legacy `content`
+   * field. Tool blocks are summarized inline so MCP tail-readers still see
+   * something coherent ("[Tool] Reading App.vue:42-89") even without the
+   * rich block surface.
+   */
+  function rollupText(blocks: WorkStreamBlock[]): string {
+    const parts: string[] = []
+    for (const b of blocks) {
+      if (b.kind === 'text') parts.push(b.text)
+      else if (b.kind === 'tool_call') parts.push(`[Tool] ${b.summary}`)
+      else if (b.kind === 'tool_result') parts.push(`[Result] ${b.summary}`)
+    }
+    return parts.join('\n').trim()
+  }
+
+  async function runOne(userText: string, isSeed = false): Promise<void> {
+    reset()
+    status.value = 'running'
+    // Broadcast "this task has an active run" so TaskCard can pulse its
+    // dot. Independent of the task's persisted `status` field — the agent
+    // doesn't always call annotask_update_task to flip status, especially
+    // in chat-only flows.
+    const taskId = thread.taskId.value
+    if (taskId) markRunStarted(taskId)
+
+    // Resolve persona + provider up front so we can gate HTTP-only providers
+    // out of the apply path. Personas bundle provider + model + effort +
+    // system-prompt extras; the fallback uses the global `activeProvider`
+    // settings so legacy behavior holds when no persona matches.
+    const currentTask = taskId ? useTasks().tasks.value.find((t) => t.id === taskId) : undefined
+    const taskType = currentTask && typeof currentTask.type === 'string' ? currentTask.type : undefined
+    const persona = isSeed ? providerSettings.getPersonaForTaskType(taskType) : null
+
+    const activeProviderId = persona?.providerId ?? providerSettings.activeProvider.value
+    const activeCfg = providerSettings.settings.value.providers[activeProviderId]
+    const activeModel = (persona && persona.model.length > 0 ? persona.model : activeCfg.model) ?? ''
+    const activeEffort = persona && persona.effort !== 'auto' ? persona.effort : activeCfg.effort
+
+    // Phase 3 v1: only local CLIs can apply tasks (they have native file-edit
+    // tools and the spawn `cwd` lands them in the project root). HTTP-only
+    // providers have no file-write path yet, so refuse the seed run and tell
+    // the user how to fix it.
+    if (isSeed && !isLocalCliProvider(activeProviderId)) {
+      status.value = 'error'
+      errorMessage.value = `${activeProviderId} can't apply tasks yet — pick a persona that uses a local CLI (claude-local, codex-local, opencode-local, copilot-local) in Settings → Agents.`
+      if (taskId) markRunFinished(taskId)
+      return
+    }
+
+    // Seed runs ape the canonical annotask lifecycle: lock the task on
+    // start (pending|denied → in_progress) and flip to review on clean
+    // completion. Free-form chat turns (isSeed = false) leave status alone.
+    if (isSeed && taskId) {
+      await lockTaskOnStart(taskId)
+    }
+
+    // Enrich the seed prompt with task grounding so the CLI has file/line
+    // anchors without having to round-trip through MCP. Free-form chat is
+    // sent verbatim.
+    const promptToSend = isSeed && currentTask ? buildSeedPrompt(currentTask, userText) : userText
+
+    try {
+      await thread.append({ role: 'user', content: promptToSend })
+    } catch (err) {
+      status.value = 'error'
+      errorMessage.value = `Failed to record user message: ${(err as Error).message}`
+      // The seed lock was already taken above — release it (and clear the
+      // live-run indicator) or the task is stuck in_progress forever.
+      await finalizeErrorExit(taskId, isSeed)
+      return
+    }
+
+    const history = toProviderMessages(thread.messages.value)
+
+    // Pre-warm the MCP tool catalog so the first tool-using turn (Phase 3+)
+    // doesn't pay an extra round-trip. Errors are non-fatal — the catalog
+    // fetch is best-effort.
+    fetchMcpToolCatalog().catch(() => {})
+
+    const baseSystemPrompt = await fetchSystemPrompt(taskType)
+    // Compose persona system-prompt layers in order:
+    //   skill+companion  →  projectDirections (the single per-agent blob)
+    //   →  systemPromptExtras (custom persona overrides)
+    // projectDirections is the only instruction set the user sees and edits;
+    // it's written by the init CLI from `BUILT_IN_PERSONAS[].roleDirections`
+    // (used as a reference template, not a runtime layer). roleDirections is
+    // kept here as a safety-net fallback for the rare case projectDirections
+    // is empty (e.g. before init has ever run).
+    const personaRole = persona?.roleDirections?.trim() ?? ''
+    const projectDirections = persona
+      ? (agentConfigs.configs.value[persona.id]?.projectDirections ?? '').trim()
+      : ''
+    const personaExtras = persona?.systemPromptExtras?.trim() ?? ''
+    const layers = [baseSystemPrompt]
+    if (projectDirections.length > 0) layers.push(projectDirections)
+    else if (personaRole.length > 0) layers.push(personaRole)
+    if (personaExtras.length > 0) layers.push(personaExtras)
+    const systemPrompt = layers.join('\n\n---\n\n')
+
+    let provider: import('../../embedded/provider.js').LLMProvider
+    try {
+      // If a persona is active and selects a different provider than the
+      // global active one, fork the settings so makeProvider keys off the
+      // persona's choice without mutating the user's persisted activeProvider.
+      const settingsForCall = persona && persona.providerId !== providerSettings.settings.value.activeProvider
+        ? { ...providerSettings.settings.value, activeProvider: persona.providerId }
+        : providerSettings.settings.value
+      provider = makeProvider(settingsForCall, {
+        referer: typeof window !== 'undefined' ? window.location.origin : undefined,
+        appTitle: 'Annotask',
+      })
+      currentProvider = provider
+    } catch (err) {
+      status.value = 'error'
+      errorMessage.value = (err as Error).message
+      // Same stuck-task hazard as the append failure above: a seed run
+      // already locked the task, so a missing-API-key (or any factory)
+      // error must still unwind the lock + live-run indicator.
+      await finalizeErrorExit(taskId, isSeed)
+      return
+    }
+
+    aborter = new AbortController()
+    let stopReason: string | undefined
+
+    // Resolve the effective permission mode (task ?? provider ?? global).
+    // Local-CLI providers translate the mode to their own permission flag at
+    // spawn time. HTTP/API providers currently ignore it (no client-side
+    // write tools wired).
+    const taskPermissionMode = currentTask?.permissionMode
+    const providerPermissionMode = (activeCfg as { permissionMode?: PermissionMode }).permissionMode
+    const resolvedPermissionMode = resolveEffectivePermissionMode(
+      taskPermissionMode,
+      providerPermissionMode,
+      providerSettings.settings.value.permissionMode,
+    )
+    // Local CLIs run headless, so `'default'` ("Auto") escalates to the
+    // per-CLI working mode: bypass on claude/opencode (no headless ask-mode),
+    // while codex/copilot keep their safer sandboxed/minimal `default`. HTTP
+    // providers ignore permission mode entirely.
+    const cliBin: InitCliBin | null = activeProviderId.endsWith('-local')
+      ? (activeProviderId.slice(0, -'-local'.length) as InitCliBin)
+      : null
+    const effectivePermissionMode = cliBin
+      ? normalizeHeadlessMode(resolvedPermissionMode, cliBin)
+      : resolvedPermissionMode
+
+    // Plan mode needs model-level enforcement on opencode/copilot (no native
+    // read-only flag in their headless modes). Prepend a strong directive so
+    // the model refuses write tools on its own. Claude/codex still get
+    // CLI/sandbox enforcement on top via `permissionMode` below.
+    const permissionPrefix = permissionModeSystemPromptPrefix(effectivePermissionMode)
+    const systemPromptWithPermission = permissionPrefix
+      ? `${permissionPrefix}\n\n---\n\n${systemPrompt}`
+      : systemPrompt
+
+    // Redact secrets from outgoing messages/prompt when enabled.
+    const redact = providerSettings.settings.value.redactionEnabled
+    const outHistory = redact ? redactMessages(history) : history
+    const outSystemPrompt = redact ? redactString(systemPromptWithPermission) : systemPromptWithPermission
+
+    const logEnabled = providerSettings.settings.value.eventLogEnabled
+    const { eventLog } = providerSettings
+    const conversationId = taskId ?? 'chat'
+    const turnStartTime = Date.now()
+
+    // Stream the turn as a single *partial* assistant message: append it now
+    // (empty) and patch it in place as events arrive. This is the only channel
+    // by which an observer that isn't this exact instance — a Conversation tab
+    // that attached mid-run, an external MCP tail-reader, the running-timer in
+    // another tab — sees live progress. `currentBlocks` (below) stays the
+    // smooth local surface for the tab that owns the run.
+    let partialId: string | null = null
+    try {
+      const seed = await thread.append({
+        role: 'assistant',
+        content: '',
+        providerId: activeProviderId,
+        model: activeModel,
+        isPartial: true,
+        lastEventAt: turnStartTime,
+      })
+      partialId = seed.id
+    } catch {
+      // Non-fatal: fall back to the single post-turn write (still works, just
+      // not streamed). partialId stays null and the final persist re-appends.
+    }
+
+    // Throttled flush of the live blocks into the partial message (~300ms).
+    let lastEventAt = turnStartTime
+    let lastFlushedBlocks: WorkStreamBlock[] | null = null
+    let flushing = false
+    async function flushPartial(final: boolean): Promise<void> {
+      if (!partialId) return
+      if (flushing && !final) return
+      const blocks = currentBlocks.value
+      if (!final && blocks === lastFlushedBlocks) return // nothing new since last flush
+      flushing = true
+      lastFlushedBlocks = blocks
+      try {
+        await thread.update(partialId, {
+          content: rollupText(blocks),
+          blocks,
+          lastEventAt,
+          ...(final
+            ? {
+                isPartial: false,
+                usage: {
+                  inputTokens: usage.value.input,
+                  outputTokens: usage.value.output,
+                  cacheReadTokens: usage.value.cacheRead,
+                  cacheCreationTokens: usage.value.cacheWrite,
+                },
+              }
+            : {}),
+        })
+      } catch {
+        // Best-effort mid-stream; the final flush re-tries and its error
+        // (if any) surfaces below.
+      } finally {
+        flushing = false
+      }
+    }
+    const flushTimer = partialId ? setInterval(() => { void flushPartial(false) }, 300) : null
+
+    // Stall watchdog. `idleTimeoutMs` aborts a run that stops producing output;
+    // `maxRunDurationMs` is an absolute ceiling. Either triggers `aborter.abort()`
+    // and records a reason so the post-loop block can explain + unblock the queue.
+    // `0` disables that timer.
+    const idleMs = providerSettings.settings.value.idleTimeoutMs
+    const maxMs = providerSettings.settings.value.maxRunDurationMs
+    let watchdogReason: 'idle-timeout' | 'max-duration' | null = null
+    const idleTimer = idleMs > 0
+      ? setInterval(() => {
+          if (Date.now() - lastEventAt > idleMs) {
+            watchdogReason = watchdogReason ?? 'idle-timeout'
+            aborter?.abort()
+          }
+        }, Math.max(1000, Math.min(idleMs, 15_000)))
+      : null
+    const maxTimer = maxMs > 0
+      ? setTimeout(() => {
+          watchdogReason = watchdogReason ?? 'max-duration'
+          aborter?.abort()
+        }, maxMs)
+      : null
+    function clearWatchdog(): void {
+      if (flushTimer) clearInterval(flushTimer)
+      if (idleTimer) clearInterval(idleTimer)
+      if (maxTimer) clearTimeout(maxTimer)
+    }
+
+    try {
+      for await (const ev of provider.stream(outHistory, [], {
+        systemPrompt: outSystemPrompt,
+        signal: aborter.signal,
+        model: activeModel || undefined,
+        effort: activeEffort,
+        permissionMode: effectivePermissionMode,
+        // Lets the server key its run registry by task: one live run per task
+        // (no cross-tab double-spawn) + orphaned-task finalization.
+        taskId: taskId ?? undefined,
+      })) {
+        lastEventAt = Date.now()
+        applyEvent(ev)
+        if (ev.type === 'tool_call' && logEnabled) {
+          eventLog.appendToolCall({
+            conversationId,
+            provider: activeProviderId,
+            model: activeModel || 'default',
+            toolName: ev.name,
+            toolUseId: ev.id,
+            input: ev.input,
+          })
+        } else if (ev.type === 'error') {
+          errorMessage.value = ev.error
+          stopReason = stopReason ?? 'error'
+          if (logEnabled) {
+            eventLog.append({
+              kind: 'error',
+              conversationId,
+              provider: activeProviderId,
+              model: activeModel || 'default',
+              reason: 'provider_error',
+              detail: ev.error,
+            })
+          }
+        } else if (ev.type === 'done') {
+          if (!stopReason) stopReason = ev.stopReason
+        }
+      }
+    } catch (err) {
+      stopReason = stopReason ?? 'error'
+      errorMessage.value = errorMessage.value ?? (err as Error).message
+    } finally {
+      clearWatchdog()
+    }
+
+    // A watchdog abort masquerades as a generic abort to the stream; promote
+    // it to its own stop reason and a human-readable message so observers
+    // understand the run was killed for inactivity / duration, not by the user.
+    if (watchdogReason) {
+      stopReason = 'aborted'
+      const idleSecs = Math.round(idleMs / 1000)
+      const maxMins = Math.round(maxMs / 60_000)
+      errorMessage.value = watchdogReason === 'idle-timeout'
+        ? `Run cancelled: no output for ${idleSecs}s.`
+        : `Run cancelled: exceeded the ${maxMins}-minute limit.`
+    }
+
+    // Log the completed turn to the local event log.
+    if (logEnabled) {
+      eventLog.append({
+        kind: 'turn',
+        conversationId,
+        provider: activeProviderId,
+        model: activeModel || 'default',
+        inputTokens: usage.value.input,
+        outputTokens: usage.value.output,
+        cacheReadTokens: usage.value.cacheRead || undefined,
+        cacheCreationTokens: usage.value.cacheWrite || undefined,
+        latencyMs: Date.now() - turnStartTime,
+        stopReason: stopReason ?? 'end_turn',
+      })
+    }
+
+    // Persist the turn. With a partial message in flight we flush it one last
+    // time (clears `isPartial`, attaches final usage). Without one (the seed
+    // append failed earlier) we fall back to the legacy single append. The
+    // block timeline is the rich surface; `content` is a flat text rollup so
+    // MCP / CLI tail-readers still see meaningful output without parsing blocks.
+    const blocks = currentBlocks.value
+    if (partialId) {
+      await flushPartial(true)
+    } else if (blocks.length > 0) {
+      try {
+        await thread.append({
+          role: 'assistant',
+          content: rollupText(blocks),
+          providerId: activeProviderId,
+          model: activeModel,
+          usage: {
+            inputTokens: usage.value.input,
+            outputTokens: usage.value.output,
+            cacheReadTokens: usage.value.cacheRead,
+            cacheCreationTokens: usage.value.cacheWrite,
+          },
+          blocks,
+        })
+      } catch (err) {
+        errorMessage.value = errorMessage.value ?? `Failed to record assistant turn: ${(err as Error).message}`
+      }
+    }
+
+    // The turn's tokens now live on its persisted ThreadMessage. Zero the live
+    // accumulator so the header's `tokenSummary` (persisted-message sum + live
+    // accumulator) doesn't count this turn twice in the idle gap before the
+    // next turn's `reset()` clears it.
+    usage.value = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+
+    // Surface a watchdog stall or a failed seed run as a system message so
+    // it's part of the persisted transcript (visible to every observer +
+    // MCP tail-readers) — the error strip is local to this tab.
+    const seedRunFailed = isSeed && !!taskId && !watchdogReason && stopReason === 'error'
+    if ((watchdogReason || seedRunFailed) && errorMessage.value) {
+      try {
+        await thread.append({ role: 'system', content: errorMessage.value })
+      } catch { /* best-effort */ }
+    }
+
+    const finalBlocks = blocks
+    currentBlocks.value = []
+    aborter = null
+    currentProvider = null
+    // Cross-tab dedup: the spawn was refused because another tab already owns a
+    // live run for this task. This run never started — DON'T touch the task's
+    // status (the winning tab is mid-write; reverting/reviewing it would corrupt
+    // that run). Surface a gentle note and bail before any transition.
+    const ownedByAnotherTab = stopReason === 'already_running'
+    if (ownedByAnotherTab) {
+      status.value = 'idle'
+      errorMessage.value = 'This task is already being applied in another tab or session.'
+      // Cleanup only; the caller (send) drains any queued chat turns on return.
+      if (taskId) { lockedSeedTasks.delete(taskId); markRunFinished(taskId) }
+      return
+    }
+    status.value =
+      stopReason === 'aborted' ? 'aborted'
+      : stopReason === 'error' ? 'error'
+      : 'completed'
+
+    if (isSeed && taskId && watchdogReason) {
+      // A stalled/timed-out seed run lands the task in `blocked` (not `pending`)
+      // so the auto-run driver won't immediately re-queue it into the same
+      // stall — a human reviews the reason and retries deliberately.
+      await markTaskBlocked(taskId, errorMessage.value ?? 'Run cancelled by the stall watchdog.')
+    } else if (isSeed && taskId && status.value === 'completed') {
+      await markTaskForReview(taskId, finalBlocks)
+    } else if (isSeed && taskId && (status.value === 'error' || status.value === 'aborted')) {
+      // A seed run that errored out (provider stream threw, CLI exited
+      // non-zero, spawn failed mid-flight) OR was deliberately aborted (the
+      // Stop button / requestAutoRunCancel — which ends the stream as
+      // 'aborted' with no watchdogReason) must release its lock back to
+      // `pending` or the task is stranded in_progress with no agent attached.
+      // Finalizing here is what keeps the server's orphan-finalizer from
+      // firing 12s later and mislabeling the run "the tab was likely closed".
+      await revertTaskToPending(taskId)
+    }
+
+    if (taskId) { lockedSeedTasks.delete(taskId); markRunFinished(taskId) }
+  }
+
+  /**
+   * Lock the task at the start of a seed run. The annotask lifecycle requires
+   * `pending → in_progress` (or `denied → in_progress` on retry) before
+   * `→ review` is allowed at completion. Anything else (review/accepted/
+   * needs_info/blocked/in_progress) we leave alone — the agent is iterating,
+   * resuming, or the user already has a pending action.
+   */
+  async function lockTaskOnStart(taskId: string): Promise<void> {
+    try {
+      const taskSystem = useTasks()
+      const current = taskSystem.tasks.value.find((t) => t.id === taskId)
+      if (!current) return
+      if (current.status !== 'pending' && current.status !== 'denied') return
+      await taskSystem.updateTaskStatus(taskId, 'in_progress')
+      // Track the held lock so a pagehide (tab close) can relinquish it.
+      lockedSeedTasks.add(taskId)
+      armPagehideFlush()
+    } catch (err) {
+      // Surface in the conversation error strip, don't abort the run — the
+      // agent should still try to do useful work even if the lock fails.
+      errorMessage.value = `Couldn't lock task: ${(err as Error).message}`
+    }
+  }
+
+  /**
+   * On clean seed-run completion, flip the task to `review` with the agent's
+   * final text block as the resolution. Skips if the task drifted to another
+   * status mid-run (e.g. the agent paused via `needs_info`) — those
+   * transitions aren't valid from `in_progress → review` and the server
+   * would reject them anyway.
+   */
+  async function markTaskForReview(taskId: string, blocks: WorkStreamBlock[]): Promise<void> {
+    try {
+      const taskSystem = useTasks()
+      const current = taskSystem.tasks.value.find((t) => t.id === taskId)
+      if (!current || current.status !== 'in_progress') return
+      const resolution = extractResolution(blocks)
+      await taskSystem.updateTaskStatus(taskId, 'review', undefined, { resolution })
+    } catch (err) {
+      errorMessage.value = `Couldn't mark task for review: ${(err as Error).message}`
+    }
+  }
+
+  /**
+   * Flip a seed run's task to `blocked` after the stall watchdog killed it.
+   * `blocked` is terminal for the auto-run queue (not re-drained), so a task
+   * that consistently stalls can't loop. Only transitions from `in_progress`
+   * (the lock the seed run took) — anything else the agent moved deliberately.
+   */
+  async function markTaskBlocked(taskId: string, reason: string): Promise<void> {
+    try {
+      const taskSystem = useTasks()
+      const current = taskSystem.tasks.value.find((t) => t.id === taskId)
+      if (!current || current.status !== 'in_progress') return
+      await taskSystem.updateTaskStatus(taskId, 'blocked', undefined, { blocked_reason: reason })
+    } catch (err) {
+      errorMessage.value = `Couldn't mark task blocked: ${(err as Error).message}`
+    }
+  }
+
+  /**
+   * Release a failed seed run's lock. The seed run took `pending|denied →
+   * in_progress` at start; when the run errors out instead of completing,
+   * the lock must come off (`in_progress → pending`) or the task is stranded
+   * — locked against the auto-run queue and showing a phantom "agent
+   * working" status forever. Unlike a watchdog stall (→ `blocked`, terminal
+   * for the queue), a plain error is usually transient (provider misconfig,
+   * spawn failure), so `pending` keeps the task retryable. Only transitions
+   * from `in_progress` (the lock this run took) — anything else the agent
+   * or user moved deliberately.
+   */
+  async function revertTaskToPending(taskId: string): Promise<void> {
+    try {
+      const taskSystem = useTasks()
+      const current = taskSystem.tasks.value.find((t) => t.id === taskId)
+      if (!current || current.status !== 'in_progress') return
+      await taskSystem.updateTaskStatus(taskId, 'pending')
+    } catch (err) {
+      errorMessage.value = `Couldn't revert task to pending: ${(err as Error).message}`
+    }
+  }
+
+  /**
+   * Shared cleanup for runs that die before reaching the end-of-stream
+   * finalization (provider construction failed, user-message append failed).
+   * Mirrors the watchdog path's pattern: persist the failure as a system
+   * message so every observer (other tabs, MCP tail-readers) sees why the
+   * run ended, release a seed run's task lock, and clear the live-run
+   * indicator. Chat turns (isSeed=false) only clear the indicator — they
+   * never touched task.status.
+   */
+  async function finalizeErrorExit(taskId: string | null, isSeed: boolean): Promise<void> {
+    if (!taskId) return
+    lockedSeedTasks.delete(taskId)
+    if (isSeed) {
+      if (errorMessage.value) {
+        try {
+          await thread.append({ role: 'system', content: errorMessage.value })
+        } catch { /* best-effort — the thread itself may be what failed */ }
+      }
+      await revertTaskToPending(taskId)
+    }
+    markRunFinished(taskId)
+  }
+
+  /**
+   * Pick the resolution string for the `review` transition: prefer the last
+   * `text` block (the agent's natural sign-off), fall back to a synthesized
+   * one-liner from the tool summaries when the agent only worked silently.
+   */
+  function extractResolution(blocks: WorkStreamBlock[]): string {
+    for (let i = blocks.length - 1; i >= 0; i--) {
+      const b = blocks[i]
+      if (b.kind === 'text') {
+        const t = b.text.trim()
+        if (t.length > 0) return t
+      }
+    }
+    // No text block — synthesize from tool calls so the resolution field
+    // isn't blank.
+    const summaries: string[] = []
+    for (const b of blocks) {
+      if (b.kind === 'tool_call') summaries.push(b.summary)
+    }
+    if (summaries.length === 0) return 'Done.'
+    if (summaries.length <= 3) return summaries.join('; ')
+    return `${summaries.slice(0, 3).join('; ')}; +${summaries.length - 3} more`
+  }
+
+  /**
+   * Public entry point. If idle, fires the turn directly. If a turn is
+   * running, the message is queued and fires after the current turn ends.
+   * Once `runOne()` returns, drain the queue so chained messages fire one
+   * after the other.
+   *
+   * `opts.isSeed` distinguishes the seed run (prompt = task description)
+   * from free-form chat. Only seed runs touch task.status. Queued messages
+   * are always free-form turns — the seed always fires immediately or not
+   * at all (the auto-run driver enforces concurrency at the driver layer).
+   */
+  async function send(userText: string, opts: { isSeed?: boolean } = {}): Promise<void> {
+    const trimmed = userText.trim()
+    if (!trimmed) return
+
+    if (status.value === 'running') {
+      queuedMessages.value = [...queuedMessages.value, trimmed]
+      return
+    }
+
+    await runOne(trimmed, opts.isSeed === true)
+
+    // Drain the queue. Queued items are free-form (no isSeed) — they
+    // shouldn't bounce the task through status transitions.
+    while (queuedMessages.value.length > 0 && status.value !== 'error') {
+      const [next, ...rest] = queuedMessages.value
+      queuedMessages.value = rest
+      await runOne(next, false)
+    }
+  }
+
+  function cancelQueued(index: number): void {
+    if (index < 0 || index >= queuedMessages.value.length) return
+    queuedMessages.value = [
+      ...queuedMessages.value.slice(0, index),
+      ...queuedMessages.value.slice(index + 1),
+    ]
+  }
+
+  function abort(): void {
+    if (aborter) aborter.abort()
+    // Kill the CLI subprocess server-side so it doesn't linger after the
+    // browser-side fetch is aborted. Falls back to req.on('close') if the
+    // explicit DELETE doesn't reach the server in time.
+    currentProvider?.abortRun?.()
+  }
+
+  return {
+    status,
+    currentBlocks,
+    usage,
+    errorMessage,
+    running,
+    queuedMessages,
+    send,
+    cancelQueued,
+    abort,
+  }
+}
+
+/**
+ * Flatten the persisted thread into the provider-agnostic shape `LLMProvider`
+ * expects. System messages are dropped — the system prompt is handed in via
+ * `StreamOptions.systemPrompt` instead. Tool messages are excluded since
+ * each provider's tool loop runs in its own sandbox.
+ */
+function toProviderMessages(messages: ThreadMessage[]): ProviderMessage[] {
+  const out: ProviderMessage[] = []
+  for (const m of messages) {
+    if (m.role === 'system') continue
+    if (m.role === 'tool') continue
+    out.push({ role: m.role, content: m.content })
+  }
+  return out
+}
diff --git a/src/shell/composables/useErrorMonitor.ts b/src/shell/composables/useErrorMonitor.ts
index dbddd64..23011f9 100644
--- a/src/shell/composables/useErrorMonitor.ts
+++ b/src/shell/composables/useErrorMonitor.ts
@@ -18,6 +18,35 @@ export interface ErrorEntry {
   lastSeen: number
 }
 
+/**
+ * Normalize a stack-derived file reference to a repo-relative path.
+ *
+ * Stack frames inside the iframe reference dev-server URLs
+ * ("http://localhost:5173/src/App.vue"), Vite /@fs/ absolute imports, and
+ * cache-busted modules ("src/App.vue?t=169..."). The server's SafeSourceFile
+ * schema rejects URL-style paths and colons outright, so passing these
+ * through verbatim turned every error_fix POST into a 400 that the old
+ * createTask silently swallowed. Returns '' when the reference can't be
+ * made repo-relative — the task is still creatable without a source anchor.
+ */
+export function normalizeStackFile(raw: string): string {
+  if (!raw) return ''
+  // Dev-server URL → path portion ("http://localhost:5173/src/App.vue" →
+  // "src/App.vue"). Host may be empty (webpack-internal:///...).
+  let f = raw.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*\//i, '')
+  // Cache-buster / HMR query strings and fragments ("?t=169...", "?import").
+  f = f.replace(/[?#].*$/, '')
+  // Vite /@fs/ imports point at absolute filesystem paths. The shell can't
+  // map those back under the repo root, so drop the anchor entirely.
+  if (/^\/?@fs\//.test(f)) return ''
+  // Leading "./" and "/" — server paths are repo-relative.
+  f = f.replace(/^(\.\/)+/, '').replace(/^\/+/, '')
+  // Anything still scheme- or URL-shaped ("node:internal/...", "data:...")
+  // would 400 against SafeSourceFile — better no anchor than a failed task.
+  if (f.includes(':') || f.includes('//')) return ''
+  return f
+}
+
 export function useErrorMonitor(
   iframe: IframeManager,
   taskSystem: TaskSystem,
@@ -145,15 +174,19 @@ export function useErrorMonitor(
       const match = entry.stack.match(/(?:at\s+(\w+)\s+\()?([^\s()]+\.\w+):(\d+)/)
       if (match) {
         component = match[1] || ''
-        file = match[2] || ''
-        line = parseInt(match[3], 10) || 0
+        // Stack frames carry dev-server URLs, not repo paths — normalize or
+        // drop the anchor so the POST passes SafeSourceFile validation.
+        file = normalizeStackFile(match[2] || '')
+        line = file ? parseInt(match[3], 10) || 0 : 0
       }
     }
 
     const colorScheme = await iframe.getColorScheme()
     const frag = componentContextCapture.fromSource(component, file, line)
 
-    taskSystem.createTask({
+    // Return the result so callers can distinguish success from a rejected
+    // POST (createTask now reports failures via useTasks().lastError).
+    return taskSystem.createTask({
       type: 'error_fix',
       description: title,
       file,
diff --git a/src/shell/composables/useIframeManager.ts b/src/shell/composables/useIframeManager.ts
index 3e6a47d..d8cd8a5 100644
--- a/src/shell/composables/useIframeManager.ts
+++ b/src/shell/composables/useIframeManager.ts
@@ -6,12 +6,13 @@ import type {
   ClassSetResult, ElementClassificationData,
   LayoutContainerData, LayoutAddTrackResult, LayoutAddChildResult,
   CheckSourceMappingResult, ColorSwatch, ColorSchemeResult,
-  InsertPlaceholderResult, InsertVueComponentResult,
+  InsertPlaceholderResult, InsertVueComponentResult, PreviewComponentResult,
   InteractionMode, PerfScanResult, PerfRecording,
   ResolveComponentChainResult,
   ResolveBySelectorsResult, ResolveBySelectorsMatch,
   ComputeAccessibilityInfoResult, AccessibilityInfo,
   ComputeTabOrderResult, TabOrderEntry,
+  WireframeCapturePayload, WireframeCaptureResult,
 } from '../../shared/bridge-types'
 import type { DesignSpecThemeSelector } from '../../schema'
 
@@ -217,6 +218,21 @@ export function useIframeManager(iframeRef: Ref<HTMLIFrameElement | null>) {
     } catch { return eids.map(() => null) }
   }
 
+  /**
+   * Re-measure the per-line rects for a text selection by locating the
+   * substring inside the anchor element's text nodes. Used to refresh
+   * highlight overlays after text reflow (window/container resize), where
+   * delta translation can't track line-break shifts.
+   */
+  async function getTextRangeRects(eid: string, text: string): Promise<BridgeRect[] | null> {
+    if (!eid || !text) return null
+    try {
+      const result = await bridge.request<{ rects: BridgeRect[] } | null>('resolve:text-rects', { eid, text })
+      if (!result || !result.rects || !result.rects.length) return null
+      return result.rects.map(r => toShellRect(r) || r)
+    } catch { return null }
+  }
+
   /**
    * Ask the iframe for every element whose `data-annotask-file` matches one of
    * the supplied files. Drives the Data view's "where does this render" overlay.
@@ -452,7 +468,7 @@ export function useIframeManager(iframeRef: Ref<HTMLIFrameElement | null>) {
 
   async function insertPlaceholder(
     targetEid: string, position: string, tag: string,
-    opts?: { classes?: string; textContent?: string; category?: string; library?: string; defaultProps?: Record<string, unknown> }
+    opts?: { classes?: string; textContent?: string; category?: string; library?: string; defaultProps?: Record<string, unknown>; instanceId?: string }
   ): Promise<string> {
     try {
       const result = await bridge.request<InsertPlaceholderResult>('insert:placeholder', {
@@ -466,23 +482,33 @@ export function useIframeManager(iframeRef: Ref<HTMLIFrameElement | null>) {
     try { await bridge.request('insert:remove', { eid }) } catch {}
   }
 
-  async function moveElement(eid: string, targetEid: string, position: string): Promise<void> {
-    try { await bridge.request('move:element', { eid, targetEid, position }) } catch {}
-  }
-
   async function insertComponent(
-    targetEid: string, position: string, componentName: string, props?: Record<string, unknown>
+    targetEid: string, position: string, componentName: string, props?: Record<string, unknown>, module?: string, instanceId?: string
   ): Promise<InsertVueComponentResult> {
     try {
       return await bridge.request<InsertVueComponentResult>('insert:component', {
-        targetEid, position, componentName, props
+        targetEid, position, componentName, props, module, instanceId
       })
-    } catch { return { eid: '', mounted: false } }
+    } catch { return { eid: '', mounted: false, reason: 'no-runtime', fidelity: 'placeholder' } }
   }
 
   /** @deprecated Use insertComponent */
   const insertVueComponent = insertComponent
 
+  /** Render a component offscreen in the iframe and return a PNG snapshot +
+   *  honest fidelity. Used by the Components detail preview + drag thumbnail. */
+  async function previewComponent(
+    componentName: string, props?: Record<string, unknown>, module?: string, width?: number,
+    opts?: { repeat?: number; instanceProps?: Record<string, unknown>[] },
+  ): Promise<PreviewComponentResult> {
+    try {
+      return await bridge.request<PreviewComponentResult>('preview:component', { componentName, props, module, width, repeat: opts?.repeat, instanceProps: opts?.instanceProps }, 8000)
+    } catch (err) {
+      console.warn('[Annotask] preview:component request failed:', err)
+      return { mounted: false, reason: 'no-runtime', fidelity: 'placeholder' }
+    }
+  }
+
   async function getComponentChain(eid: string): Promise<ResolveComponentChainResult | null> {
     try {
       return await bridge.request<ResolveComponentChainResult | null>('resolve:component-chain', { eid })
@@ -495,6 +521,16 @@ export function useIframeManager(iframeRef: Ref<HTMLIFrameElement | null>) {
     } catch { return { error: 'timeout' } }
   }
 
+  /** Rasterize the current route into per-block images (wireframe mode).
+   *  Rects come back in iframe-document coordinates — deliberately NOT
+   *  converted to shell coords; the canvas renders in capture space. Progress
+   *  arrives via 'wireframe:capture-progress' bridge events. */
+  async function captureWireframe(opts?: WireframeCapturePayload): Promise<WireframeCaptureResult> {
+    try {
+      return await bridge.request<WireframeCaptureResult>('wireframe:capture', opts ?? {}, 60000)
+    } catch { return { error: 'capture timed out' } }
+  }
+
   async function scanA11y(eid?: string): Promise<{ violations: any[]; error?: string }> {
     try {
       return await bridge.request('a11y:scan', { eid }, 30000) // longer timeout for axe load
@@ -587,6 +623,7 @@ export function useIframeManager(iframeRef: Ref<HTMLIFrameElement | null>) {
     findTemplateGroup,
     getElementRect,
     getElementRects,
+    getTextRangeRects,
     getFileElementRects,
     getLocationElementRects,
     listProjectComponents,
@@ -603,6 +640,7 @@ export function useIframeManager(iframeRef: Ref<HTMLIFrameElement | null>) {
     classifyElement,
     getComponentChain,
     captureScreenshot,
+    captureWireframe,
     scanA11y,
     scrollIntoView,
     resolveBySelectors,
@@ -631,9 +669,9 @@ export function useIframeManager(iframeRef: Ref<HTMLIFrameElement | null>) {
     // Insert/Move
     insertPlaceholder,
     removePlaceholder,
-    moveElement,
     insertComponent,
     insertVueComponent,
+    previewComponent,
     // Mode
     setMode,
     // Bridge events
diff --git a/src/shell/composables/useInitFlow.ts b/src/shell/composables/useInitFlow.ts
new file mode 100644
index 0000000..f1f0150
--- /dev/null
+++ b/src/shell/composables/useInitFlow.ts
@@ -0,0 +1,468 @@
+/**
+ * Drives the InitWizard overlay. Subscribes to the server's `init:progress`
+ * WS topic and exposes a state machine for the 4-step UI:
+ *   0. `mode`   — choose skill/MCP vs embedded-agent workflow (first run only).
+ *   1. `agent`  — pick the provider the embedded agent will run through.
+ *   2. `scan`   — server runs the scanners; emits step-by-step progress.
+ *   3. `review` — user edits the assembled draft (themes, style guide),
+ *                 then commits to disk.
+ *
+ * Visibility: the wizard auto-opens when the user hasn't yet chosen a workflow
+ * (`embeddedAgentEnabled === null`) or has chosen embedded but the project
+ * has no design-spec (`isInitialized === false` from useDesignSpec). When
+ * `embeddedAgentEnabled === false` the wizard never auto-opens — the user is
+ * in skill/MCP mode and drives init from their editor agent.
+ */
+
+import { ref, computed, watch } from 'vue'
+import { on as wsOn } from '../services/wsClient'
+import { useDesignSpec } from './useDesignSpec'
+import { useProviderSettings } from './useProviderSettings'
+import type { EffortLevel, ProviderId } from '../../embedded/provider-config'
+
+export type InitStepStatus = 'pending' | 'running' | 'success' | 'error' | 'skipped'
+
+export interface InitStep {
+  id: string
+  label: string
+  status: InitStepStatus
+  message?: string
+  startedAt?: number
+  finishedAt?: number
+}
+
+export interface InitDraft {
+  spec: Record<string, any>
+  styleGuide: string
+  styleGuideExists: boolean
+  designSpecExists: boolean
+}
+
+export interface InitTokenUsage {
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheCreationTokens: number
+  turns: number
+}
+
+export interface InitState {
+  running: boolean
+  startedAt?: number
+  finishedAt?: number
+  result?: 'success' | 'error' | 'cancelled' | 'awaiting_review'
+  error?: string
+  steps: InitStep[]
+  draft?: InitDraft
+  committedAt?: number
+  agentLines?: string[]
+  agentCli?: string
+  /** Live token tally for this init run, accumulated across all CLI calls. */
+  tokenUsage?: InitTokenUsage
+}
+
+export type WizardStep = 'mode' | 'agent' | 'scan' | 'review'
+
+export interface ScanOptions {
+  /** Skip the LLM design-spec pass. Set in re-scan mode when the user only
+   *  wants to refresh agent-configs or recompute static catalogs without
+   *  rewriting design-spec.json + STYLE_GUIDE.md. */
+  skipAgentScan?: boolean
+  skipAgentConfigs?: boolean
+  skipComponents?: boolean
+  skipDataSources?: boolean
+  skipApiSchemas?: boolean
+  requestedProviderId?: ProviderId
+  requestedModel?: string
+  requestedEffort?: EffortLevel
+}
+
+const EMPTY_STATE: InitState = { running: false, steps: [] }
+
+const open = ref(false)
+const wizardStep = ref<WizardStep>('mode')
+const initState = ref<InitState>(EMPTY_STATE)
+
+// Editable copy of the server-provided draft. The user mutates these via the
+// review-step UI; on commit we POST them back. We keep this separate from
+// initState.draft so the WS rebroadcast doesn't clobber in-progress edits.
+const draftSpec = ref<Record<string, any>>({})
+const draftStyleGuide = ref('')
+const overwriteStyleGuide = ref(false)
+let draftHydrated = false
+
+let wired = false
+let designSpecRefetch: (() => Promise<void>) | null = null
+let providerSettingsRef: ReturnType<typeof useProviderSettings> | null = null
+// Module-level reference to the current designSpec value so openWizard can
+// hydrate the draft without needing a prop.
+let getDesignSpecValue: (() => Record<string, any> | null) | null = null
+
+async function fetchInitState() {
+  try {
+    const res = await fetch('/__annotask/api/init/state')
+    if (!res.ok) return
+    initState.value = await res.json()
+    hydrateDraftIfReady()
+  } catch {
+    /* offline — leave existing state */
+  }
+}
+
+function hydrateDraftIfReady() {
+  const draft = initState.value.draft
+  if (draft && !draftHydrated) {
+    draftSpec.value = JSON.parse(JSON.stringify(draft.spec))
+    draftStyleGuide.value = draft.styleGuide
+    overwriteStyleGuide.value = !draft.styleGuideExists
+    draftHydrated = true
+  }
+}
+
+async function hydrateFromCurrentSpec() {
+  const spec = getDesignSpecValue?.()
+  if (spec) {
+    draftSpec.value = JSON.parse(JSON.stringify(spec))
+    draftHydrated = true
+  }
+  // Also fetch the current style guide from disk.
+  try {
+    const res = await fetch('/__annotask/api/style-guide')
+    if (res.ok) {
+      const data = await res.json()
+      draftStyleGuide.value = data.content ?? ''
+      overwriteStyleGuide.value = false
+    }
+  } catch { /* offline */ }
+}
+
+async function startRun(opts: ScanOptions = {}) {
+  draftHydrated = false
+  try {
+    const activeProvider = providerSettingsRef?.activeProvider.value
+    const providerConfig = activeProvider ? providerSettingsRef?.settings.value.providers[activeProvider] : undefined
+    const body = {
+      ...opts,
+      ...(activeProvider ? { requestedProviderId: activeProvider } : {}),
+      ...(typeof providerConfig?.model === 'string' ? { requestedModel: providerConfig.model } : {}),
+      ...(providerConfig?.effort ? { requestedEffort: providerConfig.effort } : {}),
+    }
+    const hasOpts = Object.values(body).some(Boolean)
+    const res = await fetch('/__annotask/api/init/start', {
+      method: 'POST',
+      headers: hasOpts ? { 'Content-Type': 'application/json' } : undefined,
+      body: hasOpts ? JSON.stringify(body) : undefined,
+    })
+    if (!res.ok) throw new Error(`Init start failed: ${res.status}`)
+    initState.value = await res.json()
+    wizardStep.value = 'scan'
+  } catch (err) {
+    initState.value = {
+      ...initState.value,
+      result: 'error',
+      error: (err as Error).message,
+      running: false,
+    }
+  }
+}
+
+async function cancelRun() {
+  try {
+    await fetch('/__annotask/api/init/cancel', { method: 'POST' })
+  } catch {
+    /* swallow — UI shows last broadcast */
+  }
+}
+
+async function skipInit(): Promise<void> {
+  try {
+    await fetch('/__annotask/api/init/skip', { method: 'POST' })
+    if (designSpecRefetch) await designSpecRefetch()
+  } catch { /* swallow */ }
+  // Close the wizard regardless — the server writes a placeholder spec marking
+  // the project initialized, and the auto-open watcher won't reopen it.
+  closeWizard()
+}
+
+async function commitDraft(): Promise<boolean> {
+  try {
+    const res = await fetch('/__annotask/api/init/commit', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        spec: draftSpec.value,
+        styleGuide: draftStyleGuide.value,
+        overwriteStyleGuide: overwriteStyleGuide.value,
+      }),
+    })
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({ error: { message: res.statusText } }))
+      throw new Error(errBody?.error?.message ?? `Commit failed: ${res.status}`)
+    }
+    initState.value = await res.json()
+    if (designSpecRefetch) await designSpecRefetch()
+    return true
+  } catch (err) {
+    initState.value = {
+      ...initState.value,
+      result: 'error',
+      error: (err as Error).message,
+    }
+    return false
+  }
+}
+
+// True when the wizard was reopened post-init for a targeted re-scan rather
+// than a fresh setup. Drives Scan-step UX (default toggles off, hide
+// post-run progress from the previous run, etc.).
+const rescanMode = ref(false)
+
+function openWizard(step?: WizardStep, opts: { rescan?: boolean } = {}) {
+  rescanMode.value = !!opts.rescan
+  // Default entry: 'mode' iff the user has never chosen a workflow; otherwise
+  // 'agent'. Re-scans always land directly on 'agent'.
+  if (!step) {
+    const choice = providerSettingsRef?.settings.value.embeddedAgentEnabled
+    step = choice == null ? 'mode' : 'agent'
+  }
+  wizardStep.value = step
+  open.value = true
+  // When jumping directly to review (e.g. already initialized), hydrate draft
+  // from the current on-disk spec rather than waiting for a scan.
+  if (wizardStep.value === 'review' && !draftHydrated) {
+    hydrateFromCurrentSpec()
+  }
+}
+
+function closeWizard() {
+  open.value = false
+  rescanMode.value = false
+}
+
+// Move to a specific step from inside the wizard. Mirrors openWizard's
+// hydration logic so stepper-driven jumps to Review pull from disk if the
+// in-memory draft hasn't been populated yet.
+function goToStep(step: WizardStep) {
+  wizardStep.value = step
+  if (step === 'review' && !draftHydrated) {
+    hydrateFromCurrentSpec()
+  }
+}
+
+function nextStep() {
+  if (wizardStep.value === 'mode') wizardStep.value = 'agent'
+  else if (wizardStep.value === 'agent') wizardStep.value = 'scan'
+  else if (wizardStep.value === 'scan') wizardStep.value = 'review'
+  else if (wizardStep.value === 'review') {
+    closeWizard()
+    if (designSpecRefetch) designSpecRefetch()
+  }
+}
+
+// ── Draft editors ─────────────────────────────────────
+// Lightweight mutators that keep draftSpec immutably-replaced so Vue's
+// reactivity picks them up.
+
+interface ThemeEntry {
+  id: string
+  name: string
+  scheme?: string
+  selector: Record<string, any>
+}
+
+function getThemes(): ThemeEntry[] {
+  const t = draftSpec.value.themes
+  return Array.isArray(t) ? (t as ThemeEntry[]) : []
+}
+
+function setThemes(next: ThemeEntry[]) {
+  draftSpec.value = { ...draftSpec.value, themes: next }
+}
+
+function addTheme() {
+  const themes = getThemes()
+  let id = 'new-theme'
+  let n = 1
+  const existing = new Set(themes.map(t => t.id))
+  while (existing.has(id)) { n++; id = `new-theme-${n}` }
+  setThemes([...themes, { id, name: 'New theme', selector: { kind: 'class', host: 'html', name: id } }])
+}
+
+function updateTheme(index: number, patch: Partial<ThemeEntry>) {
+  const themes = getThemes()
+  if (index < 0 || index >= themes.length) return
+  const next = [...themes]
+  next[index] = { ...next[index], ...patch }
+  setThemes(next)
+}
+
+function updateThemeSelector(index: number, patch: Record<string, any>) {
+  const themes = getThemes()
+  if (index < 0 || index >= themes.length) return
+  const next = [...themes]
+  next[index] = { ...next[index], selector: { ...next[index].selector, ...patch } }
+  setThemes(next)
+}
+
+function removeTheme(index: number) {
+  const themes = getThemes()
+  if (index < 0 || index >= themes.length) return
+  const removedId = themes[index].id
+  const next = themes.filter((_, i) => i !== index)
+  setThemes(next)
+  if (draftSpec.value.defaultTheme === removedId) {
+    draftSpec.value = { ...draftSpec.value, defaultTheme: next[0]?.id ?? 'default' }
+  }
+}
+
+function setDefaultTheme(id: string) {
+  draftSpec.value = { ...draftSpec.value, defaultTheme: id }
+}
+
+function updateFramework(patch: Record<string, any>) {
+  const fw = draftSpec.value.framework ?? { name: 'unknown', version: '', styling: [] }
+  draftSpec.value = { ...draftSpec.value, framework: { ...fw, ...patch } }
+}
+
+function setStyleGuide(text: string) {
+  draftStyleGuide.value = text
+}
+
+function setOverwriteStyleGuide(v: boolean) {
+  overwriteStyleGuide.value = v
+}
+
+export function useInitFlow() {
+  const designSpec = useDesignSpec()
+  designSpecRefetch = designSpec.refetch
+  const providerSettings = useProviderSettings()
+  providerSettingsRef = providerSettings
+
+  if (!wired) {
+    wired = true
+
+    // Server pushes a fresh state on every step change.
+    let lastWsPushAt = 0
+    wsOn('init:progress', (data) => {
+      if (data && typeof data === 'object') {
+        lastWsPushAt = Date.now()
+        initState.value = data as InitState
+        hydrateDraftIfReady()
+      }
+    })
+
+    fetchInitState()
+
+    // Poll fallback. The WS push is the primary update channel, but if the
+    // dev server restarts mid-run (OOM, container recreate, …) the socket
+    // dies silently and the wizard's "Running…" spinner ticks forever
+    // because no fresh state ever arrives. While a run is in flight, poll
+    // every 3s; skip the poll if the WS pushed within the last 2s so we
+    // don't double-fetch during a healthy run.
+    setInterval(() => {
+      if (!initState.value.running) return
+      if (Date.now() - lastWsPushAt < 2_000) return
+      fetchInitState()
+    }, 3_000)
+    getDesignSpecValue = () => designSpec.designSpec.value as Record<string, any> | null
+
+    // Auto-open rules + deferred migration of pre-`embeddedAgentEnabled`
+    // settings:
+    //   - !initialized + null     → open Page 0 (workflow choice forced
+    //                                even if stale `agentMode` from an old
+    //                                install would otherwise have implied one)
+    //   - !initialized + true     → open at 'agent' (provider setup)
+    //   - !initialized + false    → no auto-open (skill mode)
+    //   - initialized  + null     → silently migrate from legacy `agentMode`
+    //                                (auto/manual → true, off → false) and
+    //                                do not re-prompt — these users were
+    //                                already using Annotask successfully.
+    //   - initialized  + anything → no auto-open.
+    watch(
+      () => [
+        designSpec.isLoading.value,
+        designSpec.isInitialized.value,
+        providerSettings.settings.value.embeddedAgentEnabled,
+      ] as const,
+      ([loading, initialized, embeddedChoice]) => {
+        if (loading) return
+        // Still advance scan→review for an in-flight wizard regardless of state.
+        if (open.value && wizardStep.value === 'scan' && initState.value.result === 'awaiting_review') {
+          wizardStep.value = 'review'
+        }
+        if (open.value) return
+        if (embeddedChoice == null) {
+          if (initialized) {
+            // Existing user upgrading — derive their preference from the
+            // pre-existing `agentMode` and skip Page 0.
+            const mode = providerSettings.settings.value.agentMode
+            providerSettings.setEmbeddedAgentEnabled(mode !== 'off')
+            return
+          }
+          openWizard('mode')
+          return
+        }
+        if (embeddedChoice === true && !initialized) {
+          openWizard('agent')
+        }
+      },
+      { immediate: true },
+    )
+
+    // When the scan finishes with `awaiting_review`, advance the wizard to
+    // the review step so the user sees the draft right away.
+    watch(
+      () => initState.value.result,
+      (result) => {
+        if (result === 'awaiting_review' && wizardStep.value === 'scan') {
+          wizardStep.value = 'review'
+        }
+        if (result === 'success' && initState.value.committedAt != null) {
+          designSpec.refetch()
+        }
+      },
+    )
+  }
+
+  const hasConfiguredProvider = computed(() => {
+    const active = providerSettings.activeProvider.value
+    return Boolean(active)
+  })
+
+  const overallProgress = computed(() => {
+    const steps = initState.value.steps
+    if (steps.length === 0) return 0
+    const done = steps.filter(s => s.status === 'success' || s.status === 'skipped').length
+    return Math.round((done / steps.length) * 100)
+  })
+
+  return {
+    open,
+    wizardStep,
+    rescanMode,
+    initState,
+    overallProgress,
+    hasConfiguredProvider,
+    isInitialized: designSpec.isInitialized,
+    openWizard,
+    closeWizard,
+    nextStep,
+    goToStep,
+    startRun,
+    cancelRun,
+    skipInit,
+    commitDraft,
+    // Draft state + mutators
+    draftSpec,
+    draftStyleGuide,
+    overwriteStyleGuide,
+    addTheme,
+    updateTheme,
+    updateThemeSelector,
+    removeTheme,
+    setDefaultTheme,
+    updateFramework,
+    setStyleGuide,
+    setOverwriteStyleGuide,
+  }
+}
diff --git a/src/shell/composables/useInteractionMode.ts b/src/shell/composables/useInteractionMode.ts
index 9340d55..21a9a23 100644
--- a/src/shell/composables/useInteractionMode.ts
+++ b/src/shell/composables/useInteractionMode.ts
@@ -1,10 +1,10 @@
 import { ref, watch, onMounted, onUnmounted } from 'vue'
 
-export type InteractionMode = 'select' | 'interact' | 'pin' | 'arrow' | 'draw' | 'highlight'
+export type InteractionMode = 'select' | 'interact' | 'pin' | 'arrow' | 'highlight'
 
 const stored = localStorage.getItem('annotask:mode')
 const mode = ref<InteractionMode>(
-  stored && ['select', 'interact', 'pin', 'arrow', 'draw', 'highlight'].includes(stored)
+  stored && ['select', 'interact', 'pin', 'arrow', 'highlight'].includes(stored)
     ? stored as InteractionMode
     : 'interact'
 )
@@ -18,7 +18,6 @@ function onKeyDown(e: KeyboardEvent) {
     case 'i': mode.value = 'interact'; break
     case 'p': mode.value = 'pin'; break
     case 'a': mode.value = 'arrow'; break
-    case 'd': mode.value = 'draw'; break
     case 'h': mode.value = 'highlight'; break
   }
 }
diff --git a/src/shell/composables/useKeyboardShortcuts.ts b/src/shell/composables/useKeyboardShortcuts.ts
index 1fc8803..915cc92 100644
--- a/src/shell/composables/useKeyboardShortcuts.ts
+++ b/src/shell/composables/useKeyboardShortcuts.ts
@@ -14,6 +14,7 @@ export interface KeyboardShortcutDeps {
   groupRects: Ref<unknown[]>
   activePanel: Ref<'inspector' | 'tasks'>
   doUndo: () => void
+  doRedo: () => void
   cancelSnip: () => void
   cancelPendingTask: () => void
   layoutOverlayToggle: () => void
@@ -24,8 +25,15 @@ export function useKeyboardShortcuts(deps: KeyboardShortcutDeps) {
 
   function onShellKeyDown(e: KeyboardEvent) {
     const mod = e.ctrlKey || e.metaKey
+    const k = e.key.toLowerCase()
 
-    if (mod && e.key === 'z' && !e.shiftKey) {
+    // Redo before undo so Ctrl/Cmd+Shift+Z isn't swallowed by the undo branch.
+    if (mod && (k === 'y' || (k === 'z' && e.shiftKey))) {
+      e.preventDefault()
+      deps.doRedo()
+      return
+    }
+    if (mod && k === 'z' && !e.shiftKey) {
       e.preventDefault()
       deps.doUndo()
       return
diff --git a/src/shell/composables/useOverlayEngine.ts b/src/shell/composables/useOverlayEngine.ts
new file mode 100644
index 0000000..98689b9
--- /dev/null
+++ b/src/shell/composables/useOverlayEngine.ts
@@ -0,0 +1,155 @@
+/**
+ * Shared overlay loop runtime for every surface that paints rects over the
+ * iframe DOM and must keep them aligned as the app scrolls / resizes:
+ * data-source highlights, a11y highlights, and (soon) the wireframe canvas's
+ * drop-targets and placement outlines.
+ *
+ * Before this, `useDataHighlights` and `useA11yHighlights` each carried their
+ * own copy of the same boilerplate — an rAF tick, a re-entrancy guard, a
+ * page-visibility guard, and the active/inputs watchers — which drifted out of
+ * sync and gave the wireframe nowhere to plug in. This is the single home for
+ * that lifecycle (and the natural seat for the activity-throttled, delta-aware
+ * refresh in overlay step O5).
+ *
+ * The engine owns *when* a refresh runs; the producer owns *what* a refresh
+ * does (its bridge calls + rect merge). A producer stays a plain
+ * `async refresh()` that resolves + sets its own `rects` ref; the engine
+ * guarantees it is never run re-entrantly, never while the tab is hidden, and
+ * never while the surface is inactive or idle.
+ */
+import { watch, type Ref } from 'vue'
+
+/** Shared upper bound on rects drawn in one overlay pass. Centralized here so
+ *  every surface (and the density/clustering work in O4) shares one budget
+ *  instead of each composable hard-coding its own 400. */
+export const OVERLAY_RECT_CAP = 400
+
+/**
+ * Minimum gap between rect re-resolves while the loop runs (~30fps). The loop
+ * still ALWAYS refreshes — it's only rate-capped — so overlays can never go
+ * stale beyond this bound (imperceptible during scroll), but the per-frame
+ * bridge round-trip cost is roughly halved versus refreshing every animation
+ * frame. `kick()` bypasses the cap so focus/source changes paint instantly.
+ *
+ * A fuller "only refresh when the iframe actually moved" gate would need the
+ * iframe to emit scroll/resize/mutation signals (it doesn't today, and the
+ * annotation-rect loop polls every frame the same way) — a coordinated
+ * cross-overlay change left as follow-up. This cap is the safe, no-staleness win.
+ */
+const MIN_REFRESH_INTERVAL_MS = 33
+
+function nowMs(): number {
+  return typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now()
+}
+
+export interface OverlayLoopDeps {
+  /** True while the overlay surface is visible. The loop only runs while
+   *  active; flipping it false stops the rAF loop and triggers `onDeactivate`. */
+  active: Ref<boolean>
+  /** One refresh pass against the iframe DOM — resolve locations/selectors to
+   *  rects and assign the producer's own `rects` ref. The engine guards
+   *  re-entrancy and page-visibility, so this can stay a plain async resolve. */
+  refresh: () => Promise<void>
+  /** Reactive inputs whose change should (re)drive the loop — typically the
+   *  producer's source / violation list. Watched deeply; a change kicks an
+   *  immediate refresh and ensures the loop is running. */
+  inputs: () => unknown
+  /** Optional idle predicate. When it returns true the loop stops itself (and
+   *  `startLoop` won't start) so an empty surface costs zero rAF time — mirrors
+   *  the old "stop the loop when there are no sources" behavior. */
+  isIdle?: () => boolean
+  /** Clear producer state (rects, focus, …) when the surface deactivates. */
+  onDeactivate?: () => void
+}
+
+export interface OverlayLoop {
+  /** Ensure the rAF loop is running (no-op if already running, inactive, or
+   *  idle). */
+  startLoop: () => void
+  /** Refresh immediately and ensure the loop is running — call after pushing
+   *  new inputs so the surface paints within the same frame instead of waiting
+   *  for the next tick. */
+  kick: () => void
+  /** Run exactly one refresh pass now, guarded against re-entrancy. */
+  runOnce: () => Promise<void>
+}
+
+export function useOverlayLoop(deps: OverlayLoopDeps): OverlayLoop {
+  const { active, refresh, inputs, isIdle, onDeactivate } = deps
+
+  let loopRunning = false
+  let rafHandle: number | null = null
+  let refreshInFlight = false
+  let lastRunAt = 0
+
+  function idle(): boolean {
+    return isIdle ? isIdle() : false
+  }
+
+  async function runOnce(): Promise<void> {
+    if (refreshInFlight) return
+    refreshInFlight = true
+    lastRunAt = nowMs()
+    try {
+      await refresh()
+    } finally {
+      refreshInFlight = false
+    }
+  }
+
+  function stopLoop(): void {
+    loopRunning = false
+    if (rafHandle !== null) {
+      cancelAnimationFrame(rafHandle)
+      rafHandle = null
+    }
+  }
+
+  function startLoop(): void {
+    if (loopRunning || !active.value || idle()) return
+    loopRunning = true
+    const tick = () => {
+      if (!active.value || idle()) {
+        stopLoop()
+        return
+      }
+      // Skip work while the tab is backgrounded, but keep the rAF alive so the
+      // loop resumes the instant the tab is visible again.
+      if (typeof document !== 'undefined' && document.hidden) {
+        rafHandle = requestAnimationFrame(tick)
+        return
+      }
+      // Rate-cap the bridge round-trip to ~30fps. Always refreshes (no
+      // staleness) — just not on every single animation frame.
+      if (nowMs() - lastRunAt >= MIN_REFRESH_INTERVAL_MS) runOnce()
+      rafHandle = requestAnimationFrame(tick)
+    }
+    rafHandle = requestAnimationFrame(tick)
+  }
+
+  function kick(): void {
+    if (!active.value) return
+    runOnce() // immediate — bypasses the rate cap (runOnce stamps lastRunAt)
+    startLoop()
+  }
+
+  watch(active, (v, old) => {
+    if (v && !old) {
+      kick()
+    } else if (!v && old) {
+      // Cancel the queued tick too — a bare `loopRunning = false` leaves one
+      // frame in flight, and a reactivate before it fires would stack a second
+      // loop on top of it.
+      stopLoop()
+      onDeactivate?.()
+    }
+  })
+
+  // Deep-watch the producer's inputs so a new source/violation list repaints
+  // immediately (and restarts the loop if it had idled out).
+  watch(inputs, () => {
+    if (active.value) kick()
+  }, { deep: true })
+
+  return { startLoop, kick, runOnce }
+}
diff --git a/src/shell/composables/usePaletteDrag.ts b/src/shell/composables/usePaletteDrag.ts
new file mode 100644
index 0000000..a45984e
--- /dev/null
+++ b/src/shell/composables/usePaletteDrag.ts
@@ -0,0 +1,44 @@
+import { ref } from 'vue'
+import type { WireframeKind } from '../../shared/wireframe-types'
+
+/**
+ * A normalized palette item being dragged — superset of CatalogItem (HTML /
+ * layout-preset) and a live project/library component.
+ */
+export interface PaletteDragItem {
+  kind: WireframeKind
+  /** Component constructor name (kind === 'component') or the HTML/preset tag. */
+  componentName: string
+  tag: string
+  label: string
+  library?: string
+  /** Import specifier (e.g. "primevue/button") for on-demand loading. */
+  module?: string
+  props?: Record<string, unknown>
+  /** Sample props for the live mount/preview only — NOT persisted as real props. */
+  previewProps?: Record<string, unknown>
+  classes?: string
+  textContent?: string
+  /** CatalogItem category (e.g. 'layout-preset') — drives placeholder styling. */
+  category?: string
+  /** Scanner hint so the drop can predict fidelity before mounting. */
+  fidelityHint?: 'live' | 'isolated-preview' | 'placeholder' | 'unknown'
+  /** Owning MFE id (the component's home package), carried from the palette
+   *  through the drop so the placed block can be stamped. */
+  mfe?: string
+}
+
+// Module-singleton: native HTML5 drag events block `dataTransfer.getData` during
+// `dragover`, so the drop-shield and live drop indicator read the in-flight drag
+// identity from this shared ref instead of the event.
+const draggingItem = ref<PaletteDragItem | null>(null)
+
+export function usePaletteDrag() {
+  function startDrag(item: PaletteDragItem): void {
+    draggingItem.value = item
+  }
+  function endDrag(): void {
+    draggingItem.value = null
+  }
+  return { draggingItem, startDrag, endDrag }
+}
diff --git a/src/shell/composables/useProjectComponents.ts b/src/shell/composables/useProjectComponents.ts
index 588a346..74cc75a 100644
--- a/src/shell/composables/useProjectComponents.ts
+++ b/src/shell/composables/useProjectComponents.ts
@@ -50,6 +50,11 @@ export interface LibraryComponent {
   slots?: LibrarySlot[]
   events?: LibraryEvent[]
   sourceFile?: string | null
+  /** Provider-dependence markers from the scanner (see ScannedComponent). */
+  providerSignals?: string[]
+  /** Coarse render-fidelity hint so the palette can pre-mark a component as
+   *  isolated-preview before attempting a throwing mount. */
+  fidelityHint?: 'live' | 'isolated-preview' | 'placeholder' | 'unknown'
 }
 
 export interface LibraryCatalog {
@@ -127,11 +132,18 @@ async function load(iframe?: ReturnType<typeof useIframeManager>): Promise<void>
   isLoading.value = true
   loadError.value = null
   try {
-    const [catalog, usage] = await Promise.all([
+    const [catalog, projectLib, usage] = await Promise.all([
       fetchJson<LibraryComponentsIndex>('components'),
+      fetchJson<{ library: LibraryCatalog }>('project-components'),
       fetchJson<{ usage: Record<string, string[]>; imports?: Record<string, Record<string, string[]>> }>('component-usage'),
     ])
-    libraries.value = catalog?.libraries ?? []
+    // The user's own components come first — a design tool designs with the
+    // project's components, and same-named project components shadow library
+    // exports in metadata lookups.
+    const project = projectLib?.library
+    libraries.value = project && project.components.length > 0
+      ? [project, ...(catalog?.libraries ?? [])]
+      : (catalog?.libraries ?? [])
     const map = new Map<string, string[]>()
     for (const [name, files] of Object.entries(usage?.usage ?? {})) {
       map.set(name, files)
@@ -180,8 +192,13 @@ async function refreshRenderedFiles(iframe: ReturnType<typeof useIframeManager>)
 /** Does an import specifier (`from '…'`) belong to this library? Matches the
  *  package name exactly or as a subpath prefix so `@mantine/core` attributes
  *  imports from `@mantine/core/Button`, `primevue` attributes
- *  `primevue/button`, etc. */
+ *  `primevue/button`, etc. The synthetic "Project" library owns relative
+ *  imports (`./components/PlanetCard.vue`, `../ui/Button`) and `@/…`/`~/…`
+ *  src aliases — the project's own components are imported that way. */
 function fromMatchesLibrary(from: string, libName: string): boolean {
+  if (libName === 'Project') {
+    return from.startsWith('./') || from.startsWith('../') || from.startsWith('@/') || from.startsWith('~/')
+  }
   return from === libName || from.startsWith(libName + '/')
 }
 
@@ -380,6 +397,36 @@ const filteredLibraries = computed<LibraryCatalog[]>(() => {
     .filter(lib => lib.components.length > 0)
 })
 
+/** Predict whether a palette component can render a LIVE snapshot on the CURRENT
+ *  iframe surface, and which MFE owns it. There is exactly one active surface and
+ *  one global component registry, so a Project component defined in / used only by
+ *  a DIFFERENT MFE isn't reachable here — mark it unavailable (honest) but still
+ *  report its owning MFE so apply-time codegen imports from the right package.
+ *  Third-party libraries are left renderable: the registry is the real arbiter we
+ *  can't see statically, and over-blocking a shared design system would make the
+ *  palette feel broken. Returns renderable:true / owningMfe:null in single-MFE or
+ *  non-workspace projects (no gating). The owning MFE comes from the component's
+ *  workspace-relative usage files (the same signal filteredLibraries trusts) plus
+ *  its definition file when that is workspace-relative. */
+function surfaceRenderInfo(libName: string, c: LibraryComponent): { renderable: boolean; owningMfe: string | null } {
+  const ws = useWorkspace()
+  if (!ws.hasAnyMfes.value) return { renderable: true, owningMfe: null }
+  const cur = ws.currentMfe.value
+  // Only the project's own components are gated cross-MFE; installed libraries
+  // are assumed available across surfaces.
+  if (libName !== 'Project') return { renderable: true, owningMfe: cur }
+  const mfes = new Set<string>()
+  for (const f of filesForLibComponent(libName, c.name)) {
+    const id = ws.mfeForFile(f)
+    if (id) mfes.add(id)
+  }
+  const srcMfe = c.sourceFile ? ws.mfeForFile(c.sourceFile) : null
+  if (srcMfe) mfes.add(srcMfe)
+  if (mfes.size === 0) return { renderable: true, owningMfe: null } // unattributed → allow
+  if (cur && mfes.has(cur)) return { renderable: true, owningMfe: cur }
+  return { renderable: false, owningMfe: [...mfes][0] }
+}
+
 function select(libraryName: string, componentName: string): void {
   selectedKey.value = `${libraryName}:::${componentName}`
   selectedLibrary.value = libraryName
@@ -587,5 +634,6 @@ export function useComponentLibrary(iframe?: ReturnType<typeof useIframeManager>
     isUsedInLib,
     isOnPageInLib,
     filesForLibComponent,
+    surfaceRenderInfo,
   }
 }
diff --git a/src/shell/composables/useProviderSettings.ts b/src/shell/composables/useProviderSettings.ts
new file mode 100644
index 0000000..b67275e
--- /dev/null
+++ b/src/shell/composables/useProviderSettings.ts
@@ -0,0 +1,320 @@
+import { ref, computed, watch, type Ref, type ComputedRef } from 'vue'
+import {
+  DEFAULT_PROVIDER_SETTINGS,
+  parseProviderSettings,
+  isActiveProviderReady,
+  type AgentMode,
+  type EffortLevel,
+  type LocalCliReadiness,
+  type ProviderId,
+  type ProviderSettings,
+  type ProviderConfig,
+  PROVIDER_IDS,
+} from '../../embedded/provider-config.js'
+import type { PermissionMode } from '../../schema.js'
+import {
+  combinePersonas,
+  resolvePersonaForTaskType,
+  type PersonaConfig,
+  type PersonaRuntimeOverride,
+} from '../../embedded/persona.js'
+import { EventLog, type PersistenceSink } from '../../embedded/event-log.js'
+import { useAgentConfigs } from './useAgentConfigs.js'
+
+/**
+ * Multi-provider settings for the embedded chat. Singleton because the
+ * settings sheet, the Conversation tab header, the first-run modal, and
+ * the task-creation auto-run hook all read from the same source.
+ *
+ * Storage posture: localStorage only, behind a single key. Keys never
+ * leave the browser.
+ *
+ * Per-task USD cost caps were removed: heterogeneous providers (local
+ * CLIs, OpenRouter, Paperclip, …) have no portable pricing surface, so a
+ * dollar-denominated cap can't be meaningful across the matrix. Token
+ * counts come back from each provider when they support it and the UI
+ * surfaces them informationally.
+ */
+
+const STORAGE_KEY = 'annotask:ai:providerSettings'
+
+let singleton: ReturnType<typeof create> | null = null
+
+interface PersistenceShim {
+  load(): unknown
+  save(value: unknown): void
+}
+
+function makeLocalStorageShim(): PersistenceShim {
+  return {
+    load: () => {
+      try {
+        return localStorage.getItem(STORAGE_KEY)
+      } catch {
+        return null
+      }
+    },
+    save: (value) => {
+      try {
+        localStorage.setItem(STORAGE_KEY, JSON.stringify(value))
+      } catch {
+        // Quota errors are best-effort; the user can re-enter on next reload.
+      }
+    },
+  }
+}
+
+function makeLocalStoragePersistenceSink(): PersistenceSink | undefined {
+  if (typeof localStorage === 'undefined') return undefined
+  return localStorage
+}
+
+/** Accessor for per-agent overrides sourced from `.annotask/agents.json`.
+ *  Returns a snapshot map keyed by persona id; called from the `personas`
+ *  computed so it must be reactive on each read (Vue's tracking handles this
+ *  as long as it touches a reactive ref). */
+type AgentOverridesAccessor = () => Record<string, PersonaRuntimeOverride>
+
+function create(
+  persistence: PersistenceShim = makeLocalStorageShim(),
+  agentOverrides: AgentOverridesAccessor = () => ({}),
+) {
+  const initial = parseProviderSettings(persistence.load())
+  const settings: Ref<ProviderSettings> = ref(initial)
+
+  watch(
+    settings,
+    (next) => {
+      persistence.save(next)
+    },
+    { deep: true },
+  )
+
+  /**
+   * Local-CLI probe. The settings panel writes to this with whatever
+   * `/__annotask/api/agent/detect` reports; the readiness computation
+   * reads it so local-CLI providers can be marked ready or not without
+   * baking the probe into provider-config itself.
+   */
+  const localCliProbe = ref<LocalCliReadiness>({})
+
+  const activeProvider: ComputedRef<ProviderId> = computed(() => settings.value.activeProvider)
+
+  const ready = computed(() => isActiveProviderReady(settings.value, localCliProbe.value))
+
+  const eventLog = new EventLog({
+    persistence: makeLocalStoragePersistenceSink(),
+    persistenceKey: 'annotask:ai:eventLog',
+  })
+
+  function setLocalCliProbe(probe: LocalCliReadiness) {
+    localCliProbe.value = probe
+  }
+
+  function setActiveProvider(id: ProviderId) {
+    settings.value = { ...settings.value, activeProvider: id }
+  }
+
+  function setProviderConfig<C extends ProviderConfig>(config: C) {
+    settings.value = {
+      ...settings.value,
+      providers: { ...settings.value.providers, [config.id]: config },
+    }
+  }
+
+  /** Update the effort knob for the named provider in-place. */
+  function setEffort(id: ProviderId, effort: EffortLevel) {
+    const current = settings.value.providers[id]
+    setProviderConfig({ ...current, effort } as ProviderConfig)
+  }
+
+  /** Update the model id for the named provider in-place. Empty = auto. */
+  function setModel(id: ProviderId, model: string) {
+    const current = settings.value.providers[id]
+    setProviderConfig({ ...current, model } as ProviderConfig)
+  }
+
+  function setAgentMode(mode: AgentMode) {
+    settings.value = { ...settings.value, agentMode: mode }
+  }
+
+  /**
+   * Top-level embedded-agent toggle. Set to `true` to enable the in-shell
+   * Conversation tab / auto-run / provider setup; `false` puts the user in
+   * skill/MCP mode (classic UI, no spawned subprocess, MCP server still up).
+   * When switching from off→on for the first time we also ensure `agentMode`
+   * is non-`'off'` so the user actually sees the agent running.
+   */
+  function setEmbeddedAgentEnabled(value: boolean) {
+    const next: ProviderSettings = { ...settings.value, embeddedAgentEnabled: value }
+    if (value && next.agentMode === 'off') next.agentMode = 'auto'
+    settings.value = next
+  }
+
+  function setPermissionMode(mode: PermissionMode) {
+    settings.value = { ...settings.value, permissionMode: mode }
+  }
+
+  /**
+   * Per-provider permission-mode override. Passing `null` clears the override
+   * so the provider inherits the global setting. Only local-CLI providers
+   * carry the field — calling this with an HTTP provider id is a no-op.
+   */
+  function setProviderPermissionMode(id: ProviderId, mode: PermissionMode | null) {
+    const current = settings.value.providers[id]
+    if (!('permissionMode' in current) && mode === null) return
+    if (id !== 'claude-local' && id !== 'codex-local' && id !== 'opencode-local' && id !== 'copilot-local') return
+    const next = { ...current, permissionMode: mode ?? undefined } as ProviderConfig
+    setProviderConfig(next)
+  }
+
+  function setOnboardingDismissed(dismissed = true) {
+    settings.value = { ...settings.value, onboardingDismissed: dismissed }
+  }
+
+  function setRedactionEnabled(on: boolean) {
+    settings.value = { ...settings.value, redactionEnabled: on }
+  }
+
+  function setEventLogEnabled(on: boolean) {
+    settings.value = { ...settings.value, eventLogEnabled: on }
+  }
+
+  /** Run-safety watchdog knobs. Stored in ms; `0` disables that timer. */
+  function setIdleTimeoutMs(ms: number) {
+    settings.value = { ...settings.value, idleTimeoutMs: Math.max(0, Math.floor(ms)) }
+  }
+
+  function setMaxRunDurationMs(ms: number) {
+    settings.value = { ...settings.value, maxRunDurationMs: Math.max(0, Math.floor(ms)) }
+  }
+
+  // ── Personas ─────────────────────────────────────────
+  //
+  // Built-ins are merged in at read time so the UI never shows a stale
+  // snapshot when persona.ts is updated in a new annotask release.
+
+  const personas: ComputedRef<PersonaConfig[]> = computed(() =>
+    combinePersonas(settings.value.customPersonas ?? [], agentOverrides()),
+  )
+
+  function getPersonaForTaskType(taskType: string | undefined): PersonaConfig | null {
+    return resolvePersonaForTaskType(personas.value, taskType, settings.value.personaOverrides ?? {})
+  }
+
+  /** Insert or replace a custom persona by id. Built-ins are never written
+   *  to `customPersonas`; instead, editing a built-in clones it as
+   *  `custom:<built-in-id>` so the original stays available. */
+  function upsertPersona(persona: PersonaConfig) {
+    const existing = settings.value.customPersonas ?? []
+    const idx = existing.findIndex(p => p.id === persona.id)
+    const next = persona.isCustom ? persona : { ...persona, isCustom: true }
+    const updated = idx >= 0
+      ? existing.map((p, i) => i === idx ? next : p)
+      : [...existing, next]
+    settings.value = { ...settings.value, customPersonas: updated }
+  }
+
+  function deletePersona(id: string) {
+    const existing = settings.value.customPersonas ?? []
+    const updated = existing.filter(p => p.id !== id)
+    // Also drop any override pinning a task type to this persona.
+    const overrides = { ...(settings.value.personaOverrides ?? {}) }
+    for (const k of Object.keys(overrides)) {
+      if (overrides[k] === id) delete overrides[k]
+    }
+    settings.value = { ...settings.value, customPersonas: updated, personaOverrides: overrides }
+  }
+
+  function setPersonaOverride(taskType: string, personaId: string | null) {
+    const overrides = { ...(settings.value.personaOverrides ?? {}) }
+    if (personaId == null || personaId === '') {
+      delete overrides[taskType]
+    } else {
+      overrides[taskType] = personaId
+    }
+    settings.value = { ...settings.value, personaOverrides: overrides }
+  }
+
+  return {
+    settings,
+    activeProvider,
+    ready,
+    providerIds: PROVIDER_IDS,
+    localCliProbe,
+    setLocalCliProbe,
+    setActiveProvider,
+    setProviderConfig,
+    setEffort,
+    setModel,
+    setAgentMode,
+    setEmbeddedAgentEnabled,
+    setPermissionMode,
+    setProviderPermissionMode,
+    setOnboardingDismissed,
+    setRedactionEnabled,
+    setEventLogEnabled,
+    setIdleTimeoutMs,
+    setMaxRunDurationMs,
+    personas,
+    getPersonaForTaskType,
+    upsertPersona,
+    deletePersona,
+    setPersonaOverride,
+    eventLog,
+  }
+}
+
+export type UseProviderSettings = ReturnType<typeof create>
+
+export function useProviderSettings(): UseProviderSettings {
+  if (!singleton) {
+    // Wire in per-agent overrides from `.annotask/agents.json` so the
+    // persona resolver picks up project-specific provider/model/effort
+    // without each consumer having to know about agent-configs.
+    singleton = create(makeLocalStorageShim(), () => {
+      const cfg = useAgentConfigs().configs.value
+      const out: Record<string, PersonaRuntimeOverride> = {}
+      for (const [id, entry] of Object.entries(cfg)) {
+        const o: PersonaRuntimeOverride = {}
+        if (entry.providerId) o.providerId = entry.providerId
+        if (typeof entry.model === 'string') o.model = entry.model
+        if (entry.effort) o.effort = entry.effort
+        if (Object.keys(o).length > 0) out[id] = o
+      }
+      return out
+    })
+  }
+  return singleton
+}
+
+/**
+ * Reset the singleton. Test-only — production callers should never need
+ * this.
+ */
+export function resetProviderSettingsForTests(): void {
+  singleton = null
+}
+
+/**
+ * Construct a non-singleton instance with an explicit persistence shim.
+ * Used by tests so they don't share state through the module-level
+ * singleton.
+ */
+export function createProviderSettingsForTests(initial: unknown = null) {
+  let stored = initial
+  return create({
+    load: () => stored,
+    save: (v) => {
+      stored = JSON.stringify(v)
+    },
+  })
+}
+
+// Re-exports so the panel can import everything from one place.
+export {
+  DEFAULT_PROVIDER_SETTINGS,
+  PROVIDER_IDS,
+}
+export type { AgentMode, EffortLevel, ProviderId, ProviderSettings, ProviderConfig }
+export type { PermissionMode } from '../../schema.js'
diff --git a/src/shell/composables/useSelectionModel.ts b/src/shell/composables/useSelectionModel.ts
index 9b4c455..e3b2554 100644
--- a/src/shell/composables/useSelectionModel.ts
+++ b/src/shell/composables/useSelectionModel.ts
@@ -14,6 +14,10 @@ export interface SelectionData {
   parentComponent?: string
   /** Visible label text, used for agent disambiguation in task context. */
   text?: string
+  /** Set when the selection is an annotask-mounted wireframe placement — the
+   *  eid is the placement container's; file/line are empty (no source exists
+   *  yet) and template-group/source-anchored flows must not run. */
+  instanceId?: string
 }
 
 /**
@@ -103,6 +107,9 @@ export function useSelectionModel(
 
   async function refreshElementRole() {
     if (!primarySelection.value) { selectedElementRole.value = null; return }
+    // Placements have a fixed identity — classification by DOM shape would
+    // mislabel the container div as 'container'/'content'.
+    if (primarySelection.value.instanceId) { selectedElementRole.value = 'placement'; return }
     const classification = await iframe.classifyElement(primarySelection.value.eid)
     selectedElementRole.value = classification?.role || null
   }
diff --git a/src/shell/composables/useShellNavigation.ts b/src/shell/composables/useShellNavigation.ts
index bf92cbe..a143c22 100644
--- a/src/shell/composables/useShellNavigation.ts
+++ b/src/shell/composables/useShellNavigation.ts
@@ -4,12 +4,12 @@ import type { InteractionMode } from './useInteractionMode'
 
 export type ShellView = 'editor' | 'design' | 'develop'
 export type DesignSection = 'tokens' | 'inspector' | 'components'
-export type DevelopSection = 'a11y' | 'data' | 'libraries' | 'perf' | 'errors'
+export type DevelopSection = 'a11y' | 'data' | 'perf' | 'errors'
 export type ActivePanel = 'tasks' | 'inspector'
 
 const SHELL_VIEWS: ShellView[] = ['editor', 'design', 'develop']
 const DESIGN_SECTIONS: DesignSection[] = ['tokens', 'inspector', 'components']
-const DEVELOP_SECTIONS: DevelopSection[] = ['a11y', 'data', 'libraries', 'perf', 'errors']
+const DEVELOP_SECTIONS: DevelopSection[] = ['a11y', 'data', 'perf', 'errors']
 const ACTIVE_PANELS: ActivePanel[] = ['tasks', 'inspector']
 
 const SHELL_VIEW_KEY = 'annotask:shellView'
@@ -25,6 +25,14 @@ function migrateLegacyNavigation(): void {
   try {
     const legacyView = localStorage.getItem(SHELL_VIEW_KEY)
     const legacyPerf = localStorage.getItem(LEGACY_PERF_SECTION_KEY)
+    const legacyDevelop = localStorage.getItem(DEVELOP_SECTION_KEY)
+    if (legacyDevelop === 'libraries') {
+      localStorage.setItem(DEVELOP_SECTION_KEY, 'data')
+    }
+    // The standalone Palette section was merged into Components.
+    if (localStorage.getItem(DESIGN_SECTION_KEY) === 'palette') {
+      localStorage.setItem(DESIGN_SECTION_KEY, 'components')
+    }
     if (!legacyView && !legacyPerf) return
 
     if (legacyView === 'theme') {
diff --git a/src/shell/composables/useStyleEditor.ts b/src/shell/composables/useStyleEditor.ts
index cfe3595..3646c5c 100644
--- a/src/shell/composables/useStyleEditor.ts
+++ b/src/shell/composables/useStyleEditor.ts
@@ -1,10 +1,11 @@
-import { ref, computed, watch } from 'vue'
+import { computed, watch } from 'vue'
 import type { CatalogItem } from '../types'
-import type { AnnotaskReport } from '../../schema'
+import type { AnnotaskReport, WireframeDirectionChange } from '../../schema'
 import { useDesignSpec } from './useDesignSpec'
 import { useViewportPreview } from './useViewportPreview'
 import { useInteractionHistory } from './useInteractionHistory'
 import { send as wsSend } from '../services/wsClient'
+import { useDesignSession, type ShellSessionEntry } from './useDesignSession'
 
 export interface StyleChangeRecord {
   id: string
@@ -44,25 +45,6 @@ export interface InsertChangeRecord {
   placeholderEl?: Element
 }
 
-export interface MoveChangeRecord {
-  id: string
-  type: 'component_move'
-  description: string
-  file: string
-  section: 'template'
-  line: number
-  component?: string
-  mfe?: string
-  element_tag: string
-  from_file: string
-  from_line: number
-  move_to: {
-    target_file: string
-    target_line: number
-    position: 'before' | 'after' | 'append' | 'prepend'
-  }
-}
-
 export interface AnnotationChangeRecord {
   id: string
   type: 'annotation'
@@ -97,22 +79,44 @@ export interface ClassChangeRecord {
   after: { classes: string }
 }
 
-export type ChangeRecord = StyleChangeRecord | ClassChangeRecord | InsertChangeRecord | MoveChangeRecord | AnnotationChangeRecord
+// WireframeDirectionChange rides the same journal (the apply loop's transport)
+// but is invisible to the report/inspector projections: shapeChange has no
+// case for it, and the pending-change UIs filter to style/class.
+export type ChangeRecord = StyleChangeRecord | ClassChangeRecord | InsertChangeRecord | AnnotationChangeRecord | WireframeDirectionChange
 
-const changes = ref<ChangeRecord[]>([])
 let changeCounter = 0
 
-// Map change id → eid for undo/collapse tracking
-const eidRefs = new Map<string, string>()
-
 function broadcast(event: string, data: unknown) {
   wsSend(event, data)
 }
 
+/** Entries the change buffer / report should surface: pending work only.
+ *  'written' edits are in source (re-committing would double-apply),
+ *  'applying' ones are riding an in-flight apply batch, and placement
+ *  entries (instanceId) belong to the wireframe lifecycle — they surface in
+ *  the placements/session panels, never in the Annotate report (placements
+ *  were never report changes before the session existed either). */
+function isReportable(e: ShellSessionEntry): boolean {
+  return (e.live.status === 'pending' || e.live.status === 'failed') && !e.instanceId
+}
+
+/**
+ * The style editor — now a façade over the design-session journal
+ * (useDesignSession). The journal is ordered (append-or-amend: a continuous
+ * gesture amends its entry; a non-adjacent re-edit appends) so session-wide
+ * undo works across styles, classes, and placements. This façade's contract
+ * is FROZEN: the public API, the collapsed `changes` view, the `report`
+ * shape, and the `report:updated`/`changes:cleared` broadcasts feed the
+ * Annotate tab, GET /api/report, and `annotask watch` — its test suite must
+ * pass unmodified.
+ */
 export function useStyleEditor() {
+  const session = useDesignSession()
+
   /**
    * Record a style change. The actual DOM mutation is done by the bridge.
-   * Collapses changes so only one record per eid+property exists.
+   * Collapses changes so only one record per eid+property exists (projection;
+   * the journal keeps gesture-grained entries for ordered undo).
    *
    * If `meta.tokenRole` is set, the change was picked from a design token
    * (e.g. 'primary') and the description/commit message references the
@@ -126,27 +130,19 @@ export function useStyleEditor() {
     meta: { file: string; line: string; component: string; mfe?: string; tokenRole?: string }
   ) {
     const displayValue = meta.tokenRole ? `${meta.tokenRole} (${value})` : value
+    const line = parseInt(meta.line) || 0
+    const description = `Set ${property} to ${displayValue}`
+    const gestureKey = `style|${meta.file}|${line}|${property}|${session.activeBreakpointId.value ?? ''}`
 
-    // Find existing change for this eid + property + source location
-    const existing = changes.value.find(
-      c => c.type === 'style_update' && c.file === meta.file && c.line === (parseInt(meta.line) || 0)
-        && c.property === property && eidRefs.get(c.id) === eid
-    ) as StyleChangeRecord | undefined
-
-    if (existing) {
-      existing.after = value
-      existing.tokenRole = meta.tokenRole
-      existing.description = `Set ${property} to ${displayValue}`
-    } else {
-      changeCounter++
-      const id = `s${changeCounter}`
-      changes.value.push({
-        id,
+    changeCounter++
+    session.record({
+      change: {
+        id: `s${changeCounter}`,
         type: 'style_update',
-        description: `Set ${property} to ${displayValue}`,
+        description,
         file: meta.file,
         section: 'style',
-        line: parseInt(meta.line) || 0,
+        line,
         component: meta.component,
         ...(meta.mfe ? { mfe: meta.mfe } : {}),
         element: 'element', // tag not available here, fine for report
@@ -154,15 +150,25 @@ export function useStyleEditor() {
         before,
         after: value,
         ...(meta.tokenRole ? { tokenRole: meta.tokenRole } : {}),
-      })
-      eidRefs.set(id, eid)
-    }
+      },
+      anchor: { file: meta.file, line, component: meta.component, ...(meta.mfe ? { mfe: meta.mfe } : {}) },
+      eid,
+      amendKey: `${gestureKey}|${eid}`,
+      gestureKey,
+      amendTop: (top) => {
+        if (top.type !== 'style_update') return
+        top.after = value
+        top.tokenRole = meta.tokenRole
+        top.description = description
+      },
+    })
   }
 
   function recordInsert(target: { file: string; line: string; component: string; position: string }, item: CatalogItem): string {
     changeCounter++
     const id = `ci${changeCounter}`
     const isInside = target.position === 'append' || target.position === 'prepend'
+    const line = parseInt(target.line) || 0
 
     const record: InsertChangeRecord = {
       id,
@@ -170,7 +176,7 @@ export function useStyleEditor() {
       description: `Insert <${item.tag}> ${target.position} in ${target.component}`,
       file: target.file,
       section: 'template',
-      line: parseInt(target.line) || 0,
+      line,
       component: target.component,
       insert_inside: isInside ? {
         component: target.component,
@@ -185,7 +191,10 @@ export function useStyleEditor() {
       },
     }
 
-    changes.value.push(record)
+    session.record({
+      change: record,
+      anchor: { file: target.file, line, component: target.component, position: target.position as InsertChangeRecord['insert_position'] },
+    })
     return id
   }
 
@@ -196,13 +205,14 @@ export function useStyleEditor() {
   }): string {
     changeCounter++
     const id = `an${changeCounter}`
+    const line = parseInt(meta.line) || 0
     const record: AnnotationChangeRecord = {
       id,
       type: 'annotation',
       description: meta.intent,
       file: meta.file,
       section: 'template',
-      line: parseInt(meta.line) || 0,
+      line,
       component: meta.component,
       ...(meta.mfe ? { mfe: meta.mfe } : {}),
       intent: meta.intent,
@@ -215,7 +225,10 @@ export function useStyleEditor() {
       },
       pinId: meta.pinId,
     }
-    changes.value.push(record)
+    session.record({
+      change: record,
+      anchor: { file: meta.file, line, targetTag: meta.elementTag, component: meta.component, ...(meta.mfe ? { mfe: meta.mfe } : {}) },
+    })
     return id
   }
 
@@ -226,61 +239,59 @@ export function useStyleEditor() {
     meta: { file: string; line: string; component: string; mfe?: string }
   ): string {
     const lineNum = parseInt(meta.line) || 0
-    const existing = changes.value.find(c => {
-      if (c.type !== 'class_update') return false
-      if (c.file !== meta.file || c.line !== lineNum) return false
-      return eidRefs.get(c.id) === eid
-    }) as ClassChangeRecord | undefined
-
-    if (existing) {
-      existing.after = { classes: afterClasses }
-      existing.description = `Update classes`
-      return existing.id
-    }
+    const gestureKey = `class|${meta.file}|${lineNum}|${session.activeBreakpointId.value ?? ''}`
 
     changeCounter++
-    const id = `cl${changeCounter}`
-    changes.value.push({
-      id,
-      type: 'class_update',
-      description: `Update classes`,
-      file: meta.file,
-      section: 'template',
-      line: lineNum,
-      component: meta.component,
-      ...(meta.mfe ? { mfe: meta.mfe } : {}),
-      element: 'element',
-      before: { classes: beforeClasses },
-      after: { classes: afterClasses },
+    const entry = session.record({
+      change: {
+        id: `cl${changeCounter}`,
+        type: 'class_update',
+        description: `Update classes`,
+        file: meta.file,
+        section: 'template',
+        line: lineNum,
+        component: meta.component,
+        ...(meta.mfe ? { mfe: meta.mfe } : {}),
+        element: 'element',
+        before: { classes: beforeClasses },
+        after: { classes: afterClasses },
+      },
+      anchor: { file: meta.file, line: lineNum, component: meta.component, ...(meta.mfe ? { mfe: meta.mfe } : {}) },
+      eid,
+      amendKey: `${gestureKey}|${eid}`,
+      gestureKey,
+      amendTop: (top) => {
+        if (top.type !== 'class_update') return
+        top.after = { classes: afterClasses }
+        top.description = `Update classes`
+      },
     })
-    eidRefs.set(id, eid)
-    return id
+    return entry.change.id
   }
 
   /**
-   * Undo the last change. Returns undo info so the caller can
-   * delegate the actual DOM revert to the bridge.
+   * Undo the last change (the session journal tail). Returns undo info so the
+   * caller can delegate the actual revert to the bridge — or, for a placement
+   * entry, to the wireframe deletePlacement pipeline.
    */
-  function undo(): { type: string; eid?: string; property?: string; value?: string; classes?: string } | null {
-    if (changes.value.length === 0) return null
+  function undo(): { type: string; eid?: string; property?: string; value?: string; classes?: string; instanceId?: string } | null {
+    const popped = session.popForUndo()
+    if (!popped) return null
+    const c = popped.change
 
-    const last = changes.value.pop()!
-
-    if (last.type === 'style_update') {
-      const eid = eidRefs.get(last.id)
-      eidRefs.delete(last.id)
+    if (c.type === 'style_update') {
       broadcast('report:updated', report.value)
-      return { type: 'style', eid, property: last.property, value: last.before }
-    } else if (last.type === 'class_update') {
-      const eid = eidRefs.get(last.id)
-      eidRefs.delete(last.id)
+      return { type: 'style', eid: popped.eid, property: c.property, value: c.before }
+    } else if (c.type === 'class_update') {
       broadcast('report:updated', report.value)
-      return { type: 'class', eid, classes: last.before.classes }
-    } else if (last.type === 'component_insert') {
-      const eid = eidRefs.get(last.id)
-      eidRefs.delete(last.id)
+      return { type: 'class', eid: popped.eid, classes: c.before.classes }
+    } else if (c.type === 'component_insert') {
       broadcast('report:updated', report.value)
-      return { type: 'insert_remove', eid }
+      if (popped.instanceId) {
+        // Wireframe placement — caller deletes the instance (doc + live node).
+        return { type: 'placement_delete', instanceId: popped.instanceId }
+      }
+      return { type: 'insert_remove', eid: popped.eid }
     }
 
     broadcast('report:updated', report.value)
@@ -288,53 +299,49 @@ export function useStyleEditor() {
   }
 
   function removeChange(id: string) {
-    changes.value = changes.value.filter(c => c.id !== id)
-    eidRefs.delete(id)
+    const entry = session.findByChangeId(id)
+    if (!entry) return
+    // A collapsed projection record stands for its whole amend-group — remove
+    // every entry sharing the key, exactly like removing the single collapsed
+    // record before the journal existed.
+    if (entry.amendKey) {
+      session.removeWhere((e) => e.amendKey === entry.amendKey)
+    } else {
+      session.removeWhere((e) => e.id === entry.id)
+    }
   }
 
   /**
    * Remove all changes for a specific file:line (element).
    * Returns placeholder eids that need to be removed via bridge.
+   * Placement entries are NOT touched — placements belong to the wireframe
+   * lifecycle (deletePlacement / Build / discard), not the change buffer.
    */
   function removeChangesFor(file: string, line: number): string[] {
+    const removed = session.removeWhere((e) => !e.instanceId && e.change.file === file && e.change.line === line)
     const placeholderEids: string[] = []
-    const removed: string[] = []
-    changes.value = changes.value.filter(c => {
-      if (c.file === file && c.line === line) {
-        removed.push(c.id)
-        if (c.type === 'component_insert') {
-          const eid = eidRefs.get(c.id)
-          if (eid) placeholderEids.push(eid)
-        }
-        return false
-      }
-      return true
-    })
-    for (const id of removed) eidRefs.delete(id)
+    for (const e of removed) {
+      if (e.change.type === 'component_insert' && e.eid) placeholderEids.push(e.eid)
+    }
     broadcast('report:updated', report.value)
     return placeholderEids
   }
 
   function removeAnnotationsByFile(file: string, line: number) {
-    changes.value = changes.value.filter(c => {
-      if (c.type !== 'annotation') return true
-      return !(c.file === file && c.line === line)
-    })
+    session.removeWhere((e) => e.change.type === 'annotation' && e.change.file === file && e.change.line === line)
   }
 
   /**
    * Clear all changes. Returns eids of placeholders that need to be removed via bridge.
+   * Placement entries survive (see removeChangesFor) — discarding placements is
+   * the session discard's job.
    */
   function clearChanges(): string[] {
+    const removed = session.removeWhere((e) => !e.instanceId)
     const placeholderEids: string[] = []
-    for (const c of changes.value) {
-      if (c.type === 'component_insert') {
-        const eid = eidRefs.get(c.id)
-        if (eid) placeholderEids.push(eid)
-      }
+    for (const e of removed) {
+      if (e.change.type === 'component_insert' && e.eid) placeholderEids.push(e.eid)
     }
-    changes.value = []
-    eidRefs.clear()
     broadcast('changes:cleared', {})
     return placeholderEids
   }
@@ -365,12 +372,6 @@ export function useStyleEditor() {
         return { ...base, component: c.component, element: c.element, before: c.before, after: c.after }
       case 'component_insert':
         return { ...base, insert_inside: c.insert_inside, insert_position: c.insert_position, component: c.inserted }
-      case 'component_move':
-        return {
-          ...base,
-          element: { tag: c.element_tag, component: c.component, from_file: c.from_file, from_line: c.from_line },
-          move_to: c.move_to,
-        }
       case 'annotation':
         return { ...base, component: c.component, intent: c.intent, action: c.action, context: c.context }
       default:
@@ -378,12 +379,47 @@ export function useStyleEditor() {
     }
   }
 
+  /**
+   * Collapsed pending-change view — one record per amend-group, ordered by
+   * first occurrence, `before` from first touch + `after` from the latest.
+   * This is the projection the Annotate tab, the inspector's selection list,
+   * and commit-as-task consume; the underlying journal stays gesture-grained
+   * for ordered undo.
+   */
+  const changes = computed<ChangeRecord[]>(() => {
+    const visible = session.entries.value.filter(isReportable)
+    const byKey = new Map<string, ShellSessionEntry[]>()
+    const order: string[] = []
+    for (const e of visible) {
+      const key = e.amendKey ?? `solo:${e.id}`
+      const group = byKey.get(key)
+      if (group) {
+        group.push(e)
+      } else {
+        byKey.set(key, [e])
+        order.push(key)
+      }
+    }
+    return order.map((key) => {
+      const group = byKey.get(key)!
+      if (group.length === 1) return group[0].change
+      const first = group[0].change
+      const last = group[group.length - 1].change
+      const collapsed = { ...last } as ChangeRecord
+      if ('before' in collapsed && 'before' in first) {
+        ;(collapsed as { before: unknown }).before = (first as { before: unknown }).before
+      }
+      return collapsed
+    })
+  })
+
   // Collapsed report — no duplicates, only final values
   const report = computed(() => {
     if (changes.value.length === 0) return null
 
     const meaningful = changes.value.filter(c => {
-      if (c.type === 'component_insert' || c.type === 'component_move' || c.type === 'annotation') return true
+      if (c.type === 'component_insert' || c.type === 'annotation') return true
+      if (c.type === 'wireframe_direction') return false // apply-loop transport, never reported
       if (c.type === 'class_update') return c.before.classes !== c.after.classes
       return c.before !== c.after
     })
diff --git a/src/shell/composables/useTabOrderOverlay.ts b/src/shell/composables/useTabOrderOverlay.ts
index e5da0b9..3aa246c 100644
--- a/src/shell/composables/useTabOrderOverlay.ts
+++ b/src/shell/composables/useTabOrderOverlay.ts
@@ -4,14 +4,25 @@
  * native interactives, and DOM/visual reorderings. Synthesizes `tab-order`
  * a11y_fix tasks for any flagged item.
  *
- * Lifecycle: refresh runs once per `enable()` and on each rAF tick while
- * active — no auto-poll between renders, since the user explicitly opted in.
- * Disabling clears the overlay and stops the loop.
+ * Lifecycle: refresh runs once per `enable()` and then on a rAF loop while
+ * active so badges track scroll/resize. Each refresh is a full-DOM
+ * compute:tab-order bridge walk — far too heavy for every animation frame —
+ * so the loop is rate-capped to ~30fps, mirroring useOverlayEngine's
+ * MIN_REFRESH_INTERVAL_MS. Disabling clears the overlay and stops the loop.
  */
 import { ref, watch, type Ref } from 'vue'
 import type { TabOrderEntry, ComputeTabOrderResult } from '../../shared/bridge-types'
 import type { useIframeManager } from './useIframeManager'
 
+// Same cap as useOverlayEngine: rects can go at most one capped interval
+// stale (imperceptible during scroll) while the bridge round-trip cost is
+// roughly halved versus refreshing every animation frame.
+const MIN_REFRESH_INTERVAL_MS = 33
+
+function nowMs(): number {
+  return typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now()
+}
+
 export type TabOrderFlag = 'positive' | 'unreachable' | 'reorder' | null
 
 export interface TabOrderBadge extends TabOrderEntry {
@@ -33,10 +44,12 @@ export function useTabOrderOverlay(deps: {
 
   let loopRunning = false
   let inflight = false
+  let lastRunAt = 0
 
   async function refresh(): Promise<void> {
     if (inflight) return
     inflight = true
+    lastRunAt = nowMs()
     try {
       const result = await iframe.computeTabOrder()
       const flagsByEid = new Map<string, { flag: TabOrderFlag; reason: string }>()
@@ -82,7 +95,8 @@ export function useTabOrderOverlay(deps: {
         requestAnimationFrame(tick)
         return
       }
-      refresh()
+      // Rate-cap the full-DOM bridge walk to ~30fps (see header comment).
+      if (nowMs() - lastRunAt >= MIN_REFRESH_INTERVAL_MS) refresh()
       requestAnimationFrame(tick)
     }
     requestAnimationFrame(tick)
diff --git a/src/shell/composables/useTaskThread.ts b/src/shell/composables/useTaskThread.ts
new file mode 100644
index 0000000..0896749
--- /dev/null
+++ b/src/shell/composables/useTaskThread.ts
@@ -0,0 +1,296 @@
+/**
+ * Client for the per-task conversation thread endpoint.
+ *
+ * Wraps `GET/POST /__annotask/api/tasks/:id/messages` and the SSE stream at
+ * `/messages/stream`. Returns a tiny reactive interface the Conversation tab
+ * binds to:
+ *
+ *   const thread = useTaskThread()
+ *   await thread.open(taskId)         // load snapshot + subscribe
+ *   thread.messages.value             // ShallowRef<ThreadMessage[]>
+ *   await thread.append({...})        // optimistic append
+ *   thread.close()                    // unsubscribe on unmount
+ *
+ * The composable is *not* a singleton — each Conversation tab instance owns
+ * its own subscriber, so opening two tasks at once doesn't cross-wire their
+ * EventSource feeds. The store on the server is the single source of truth
+ * (writes from MCP / CLI agents fan out to all open browser tabs).
+ */
+
+import { ref, shallowRef, computed, type Ref, type ShallowRef } from 'vue'
+import type { WorkStreamBlock } from '../../shared/work-stream'
+
+export type ThreadRole = 'user' | 'assistant' | 'system' | 'tool'
+
+export interface ThreadMessage {
+  id: string
+  ts: number
+  role: ThreadRole
+  content: string
+  providerId?: string
+  model?: string
+  usage?: {
+    inputTokens: number
+    outputTokens: number
+    cacheReadTokens?: number
+    cacheCreationTokens?: number
+  }
+  toolCalls?: Array<{ id: string; name: string; input: unknown }>
+  toolUseId?: string
+  /** Ordered work-stream timeline for the turn. Rendered by the rich UI. */
+  blocks?: WorkStreamBlock[]
+  /** True while the assistant turn is still streaming (updated in place). */
+  isPartial?: boolean
+  /** Wall-clock of the last streamed event for a partial turn. */
+  lastEventAt?: number
+}
+
+export interface AppendInput {
+  role: ThreadRole
+  content: string
+  providerId?: string
+  model?: string
+  usage?: ThreadMessage['usage']
+  blocks?: WorkStreamBlock[]
+  isPartial?: boolean
+  lastEventAt?: number
+}
+
+/** Patchable fields for an in-place message update (streaming a partial turn). */
+export interface UpdateInput {
+  content?: string
+  blocks?: WorkStreamBlock[]
+  usage?: ThreadMessage['usage']
+  isPartial?: boolean
+  lastEventAt?: number
+  model?: string
+  providerId?: string
+}
+
+export type ThreadStatus = 'idle' | 'loading' | 'live' | 'error' | 'reconnecting'
+
+const API_BASE = '/__annotask/api'
+
+export interface UseTaskThread {
+  /** Active task id this thread is bound to. */
+  taskId: Ref<string | null>
+  /** All messages received so far, in order. */
+  messages: ShallowRef<ThreadMessage[]>
+  /** Live status of the SSE connection. */
+  status: Ref<ThreadStatus>
+  /** Latest error string, when status is `error`. */
+  error: Ref<string | null>
+  /** Last seen message id — clients can pass this in `Last-Event-ID` on reconnect. */
+  lastId: Ref<string | null>
+  /** Open the thread for a task: load snapshot then subscribe to live updates. */
+  open(taskId: string): Promise<void>
+  /** Append a message via HTTP. Returns the persisted message. */
+  append(input: AppendInput): Promise<ThreadMessage>
+  /** Patch a message in place (by id). Returns the merged message. */
+  update(id: string, patch: UpdateInput): Promise<ThreadMessage>
+  /** Close the SSE stream. Safe to call repeatedly. */
+  close(): void
+}
+
+export function useTaskThread(): UseTaskThread {
+  const taskId = ref<string | null>(null)
+  const messages = shallowRef<ThreadMessage[]>([])
+  const status = ref<ThreadStatus>('idle')
+  const error = ref<string | null>(null)
+  const lastId = ref<string | null>(null)
+
+  let es: EventSource | null = null
+  // Generation counter — every open() bumps it. Late-arriving fetches from a
+  // previous open() compare against the current generation and bail out.
+  let generation = 0
+  // Give-up after this many consecutive reconnect failures so the user gets an
+  // actionable error instead of a silently-frozen timeline forever. Reset on a
+  // successful (re)connect and on each fresh open().
+  const MAX_RECONNECT_ATTEMPTS = 6
+  let reconnectAttempts = 0
+
+  function pushMessage(msg: ThreadMessage) {
+    // Upsert by id. A partial assistant turn arrives once on append and then
+    // repeatedly via update() / the SSE echo of each in-place rewrite —
+    // replacing the existing entry lets the timeline grow live. For a brand
+    // new id we append. (Also dedupes the SSE replay after a reconnect.)
+    const idx = messages.value.findIndex((m) => m.id === msg.id)
+    if (idx >= 0) {
+      const next = messages.value.slice()
+      next[idx] = msg
+      messages.value = next
+      return
+    }
+    messages.value = [...messages.value, msg]
+    lastId.value = msg.id
+  }
+
+  function reset() {
+    messages.value = []
+    lastId.value = null
+    error.value = null
+  }
+
+  function close() {
+    if (es) {
+      try { es.close() } catch { /* ignore */ }
+      es = null
+    }
+    status.value = 'idle'
+  }
+
+  async function open(id: string): Promise<void> {
+    const gen = ++generation
+    close()
+    taskId.value = id
+    reset()
+    reconnectAttempts = 0
+    status.value = 'loading'
+    try {
+      const res = await fetch(`${API_BASE}/tasks/${encodeURIComponent(id)}/messages`)
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const body = (await res.json()) as { messages?: ThreadMessage[] }
+      if (gen !== generation) return // raced with another open()
+      const list = Array.isArray(body.messages) ? body.messages : []
+      messages.value = list
+      lastId.value = list.length > 0 ? list[list.length - 1].id : null
+    } catch (err) {
+      if (gen !== generation) return
+      status.value = 'error'
+      error.value = `Failed to load conversation: ${(err as Error).message}`
+      return
+    }
+
+    // Subscribe to live updates. EventSource forwards Last-Event-ID itself
+    // on reconnect; we seed the initial replay via `?after=` so the server
+    // doesn't have to re-send what we already pulled in the snapshot.
+    const url = `${API_BASE}/tasks/${encodeURIComponent(id)}/messages/stream${lastId.value ? `?after=${encodeURIComponent(lastId.value)}` : ''}`
+    try {
+      es = new EventSource(url)
+    } catch (err) {
+      status.value = 'error'
+      error.value = `Failed to open stream: ${(err as Error).message}`
+      return
+    }
+    es.addEventListener('message', (ev: MessageEvent<string>) => {
+      try {
+        const msg = JSON.parse(ev.data) as ThreadMessage
+        pushMessage(msg)
+      } catch { /* ignore malformed frames */ }
+    })
+    es.addEventListener('open', () => { reconnectAttempts = 0; status.value = 'live'; error.value = null })
+    es.addEventListener('error', () => {
+      reconnectAttempts += 1
+      if (reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+        // Stop the indefinite silent reconnect and surface an actionable error.
+        close()
+        status.value = 'error'
+        error.value = 'Lost connection to the conversation stream. Click retry.'
+        return
+      }
+      // EventSource auto-reconnects; surface the state but don't tear down.
+      status.value = 'reconnecting'
+    })
+  }
+
+  async function append(input: AppendInput): Promise<ThreadMessage> {
+    const id = taskId.value
+    if (!id) throw new Error('Thread is not open')
+    const res = await fetch(`${API_BASE}/tasks/${encodeURIComponent(id)}/messages`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        role: input.role,
+        content: input.content,
+        providerId: input.providerId,
+        model: input.model,
+        usage: input.usage,
+        blocks: input.blocks,
+        isPartial: input.isPartial,
+        lastEventAt: input.lastEventAt,
+      }),
+    })
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`Append failed (HTTP ${res.status}): ${text.slice(0, 200)}`)
+    }
+    const msg = (await res.json()) as ThreadMessage
+    // The SSE stream will also deliver this message (via the server's
+    // broadcast) but the upsert in pushMessage tolerates both paths so the
+    // composer can show it immediately without waiting for the round-trip.
+    pushMessage(msg)
+    return msg
+  }
+
+  async function update(id: string, patch: UpdateInput): Promise<ThreadMessage> {
+    const tid = taskId.value
+    if (!tid) throw new Error('Thread is not open')
+    const res = await fetch(
+      `${API_BASE}/tasks/${encodeURIComponent(tid)}/messages/${encodeURIComponent(id)}`,
+      {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(patch),
+      },
+    )
+    if (!res.ok) {
+      const text = await res.text().catch(() => '')
+      throw new Error(`Update failed (HTTP ${res.status}): ${text.slice(0, 200)}`)
+    }
+    const msg = (await res.json()) as ThreadMessage
+    pushMessage(msg)
+    return msg
+  }
+
+  return { taskId, messages, status, error, lastId, open, append, update, close }
+}
+
+/**
+ * Convenience: return the active provider config snapshot probe needed by
+ * `useEmbeddedAgent` and the Conversation tab's empty state. Kept here so
+ * the Conversation tab doesn't have to know about the agent-detect schema.
+ */
+export interface AgentDetectSnapshot {
+  'claude-local': { found: boolean; loggedIn?: boolean; version?: string }
+  'codex-local': { found: boolean; loggedIn?: boolean; version?: string }
+  'opencode-local': { found: boolean; loggedIn?: boolean; version?: string }
+  'copilot-local': { found: boolean; loggedIn?: boolean; version?: string }
+  copilot: { found: boolean; loggedIn?: boolean; version?: string }
+  openrouter: { hasEnv: boolean }
+  ts: number
+}
+
+const detectCache = ref<AgentDetectSnapshot | null>(null)
+const detectLoading = ref(false)
+
+/** Detect what local CLIs are installed. Cached for the lifetime of the page. */
+export async function fetchAgentDetect(force = false): Promise<AgentDetectSnapshot | null> {
+  if (!force && detectCache.value) return detectCache.value
+  if (detectLoading.value) {
+    // Wait for in-flight probe — simple busy-wait loop, fine because the
+    // server-side probe is 30s-cached and fast.
+    while (detectLoading.value) await new Promise((r) => setTimeout(r, 50))
+    return detectCache.value
+  }
+  detectLoading.value = true
+  try {
+    const res = await fetch(`${API_BASE}/agent/detect`)
+    if (!res.ok) return null
+    const snap = (await res.json()) as AgentDetectSnapshot
+    detectCache.value = snap
+    return snap
+  } catch {
+    return null
+  } finally {
+    detectLoading.value = false
+  }
+}
+
+/** Reactive accessor — Conversation tab binds to this for the empty state. */
+export function useAgentDetect() {
+  return {
+    snapshot: computed(() => detectCache.value),
+    loading: computed(() => detectLoading.value),
+    refresh: () => fetchAgentDetect(true),
+  }
+}
diff --git a/src/shell/composables/useTaskWorkflows.ts b/src/shell/composables/useTaskWorkflows.ts
index 2e33f4f..5c867ea 100644
--- a/src/shell/composables/useTaskWorkflows.ts
+++ b/src/shell/composables/useTaskWorkflows.ts
@@ -11,6 +11,8 @@ import type { SelectionData } from './useSelectionModel'
 import type { Task } from './useTasks'
 import { resolveForSelection, resolveForElement, type DataContextProbeResult } from '../services/dataContextClient'
 import { useComponentContextCapture } from './useComponentContextCapture'
+import { useProviderSettings } from './useProviderSettings'
+import { requestAutoRun } from './useAgentMode'
 
 export interface PendingTaskContext {
   kind: 'pin' | 'arrow' | 'highlight' | 'select'
@@ -54,11 +56,9 @@ export function useTaskWorkflows(deps: {
   const detailTaskId = ref<string | null>(null)
   const confirmDeleteTaskId = ref<string | null>(null)
   const detailTask = computed(() => detailTaskId.value ? deps.taskSystem.tasks.value.find(t => t.id === detailTaskId.value) ?? null : null)
-  const sectionTaskMap = ref<Record<string, string>>({})
   const arrowDragTargetRect = ref<{ x: number; y: number; width: number; height: number } | null>(null)
   let arrowDragResolveTimer: ReturnType<typeof setTimeout> | null = null
   const arrowTaskIds = new Set<string>()
-  const sectionSubmitInFlight = new Set<string>()
   const restoredTaskIds = new Set<string>()
   const componentContextCapture = useComponentContextCapture(deps.iframe)
 
@@ -77,12 +77,6 @@ export function useTaskWorkflows(deps: {
           Math.abs(a.fromX - v.fromX) < 5 && Math.abs(a.fromY - v.fromY) < 5
         )
         if (arrow) deps.annotations.removeArrow(arrow.id)
-      } else if (v.kind === 'section') {
-        if (v.annotationId) deps.annotations.removeDrawnSection(v.annotationId)
-        const section = deps.annotations.drawnSections.value.find((s: any) =>
-          Math.abs(s.x - v.x) < 5 && Math.abs(s.y - v.y) < 5
-        )
-        if (section) deps.annotations.removeDrawnSection(section.id)
       } else if (v.kind === 'highlight') {
         if (v.annotationId) deps.annotations.removeHighlight(v.annotationId)
         const ctx = task.context || {}
@@ -176,9 +170,22 @@ export function useTaskWorkflows(deps: {
       const dc = await resolveForSelection(denyFile, denyLine)
       if (dc) extra.data_context = dc
     }
-    deps.taskSystem.updateTaskStatus(taskId, 'denied', denyFeedbackText.value.trim(), Object.keys(extra).length > 0 ? extra : undefined)
+    await deps.taskSystem.updateTaskStatus(taskId, 'denied', denyFeedbackText.value.trim(), Object.keys(extra).length > 0 ? extra : undefined)
     denyingTaskId.value = null
     denyFeedbackText.value = ''
+    // Auto-mode retry: hand the denied task (now carrying the user's
+    // feedback) back to the auto-run driver so the agent gets another
+    // pass without the user having to click anything. Same readiness gate
+    // as the create path — if embedded mode is off, agentMode is manual,
+    // or no provider is ready, the deny just sits there for manual retry.
+    const providerSettings = useProviderSettings()
+    if (
+      providerSettings.settings.value.embeddedAgentEnabled === true
+      && providerSettings.settings.value.agentMode === 'auto'
+      && providerSettings.ready.value
+    ) {
+      requestAutoRun(taskId)
+    }
   }
 
   function submitNewTask() {
@@ -274,41 +281,21 @@ export function useTaskWorkflows(deps: {
           body: JSON.stringify({ html: frag.rendered }),
         }).catch(() => { /* best-effort */ })
       }
-    }
-    return task
-  }
-
-  async function onSectionSubmit(id: string) {
-    if (sectionSubmitInFlight.has(id)) return
-    const section = deps.annotations.drawnSections.value.find(s => s.id === id)
-    if (!section || !section.prompt.trim()) return
-    sectionSubmitInFlight.add(id)
-    try {
-      const existingTaskId = sectionTaskMap.value[id]
-      if (existingTaskId) {
-        await deps.taskSystem.updateTask(existingTaskId, { description: section.prompt.trim() })
-        return
+      // Agent-mode auto-run. Only `auto` mode hands tasks off automatically;
+      // `manual` waits for the user to click Run-with-agent, and `off`
+      // hides the in-shell chat entirely (terminal/MCP only). The send()
+      // fires inside ConversationTab.vue once it mounts — we just enqueue
+      // the id here so the watcher in App.vue opens the right modal.
+      const providerSettings = useProviderSettings()
+      if (
+        providerSettings.settings.value.embeddedAgentEnabled === true
+        && providerSettings.settings.value.agentMode === 'auto'
+        && providerSettings.ready.value
+      ) {
+        requestAutoRun(task.id)
       }
-      deps.styleEditor.recordAnnotation({
-        file: section.nearFile || '',
-        line: String(section.nearLine || 0),
-        component: section.nearComponent || '',
-        intent: section.prompt.trim(),
-        action: 'section_request',
-      })
-      const task = await createRouteTask({
-        type: 'section_request',
-        description: section.prompt.trim(),
-        file: section.nearFile || undefined,
-        line: section.nearLine || undefined,
-        component: section.nearComponent || undefined,
-        placement: section.placement || undefined,
-        visual: { kind: 'section', annotationId: section.id, x: Math.round(section.x), y: Math.round(section.y), width: Math.round(section.width), height: Math.round(section.height), nearEid: section.nearEid },
-      })
-      if (task) sectionTaskMap.value = { ...sectionTaskMap.value, [id]: task.id }
-    } finally {
-      sectionSubmitInFlight.delete(id)
     }
+    return task
   }
 
   function onArrowDragMove(x: number, y: number) {
@@ -372,14 +359,11 @@ export function useTaskWorkflows(deps: {
     return `<${tag}>${label}`
   }
 
-  /** Remove any uncommitted annotation (pending pin/arrow/highlight or orphan section). */
+  /** Remove any uncommitted annotation (pending pin/arrow/highlight). */
   function discardUncommittedAnnotations() {
     if (pendingTaskCreation.value && pendingTaskCreation.value.kind !== 'select') {
       cancelPendingTask()
     }
-    for (const s of [...deps.annotations.drawnSections.value]) {
-      if (!sectionTaskMap.value[s.id]) deps.annotations.removeDrawnSection(s.id)
-    }
   }
 
   function onArrowCreated(arrowId: string, fromCtx: { file: string; line: string; component: string; tag: string; classes?: string; text?: string } | null, toCtx: { file: string; line: string; component: string; tag: string; classes?: string; text?: string } | null) {
@@ -413,10 +397,10 @@ export function useTaskWorkflows(deps: {
     pendingTaskText.value = ''
   }
 
-  async function submitPendingArrowTask(id: string, description: string) {
+  async function submitPendingArrowTask(id: string, description: string): Promise<Task | null> {
     const arrow = deps.annotations.arrows.value.find(a => a.id === id)
-    if (!arrow || !description.trim()) return
-    if (arrowTaskIds.has(id)) return
+    if (!arrow || !description.trim()) return null
+    if (arrowTaskIds.has(id)) return null
     arrowTaskIds.add(id)
 
     deps.annotations.updateArrow(id, { label: description.trim() })
@@ -434,7 +418,7 @@ export function useTaskWorkflows(deps: {
     const toText = (meta.toText as string) || ''
     const fromCC = arrow.fromEid ? await componentContextCapture.capture(arrow.fromEid) : {}
     const toCC = arrow.toEid ? await componentContextCapture.capture(arrow.toEid) : {}
-    createRouteTask({
+    const task = await createRouteTask({
       type: 'annotation',
       description: description.trim(),
       file: arrow.fromFile || '',
@@ -460,6 +444,10 @@ export function useTaskWorkflows(deps: {
 
       },
     })
+    // Failed creation (400/network): release the dedup guard so the user can
+    // retry the same arrow after fixing whatever the server rejected.
+    if (!task) arrowTaskIds.delete(id)
+    return task
   }
 
   async function submitPendingTask() {
@@ -470,6 +458,11 @@ export function useTaskWorkflows(deps: {
 
     submittingPendingTask.value = true
     try {
+      // Track the created task per branch — a null result (server 400 or
+      // network failure) must keep the user's typed draft in the panel so
+      // they can retry without retyping. useTasks().lastError carries the
+      // reason for the UI to surface.
+      let created: Task | null = null
       if (ctx.kind === 'pin') {
         const meta = ctx.meta as { elementTag: string; elementClasses: string; pinX: number; pinY: number; elementText?: string; elementSourceTag?: string }
         deps.annotations.updatePinNote(ctx.annotationId!, description)
@@ -478,7 +471,7 @@ export function useTaskWorkflows(deps: {
           intent: description,
           elementTag: meta.elementTag, elementClasses: meta.elementClasses,
         })
-        await createRouteTask({
+        created = await createRouteTask({
           type: 'annotation',
           description,
           file: ctx.file, line: parseInt(String(ctx.line)) || 0, component: ctx.component,
@@ -491,7 +484,7 @@ export function useTaskWorkflows(deps: {
           },
         })
       } else if (ctx.kind === 'arrow') {
-        await submitPendingArrowTask(ctx.annotationId!, description)
+        created = await submitPendingArrowTask(ctx.annotationId!, description)
       } else if (ctx.kind === 'highlight') {
         const meta = ctx.meta as { selectedText: string; elementTag: string; elementSourceTag?: string }
         deps.annotations.updateHighlight(ctx.annotationId!, { prompt: description })
@@ -501,7 +494,7 @@ export function useTaskWorkflows(deps: {
           file: ctx.file, line: String(ctx.line), component: ctx.component,
           intent, action: 'text_edit', elementTag: meta.elementTag,
         })
-        await createRouteTask({
+        created = await createRouteTask({
           type: 'annotation', description: intent, file: ctx.file, line: parseInt(String(ctx.line)) || 0,
           component: ctx.component, action: 'text_edit',
           visual: { kind: 'highlight', annotationId: ctx.annotationId, eid: hl?.eid, rect: hl?.rect, rects: hl?.rects, color: hl?.color },
@@ -530,10 +523,15 @@ export function useTaskWorkflows(deps: {
           deps.taskElementRects.value = [...deps.taskElementRects.value, ...currentRects.map(rect => ({ taskId: task.id, rect }))]
           deps.startAnnotationLoop()
         }
+        created = task
       }
 
-      pendingTaskCreation.value = null
-      pendingTaskText.value = ''
+      // Only a successful creation clears the draft and closes the panel.
+      // On failure the annotation + typed description stay put for a retry.
+      if (created) {
+        pendingTaskCreation.value = null
+        pendingTaskText.value = ''
+      }
     } finally {
       submittingPendingTask.value = false
     }
@@ -652,16 +650,6 @@ export function useTaskWorkflows(deps: {
           ...(toEl.file ? { toFile: toEl.file as string } : {}),
           ...(toEl.line ? { toLine: toEl.line as number } : {}),
         })
-      } else if (v.kind === 'section') {
-        const section = deps.annotations.addDrawnSection(v.x, v.y, v.width, v.height)
-        section.route = taskRoute
-        if ((task as any).prompt || task.description) {
-          deps.annotations.updateDrawnSection(section.id, {
-            prompt: (task as any).prompt || task.description,
-            nearFile: task.file, nearLine: task.line,
-          })
-        }
-        sectionTaskMap.value = { ...sectionTaskMap.value, [section.id]: task.id }
       } else if (v.kind === 'highlight') {
         const ctx = (task as any).context || {}
         const hl = deps.annotations.addHighlight(
@@ -686,9 +674,6 @@ export function useTaskWorkflows(deps: {
       if (!a.fromEid && a.fromFile && a.fromLine) return true
       if (!a.toEid && a.toFile && a.toLine) return true
     }
-    for (const s of deps.annotations.drawnSections.value) {
-      if (!s.nearEid && s.nearFile && s.nearLine) return true
-    }
     for (const h of deps.annotations.highlights.value) {
       if (!h.eid && h.file && h.line) return true
     }
@@ -736,16 +721,6 @@ export function useTaskWorkflows(deps: {
       }
     }
 
-    // Restored drawn sections
-    for (const section of deps.annotations.drawnSections.value) {
-      if (!section.nearEid && section.nearFile && section.nearLine) {
-        const g = await deps.iframe.findTemplateGroup(section.nearFile, String(section.nearLine), '')
-        if (g.eids.length > 0) {
-          deps.annotations.updateDrawnSection(section.id, { nearEid: g.eids[0] })
-        }
-      }
-    }
-
     // Restored text highlights
     for (const hl of deps.annotations.highlights.value) {
       if (!hl.eid && hl.file && hl.line) {
@@ -806,13 +781,12 @@ export function useTaskWorkflows(deps: {
     denyingTaskId, denyFeedbackText,
     detailTaskId, detailTask,
     confirmDeleteTaskId,
-    sectionTaskMap, arrowDragTargetRect,
+    arrowDragTargetRect,
     restoredTaskIds,
     discardUncommittedAnnotations,
     removeTaskAnnotations, executeDeleteTask,
     acceptTask, submitDeny, submitNewTask,
     createRouteTask,
-    onSectionSubmit,
     onArrowDragMove, onArrowDragEnd,
     describeElement, onArrowCreated,
     submitPendingTask, cancelPendingTask,
diff --git a/src/shell/composables/useTasks.ts b/src/shell/composables/useTasks.ts
index 8fd76b6..15cddfa 100644
--- a/src/shell/composables/useTasks.ts
+++ b/src/shell/composables/useTasks.ts
@@ -5,8 +5,34 @@ import type { AnnotaskTask, AgentFeedbackQuestion, AgentFeedbackEntry } from '..
 export type Task = AnnotaskTask
 export type { AgentFeedbackQuestion, AgentFeedbackEntry }
 
+export interface TaskApiError {
+  code: string
+  message: string
+}
+
 const tasks = ref<Task[]>([])
 const isLoading = ref(false)
+/**
+ * Last failed task mutation, or null after a success. The server rejects
+ * bad payloads with a 400 (e.g. SafeSourceFile refusing a URL-shaped file
+ * path) — before this ref existed those failures were silently swallowed
+ * and the error body was returned as if it were the created task. UI
+ * surfaces (pending task panel, App) read this to tell the user what
+ * actually went wrong.
+ */
+const lastError = ref<TaskApiError | null>(null)
+
+/** Parse the server's `{ error: { code, message } }` body (sendError in
+ *  api.ts); fall back to the HTTP status for non-JSON bodies. */
+async function readApiError(res: Response): Promise<TaskApiError> {
+  try {
+    const body = await res.json()
+    if (body?.error?.code && body?.error?.message) {
+      return { code: String(body.error.code), message: String(body.error.message) }
+    }
+  } catch { /* non-JSON body */ }
+  return { code: 'http_error', message: `HTTP ${res.status}` }
+}
 
 async function fetchTasks() {
   try {
@@ -25,28 +51,60 @@ async function createTask(task: Partial<Task>): Promise<Task | null> {
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(task),
     })
+    if (!res.ok) {
+      lastError.value = await readApiError(res)
+      console.error(`[Annotask] createTask failed (${lastError.value.code}): ${lastError.value.message}`)
+      return null
+    }
+    lastError.value = null
     const created = await res.json()
     await fetchTasks()
     return created
-  } catch { return null }
+  } catch {
+    lastError.value = { code: 'network_error', message: 'Could not reach the Annotask server' }
+    console.error('[Annotask] createTask failed: server unreachable')
+    return null
+  }
 }
 
-async function updateTask(id: string, updates: Record<string, unknown>) {
+async function updateTask(id: string, updates: Record<string, unknown>): Promise<boolean> {
   try {
-    await fetch(`/__annotask/api/tasks/${id}`, {
+    const res = await fetch(`/__annotask/api/tasks/${id}`, {
       method: 'PATCH',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify(updates),
     })
+    if (!res.ok) {
+      lastError.value = await readApiError(res)
+      console.error(`[Annotask] updateTask failed (${lastError.value.code}): ${lastError.value.message}`)
+      return false
+    }
+    lastError.value = null
     await fetchTasks()
-  } catch {}
+    return true
+  } catch {
+    lastError.value = { code: 'network_error', message: 'Could not reach the Annotask server' }
+    console.error('[Annotask] updateTask failed: server unreachable')
+    return false
+  }
 }
 
-async function deleteTask(id: string) {
+async function deleteTask(id: string): Promise<boolean> {
   try {
-    await fetch(`/__annotask/api/tasks/${id}`, { method: 'DELETE' })
+    const res = await fetch(`/__annotask/api/tasks/${id}`, { method: 'DELETE' })
+    if (!res.ok) {
+      lastError.value = await readApiError(res)
+      console.error(`[Annotask] deleteTask failed (${lastError.value.code}): ${lastError.value.message}`)
+      return false
+    }
+    lastError.value = null
     await fetchTasks()
-  } catch {}
+    return true
+  } catch {
+    lastError.value = { code: 'network_error', message: 'Could not reach the Annotask server' }
+    console.error('[Annotask] deleteTask failed: server unreachable')
+    return false
+  }
 }
 
 async function updateTaskStatus(id: string, status: Task['status'], feedback?: string, extra?: Record<string, unknown>) {
@@ -74,6 +132,10 @@ export function useTasks() {
       const d = data as { tasks?: Task[] }
       tasks.value = d?.tasks || []
     })
+    // While the socket is down we miss every tasks:updated broadcast (agents
+    // keep mutating tasks via MCP/CLI regardless). Resync over HTTP as soon
+    // as the connection comes back.
+    wsOn('reconnected', () => { void fetchTasks() })
   }
 
   const pendingTasks = computed(() => tasks.value.filter(t => t.status === 'pending'))
@@ -84,7 +146,7 @@ export function useTasks() {
 
   return {
     tasks, pendingTasks, reviewTasks, deniedTasks, needsInfoTasks, blockedTasks,
-    isLoading,
+    isLoading, lastError,
     createTask, updateTask, deleteTask, updateTaskStatus, respondToAgent,
     fetchTasks,
   }
diff --git a/src/shell/composables/useWireframeCanvas.ts b/src/shell/composables/useWireframeCanvas.ts
new file mode 100644
index 0000000..29a9a0c
--- /dev/null
+++ b/src/shell/composables/useWireframeCanvas.ts
@@ -0,0 +1,267 @@
+import { ref, computed, watch, type Ref } from 'vue'
+import { usePaletteDrag } from './usePaletteDrag'
+import { useWireframeDoc, type WireframeIframe } from './useWireframeDoc'
+import { useDesignSession } from './useDesignSession'
+import { normalizeRoute } from '../utils/routes'
+import type { DropIndicatorRect } from '../types'
+import type { InsertChangeRecord } from './useStyleEditor'
+import type { WireframeInstance, WireframeFidelity } from '../../shared/wireframe-types'
+import type { ResolvedElement, InsertVueComponentResult } from '../../shared/bridge-types'
+
+/** The iframe surface the wireframe canvas needs — structural so tests can
+ *  pass a small mock; useIframeManager's return satisfies it. */
+export interface WireframeCanvasIframe extends WireframeIframe {
+  currentRoute: Ref<string>
+  bridgeReady: Ref<boolean>
+  resolveElementAt: (shellX: number, shellY: number) => Promise<ResolvedElement | null>
+  insertComponent: (targetEid: string, position: string, componentName: string, props?: Record<string, unknown>, module?: string, instanceId?: string) => Promise<InsertVueComponentResult>
+  removePlaceholder: (eid: string) => Promise<void>
+}
+
+export interface WireframeCanvasDeps {
+  iframe: WireframeCanvasIframe
+  /** Task creation goes through useTaskWorkflows so wireframe tasks pick up
+   *  route/viewport/color-scheme enrichment like every other task type. */
+  createRouteTask: (data: Record<string, unknown>) => Promise<{ id: string } | null>
+}
+
+/**
+ * Wireframe canvas pipeline — the drop shield handlers (palette drag-over
+ * throttle + drop indicator + instance construction/persistence), the Build
+ * collector, placement deletion, and the bridgeReady/route reapply watchers.
+ * Extracted from App.vue per the shell architecture rule: App.vue
+ * orchestrates, composables own behavior.
+ */
+export function useWireframeCanvas(deps: WireframeCanvasDeps) {
+  const { iframe } = deps
+  const { currentRoute } = iframe
+
+  const paletteDrag = usePaletteDrag()
+  const wireframeDoc = useWireframeDoc()
+  const session = useDesignSession()
+  // instanceId → live container eid, populated on drop + on reapply. Runtime
+  // only (container eids are session-volatile). deletePlacement reads it to
+  // unmount the live node; reapply repopulates it after reload/route change.
+  const containerEids = new Map<string, string>()
+  function registerContainer(instanceId: string, containerEid: string): void {
+    containerEids.set(instanceId, containerEid)
+  }
+  const dropIndicator = ref<DropIndicatorRect | null>(null)
+  // dragover fires at high frequency; throttle the resolve round-trip (~30fps)
+  // and guard against re-entrant in-flight requests, like the overlay engine.
+  let lastDragResolveAt = 0
+  let dragResolveInFlight = false
+
+  function dropPositionFor(rect: { y: number; height: number }, clientY: number): 'before' | 'after' | 'append' {
+    const rel = (clientY - rect.y) / Math.max(rect.height, 1)
+    if (rel < 0.25) return 'before'
+    if (rel > 0.75) return 'after'
+    return 'append'
+  }
+
+  async function onPaletteDragOver(e: DragEvent): Promise<void> {
+    if (!paletteDrag.draggingItem.value) return
+    const now = Date.now()
+    if (dragResolveInFlight || now - lastDragResolveAt < 33) return
+    lastDragResolveAt = now
+    dragResolveInFlight = true
+    try {
+      const hit = await iframe.resolveElementAt(e.clientX, e.clientY)
+      // A mounted placement is not a drop target: it has no source anchor yet,
+      // so a drop relative to it could not be expressed in real source.
+      if (!hit || hit.instance_id) { dropIndicator.value = null; return }
+      dropIndicator.value = {
+        x: hit.rect.x, y: hit.rect.y, width: hit.rect.width, height: hit.rect.height,
+        position: dropPositionFor(hit.rect, e.clientY),
+      }
+    } finally {
+      dragResolveInFlight = false
+    }
+  }
+
+  function onPaletteDragLeave(): void {
+    dropIndicator.value = null
+  }
+
+  async function onPaletteDrop(e: DragEvent): Promise<void> {
+    const item = paletteDrag.draggingItem.value
+    paletteDrag.endDrag()
+    dropIndicator.value = null
+    if (!item) return
+    const hit = await iframe.resolveElementAt(e.clientX, e.clientY)
+    if (!hit || hit.instance_id) return
+    const position = dropPositionFor(hit.rect, e.clientY)
+
+    // Generate the instance id up front so it can be stamped on the mounted node
+    // (data-annotask-instance) — placement identity for click/selection,
+    // drop-target refusal, capture exclusion, and reapply's idempotency probe.
+    const instanceId = `wfi-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`
+    // Components live-mount (honest fidelity from the bridge). HTML / layout
+    // presets render through insert:placeholder (createPlaceholder styles them) —
+    // never through insert:component, which would leave an empty div.
+    let fidelity: WireframeFidelity = 'placeholder'
+    let containerEid = ''
+    if (item.kind === 'component') {
+      // Mount with sample props (display) + on-demand module load; persist the
+      // REAL props (item.props) below, not the sample ones.
+      const res = await iframe.insertComponent(hit.eid, position, item.componentName, item.previewProps ?? item.props, item.module, instanceId)
+      fidelity = res.fidelity ?? (res.mounted ? 'live' : 'placeholder')
+      containerEid = res.eid
+    } else {
+      containerEid = await iframe.insertPlaceholder(hit.eid, position, item.tag, {
+        classes: item.classes,
+        textContent: item.textContent,
+        category: item.category,
+        library: item.library,
+        defaultProps: item.props,
+        instanceId,
+      })
+    }
+    if (containerEid) registerContainer(instanceId, containerEid)
+
+    const instance: WireframeInstance = {
+      id: instanceId,
+      kind: item.kind,
+      anchor: {
+        file: hit.file,
+        line: parseInt(hit.line, 10) || 0,
+        position,
+        component: hit.component,
+        targetTag: hit.tag,
+        targetEid: hit.eid,
+      },
+      inserted: {
+        tag: item.tag,
+        componentName: item.kind === 'component' ? item.componentName : undefined,
+        library: item.library,
+        module: item.module,
+        props: item.props,
+        classes: item.classes,
+        text_content: item.textContent,
+      },
+      fidelity,
+      mounted: item.kind === 'component' ? fidelity !== 'placeholder' : true,
+      status: 'placed',
+      // Persist the previewed samples separately from the real props: reapply
+      // re-mounts with them, and the agent reads them as label/value hints.
+      ...(item.previewProps ? { previewProps: item.previewProps } : {}),
+      createdAt: Date.now(),
+    }
+    void wireframeDoc.saveInstance(normalizeRoute(currentRoute.value), instance)
+
+    // Journal the placement so session-wide undo can interleave it with style
+    // edits. Cross-reference only — wireframe.json stays the canonical artifact
+    // (the entry never duplicates the instance payload beyond the insert shape).
+    const placeChange: InsertChangeRecord = {
+      id: `wf-${instanceId}`,
+      type: 'component_insert',
+      description: `Place <${item.kind === 'component' ? item.componentName : item.tag}> ${position} ${hit.component || hit.tag}`,
+      file: hit.file,
+      section: 'template',
+      line: parseInt(hit.line, 10) || 0,
+      component: hit.component,
+      insert_position: position,
+      inserted: instance.inserted,
+    }
+    session.record({
+      change: placeChange,
+      anchor: { file: hit.file, line: parseInt(hit.line, 10) || 0, targetTag: hit.tag, component: hit.component, position },
+      route: normalizeRoute(currentRoute.value),
+      ...(containerEid ? { eid: containerEid } : {}),
+      instanceId,
+    })
+  }
+
+  // Placements on the current route — drives the palette's placements panel.
+  const wireframePlacements = computed(() => wireframeDoc.instancesForRoute(normalizeRoute(currentRoute.value)))
+  // Only never-built placements are buildable; building/applied ones already
+  // belong to a task (the panel shows them with their status chip instead).
+  const placedCount = computed(() => wireframePlacements.value.filter((i) => (i.status ?? 'placed') === 'placed').length)
+
+  // Turn the current route's PLACED instances into ONE wireframe_apply task the
+  // agent implements via /annotask-apply, then stamp them 'building' against
+  // that task. The dominant anchor file (the route's page component) is the
+  // task-level anchor; per-instance anchors live in the context.
+  const isBuilding = ref(false)
+  async function buildWireframeRoute(): Promise<void> {
+    // Re-entrancy guard: without it a double-click collects the same 'placed'
+    // batch twice before the first build's 'building' stamp persists.
+    if (isBuilding.value) return
+    const route = normalizeRoute(currentRoute.value)
+    const instances = wireframeDoc.instancesForRoute(route).filter((i) => (i.status ?? 'placed') === 'placed')
+    if (instances.length === 0) return
+    isBuilding.value = true
+    try {
+      const fileCounts = new Map<string, number>()
+      for (const i of instances) fileCounts.set(i.anchor.file, (fileCounts.get(i.anchor.file) ?? 0) + 1)
+      let domFile = instances[0].anchor.file
+      let domCount = -1
+      for (const [f, c] of fileCounts) if (c > domCount) { domFile = f; domCount = c }
+      const domLine = instances.find((i) => i.anchor.file === domFile)?.anchor.line ?? 0
+      const summaryLines = instances.map((i) => {
+        const what = i.kind === 'component' ? (i.inserted.componentName ?? i.inserted.tag) : i.inserted.tag
+        return `- <${what}> ${i.anchor.position} ${i.anchor.component || i.anchor.targetTag || 'target'}`
+      })
+      const description = `Implement ${instances.length} placement${instances.length === 1 ? '' : 's'} on ${route}:\n${summaryLines.join('\n')}`
+      const task = await deps.createRouteTask({
+        type: 'wireframe_apply',
+        description,
+        file: domFile,
+        line: domLine,
+        context: { wireframe: { route, instances } },
+      })
+      // Stamp ONLY on success — a failed POST leaves the batch 'placed' so the
+      // user can retry Build instead of orphaning instances against no task.
+      if (task?.id) {
+        await wireframeDoc.markInstancesBuilding(route, instances.map((i) => i.id), task.id)
+      }
+    } finally {
+      isBuilding.value = false
+    }
+  }
+
+  /** Remove one placement: unmount its live preview node (if mounted this
+   *  session), delete it from the persisted doc, and drop its session entry. */
+  async function deletePlacement(id: string): Promise<void> {
+    const containerEid = containerEids.get(id)
+    if (containerEid) {
+      await iframe.removePlaceholder(containerEid)
+      containerEids.delete(id)
+    }
+    await wireframeDoc.deleteInstance(normalizeRoute(currentRoute.value), id)
+    session.removeByInstanceId(id)
+  }
+
+  // Re-apply persisted placements after the iframe (re)loads or the route
+  // changes. A fresh bridge means a fresh DOM, so force a clean re-apply.
+  // The design-session preview replay rides the same triggers: a persisted
+  // session must never claim edits the fresh iframe doesn't show.
+  watch(iframe.bridgeReady, (ready) => {
+    if (!ready) return
+    wireframeDoc.resetApplied()
+    containerEids.clear() // fresh DOM → stale container eids
+    void wireframeDoc.reapply(normalizeRoute(currentRoute.value), iframe, { force: true, onInstanceMounted: registerContainer })
+    session.resetPreviewApplied()
+    void session.reapplyPreviews(normalizeRoute(currentRoute.value), iframe, { force: true })
+  })
+  watch(currentRoute, (r) => {
+    if (!iframe.bridgeReady.value) return
+    void wireframeDoc.reapply(normalizeRoute(r), iframe, { onInstanceMounted: registerContainer })
+    void session.reapplyPreviews(normalizeRoute(r), iframe)
+  })
+
+  return {
+    paletteDrag,
+    wireframeDoc,
+    registerContainer,
+    dropIndicator,
+    onPaletteDragOver,
+    onPaletteDragLeave,
+    onPaletteDrop,
+    wireframePlacements,
+    placedCount,
+    isBuilding,
+    buildWireframeRoute,
+    deletePlacement,
+  }
+}
diff --git a/src/shell/composables/useWireframeDoc.ts b/src/shell/composables/useWireframeDoc.ts
new file mode 100644
index 0000000..120b204
--- /dev/null
+++ b/src/shell/composables/useWireframeDoc.ts
@@ -0,0 +1,296 @@
+import { ref } from 'vue'
+import { on as wsOn } from '../services/wsClient'
+import {
+  emptyWireframeDocument,
+  type WireframeDocument,
+  type WireframeInstance,
+  type WireframeCanvasState,
+} from '../../shared/wireframe-types'
+
+/** The subset of the iframe manager that re-applying instances needs. */
+export interface WireframeIframe {
+  findTemplateGroup: (file: string, line: string, tagName: string) => Promise<{ eids: string[] }>
+  insertComponent: (targetEid: string, position: string, componentName: string, props?: Record<string, unknown>, module?: string, instanceId?: string) => Promise<{ eid: string }>
+  insertPlaceholder: (
+    targetEid: string,
+    position: string,
+    tag: string,
+    opts?: { classes?: string; textContent?: string; category?: string; library?: string; defaultProps?: Record<string, unknown>; instanceId?: string },
+  ) => Promise<string>
+  /** Optional DOM idempotency probe: lets reapply skip an instance whose
+   *  `[data-annotask-instance]` node is still in the iframe (HMR re-renders
+   *  don't always wipe the DOM, but they do re-fire bridgeReady → force
+   *  reapply). useIframeManager satisfies this structurally. */
+  resolveBySelectors?: (selectors: string[]) => Promise<Array<{ selector: string; eid: string | null }>>
+}
+
+// Module-singleton so every consumer shares one document + one WS subscription.
+const doc = ref<WireframeDocument>(emptyWireframeDocument())
+const isLoading = ref(false)
+const loadError = ref<string | null>(null)
+// Instances whose durable (file, line, tag) anchor no longer resolves in the
+// live DOM — source drifted since the placement. Surfaced as a badge in the
+// placements panel instead of a console.warn nobody sees.
+const staleIds = ref<string[]>([])
+// Instances whose insert call threw during the last reapply pass. Kept
+// separate from staleIds: a failure is a bug/transient, a stale anchor is the
+// user's source moving on.
+const failedIds = ref<string[]>([])
+
+let initialized = false
+// Re-apply de-dup: which instance ids have been mounted into the CURRENT iframe
+// document for the route below. Reset on route change or a forced reload.
+let appliedRoute: string | null = null
+const appliedIds = new Set<string>()
+
+function setMembership(list: typeof staleIds, id: string, present: boolean): void {
+  const has = list.value.includes(id)
+  if (present && !has) list.value = [...list.value, id]
+  else if (!present && has) list.value = list.value.filter((x) => x !== id)
+}
+
+async function load(): Promise<void> {
+  isLoading.value = true
+  loadError.value = null
+  try {
+    const res = await fetch('/__annotask/api/wireframe')
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    doc.value = (await res.json()) as WireframeDocument
+  } catch (err) {
+    loadError.value = (err as Error).message ?? 'Failed to load wireframe'
+    doc.value = emptyWireframeDocument()
+  } finally {
+    isLoading.value = false
+  }
+}
+
+async function persist(): Promise<void> {
+  doc.value.updatedAt = Date.now()
+  try {
+    const res = await fetch('/__annotask/api/wireframe', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      // doc.value carries the rev from the last GET/PUT — the server's CAS
+      // rejects a stale one so two tabs can't last-writer-wins each other.
+      body: JSON.stringify(doc.value),
+    })
+    if (res.status === 409) {
+      // Another writer (tab, or the server's task-accept hook) committed
+      // first. Re-load and surface; never auto-retry the write — replaying
+      // this in-memory doc would silently clobber the other writer's changes.
+      await load()
+      loadError.value = 'Wireframe changed in another tab — reloaded.'
+      return
+    }
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    doc.value = (await res.json()) as WireframeDocument
+  } catch (err) {
+    loadError.value = (err as Error).message ?? 'Failed to save wireframe'
+  }
+}
+
+function instancesForRoute(route: string): WireframeInstance[] {
+  return doc.value.routes.find((r) => r.route === route)?.instances ?? []
+}
+
+async function saveInstance(route: string, instance: WireframeInstance): Promise<void> {
+  let entry = doc.value.routes.find((r) => r.route === route)
+  if (!entry) {
+    entry = { route, instances: [] }
+    doc.value.routes.push(entry)
+  }
+  const idx = entry.instances.findIndex((i) => i.id === instance.id)
+  if (idx >= 0) entry.instances.splice(idx, 1, instance)
+  else entry.instances.push(instance)
+  entry.updatedAt = Date.now()
+  await persist()
+}
+
+/** Patch one instance in place (e.g. a moved anchor or status change) and
+ *  persist. Merges `patch.anchor` shallowly so callers can pass just the moved
+ *  fields. No-ops if the instance isn't found. */
+async function updateInstance(route: string, id: string, patch: Partial<WireframeInstance>): Promise<void> {
+  const entry = doc.value.routes.find((r) => r.route === route)
+  const inst = entry?.instances.find((i) => i.id === id)
+  if (!entry || !inst) return
+  const nextAnchor = patch.anchor ? { ...inst.anchor, ...patch.anchor } : inst.anchor
+  Object.assign(inst, patch, { anchor: nextAnchor, updatedAt: Date.now() })
+  entry.updatedAt = Date.now()
+  await persist()
+}
+
+/**
+ * Stamp a batch of instances 'building' against the task that now owns them —
+ * one persist for the whole batch, not one PUT per instance. Called by Build
+ * right after the wireframe_apply task is created; the stamp is what makes a
+ * second Build click a no-op (it only collects 'placed' instances).
+ */
+async function markInstancesBuilding(route: string, ids: string[], taskId: string): Promise<void> {
+  const entry = doc.value.routes.find((r) => r.route === route)
+  if (!entry || ids.length === 0) return
+  const idSet = new Set(ids)
+  let touched = false
+  for (const inst of entry.instances) {
+    if (!idSet.has(inst.id)) continue
+    inst.status = 'building'
+    inst.taskId = taskId
+    inst.updatedAt = Date.now()
+    touched = true
+  }
+  if (!touched) return
+  entry.updatedAt = Date.now()
+  await persist()
+}
+
+async function deleteInstance(route: string, id: string): Promise<void> {
+  const entry = doc.value.routes.find((r) => r.route === route)
+  if (!entry) return
+  entry.instances = entry.instances.filter((i) => i.id !== id)
+  entry.updatedAt = Date.now()
+  // Drop all bookkeeping for the dead id so badges and the de-dup set don't
+  // reference an instance that no longer exists.
+  appliedIds.delete(id)
+  setMembership(staleIds, id, false)
+  setMembership(failedIds, id, false)
+  await persist()
+}
+
+/**
+ * Re-mount the route's persisted instances into the live iframe after a reload
+ * or route change. Only `status: 'placed'` (or legacy-undefined) instances
+ * mount — 'building'/'applied' never re-mount, which is what stops a placement
+ * from rendering NEXT TO the agent's freshly applied component when its edit
+ * triggers HMR during review.
+ *
+ * Each instance is isolated: a stale anchor (source changed) or a throwing
+ * insert fails soft — it lands in `staleIds`/`failedIds` for the placements
+ * panel and never blocks the rest of the route, never deletes the instance.
+ */
+async function reapply(
+  route: string,
+  iframe: WireframeIframe,
+  opts?: { force?: boolean; onInstanceMounted?: (id: string, containerEid: string) => void },
+): Promise<void> {
+  if (opts?.force || route !== appliedRoute) {
+    appliedRoute = route
+    appliedIds.clear()
+  }
+  const candidates = instancesForRoute(route).filter(
+    (i) => (i.status ?? 'placed') === 'placed' && !appliedIds.has(i.id),
+  )
+  if (candidates.length === 0) return
+
+  // DOM idempotency guard: a forced reapply can race an iframe whose DOM kept
+  // the previous mounts (soft HMR). Skip any instance whose stamped node is
+  // still present. Best-effort — appliedIds + the status filter already cover
+  // the common SPA-route case when the probe isn't available.
+  const alreadyInDom = new Set<string>()
+  if (iframe.resolveBySelectors) {
+    try {
+      const matches = await iframe.resolveBySelectors(candidates.map((i) => `[data-annotask-instance="${i.id}"]`))
+      matches.forEach((m, idx) => {
+        if (m.eid) alreadyInDom.add(candidates[idx].id)
+      })
+    } catch { /* probe is best-effort */ }
+  }
+
+  for (const inst of candidates) {
+    if (alreadyInDom.has(inst.id)) {
+      appliedIds.add(inst.id)
+      continue
+    }
+    try {
+      const group = await iframe.findTemplateGroup(inst.anchor.file, String(inst.anchor.line), inst.anchor.targetTag ?? '')
+      if (group.eids.length === 0) {
+        setMembership(staleIds, inst.id, true)
+        continue
+      }
+      setMembership(staleIds, inst.id, false)
+      appliedIds.add(inst.id)
+      const targetEid = group.eids[0]
+      // Stamp the instance id on the re-mounted node (placement identity +
+      // idempotency probe); record the resulting container eid for unmount lookups.
+      if (inst.kind === 'component') {
+        // Mount with the sample props the user previewed (when captured) so a
+        // reload doesn't degrade a live mount to an empty 'rendered-empty' box.
+        const res = await iframe.insertComponent(targetEid, inst.anchor.position, inst.inserted.componentName ?? inst.inserted.tag, inst.previewProps ?? inst.inserted.props, inst.inserted.module, inst.id)
+        if (res?.eid) opts?.onInstanceMounted?.(inst.id, res.eid)
+      } else {
+        const eid = await iframe.insertPlaceholder(targetEid, inst.anchor.position, inst.inserted.tag, {
+          classes: inst.inserted.classes,
+          textContent: inst.inserted.text_content,
+          category: inst.kind === 'layout-preset' ? 'layout-preset' : undefined,
+          library: inst.inserted.library,
+          defaultProps: inst.inserted.props,
+          instanceId: inst.id,
+        })
+        if (eid) opts?.onInstanceMounted?.(inst.id, eid)
+      }
+      setMembership(failedIds, inst.id, false)
+    } catch (err) {
+      setMembership(failedIds, inst.id, true)
+      console.warn(`[Annotask] wireframe reapply failed for ${inst.id} (${inst.anchor.file}:${inst.anchor.line}):`, err)
+    }
+  }
+}
+
+/** Drop the re-apply de-dup state (e.g. before a forced reload re-apply). */
+function resetApplied(): void {
+  appliedRoute = null
+  appliedIds.clear()
+}
+
+// ── Snapshot-wireframe canvas ─────────────────────────────
+
+function canvasForRoute(route: string): WireframeCanvasState | null {
+  return doc.value.routes.find((r) => r.route === route)?.canvas ?? null
+}
+
+/** Replace the route's canvas wholesale and persist. The canvas is one
+ *  editing surface — block-level patch methods would re-implement the doc. */
+async function saveCanvas(route: string, canvas: WireframeCanvasState): Promise<void> {
+  let entry = doc.value.routes.find((r) => r.route === route)
+  if (!entry) {
+    entry = { route, instances: [] }
+    doc.value.routes.push(entry)
+  }
+  entry.canvas = canvas
+  entry.updatedAt = Date.now()
+  await persist()
+}
+
+async function clearCanvas(route: string): Promise<void> {
+  const entry = doc.value.routes.find((r) => r.route === route)
+  if (!entry?.canvas) return
+  delete entry.canvas
+  entry.updatedAt = Date.now()
+  await persist()
+}
+
+export function useWireframeDoc() {
+  if (!initialized) {
+    initialized = true
+    void load()
+    // Another shell/tab (or an external edit) changed the doc — re-load. Never
+    // re-PUT here, or two listeners would ping-pong forever.
+    wsOn('wireframe:updated', () => { void load() })
+  }
+  return {
+    doc,
+    isLoading,
+    loadError,
+    staleIds,
+    failedIds,
+    load,
+    instancesForRoute,
+    saveInstance,
+    updateInstance,
+    markInstancesBuilding,
+    deleteInstance,
+    reapply,
+    resetApplied,
+    canvasForRoute,
+    saveCanvas,
+    clearCanvas,
+  }
+}
diff --git a/src/shell/composables/useWireframeMode.ts b/src/shell/composables/useWireframeMode.ts
new file mode 100644
index 0000000..0a29e41
--- /dev/null
+++ b/src/shell/composables/useWireframeMode.ts
@@ -0,0 +1,1008 @@
+import { ref, computed, watch, type Ref } from 'vue'
+import { useWireframeDoc } from './useWireframeDoc'
+import { useDesignSession } from './useDesignSession'
+import { useCanvasSelection } from './useCanvasSelection'
+import { useCanvasHistory } from './useCanvasHistory'
+import { computeWireframeDirections } from '../utils/wireframeDirections'
+import { composeWireframeDiff } from '../utils/wireframeComposite'
+import { normalizeRoute } from '../utils/routes'
+import type { WireframeBlock, WireframeCanvasState, WireframeDataBinding, WireframeFidelity, WireframePaletteRef } from '../../shared/wireframe-types'
+import type { WireframeCapturePayload, WireframeCaptureResult, WireframeCaptureProgress } from '../../shared/bridge-types'
+import type { InteractionMode } from './useInteractionMode'
+
+/** localStorage flag so F5 re-enters wireframe mode (W2 accept). Only the
+ *  ACTIVE bit lives client-side — the canvas itself is server-persisted. */
+const STORAGE_KEY = 'annotask:wireframe'
+
+export interface WireframeModeIframe {
+  currentRoute: Ref<string>
+  bridgeReady: Ref<boolean>
+  captureWireframe: (opts?: WireframeCapturePayload) => Promise<WireframeCaptureResult>
+  /** Offscreen component mount → honest snapshot (palette drops). `opts.repeat`
+   *  mounts N stacked instances; `opts.instanceProps` overlays per-instance prop
+   *  values (bound data rows). */
+  previewComponent: (componentName: string, props?: Record<string, unknown>, module?: string, width?: number, opts?: { repeat?: number; instanceProps?: Record<string, unknown>[] }) => Promise<{ mounted: boolean; fidelity?: string | null; dataUrl?: string; width?: number; height?: number; error?: string }>
+  /** Durable-anchor → live eids re-resolution (explode targets). */
+  findTemplateGroup: (file: string, line: string, tagName: string) => Promise<{ eids: string[] }>
+  // `any` matches the bridge event registry's signature (iframeBridge.on).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onBridgeEvent: (type: string, handler: (payload: any) => void) => void
+}
+
+/** What the palette hands a canvas drop — mirrors usePaletteDrag's item. */
+export interface WireframeDropItem {
+  kind: 'component' | 'html' | 'layout-preset'
+  tag: string
+  componentName?: string
+  library?: string
+  module?: string
+  props?: Record<string, unknown>
+  previewProps?: Record<string, unknown>
+  classes?: string
+  textContent?: string
+  category?: string
+}
+
+export interface WireframeModeDeps {
+  iframe: WireframeModeIframe
+  interactionMode: Ref<InteractionMode>
+  /** Top-level shell view — leaving 'design' exits wireframe mode. */
+  shellView: Ref<string>
+}
+
+/** The honest snapshot a generate/drop produced — preview:component's
+ *  result, normalized. No dataUrl ⇒ placeholder fidelity, never fabricated. */
+export interface PaletteSnapshot {
+  dataUrl?: string
+  width?: number
+  height?: number
+  fidelity?: WireframeFidelity
+  mounted?: boolean
+}
+
+let blockCounter = 0
+function mintBlockId(): string {
+  blockCounter++
+  return `wfb-${Date.now().toString(36)}-${blockCounter.toString(36)}`
+}
+
+/**
+ * Wireframe mode — freezes the current route into a manipulable image canvas.
+ *
+ * Capture rasterizes the live view into per-block PNGs (the bridge walks the
+ * DOM; images ARE the rendered truth at capture time), uploads them as
+ * sidecar files, and persists block geometry + anchors to wireframe.json.
+ * The live iframe stays mounted underneath the canvas overlay the whole time,
+ * so exiting is lossless — no reload, no re-navigation.
+ */
+export function useWireframeMode(deps: WireframeModeDeps) {
+  const { iframe, interactionMode, shellView } = deps
+  const wireframeDoc = useWireframeDoc()
+  const session = useDesignSession()
+
+  const active = ref(false)
+  const capturing = ref(false)
+  const progress = ref<WireframeCaptureProgress | null>(null)
+  const error = ref<string | null>(null)
+  /** Working copy of the route's canvas while the mode is active. */
+  const canvas = ref<WireframeCanvasState | null>(null)
+  /** The route the working canvas belongs to. Saves key off THIS, not the
+   *  live iframe route — a route change fires the exit-flush while the iframe
+   *  has already moved on, and keying off the live route would persist the old
+   *  canvas under the new route. */
+  const canvasRoute = ref<string | null>(null)
+  /** This-session dataUrls (blockId → PNG) — instant render before/while the
+   *  uploads land; after a reload images come from the snapshot routes. */
+  const liveImages = ref<Record<string, string>>({})
+  /** Blocks whose snapshot is currently rendering (place-first first fill, or a
+   *  live reconfigure regen). CLIENT-ONLY — never persisted, so a reload mid-
+   *  generation reads the block as an honest 'placeholder', never a stuck
+   *  shimmer. The canvas reads this to show the "rendering…" overlay. */
+  const generatingIds = ref<Set<string>>(new Set())
+  function setGenerating(id: string, on: boolean): void {
+    const has = generatingIds.value.has(id)
+    if (on === has) return
+    const next = new Set(generatingIds.value)
+    if (on) next.add(id); else next.delete(id)
+    generatingIds.value = next
+  }
+
+  // Selection + undo/redo operate on the working canvas. History snapshots both
+  // blocks AND selection, so undo restores what was selected at each step.
+  const selection = useCanvasSelection(canvas)
+  const history = useCanvasHistory(
+    () => ({ blocks: canvas.value?.blocks ?? [], selection: selection.selectedIds.value }),
+    (snap) => {
+      if (!canvas.value) return
+      canvas.value.blocks = snap.blocks
+      selection.setSelection(snap.selection)
+      persistSoon()
+    },
+  )
+
+  iframe.onBridgeEvent('wireframe:capture-progress', (p: WireframeCaptureProgress) => {
+    if (capturing.value) progress.value = p
+  })
+
+  function activeRoute(): string {
+    return normalizeRoute(iframe.currentRoute.value)
+  }
+
+  /** Resolve a block's image source: session dataUrl first, then the
+   *  persisted sidecar file. Null = the honest "capture failed" hatch.
+   *  Strictly own-id keyed: duplicates get their own liveImages entry at
+   *  duplication time, so a later regenerate of the original can't bleed
+   *  into them through a shared key. */
+  function imageSrc(block: WireframeBlock): string | null {
+    const live = liveImages.value[block.id]
+    if (live) return live
+    if (block.image) return `/__annotask/wireframe-snapshots/${block.image}`
+    return null
+  }
+
+  async function uploadSnapshot(id: string, dataUrl: string): Promise<string | null> {
+    try {
+      const res = await fetch('/__annotask/api/wireframe-snapshots', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ id, data: dataUrl }),
+      })
+      if (!res.ok) return null
+      return ((await res.json()) as { filename: string }).filename
+    } catch {
+      return null
+    }
+  }
+
+  async function deleteSnapshot(filename: string): Promise<void> {
+    try {
+      await fetch(`/__annotask/api/wireframe-snapshots/${filename}`, { method: 'DELETE' })
+    } catch { /* best-effort cleanup */ }
+  }
+
+  function setFlag(on: boolean): void {
+    try {
+      if (on) localStorage.setItem(STORAGE_KEY, '1')
+      else localStorage.removeItem(STORAGE_KEY)
+    } catch { /* storage may be unavailable */ }
+  }
+
+  /** Capture the live route into a fresh canvas. Returns false (and stays in
+   *  live view) when there is nothing honest to show. */
+  async function captureIntoCanvas(route: string): Promise<boolean> {
+    capturing.value = true
+    progress.value = null
+    error.value = null
+    try {
+      const res = await iframe.captureWireframe()
+      if (res.error || !res.blocks?.length || !res.viewport) {
+        error.value = res.error ?? 'nothing to capture'
+        return false
+      }
+
+      const blocks: WireframeBlock[] = []
+      const uploads: Array<{ id: string; dataUrl: string }> = []
+      const nextImages: Record<string, string> = {}
+      res.blocks.forEach((b, i) => {
+        const id = mintBlockId()
+        const rect = { x: b.rect.x, y: b.rect.y, width: b.rect.width, height: b.rect.height }
+        const block: WireframeBlock = {
+          id,
+          kind: 'captured',
+          rect,
+          originalRect: { ...rect },
+          z: i + 1,
+          createdAt: Date.now(),
+          anchor: {
+            file: b.file,
+            line: parseInt(b.line, 10) || 0,
+            ...(b.component ? { component: b.component } : {}),
+            ...(b.source_tag ? { sourceTag: b.source_tag } : {}),
+            ...(b.cls ? { cssClass: b.cls } : {}),
+            tag: b.tag,
+            role: b.role,
+          },
+          ...(b.error ? { captureError: b.error } : {}),
+          ...(b.clipped ? { clipped: true } : {}),
+        }
+        if (b.dataUrl) {
+          nextImages[id] = b.dataUrl
+          uploads.push({ id, dataUrl: b.dataUrl })
+        }
+        blocks.push(block)
+      })
+
+      const next: WireframeCanvasState = {
+        capturedAt: Date.now(),
+        viewport: res.viewport,
+        ...(res.truncated ? { truncated: true } : {}),
+        blocks,
+      }
+      liveImages.value = nextImages
+      canvas.value = next
+      canvasRoute.value = route
+      history.clear()
+
+      // Uploads are sequential-ish but independent: a failed upload leaves the
+      // block image-less on disk (renders from memory this session, honest
+      // hatch after reload) — never a fabricated picture.
+      const byId = new Map(blocks.map((b) => [b.id, b]))
+      await Promise.all(uploads.map(async ({ id, dataUrl }) => {
+        const filename = await uploadSnapshot(id, dataUrl)
+        if (filename) byId.get(id)!.image = filename
+      }))
+      if (res.fullDataUrl) {
+        const fullId = `wf-full-${Date.now().toString(36)}`
+        const filename = await uploadSnapshot(fullId, res.fullDataUrl)
+        if (filename) next.fullImage = filename
+      }
+
+      await wireframeDoc.saveCanvas(route, next)
+      return true
+    } finally {
+      capturing.value = false
+      progress.value = null
+    }
+  }
+
+  /** Toggle ON: reuse the route's persisted canvas if one exists, else
+   *  capture. Never captures at boot — only on explicit entry. */
+  async function enter(): Promise<void> {
+    if (active.value || capturing.value) return
+    const route = activeRoute()
+    const existing = wireframeDoc.canvasForRoute(route)
+    if (existing) {
+      canvas.value = existing
+      canvasRoute.value = route
+      history.clear()
+    } else {
+      const ok = await captureIntoCanvas(route)
+      if (!ok) return
+    }
+    interactionMode.value = 'select'
+    active.value = true
+    setFlag(true)
+  }
+
+  /** Toggle OFF: the live app is still there underneath — lossless. The
+   *  canvas stays persisted; re-entering reuses it. */
+  function exit(): void {
+    flushPersist()
+    active.value = false
+    canvas.value = null
+    canvasRoute.value = null
+    history.clear()
+    setFlag(false)
+    // Clear any capture/explode error so the App-level banner (shown when the
+    // canvas is unmounted) doesn't linger after a clean exit.
+    error.value = null
+  }
+
+  /** Discard the persisted canvas (and its snapshot files) and capture fresh.
+   *  Wholesale by design: merging old coordinates onto a re-rendered page
+   *  could silently lie about what the user is looking at. */
+  async function recapture(): Promise<void> {
+    if (capturing.value) return
+    const route = activeRoute()
+    const old = wireframeDoc.canvasForRoute(route)
+    if (old) {
+      const files = [...old.blocks.map((b) => b.image), old.fullImage].filter((f): f is string => !!f)
+      await wireframeDoc.clearCanvas(route)
+      void Promise.all(files.map(deleteSnapshot))
+    }
+    liveImages.value = {}
+    canvas.value = null
+    const ok = await captureIntoCanvas(route)
+    if (!ok) {
+      // Capture failed after the old canvas was discarded — drop to live view
+      // rather than showing a stale sketch we just deleted.
+      exit()
+      return
+    }
+    active.value = true
+    setFlag(true)
+  }
+
+  // Persist canvas mutations (drag/resize/notes/blocks) with a trailing
+  // debounce so pointer-up bursts don't stack PUTs.
+  let persistTimer: ReturnType<typeof setTimeout> | null = null
+  function persistSoon(): void {
+    if (!canvas.value || !canvasRoute.value) return
+    if (persistTimer) clearTimeout(persistTimer)
+    persistTimer = setTimeout(() => {
+      persistTimer = null
+      if (canvas.value && canvasRoute.value) void wireframeDoc.saveCanvas(canvasRoute.value, canvas.value)
+    }, 300)
+  }
+
+  /** Cancel the trailing debounce and write once, NOW. Called on exit so the
+   *  last drag/edit can't be dropped by `canvas.value` being cleared before the
+   *  pending timer fires (the old fire-and-forget timer lost that tail edit). */
+  function flushPersist(): void {
+    if (persistTimer) { clearTimeout(persistTimer); persistTimer = null }
+    if (canvas.value && canvasRoute.value) void wireframeDoc.saveCanvas(canvasRoute.value, canvas.value)
+  }
+
+  // ── Block operations (W2 manipulation) ────────────────────
+
+  function findBlock(id: string): WireframeBlock | null {
+    return canvas.value?.blocks.find((b) => b.id === id) ?? null
+  }
+
+  function maxZ(): number {
+    return (canvas.value?.blocks ?? []).reduce((m, b) => Math.max(m, b.z), 0)
+  }
+
+  function minZ(): number {
+    const blocks = canvas.value?.blocks ?? []
+    return blocks.length ? blocks.reduce((m, b) => Math.min(m, b.z), Infinity) : 0
+  }
+
+  // Rect updates are gesture/nudge driven: the component brackets a drag with
+  // history.begin()/end() and records once per arrow-nudge, so this stays out
+  // of the history (recording per pointermove would bury the stack).
+  function updateBlockRect(id: string, rect: { x: number; y: number; width: number; height: number }): void {
+    const b = findBlock(id)
+    if (!b) return
+    b.rect = { ...rect }
+    b.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  function bringToFront(id: string): void {
+    const b = findBlock(id)
+    if (!b) return
+    const top = maxZ()
+    if (b.z === top && canvas.value!.blocks.filter((x) => x.z === top).length === 1) return
+    history.record('z:' + id)
+    b.z = top + 1
+    b.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  function sendToBack(id: string): void {
+    const b = findBlock(id)
+    if (!b) return
+    const bottom = minZ()
+    if (b.z === bottom && canvas.value!.blocks.filter((x) => x.z === bottom).length === 1) return
+    history.record('z:' + id)
+    b.z = bottom - 1
+    b.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  /** One layer up: swap z with the nearest block currently above it. */
+  function bringForward(id: string): void {
+    const c = canvas.value
+    const b = findBlock(id)
+    if (!c || !b) return
+    const above = c.blocks
+      .filter((x) => !x.deleted && x.z > b.z)
+      .sort((p, q) => p.z - q.z)[0]
+    if (!above) return // already on top
+    history.record('z:' + id)
+    const z = b.z
+    b.z = above.z
+    above.z = z
+    b.updatedAt = Date.now()
+    above.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  /** One layer down: swap z with the nearest block currently below it. */
+  function sendBackward(id: string): void {
+    const c = canvas.value
+    const b = findBlock(id)
+    if (!c || !b) return
+    const below = c.blocks
+      .filter((x) => !x.deleted && x.z < b.z)
+      .sort((p, q) => q.z - p.z)[0]
+    if (!below) return // already at the bottom
+    history.record('z:' + id)
+    const z = b.z
+    b.z = below.z
+    below.z = z
+    b.updatedAt = Date.now()
+    below.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  function setNote(id: string, note: string): void {
+    const b = findBlock(id)
+    if (!b) return
+    history.record('note:' + id)
+    const trimmed = note.trim()
+    if (trimmed) b.note = trimmed
+    else delete b.note
+    b.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  /** USER-WRITTEN markdown for a drawn section — travels verbatim. */
+  function setBlockMd(id: string, md: string): void {
+    const b = findBlock(id)
+    if (!b) return
+    history.record('md:' + id)
+    const trimmed = md.trim()
+    if (trimmed) b.md = trimmed
+    else delete b.md
+    b.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  /** Attach/clear a data-source binding. The picker emits a reactive proxy —
+   *  JSON-clone before it lands in the persisted doc. */
+  function setBlockData(id: string, data: WireframeDataBinding | null): void {
+    const b = findBlock(id)
+    if (!b) return
+    history.record('data:' + id)
+    if (data) b.data = JSON.parse(JSON.stringify(data)) as WireframeDataBinding
+    else delete b.data
+    b.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  /** Captured blocks soft-delete (the apply diff needs deletion as a fact);
+   *  palette/placeholder blocks are sketch material — remove outright, and
+   *  drop the snapshot file unless another block (duplicate) still shares it. */
+  function deleteBlock(id: string): void {
+    const c = canvas.value
+    const b = findBlock(id)
+    if (!c || !b) return
+    history.record('delete:' + id)
+    if (b.kind === 'captured') {
+      b.deleted = true
+      b.updatedAt = Date.now()
+    } else {
+      c.blocks = c.blocks.filter((x) => x.id !== id)
+      if (b.image && !c.blocks.some((x) => x.image === b.image)) {
+        void deleteSnapshot(b.image)
+      }
+    }
+    persistSoon()
+  }
+
+  function undeleteBlock(id: string): void {
+    const b = findBlock(id)
+    if (!b?.deleted) return
+    history.record('undelete:' + id)
+    delete b.deleted
+    b.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  const deletedBlocks = computed(() => (canvas.value?.blocks ?? []).filter((b) => b.deleted))
+
+  /** Duplicate = new sketch material based on an existing block. Shares the
+   *  image file; `duplicateOf` points at the ROOT original so the apply diff
+   *  can say "another <X>" even through duplicate-of-duplicate chains. */
+  function duplicateBlock(id: string): string | null {
+    const c = canvas.value
+    const src = findBlock(id)
+    if (!c || !src || src.deleted) return null
+    history.record('duplicate:' + id)
+    const copy: WireframeBlock = {
+      ...JSON.parse(JSON.stringify(src)) as WireframeBlock,
+      id: mintBlockId(),
+      rect: { ...src.rect, x: src.rect.x + 16, y: src.rect.y + 16 },
+      z: maxZ() + 1,
+      duplicateOf: src.duplicateOf ?? src.id,
+      createdAt: Date.now(),
+    }
+    delete copy.updatedAt
+    // Own liveImages entry — the copy renders the image AS IT IS NOW even if
+    // the original regenerates later (imageSrc is strictly own-id keyed).
+    const srcLive = liveImages.value[src.id]
+    if (srcLive) liveImages.value = { ...liveImages.value, [copy.id]: srcLive }
+    c.blocks.push(copy)
+    persistSoon()
+    return copy.id
+  }
+
+  /** Mint one palette block from a component ref + snapshot. Deep-clones the
+   *  ref and binding at the boundary (reactive proxies must never land in the
+   *  persisted doc), registers the in-session image, uploads the sidecar PNG,
+   *  and persists. Returns the new block id. */
+  async function addPaletteBlock(
+    componentRef: WireframePaletteRef,
+    snapshot: PaletteSnapshot,
+    at: { x: number; y: number },
+    data?: WireframeDataBinding,
+  ): Promise<string | null> {
+    const c = canvas.value
+    if (!c) return null
+    history.record('add')
+    const id = mintBlockId()
+    const width = snapshot.width && snapshot.width > 24 ? snapshot.width : 320
+    const height = snapshot.height && snapshot.height > 24 ? snapshot.height : 120
+    const block: WireframeBlock = {
+      id,
+      kind: 'palette',
+      rect: { x: at.x, y: at.y, width, height },
+      z: maxZ() + 1,
+      createdAt: Date.now(),
+      component: JSON.parse(JSON.stringify(componentRef)) as WireframePaletteRef,
+      fidelity: snapshot.fidelity ?? (snapshot.mounted ? 'isolated-preview' : 'placeholder'),
+      ...(data ? { data: JSON.parse(JSON.stringify(data)) as WireframeDataBinding } : {}),
+    }
+    if (snapshot.dataUrl) {
+      liveImages.value = { ...liveImages.value, [id]: snapshot.dataUrl }
+      const filename = await uploadSnapshot(id, snapshot.dataUrl)
+      if (filename) block.image = filename
+    } else {
+      block.fidelity = 'placeholder'
+    }
+    c.blocks.push(block)
+    persistSoon()
+    return id
+  }
+
+  /** Place-first: synchronously mint an IMAGELESS palette block at the drop
+   *  point, auto-select it, and record ONE undo entry — the snapshot is filled
+   *  in afterwards (by the generator) through updatePaletteBlock with
+   *  recordHistory:false, so it folds into this single entry. The block is
+   *  honest from the first frame: fidelity 'placeholder', no fabricated pixels,
+   *  and `generatingIds` drives the "rendering…" shimmer until the fill lands.
+   *  Returns the new block id (null while the sketch is locked). */
+  function placeComponentBlock(componentRef: WireframePaletteRef, at: { x: number; y: number }): string | null {
+    const c = canvas.value
+    if (!c || building.value) return null
+    history.record('add')
+    const id = mintBlockId()
+    const block: WireframeBlock = {
+      id,
+      kind: 'palette',
+      rect: { x: at.x, y: at.y, width: 320, height: 120 },
+      z: maxZ() + 1,
+      createdAt: Date.now(),
+      component: JSON.parse(JSON.stringify(componentRef)) as WireframePaletteRef,
+      fidelity: 'placeholder',
+    }
+    c.blocks.push(block)
+    selection.select(id)
+    setGenerating(id, true)
+    persistSoon()
+    return id
+  }
+
+  /** Regenerate-in-place: patch a placed palette block's props/binding and/or
+   *  swap its snapshot. Re-uploads under the SAME block id (`<id>.png`
+   *  overwrites; the current session renders from liveImages so there is no
+   *  cache-bust concern). Position is preserved; dims follow the snapshot. */
+  async function updatePaletteBlock(id: string, patch: {
+    props?: Record<string, unknown>
+    previewProps?: Record<string, unknown>
+    data?: WireframeDataBinding | null
+    snapshot?: PaletteSnapshot
+  }, opts: { recordHistory?: boolean } = {}): Promise<void> {
+    const b = findBlock(id)
+    if (!b || b.kind !== 'palette' || !b.component) return
+    // The drop and prop/binding edits already snapshot the pre-mutation state;
+    // the async snapshot fill that follows is a derived image swap that must
+    // FOLD into that one entry (recordHistory:false) so a place + render — or a
+    // prop-edit burst + its regen — is a single undo. The prop/binding setters
+    // pass recordHistory:true (coalesce-keyed) so a burst still folds.
+    if (opts.recordHistory !== false) history.record('regenerate:' + id)
+    if (patch.props !== undefined) {
+      if (Object.keys(patch.props).length > 0) b.component.props = JSON.parse(JSON.stringify(patch.props)) as Record<string, unknown>
+      else delete b.component.props
+    }
+    if (patch.previewProps !== undefined) {
+      if (Object.keys(patch.previewProps).length > 0) b.component.previewProps = JSON.parse(JSON.stringify(patch.previewProps)) as Record<string, unknown>
+      else delete b.component.previewProps
+    }
+    if (patch.data !== undefined) {
+      if (patch.data) b.data = JSON.parse(JSON.stringify(patch.data)) as WireframeDataBinding
+      else delete b.data
+    }
+    const snap = patch.snapshot
+    if (snap) {
+      b.fidelity = snap.fidelity ?? (snap.mounted ? 'isolated-preview' : 'placeholder')
+      if (snap.dataUrl) {
+        liveImages.value = { ...liveImages.value, [b.id]: snap.dataUrl }
+        // Fresh filename per regenerate: duplicates may share the OLD file
+        // (overwriting it would silently change them), and the browser caches
+        // snapshot URLs for an hour (same-name re-upload would be masked
+        // after the next reload).
+        const oldImage = b.image
+        const filename = await uploadSnapshot(mintBlockId(), snap.dataUrl)
+        if (filename) {
+          b.image = filename
+          const c = canvas.value
+          if (oldImage && oldImage !== filename && c && !c.blocks.some((x) => x.image === oldImage)) {
+            void deleteSnapshot(oldImage)
+          }
+        }
+        if (snap.width && snap.width > 24) b.rect.width = snap.width
+        if (snap.height && snap.height > 24) b.rect.height = snap.height
+      } else {
+        b.fidelity = 'placeholder'
+      }
+    }
+    b.updatedAt = Date.now()
+    persistSoon()
+  }
+
+  /** Palette drop onto the canvas: components render as an honest
+   *  preview:component snapshot (live iframe under the overlay does the
+   *  mounting); html/layout-preset catalog items become labeled placeholders —
+   *  there is no real render to rasterize, so we never fabricate one. */
+  async function dropPaletteItem(item: WireframeDropItem, at: { x: number; y: number }): Promise<void> {
+    const c = canvas.value
+    if (!c) return
+    // Components are placed first (imageless) via placeComponentBlock and filled
+    // by the generator — they never reach here. This path is html/layout-preset
+    // catalog items: there is no real render to rasterize, so they become
+    // labeled placeholders, never a fabricated snapshot.
+    history.record('add')
+    const id = mintBlockId()
+    c.blocks.push({
+      id,
+      kind: 'placeholder',
+      rect: { x: at.x, y: at.y, width: 320, height: 120 },
+      z: maxZ() + 1,
+      createdAt: Date.now(),
+      label: item.textContent || item.category || `<${item.tag}>`,
+    })
+    persistSoon()
+  }
+
+  /** User-drawn placeholder box — visibly a sketch, never fabricated UI. */
+  function addPlaceholderBlock(rect: { x: number; y: number; width: number; height: number }, label: string): string | null {
+    const c = canvas.value
+    if (!c) return null
+    history.record('add')
+    const id = mintBlockId()
+    c.blocks.push({
+      id,
+      kind: 'placeholder',
+      rect: { ...rect },
+      z: maxZ() + 1,
+      createdAt: Date.now(),
+      label: label.trim() || 'placeholder',
+    })
+    persistSoon()
+    return id
+  }
+
+  /**
+   * Explode (W4): re-capture one captured block a level deeper — the block is
+   * replaced by per-child blocks, each carrying its own source anchor. The
+   * children rasterize from the LIVE page (the only honest pixel source) and
+   * are translated by the block's canvas delta so they land inside the box
+   * the user sees, even after a move.
+   */
+  async function explodeBlock(id: string): Promise<boolean> {
+    const c = canvas.value
+    const parent = findBlock(id)
+    if (!c || !parent || parent.kind !== 'captured' || parent.deleted || capturing.value) return false
+    if (!parent.anchor?.file || !parent.originalRect) return false
+    if (parent.shell) {
+      error.value = 'Already exploded — its children are separate blocks.'
+      return false
+    }
+    error.value = null
+
+    // Re-resolve the live element from the durable anchor (eids are volatile).
+    const group = await iframe.findTemplateGroup(parent.anchor.file, String(parent.anchor.line), parent.anchor.tag ?? '')
+    const rootEid = group.eids[0]
+    if (!rootEid) {
+      error.value = 'Could not find this block in the live page — the source may have changed. Recapture instead.'
+      return false
+    }
+
+    capturing.value = true
+    try {
+      const res = await iframe.captureWireframe({ rootEid })
+      if (res.error || !res.blocks?.length) {
+        error.value = res.error ?? 'nothing to explode'
+        return false
+      }
+      // One block back = no finer granularity available.
+      if (res.blocks.length === 1 && res.blocks[0].eid === rootEid) {
+        error.value = 'This block has no separable children.'
+        return false
+      }
+
+      const dx = parent.rect.x - parent.originalRect.x
+      const dy = parent.rect.y - parent.originalRect.y
+      // Children stack above everything: reusing the parent's z could collide
+      // with unrelated blocks and leave render order to DOM-order luck.
+      const baseZ = maxZ() + 1
+      const uploads: Array<{ id: string; dataUrl: string }> = []
+      const nextImages = { ...liveImages.value }
+      const children: WireframeBlock[] = res.blocks.map((b, i) => {
+        const childId = mintBlockId()
+        const rect = { x: b.rect.x + dx, y: b.rect.y + dy, width: b.rect.width, height: b.rect.height }
+        if (b.dataUrl) {
+          nextImages[childId] = b.dataUrl
+          uploads.push({ id: childId, dataUrl: b.dataUrl })
+        }
+        return {
+          id: childId,
+          kind: 'captured',
+          rect,
+          // The diff baseline is the LIVE position (un-translated): a child of
+          // a moved parent is already "moved" relative to the real page.
+          originalRect: { x: b.rect.x, y: b.rect.y, width: b.rect.width, height: b.rect.height },
+          z: baseZ + i,
+          createdAt: Date.now(),
+          anchor: {
+            file: b.file,
+            line: parseInt(b.line, 10) || 0,
+            ...(b.component ? { component: b.component } : {}),
+            ...(b.source_tag ? { sourceTag: b.source_tag } : {}),
+            ...(b.cls ? { cssClass: b.cls } : {}),
+            tag: b.tag,
+            role: b.role,
+          },
+          ...(b.error ? { captureError: b.error } : {}),
+          ...(b.clipped ? { clipped: true } : {}),
+        }
+      })
+
+      // Past every early-return — about to mutate the canvas. Snapshot now so a
+      // single undo restores the parent block in place of its children.
+      history.record('explode:' + id)
+      liveImages.value = nextImages
+      const oldParentImage = parent.image
+      if (res.shellDataUrl) {
+        // The parent stays as the SHELL backdrop: the container's background/
+        // padding/inter-child surface, captured with the children hidden so
+        // moving a child never reveals a ghost copy of itself. New file id —
+        // duplicates of the parent keep referencing the original pixels.
+        liveImages.value = { ...nextImages, [parent.id]: res.shellDataUrl }
+        parent.shell = true
+        parent.updatedAt = Date.now()
+        delete parent.image
+        const shellFilename = await uploadSnapshot(`${parent.id}-shell`, res.shellDataUrl)
+        if (shellFilename) parent.image = shellFilename
+      } else {
+        // No honest shell to show — keeping the old image would ghost the
+        // children, so the parent goes and the children stand alone.
+        c.blocks = c.blocks.filter((b) => b.id !== id)
+      }
+      c.blocks.push(...children)
+      if (oldParentImage && !c.blocks.some((b) => b.image === oldParentImage)) {
+        void deleteSnapshot(oldParentImage)
+      }
+
+      const byId = new Map(children.map((b) => [b.id, b]))
+      await Promise.all(uploads.map(async ({ id: childId, dataUrl }) => {
+        const filename = await uploadSnapshot(childId, dataUrl)
+        if (filename) byId.get(childId)!.image = filename
+      }))
+      await wireframeDoc.saveCanvas(activeRoute(), c)
+      return true
+    } finally {
+      capturing.value = false
+      progress.value = null
+    }
+  }
+
+  // ── Implement this wireframe (W3 directions + agent apply) ─────────────
+
+  /** Locked while a wireframe_apply task implements this sketch. */
+  const building = computed(() => canvas.value?.status === 'building')
+  const implementing = ref(false)
+
+  /**
+   * Diff the sketch into anchored directions, compose+upload the before/after
+   * composite, replace the route's pending direction entries in the journal,
+   * and mint ONE wireframe_apply task through the existing apply loop. The
+   * caller hands the taskId to the embedded-agent auto-run.
+   */
+  async function implementWireframe(): Promise<{ taskId: string; batchId: string } | null> {
+    const c = canvas.value
+    if (!c || capturing.value || implementing.value || building.value) return null
+    implementing.value = true
+    error.value = null
+    try {
+      const route = activeRoute()
+      // The diff and the persisted doc must agree — flush pending mutations.
+      if (persistTimer) { clearTimeout(persistTimer); persistTimer = null }
+      await wireframeDoc.saveCanvas(route, c)
+
+      const directions = computeWireframeDirections(c)
+      if (directions.length === 0) {
+        error.value = 'Nothing to implement — rearrange the sketch first.'
+        return null
+      }
+
+      // Composite is best-effort reinforcement; the directions text is the
+      // contract. A failed upload never blocks the apply.
+      let screenshot: string | undefined
+      try {
+        const composite = await composeWireframeDiff({
+          canvas: c,
+          directions,
+          imageSrc,
+          beforeSrc: c.fullImage ? `/__annotask/wireframe-snapshots/${c.fullImage}` : null,
+        })
+        if (composite) {
+          const res = await fetch('/__annotask/api/screenshots', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ data: composite }),
+          })
+          if (res.ok) screenshot = ((await res.json()) as { filename: string }).filename
+        }
+      } catch { /* image is reinforcement, not the contract */ }
+
+      // Direction entries are a PROJECTION of the canvas — replace this
+      // route's pending set wholesale, then record the fresh diff.
+      session.removeWhere((e) =>
+        e.change.type === 'wireframe_direction' && e.route === route
+        && (e.live.status === 'pending' || e.live.status === 'failed'))
+      for (const d of directions) {
+        session.record({
+          change: d,
+          anchor: { file: d.file, line: d.line, ...(d.block.tag ? { targetTag: d.block.tag } : {}) },
+          route,
+        })
+      }
+
+      const result = await session.applyNow({ route, ...(screenshot ? { screenshot } : {}) })
+      if (!result) {
+        error.value = session.lastError.value ?? 'apply failed'
+        return null
+      }
+      // The server stamped the canvas 'building' — pick up the locked copy.
+      await wireframeDoc.load()
+      const locked = wireframeDoc.canvasForRoute(route)
+      if (locked) canvas.value = locked
+      return result
+    } finally {
+      implementing.value = false
+    }
+  }
+
+  /** Undo this implementation: delete the task (lifecycle revert: canvas back
+   *  to 'sketch', entries released) then restore the batch's pre-apply bytes.
+   *  The sketch is retained for tweak-and-re-implement. */
+  async function undoImplementation(): Promise<void> {
+    const taskId = canvas.value?.taskId
+    if (!taskId) return
+    try {
+      await fetch(`/__annotask/api/tasks/${encodeURIComponent(taskId)}`, { method: 'DELETE' })
+    } catch { /* task may already be gone */ }
+    await session.undoLastBatch()
+    await wireframeDoc.load()
+    const fresh = wireframeDoc.canvasForRoute(activeRoute())
+    if (fresh) {
+      canvas.value = fresh
+      canvasRoute.value = activeRoute()
+      history.clear()
+    }
+  }
+
+  // Server-side lifecycle flips (verify/accept/delete hooks broadcast
+  // wireframe:updated → the doc singleton reloads) must reach the working
+  // copy: sync ONLY the lifecycle identity so a reload can't roll back
+  // un-debounced local edits mid-drag. A canvas that disappears while locked
+  // means the task was accepted — the implementation is live; show it.
+  watch(
+    () => {
+      if (!active.value) return null
+      const c = wireframeDoc.canvasForRoute(activeRoute())
+      return c ? `${c.status ?? 'sketch'}:${c.taskId ?? ''}` : 'gone'
+    },
+    (sig) => {
+      if (!active.value || sig === null) return
+      const fresh = wireframeDoc.canvasForRoute(activeRoute())
+      if (!fresh) {
+        if (canvas.value?.status === 'building') exit()
+        return
+      }
+      const cur = canvas.value
+      if (cur && ((fresh.status ?? 'sketch') !== (cur.status ?? 'sketch') || fresh.taskId !== cur.taskId)) {
+        canvas.value = fresh
+        canvasRoute.value = activeRoute()
+        // Lifecycle flip (sketch ⇄ building) replaces the working copy — the
+        // pre-flip undo stack no longer matches it.
+        history.clear()
+      }
+    },
+  )
+
+  // The canvas is per-route and per-view: leaving the Design view or
+  // navigating the iframe exits the mode (re-entering restores the sketch).
+  watch(shellView, (v) => {
+    if (v !== 'design' && active.value) exit()
+  })
+  watch(iframe.currentRoute, (next, prev) => {
+    if (active.value && normalizeRoute(next) !== normalizeRoute(prev ?? '')) exit()
+  })
+
+  // Boot restore: re-enter only when the flag survives AND a persisted canvas
+  // exists for the current route. Never auto-capture at boot. The iframe's
+  // currentRoute starts at '/' and settles to the restored last-route a beat
+  // AFTER bridgeReady — so a no-canvas miss on the unsettled '/' must keep
+  // waiting, not clear the flag.
+  let booted = false
+  const stopBoot = watch(
+    [iframe.bridgeReady, wireframeDoc.isLoading, iframe.currentRoute],
+    ([ready, loading]) => {
+      // The immediate pass runs before `stopBoot` exists — gate on a flag and
+      // detach the watcher on the first post-boot change instead.
+      if (booted) { stopBoot(); return }
+      if (!ready || loading) return
+      let flagged = false
+      try { flagged = localStorage.getItem(STORAGE_KEY) === '1' } catch { /* ignore */ }
+      if (!flagged) { booted = true; return }
+      const route = activeRoute()
+      const existing = wireframeDoc.canvasForRoute(route)
+      if (existing && shellView.value === 'design') {
+        booted = true
+        canvas.value = existing
+        canvasRoute.value = route
+        history.clear()
+        interactionMode.value = 'select'
+        active.value = true
+      } else if (route !== '/') {
+        // The route has settled somewhere without a sketch — stale flag.
+        booted = true
+        setFlag(false)
+      }
+      // route === '/' with no canvas: still settling — keep watching.
+    },
+    { immediate: true },
+  )
+
+  /** Canvas-scoped undo/redo. No-ops while the sketch is locked (building) or
+   *  the mode is closed — the agent-apply path has its own server-owned undo. */
+  function undo(): void {
+    if (!active.value || building.value || !canvas.value) return
+    history.undo()
+  }
+  function redo(): void {
+    if (!active.value || building.value || !canvas.value) return
+    history.redo()
+  }
+
+  return {
+    active,
+    capturing,
+    progress,
+    error,
+    canvas,
+    imageSrc,
+    enter,
+    exit,
+    recapture,
+    persistSoon,
+    deleteSnapshot,
+    // selection + history
+    selection,
+    history,
+    undo,
+    redo,
+    // block ops
+    updateBlockRect,
+    bringToFront,
+    sendToBack,
+    bringForward,
+    sendBackward,
+    setNote,
+    setBlockMd,
+    setBlockData,
+    deleteBlock,
+    undeleteBlock,
+    deletedBlocks,
+    duplicateBlock,
+    dropPaletteItem,
+    addPaletteBlock,
+    placeComponentBlock,
+    updatePaletteBlock,
+    generatingIds,
+    setGenerating,
+    findBlock,
+    addPlaceholderBlock,
+    explodeBlock,
+    // implement (W3)
+    building,
+    implementing,
+    implementWireframe,
+    undoImplementation,
+  }
+}
diff --git a/src/shell/composables/useWorkingIndicator.ts b/src/shell/composables/useWorkingIndicator.ts
new file mode 100644
index 0000000..0b23891
--- /dev/null
+++ b/src/shell/composables/useWorkingIndicator.ts
@@ -0,0 +1,73 @@
+/**
+ * Working indicator for the embedded agent.
+ *
+ * Watches a boolean "is the agent running?" ref. While true:
+ *   - shows a single static verb ("Annotasking")
+ *   - tracks elapsed seconds since the run started
+ * While false: returns null verb / zero seconds.
+ *
+ * The elapsed count anchors to an optional `startedAt` timestamp ref. Pass the
+ * persisted run-start (the partial assistant message's `ts`) so the timer
+ * survives a tab remount and is correct for a tab that attached mid-run —
+ * without it, the count would reset to 0 on every mount. When no anchor is
+ * supplied (e.g. an external skill/MCP run that creates no partial message)
+ * it falls back to "now" at the moment the run was observed.
+ */
+
+import { ref, watch, type Ref } from 'vue'
+
+const VERB = 'Annotasking'
+const TICK_MS = 1000
+
+export interface WorkingIndicator {
+  verb: Ref<string | null>
+  seconds: Ref<number>
+}
+
+export function useWorkingIndicator(
+  isRunning: Ref<boolean>,
+  startedAt?: Ref<number | null>,
+): WorkingIndicator {
+  const verb = ref<string | null>(null)
+  const seconds = ref(0)
+  let tickTimer: ReturnType<typeof setInterval> | null = null
+  // Fallback anchor for runs with no persisted start (set at observe time).
+  let fallbackStart = 0
+
+  function anchor(): number {
+    const persisted = startedAt?.value
+    if (typeof persisted === 'number' && persisted > 0) return persisted
+    return fallbackStart || Date.now()
+  }
+
+  function tick() {
+    seconds.value = Math.max(0, Math.floor((Date.now() - anchor()) / 1000))
+  }
+
+  function start() {
+    fallbackStart = Date.now()
+    verb.value = VERB
+    tick()
+    if (tickTimer) clearInterval(tickTimer)
+    tickTimer = setInterval(tick, TICK_MS)
+  }
+
+  function stop() {
+    if (tickTimer) { clearInterval(tickTimer); tickTimer = null }
+    verb.value = null
+    seconds.value = 0
+  }
+
+  watch(isRunning, (next) => {
+    if (next) start()
+    else stop()
+  }, { immediate: true })
+
+  // If the persisted anchor resolves after the run was already observed
+  // (snapshot loads a beat after mount), recompute immediately.
+  if (startedAt) {
+    watch(startedAt, () => { if (verb.value) tick() })
+  }
+
+  return { verb, seconds }
+}
diff --git a/src/shell/composables/useWorkspace.ts b/src/shell/composables/useWorkspace.ts
index 51d3f6e..f395540 100644
--- a/src/shell/composables/useWorkspace.ts
+++ b/src/shell/composables/useWorkspace.ts
@@ -75,6 +75,14 @@ const hasMultipleMfes = computed<boolean>(() => mfePackages.value.length > 1)
 /** True when at least one MFE was discovered. */
 const hasAnyMfes = computed<boolean>(() => mfePackages.value.length > 0)
 
+/** The MFE id of the CURRENT iframe surface — the package running this dev
+ *  server, resolved from its workspace-relative `currentDir`. There is exactly
+ *  one active surface and one global component registry, so this is the
+ *  authoritative answer to "which MFE can render a live snapshot here". Null in
+ *  single-MFE / non-workspace projects (no gating then) and for a root package
+ *  that isn't itself an MFE. */
+const currentMfe = computed<string | null>(() => mfeForFile(info.value?.currentDir))
+
 /**
  * Map a workspace-relative file path to the MFE id whose directory prefixes
  * it, or null when the file isn't under any MFE's package (shared libs etc.).
@@ -120,6 +128,7 @@ export function useWorkspace() {
     mfePackages,
     hasMultipleMfes,
     hasAnyMfes,
+    currentMfe,
     selectedMfes,
     toggleMfe,
     clearMfes,
diff --git a/src/shell/main.ts b/src/shell/main.ts
index 6bb3d10..d063fa5 100644
--- a/src/shell/main.ts
+++ b/src/shell/main.ts
@@ -9,5 +9,6 @@ import './styles/_highlights.css'
 import './styles/_tasks.css'
 import './styles/_a11y.css'
 import './styles/_overlays.css'
+import './styles/_ai-settings.css'
 
 createApp(App).mount('#app')
diff --git a/src/shell/services/embeddedAgent/pricing.ts b/src/shell/services/embeddedAgent/pricing.ts
new file mode 100644
index 0000000..f59de77
--- /dev/null
+++ b/src/shell/services/embeddedAgent/pricing.ts
@@ -0,0 +1,85 @@
+/**
+ * Anthropic pricing constants — single source of truth for the embedded-agent
+ * cost meter. Prices are USD per 1,000,000 tokens, mirroring Anthropic's
+ * published rate-card. Update this file when pricing changes; nothing else
+ * needs to move.
+ *
+ * Cache hits are billed at 10% of the input rate; cache writes at 125%.
+ */
+
+export interface AnthropicModelPricing {
+  /** USD per 1M input tokens. */
+  inputPerMTok: number
+  /** USD per 1M output tokens. */
+  outputPerMTok: number
+  /** Friendly label for the model picker. */
+  label: string
+}
+
+export const ANTHROPIC_PRICING: Record<string, AnthropicModelPricing> = {
+  'claude-opus-4-5': {
+    label: 'Claude Opus 4.5',
+    inputPerMTok: 15,
+    outputPerMTok: 75,
+  },
+  'claude-sonnet-4-5': {
+    label: 'Claude Sonnet 4.5',
+    inputPerMTok: 3,
+    outputPerMTok: 15,
+  },
+  'claude-haiku-4-5': {
+    label: 'Claude Haiku 4.5',
+    inputPerMTok: 1,
+    outputPerMTok: 5,
+  },
+}
+
+export const DEFAULT_MODEL = 'claude-sonnet-4-5'
+
+export const CACHE_READ_RATE = 0.1
+export const CACHE_WRITE_RATE = 1.25
+
+export interface CostBreakdown {
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
+  /** Final USD cost, summed across all rate buckets. */
+  usd: number
+}
+
+export function priceUsage(
+  model: string,
+  usage: {
+    input: number
+    output: number
+    cacheRead?: number
+    cacheWrite?: number
+  },
+): CostBreakdown {
+  const rate = ANTHROPIC_PRICING[model] ?? ANTHROPIC_PRICING[DEFAULT_MODEL]
+  const inputCost = (usage.input / 1_000_000) * rate.inputPerMTok
+  const outputCost = (usage.output / 1_000_000) * rate.outputPerMTok
+  const cacheReadCost = ((usage.cacheRead ?? 0) / 1_000_000) * rate.inputPerMTok * CACHE_READ_RATE
+  const cacheWriteCost = ((usage.cacheWrite ?? 0) / 1_000_000) * rate.inputPerMTok * CACHE_WRITE_RATE
+  return {
+    inputTokens: usage.input,
+    outputTokens: usage.output,
+    cacheReadTokens: usage.cacheRead ?? 0,
+    cacheWriteTokens: usage.cacheWrite ?? 0,
+    usd: inputCost + outputCost + cacheReadCost + cacheWriteCost,
+  }
+}
+
+export function formatUsd(usd: number): string {
+  if (usd === 0) return '$0.0000'
+  if (usd < 0.0001) return '<$0.0001'
+  if (usd < 1) return `$${usd.toFixed(4)}`
+  return `$${usd.toFixed(2)}`
+}
+
+export function formatTokens(n: number): string {
+  if (n < 1000) return String(n)
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`
+  return `${(n / 1_000_000).toFixed(2)}M`
+}
diff --git a/src/shell/services/embeddedAgent/tokenize.ts b/src/shell/services/embeddedAgent/tokenize.ts
new file mode 100644
index 0000000..1d8c80b
--- /dev/null
+++ b/src/shell/services/embeddedAgent/tokenize.ts
@@ -0,0 +1,27 @@
+/**
+ * Lightweight token estimator used by the pre-run cost meter.
+ *
+ * The real Anthropic provider (ANN-3) returns authoritative token counts via
+ * `usage` events; this estimator is only for the *pre-run* estimate shown
+ * before the user clicks Run. We deliberately avoid pulling in a tokenizer
+ * library (tiktoken / @anthropic-ai/tokenizer) — they add ~MB to the shell
+ * bundle to shift a $0.0003 estimate by a few percent.
+ *
+ * Heuristic: ~4 chars per token for English prose. We tighten to ~3.6 to
+ * stay slightly conservative on code-heavy skill content, which has shorter
+ * symbols and more punctuation than prose.
+ */
+
+const CHARS_PER_TOKEN = 3.6
+
+export function estimateTokens(text: string): number {
+  if (!text) return 0
+  return Math.ceil(text.length / CHARS_PER_TOKEN)
+}
+
+export function estimateMessages(messages: Array<{ content: string }>): number {
+  let total = 0
+  for (const m of messages) total += estimateTokens(m.content)
+  // Per-message framing overhead (role tags, tool wrappers). Small constant.
+  return total + messages.length * 4
+}
diff --git a/src/shell/services/embeddedAgent/types.ts b/src/shell/services/embeddedAgent/types.ts
new file mode 100644
index 0000000..117ced7
--- /dev/null
+++ b/src/shell/services/embeddedAgent/types.ts
@@ -0,0 +1,75 @@
+/**
+ * Shared types for the embedded agent UI surface. These are intentionally
+ * narrower than the provider-level types in `src/server/embedded-runner/`
+ * (when ANN-3 lands) — the shell only needs the event union it has to render.
+ *
+ * Keep field names aligned with the Anthropic SDK shape so the real runner can
+ * pipe events straight through.
+ */
+
+export interface AgentTextDelta {
+  kind: 'text'
+  /** Append-only text delta. */
+  delta: string
+}
+
+export interface AgentToolCall {
+  kind: 'tool_call'
+  id: string
+  name: string
+  input: Record<string, unknown>
+}
+
+export interface AgentToolResult {
+  kind: 'tool_result'
+  toolUseId: string
+  /** Short, human-readable summary for the transcript. Full payload is in `data`. */
+  summary: string
+  data?: unknown
+  isError?: boolean
+}
+
+export interface AgentUsage {
+  kind: 'usage'
+  /** Tokens billed at the standard input rate. */
+  input: number
+  /** Tokens billed at the output rate. */
+  output: number
+  /** Tokens served from the prompt cache (billed at 10% of input rate). */
+  cacheRead?: number
+  /** Tokens written to the prompt cache (billed at 125% of input rate). */
+  cacheWrite?: number
+}
+
+export interface AgentDone {
+  kind: 'done'
+  /** Final diff or summary the user is meant to see in silent mode. */
+  finalDiff?: string
+  /** Optional reason: 'completed' | 'aborted' | 'cap_exceeded' | 'error'. */
+  reason: 'completed' | 'aborted' | 'cap_exceeded' | 'error'
+  message?: string
+}
+
+export type AgentEvent =
+  | AgentTextDelta
+  | AgentToolCall
+  | AgentToolResult
+  | AgentUsage
+  | AgentDone
+
+export interface AgentRunRequest {
+  taskId: string
+  /** The change the user wants the agent to apply. */
+  task: unknown
+  /** Anthropic model id, e.g. 'claude-sonnet-4-5'. */
+  model: string
+  /** Per-task USD cap. Runner aborts when running total exceeds this. */
+  capUsd: number
+  /** Caller-provided AbortSignal so the UI can cancel cleanly. */
+  signal: AbortSignal
+}
+
+export interface AgentRunner {
+  /** Async iterable of events. Implementation is expected to honour `signal`. */
+  run(req: AgentRunRequest): AsyncIterable<AgentEvent>
+}
diff --git a/src/shell/services/mcpClient.ts b/src/shell/services/mcpClient.ts
new file mode 100644
index 0000000..ad71fd2
--- /dev/null
+++ b/src/shell/services/mcpClient.ts
@@ -0,0 +1,88 @@
+/**
+ * Browser-side MCP client. The embedded agent uses the same JSON-RPC endpoint
+ * that external editor agents (Claude Code, Cursor, Windsurf) hit, so there's
+ * one tool dispatcher serving both worlds. See src/mcp/tools.ts for the
+ * authoritative tool list and handlers.
+ *
+ * Wire format: Streamable HTTP transport, POST /__annotask/mcp with one
+ * JSON-RPC request per call. Batches are supported by the server but we don't
+ * need them here — the embedded agent dispatches one tool at a time.
+ */
+
+export interface McpToolDescriptor {
+  name: string
+  description: string
+  inputSchema: Record<string, unknown>
+}
+
+export interface McpToolContent {
+  type: string
+  text?: string
+  data?: string
+  mimeType?: string
+}
+
+export interface McpToolResult {
+  content: McpToolContent[]
+  isError?: boolean
+}
+
+const ENDPOINT = '/__annotask/mcp'
+
+let cachedCatalog: McpToolDescriptor[] | null = null
+let inFlight: Promise<McpToolDescriptor[]> | null = null
+
+async function rpc<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T> {
+  const body = {
+    jsonrpc: '2.0',
+    method,
+    params,
+    id: Date.now(),
+  }
+  const res = await fetch(ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  if (!res.ok) {
+    throw new Error(`MCP transport error: ${res.status} ${res.statusText}`)
+  }
+  const payload = await res.json() as { result?: T; error?: { code: number; message: string } }
+  if (payload.error) {
+    throw new Error(`MCP error ${payload.error.code}: ${payload.error.message}`)
+  }
+  return payload.result as T
+}
+
+/**
+ * Fetch the MCP tool catalog. Cached for the lifetime of the page — the
+ * catalog is static within a dev-server lifetime; restart the dev server to
+ * pick up tool changes.
+ */
+export async function fetchMcpToolCatalog(): Promise<McpToolDescriptor[]> {
+  if (cachedCatalog) return cachedCatalog
+  if (inFlight) return inFlight
+  inFlight = (async () => {
+    const result = await rpc<{ tools: McpToolDescriptor[] }>('tools/list')
+    cachedCatalog = result.tools
+    return cachedCatalog
+  })()
+  try {
+    return await inFlight
+  } finally {
+    inFlight = null
+  }
+}
+
+/**
+ * Dispatch one MCP tool. Returns the result envelope verbatim so callers can
+ * surface `isError` to the agent.
+ */
+export async function callMcpTool(name: string, args: Record<string, unknown>): Promise<McpToolResult> {
+  return rpc<McpToolResult>('tools/call', { name, arguments: args })
+}
+
+/** Test hook: drop the cached catalog so the next call re-fetches. */
+export function resetMcpCatalogCache(): void {
+  cachedCatalog = null
+}
diff --git a/src/shell/services/wsClient.ts b/src/shell/services/wsClient.ts
index 82f54ee..cf4bd94 100644
--- a/src/shell/services/wsClient.ts
+++ b/src/shell/services/wsClient.ts
@@ -9,6 +9,11 @@
  * - The server pings every 30s; the browser auto-replies with pong.
  * - On visibilitychange → visible, we check the socket state and
  *   reconnect immediately if it's gone stale while backgrounded.
+ *
+ * Synthetic events (emitted locally, never sent by the server):
+ * - `reconnected` — fired when the socket re-opens after a drop. Server
+ *   pushes (tasks:updated, …) sent while we were dark are gone forever, so
+ *   subscribers use this to resync their state over HTTP.
  */
 
 type Handler = (data: unknown) => void
@@ -16,8 +21,18 @@ type Handler = (data: unknown) => void
 let ws: WebSocket | null = null
 let attempt = 0
 let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+// True once the socket has opened at least once — distinguishes the initial
+// connect (no resync needed, consumers fetch on init) from a re-open after
+// a drop (missed broadcasts, resync required).
+let wasConnected = false
 const listeners = new Map<string, Set<Handler>>()
 
+function emitLocal(event: string) {
+  const handlers = listeners.get(event)
+  if (!handlers) return
+  for (const handler of handlers) handler(undefined)
+}
+
 function getUrl() {
   const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
   return `${protocol}//${window.location.host}/__annotask/ws`
@@ -31,7 +46,10 @@ function connect() {
 
     ws.onopen = () => {
       attempt = 0
+      const isReconnect = wasConnected
+      wasConnected = true
       console.log('[Annotask] WebSocket connected')
+      if (isReconnect) emitLocal('reconnected')
     }
 
     ws.onmessage = (e) => {
@@ -81,9 +99,12 @@ function ensureConnected() {
 
 // When the tab becomes visible again, verify the connection is alive.
 // Background tabs can miss the close event if the OS/browser killed the socket.
-document.addEventListener('visibilitychange', () => {
-  if (document.visibilityState === 'visible') ensureConnected()
-})
+// Guard for non-browser environments (vitest) where `document` is undefined.
+if (typeof document !== 'undefined') {
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'visible') ensureConnected()
+  })
+}
 
 export function on(event: string, handler: Handler): () => void {
   if (!listeners.has(event)) listeners.set(event, new Set())
diff --git a/src/shell/styles/_ai-settings.css b/src/shell/styles/_ai-settings.css
new file mode 100644
index 0000000..71b7c49
--- /dev/null
+++ b/src/shell/styles/_ai-settings.css
@@ -0,0 +1,232 @@
+/*
+ * Shared visual language for the AI / Providers settings panels.
+ *
+ * Both `AISettingsPanel.vue` and `ProviderSettingsPanel.vue` consume these
+ * classes so the two surfaces feel like one settings system. New AI-adjacent
+ * panels (model picker, transcript drawer headers, etc.) should reuse the
+ * same primitives before inventing a parallel one.
+ */
+
+.ai-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 28px;
+  max-width: 560px;
+}
+
+.ai-section {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.ai-section-head { display: flex; flex-direction: column; gap: 2px; }
+
+.ai-section-title {
+  font-size: 13px;
+  font-weight: 700;
+  color: var(--text);
+  margin: 0;
+  letter-spacing: 0.005em;
+}
+
+.ai-section-desc {
+  font-size: 11.5px;
+  color: var(--text-muted);
+  line-height: 1.5;
+  margin: 0;
+}
+
+.ai-section-desc code,
+.ai-section-desc strong { color: var(--text); }
+
+.ai-section-desc code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 0.92em;
+  padding: 1px 4px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 3px;
+}
+
+.ai-field { display: flex; flex-direction: column; gap: 6px; }
+
+.ai-field-inline {
+  flex-direction: row;
+  align-items: center;
+  gap: 12px;
+}
+
+.ai-label {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--text);
+}
+
+.ai-input-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 0 8px 0 10px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  transition: border-color 120ms ease, background 120ms ease;
+}
+
+.ai-input-row:focus-within { border-color: var(--accent); }
+.ai-input-row-narrow { padding: 0 8px 0 10px; max-width: 160px; }
+
+.ai-input {
+  flex: 1;
+  background: transparent;
+  border: none;
+  outline: none;
+  padding: 8px 0;
+  font-size: 12.5px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  color: var(--text);
+  min-width: 0;
+}
+
+.ai-input::placeholder { color: var(--text-muted); opacity: 0.7; }
+
+.ai-input-narrow {
+  font-family: inherit;
+  font-variant-numeric: tabular-nums;
+  width: 80px;
+}
+
+.ai-prefix {
+  color: var(--text-muted);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+
+.ai-icon-btn {
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: var(--text-muted);
+  padding: 4px;
+  border-radius: 4px;
+  display: inline-flex;
+  align-items: center;
+}
+
+.ai-icon-btn:hover { background: var(--surface-3, var(--surface-2)); color: var(--text); }
+
+.ai-hint {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 10.5px;
+  color: var(--text-muted);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
+
+.ai-actions { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
+
+.ai-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 6px 12px;
+  font-size: 11.5px;
+  font-weight: 600;
+  border-radius: 6px;
+  border: 1px solid var(--border);
+  cursor: pointer;
+  text-decoration: none;
+  transition: opacity 120ms ease, border-color 120ms ease;
+  font-family: inherit;
+}
+
+.ai-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+
+.ai-btn-primary {
+  background: var(--accent);
+  color: var(--text-on-accent);
+  border-color: var(--accent);
+}
+
+.ai-btn-primary:hover:not(:disabled) {
+  background: var(--accent-hover, var(--accent));
+  border-color: var(--accent-hover, var(--accent));
+}
+
+.ai-btn-ghost { background: var(--surface-2); color: var(--text); }
+.ai-btn-ghost:hover { border-color: var(--text-muted); }
+
+.ai-validation {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 11px;
+  font-weight: 500;
+  padding: 5px 10px;
+  border-radius: 6px;
+  align-self: flex-start;
+  line-height: 1.4;
+}
+
+.ai-validation.tone-success {
+  background: color-mix(in srgb, var(--success) 14%, transparent);
+  color: var(--success);
+}
+
+.ai-validation.tone-danger {
+  background: color-mix(in srgb, var(--danger) 14%, transparent);
+  color: var(--danger);
+}
+
+.ai-validation.tone-warning {
+  background: color-mix(in srgb, var(--warning) 14%, transparent);
+  color: var(--warning);
+}
+
+.ai-validation.tone-info {
+  background: var(--accent-muted);
+  color: var(--accent);
+}
+
+.ai-validation.tone-muted {
+  background: var(--surface-2);
+  color: var(--text-muted);
+}
+
+.ai-model-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(170px, 1fr));
+  gap: 8px;
+}
+
+.ai-model-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 10px 12px;
+  background: var(--surface-2);
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  cursor: pointer;
+  text-align: left;
+  transition: border-color 120ms ease;
+  color: var(--text);
+  font: inherit;
+}
+
+.ai-model-card:hover { border-color: var(--text-muted); }
+
+.ai-model-card.active {
+  border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 8%, var(--surface-2));
+}
+
+.ai-model-name { font-size: 12.5px; font-weight: 600; color: var(--text); }
+
+.ai-model-rate {
+  font-size: 10.5px;
+  color: var(--text-muted);
+  font-variant-numeric: tabular-nums;
+}
diff --git a/src/shell/styles/_canvas.css b/src/shell/styles/_canvas.css
index 8ecaebf..06678bf 100644
--- a/src/shell/styles/_canvas.css
+++ b/src/shell/styles/_canvas.css
@@ -36,8 +36,40 @@
   cursor: crosshair;
 }
 
-.drawing-shield.draw {
-  cursor: crosshair;
+
+/* Wireframe palette: transparent catcher over the iframe so native drag events
+   reach the shell. Always present but inert (pointer-events:none) until a drag
+   starts — `.active` turns it on without a mid-drag mount race. */
+.palette-drop-shield {
+  position: absolute;
+  inset: 0;
+  z-index: 9999;
+  pointer-events: none;
+}
+.palette-drop-shield.active {
+  pointer-events: auto;
+  cursor: copy;
+}
+
+/* Live drop indicator inside .overlay-layer (canvas-area-relative coords).
+   Outlines the resolved drop target; a top/bottom inset edge bar marks a
+   'before'/'after' insertion point. */
+.drop-indicator {
+  position: absolute;
+  z-index: 9998;
+  pointer-events: none;
+  border: 2px dashed var(--accent);
+  border-radius: 4px;
+  background: color-mix(in srgb, var(--accent) 10%, transparent);
+  box-sizing: border-box;
+}
+
+.drop-indicator.before {
+  border-top: 3px solid var(--accent);
+}
+
+.drop-indicator.after {
+  border-bottom: 3px solid var(--accent);
 }
 
 /* Main layout */
diff --git a/src/shell/styles/_highlights.css b/src/shell/styles/_highlights.css
index c7ae4f4..d49e55a 100644
--- a/src/shell/styles/_highlights.css
+++ b/src/shell/styles/_highlights.css
@@ -43,18 +43,29 @@
 }
 
 /* Data view — per-source highlights driven by useDataHighlights.
- * --hl-color is set inline per overlay from the annotation palette.
- * Dotted outline only, no fill — keeps the underlying content readable. */
+ * --hl-color is set inline per overlay (annotation palette = identity, or a
+ * latency bucket on the Network tab). Transparent fill keeps content readable.
+ *
+ * Three signals, three independent channels — so they never alias each other:
+ *   COLOR (--hl-color)       → identity, OR latency when `.latency` is set
+ *   BORDER STYLE             → confidence: dashed = precise, dotted = approximate
+ *   CORNER GLYPH (::before)  → an always-on confidence marker, legible on any
+ *                              theme regardless of the rect's opacity
+ * Opacity now encodes ONLY interaction state (focus/dim); it no longer carries
+ * confidence, so a file-level match is just as visible as a precise one. */
 .highlight.data-source {
   background: transparent;
   border: 2px dashed var(--hl-color);
-  opacity: 0.7;
-  transition: opacity 0.12s ease-out, border-width 0.12s ease-out;
+  opacity: 0.75;
+  transition: opacity 0.12s ease-out, border-width 0.12s ease-out, box-shadow 0.12s ease-out;
 }
 
+/* Focus 'pop' — a colored glow ring (not a transform, so the rect stays aligned
+ * to its element) makes the newly-focused set perceptible on a dense page. */
 .highlight.data-source.focused {
   border-width: 3px;
   opacity: 1;
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--hl-color) 35%, transparent);
 }
 
 .highlight.data-source.dimmed {
@@ -68,33 +79,64 @@
 .highlight.data-source.hover-only.dimmed { opacity: 0; }
 .highlight.data-source.hover-only.focused { opacity: 1; }
 
-/* Fallback confidence — dotted + dimmer. A wildcard file-level match
- * shouldn't read as authoritative as a precise AST binding. Focused/
- * dimmed variants compose with the base `.data-source` rules. */
-.highlight.data-source.fallback {
+/* Confidence = border style + an always-on corner glyph (NOT opacity).
+ * 'fallback' is a file-level wildcard match; 'runtime-only' is a network call
+ * with no resolved static site. Both are "approximate" — dotted border plus an
+ * ≈ marker pinned INSIDE the rect (top-left) so `.overlay-layer`'s
+ * overflow:hidden can't clip it at the canvas edge. A surface-filled chip with
+ * a colored glyph stays legible on light and dark themes alike. */
+.highlight.data-source.fallback,
+.highlight.data-source.runtime-only {
   border-style: dotted;
-  opacity: 0.4;
 }
-.highlight.data-source.fallback.focused { opacity: 0.9; }
+.highlight.data-source.fallback::before,
+.highlight.data-source.runtime-only::before {
+  content: '≈';
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  min-width: 14px;
+  height: 14px;
+  padding: 0 3px;
+  font-size: 10px;
+  font-weight: 700;
+  font-family: monospace;
+  line-height: 14px;
+  text-align: center;
+  color: var(--hl-color);
+  background: var(--surface);
+  border: 1px solid var(--hl-color);
+  border-radius: 7px;
+  pointer-events: none;
+}
+
+/* Latency encoding (Network tab) — color means "how slow", not "which source".
+ * A solid border keeps an orange "slow endpoint" visually distinct from an
+ * orange identity hue elsewhere. Ordered after the confidence rules so the
+ * solid border wins for a (rare) latency+approximate combo. */
+.highlight.data-source.latency {
+  border-style: solid;
+}
 
 /* Multi-owner overlay — same element is powered by more than one source.
- * Count badge pinned to the top-right; `data-multi-count` is the raw
- * count string set inline by App.vue. */
+ * Count badge pinned INSIDE the top-right corner (was top:-9px/right:-9px,
+ * which `.overlay-layer { overflow:hidden }` clipped for edge elements) so it's
+ * always visible. The confidence ≈ glyph sits top-left, so they never collide. */
 .highlight.data-source.multi::after {
   content: attr(data-multi-count);
   position: absolute;
-  top: -9px;
-  right: -9px;
-  min-width: 18px;
-  height: 18px;
-  padding: 0 4px;
-  font-size: 10px;
+  top: 2px;
+  right: 2px;
+  min-width: 16px;
+  height: 16px;
+  padding: 0 3px;
+  font-size: 9px;
   font-weight: 700;
   font-family: monospace;
   color: var(--text-on-accent, white);
   background: var(--accent);
-  border: 2px solid var(--surface);
-  border-radius: 9px;
+  border: 1px solid var(--surface);
+  border-radius: 8px;
   display: inline-flex;
   align-items: center;
   justify-content: center;
diff --git a/src/shell/styles/_tasks.css b/src/shell/styles/_tasks.css
index 2a2f013..f908575 100644
--- a/src/shell/styles/_tasks.css
+++ b/src/shell/styles/_tasks.css
@@ -45,6 +45,23 @@
 .task-status-dot.in_progress {
   background: var(--accent);
 }
+/* Pulsing live-activity ring — applied while an embedded agent run is
+   actively touching this task (independent of task.status, which the
+   agent doesn't always update in chat-only flows). */
+.task-status-dot.active-run {
+  animation: task-status-dot-pulse 1.4s ease-in-out infinite;
+  box-shadow: 0 0 0 0 color-mix(in srgb, var(--accent) 50%, transparent);
+}
+@keyframes task-status-dot-pulse {
+  0%, 100% {
+    opacity: 1;
+    box-shadow: 0 0 0 0 color-mix(in srgb, var(--accent) 60%, transparent);
+  }
+  50% {
+    opacity: 0.7;
+    box-shadow: 0 0 0 4px color-mix(in srgb, var(--accent) 0%, transparent);
+  }
+}
 
 .task-status-dot.review {
   background: var(--warning);
diff --git a/src/shell/themes/builtin.ts b/src/shell/themes/builtin.ts
index 2b19edb..9a92276 100644
--- a/src/shell/themes/builtin.ts
+++ b/src/shell/themes/builtin.ts
@@ -58,7 +58,6 @@ function deriveDefaults(core: ThemeCoreColors, overrides?: Partial<ShellThemeCol
     // Modes — arrow and highlight are fixed across all themes for consistency
     'mode-interact': core.indigo,
     'mode-arrow': '#ef4444',
-    'mode-draw': core['text-muted'],
     'mode-highlight': '#f59e0b',
 
     // Layout viz
diff --git a/src/shell/themes/types.ts b/src/shell/themes/types.ts
index e43968c..b86636d 100644
--- a/src/shell/themes/types.ts
+++ b/src/shell/themes/types.ts
@@ -60,7 +60,6 @@ export interface ShellThemeColors {
   // ── Interaction modes ──
   'mode-interact': string
   'mode-arrow': string
-  'mode-draw': string
   'mode-highlight': string
 
   // ── Layout visualization ──
@@ -118,7 +117,7 @@ export const THEME_COLOR_KEYS: (keyof ShellThemeColors)[] = [
   'status-pending', 'status-in-progress', 'status-review', 'status-denied',
   'status-accepted', 'status-needs-info', 'status-blocked',
   'severity-critical', 'severity-serious', 'severity-moderate', 'severity-minor',
-  'mode-interact', 'mode-arrow', 'mode-draw', 'mode-highlight',
+  'mode-interact', 'mode-arrow', 'mode-highlight',
   'layout-flex', 'layout-grid',
   'role-container', 'role-content', 'role-component',
   'syntax-property', 'syntax-string', 'syntax-number', 'syntax-boolean',
diff --git a/src/shell/utils/__tests__/bindingShape.test.ts b/src/shell/utils/__tests__/bindingShape.test.ts
new file mode 100644
index 0000000..a31ff2a
--- /dev/null
+++ b/src/shell/utils/__tests__/bindingShape.test.ts
@@ -0,0 +1,186 @@
+import { describe, it, expect } from 'vitest'
+import { flattenShape, fieldCandidates, sampleRows, buildBinding } from '../bindingShape'
+import type { DataShapeNode } from '../../../schema'
+
+// Cat[] with a nested owner object and a cycle-ref leaf — mirrors the server
+// fixture in data-source-shape.test.ts.
+const CATS: DataShapeNode = {
+  kind: 'array',
+  item: {
+    kind: 'object',
+    children: {
+      name: { kind: 'scalar', scalar: 'string' },
+      price: { kind: 'scalar', scalar: 'number' },
+      owner: { kind: 'object', children: { email: { kind: 'scalar', scalar: 'string' } } },
+      parent: { kind: 'ref', ref: 'Cat' },
+    },
+  },
+}
+
+describe('flattenShape', () => {
+  it('collapsed root shows one row, expandable + selectable, array path "[]"', () => {
+    const rows = flattenShape(CATS, new Set())
+    expect(rows).toHaveLength(1)
+    expect(rows[0]).toMatchObject({ path: '[]', key: '(response)', depth: 0, selectable: true, expandable: true })
+  })
+
+  it('expanding an array surfaces its item-object keys under the array path', () => {
+    const rows = flattenShape(CATS, new Set(['[]']))
+    expect(rows.map(r => r.path)).toEqual(['[]', '[].name', '[].price', '[].owner', '[].parent'])
+    const owner = rows.find(r => r.key === 'owner')!
+    expect(owner).toMatchObject({ depth: 1, selectable: true, expandable: true })
+    const name = rows.find(r => r.key === 'name')!
+    expect(name).toMatchObject({ selectable: false, expandable: false })
+  })
+
+  it('nested expansion produces dotted paths', () => {
+    const rows = flattenShape(CATS, new Set(['[]', '[].owner']))
+    expect(rows.map(r => r.path)).toContain('[].owner.email')
+  })
+
+  it('an object root yields plain keys; nested arrays append []', () => {
+    const root: DataShapeNode = {
+      kind: 'object',
+      children: {
+        data: { kind: 'object', children: { user: { kind: 'object', children: {} } } },
+        items: { kind: 'array', item: { kind: 'scalar', scalar: 'string' } },
+      },
+    }
+    const rows = flattenShape(root, new Set(['', 'data', 'items[]']))
+    const paths = rows.map(r => r.path)
+    expect(paths).toContain('data.user')
+    expect(paths).toContain('items[]')
+    // Scalar array item renders a synthetic row under the array path.
+    expect(rows.find(r => r.key === '(item)')?.path).toBe('items[].(item)')
+  })
+
+  it('ref leaves do not expand', () => {
+    const rows = flattenShape(CATS, new Set(['[]', 'parent']))
+    expect(rows.filter(r => r.path.startsWith('parent.')).length).toBe(0)
+  })
+})
+
+describe('fieldCandidates', () => {
+  it('arrays offer their item-object scalar/ref keys', () => {
+    expect(fieldCandidates(CATS)).toEqual(['name', 'price', 'parent'])
+  })
+
+  it('objects offer their own scalar/ref keys', () => {
+    expect(fieldCandidates(CATS.item!)).toEqual(['name', 'price', 'parent'])
+    expect(fieldCandidates({ kind: 'object', children: { email: { kind: 'scalar', scalar: 'string' } } })).toEqual(['email'])
+  })
+
+  it('non-objects offer nothing', () => {
+    expect(fieldCandidates({ kind: 'scalar', scalar: 'string' })).toEqual([])
+    expect(fieldCandidates({ kind: 'ref', ref: 'Cat' })).toEqual([])
+    expect(fieldCandidates({ kind: 'array', item: { kind: 'scalar', scalar: 'string' } })).toEqual([])
+  })
+})
+
+describe('sampleRows', () => {
+  it('uses an array example of objects as distinct rows, capped at n, fields only', () => {
+    const node: DataShapeNode = {
+      kind: 'array',
+      example: [
+        { name: 'Mercury', type: 'rocky', moons: 0 },
+        { name: 'Venus', type: 'rocky' },
+        { name: 'Earth', type: 'rocky' },
+        { name: 'Mars', type: 'rocky' },
+      ],
+      item: { kind: 'object', children: { name: { kind: 'scalar', scalar: 'string' }, type: { kind: 'scalar', scalar: 'string' } } },
+    }
+    expect(sampleRows(node, ['name', 'type'], 3)).toEqual([
+      { name: 'Mercury', type: 'rocky' },
+      { name: 'Venus', type: 'rocky' },
+      { name: 'Earth', type: 'rocky' },
+    ])
+  })
+
+  it('falls back to per-field examples on the item children (one row)', () => {
+    const node: DataShapeNode = {
+      kind: 'array',
+      item: {
+        kind: 'object',
+        children: {
+          name: { kind: 'scalar', scalar: 'string', example: 'Saturn' },
+          type: { kind: 'scalar', scalar: 'string', example: 'gas giant' },
+        },
+      },
+    }
+    expect(sampleRows(node, ['name', 'type'], 3)).toEqual([{ name: 'Saturn', type: 'gas giant' }])
+  })
+
+  it('uses a single object example for a non-array node', () => {
+    const node: DataShapeNode = {
+      kind: 'object',
+      example: { name: 'Earth', type: 'rocky' },
+      children: { name: { kind: 'scalar', scalar: 'string' }, type: { kind: 'scalar', scalar: 'string' } },
+    }
+    expect(sampleRows(node, ['name'], 3)).toEqual([{ name: 'Earth' }])
+  })
+
+  it('returns [] when the contract carries no examples (caller falls back to tokens)', () => {
+    expect(sampleRows(CATS, ['name', 'price'], 3)).toEqual([])
+  })
+
+  it('keeps only scalar field values', () => {
+    const node: DataShapeNode = {
+      kind: 'array',
+      example: [{ name: 'A', owner: { email: 'x@y.z' } }],
+      item: { kind: 'object', children: { name: { kind: 'scalar', scalar: 'string' } } },
+    }
+    expect(sampleRows(node, ['name', 'owner'], 3)).toEqual([{ name: 'A' }])
+  })
+})
+
+describe('buildBinding', () => {
+  const entry = { kind: 'composable' as const, name: 'usePlanets', file: 'src/composables/usePlanets.ts', endpoint: '/api/solar/planets' }
+
+  it('assembles a valid plain-JSON binding (module = catalog file)', () => {
+    const b = buildBinding(entry, { path: 'planets[]', fields: ['name', 'type'], shape_source: 'api-schema' })
+    expect(b).toEqual({
+      kind: 'composable',
+      name: 'usePlanets',
+      module: 'src/composables/usePlanets.ts',
+      endpoint: '/api/solar/planets',
+      path: 'planets[]',
+      fields: ['name', 'type'],
+      shape_source: 'api-schema',
+    })
+  })
+
+  it('trims and drops empty path/fields', () => {
+    const b = buildBinding(entry, { path: '  ', fields: [' name ', ''], shape_source: 'none' })
+    expect(b.path).toBeUndefined()
+    expect(b.fields).toEqual(['name'])
+  })
+
+  it('omits module/endpoint when the entry lacks them', () => {
+    const b = buildBinding({ kind: 'fetch', name: 'apiHealth', file: '', endpoint: undefined }, { shape_source: 'none' })
+    expect(b).toEqual({ kind: 'fetch', name: 'apiHealth', shape_source: 'none' })
+  })
+
+  it('throws on an unbuildable binding instead of persisting garbage', () => {
+    expect(() => buildBinding({ kind: 'composable', name: '', file: 'x.ts', endpoint: undefined }, { shape_source: 'none' })).toThrow()
+  })
+
+  it('carries sample rows, a >1 repeat, and a non-empty propMap when given', () => {
+    const b = buildBinding(entry, {
+      path: 'planets[]', fields: ['name'], shape_source: 'api-schema',
+      sample: [{ name: 'Mercury' }], repeat: 3, propMap: { label: 'name' },
+    })
+    expect(b.sample).toEqual([{ name: 'Mercury' }])
+    expect(b.repeat).toBe(3)
+    expect(b.propMap).toEqual({ label: 'name' })
+  })
+
+  it('drops empty sample/propMap and a repeat of 1', () => {
+    const b = buildBinding(entry, {
+      path: 'planets[]', fields: ['name'], shape_source: 'api-schema',
+      sample: [], repeat: 1, propMap: {},
+    })
+    expect(b.sample).toBeUndefined()
+    expect(b.repeat).toBeUndefined()
+    expect(b.propMap).toBeUndefined()
+  })
+})
diff --git a/src/shell/utils/__tests__/toolSummary.test.ts b/src/shell/utils/__tests__/toolSummary.test.ts
new file mode 100644
index 0000000..7280357
--- /dev/null
+++ b/src/shell/utils/__tests__/toolSummary.test.ts
@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest'
+import { summarizeToolCall, summarizeToolResult } from '../toolSummary'
+
+describe('summarizeToolCall', () => {
+  it('renders Read with offset+limit as a line range', () => {
+    expect(summarizeToolCall('Read', { file_path: 'src/App.vue', offset: 42, limit: 48 }))
+      .toBe('Reading src/App.vue:42-89')
+  })
+
+  it('renders Read with just offset as :42+', () => {
+    expect(summarizeToolCall('Read', { file_path: 'src/App.vue', offset: 42 }))
+      .toBe('Reading src/App.vue:42+')
+  })
+
+  it('renders bare Read paths', () => {
+    expect(summarizeToolCall('Read', { file_path: 'package.json' }))
+      .toBe('Reading package.json')
+  })
+
+  it('renders Edit and Write', () => {
+    expect(summarizeToolCall('Write', { file_path: 'a.ts' })).toBe('Writing a.ts')
+    expect(summarizeToolCall('Edit', { file_path: 'a.ts' })).toBe('Editing a.ts')
+  })
+
+  it('renders MultiEdit with count', () => {
+    expect(summarizeToolCall('MultiEdit', { file_path: 'a.ts', edits: [{}, {}, {}] }))
+      .toBe('Editing a.ts (3 edits)')
+  })
+
+  it('renders Bash with a truncated command', () => {
+    expect(summarizeToolCall('Bash', { command: 'npm test' })).toBe('Running npm test')
+    expect(summarizeToolCall('Bash', { command: 'a'.repeat(200) })).toMatch(/^Running a+…/)
+  })
+
+  it('renders Grep with pattern + path', () => {
+    expect(summarizeToolCall('Grep', { pattern: 'TODO', path: 'src/' }))
+      .toBe('Searching for "TODO" in src/')
+  })
+
+  it('renders Glob with the pattern', () => {
+    expect(summarizeToolCall('Glob', { pattern: '**/*.ts' })).toBe('Listing **/*.ts')
+  })
+
+  it('renders WebFetch + WebSearch', () => {
+    expect(summarizeToolCall('WebFetch', { url: 'https://x.test' }))
+      .toBe('Fetching https://x.test')
+    expect(summarizeToolCall('WebSearch', { query: 'vue 3 ref' }))
+      .toBe('Searching the web for "vue 3 ref"')
+  })
+
+  it('renders Task delegations', () => {
+    expect(summarizeToolCall('Task', { description: 'refactor color', subagent_type: 'Explore' }))
+      .toBe('Delegating to Explore: refactor color')
+  })
+
+  it('falls back to name(args) for unknown tools', () => {
+    expect(summarizeToolCall('UnknownTool', { key: 'value', count: 3 }))
+      .toBe('UnknownTool(key="value", count=3)')
+  })
+
+  it('handles non-object inputs without throwing', () => {
+    expect(summarizeToolCall('Read', null)).toBe('Reading file')
+    expect(summarizeToolCall('Bash', 'literal string')).toBe('Running shell command')
+  })
+})
+
+describe('summarizeToolResult', () => {
+  it('returns "OK" for empty success', () => {
+    expect(summarizeToolResult('')).toBe('OK')
+  })
+
+  it('returns "Error" for empty failure', () => {
+    expect(summarizeToolResult('', true)).toBe('Error')
+  })
+
+  it('prefixes Error with the first line', () => {
+    expect(summarizeToolResult('Module not found\nat line 5', true))
+      .toBe('Error: Module not found')
+  })
+
+  it('reports line count when content is multi-line', () => {
+    expect(summarizeToolResult('a\nb\nc\nd\ne')).toBe('5 lines returned')
+  })
+
+  it('returns a truncated first line for short content', () => {
+    expect(summarizeToolResult('single line answer')).toBe('single line answer')
+  })
+})
diff --git a/src/shell/utils/__tests__/wireframeDirections.test.ts b/src/shell/utils/__tests__/wireframeDirections.test.ts
new file mode 100644
index 0000000..27b8ee4
--- /dev/null
+++ b/src/shell/utils/__tests__/wireframeDirections.test.ts
@@ -0,0 +1,297 @@
+import { describe, it, expect } from 'vitest'
+import { computeWireframeDirections, directionAnchor } from '../wireframeDirections'
+import type { WireframeBlock, WireframeCanvasState } from '../../../shared/wireframe-types'
+
+function captured(id: string, y: number, height: number, line: number, extra: Partial<WireframeBlock> = {}): WireframeBlock {
+  const rect = { x: 0, y, width: 800, height }
+  return {
+    id,
+    kind: 'captured',
+    rect: { ...rect },
+    originalRect: { ...rect },
+    z: 1,
+    createdAt: 1,
+    anchor: { file: 'src/pages/PlanetsPage.vue', line, component: 'PlanetsPage', sourceTag: id, tag: 'div' },
+    ...extra,
+  }
+}
+
+function canvasWith(blocks: WireframeBlock[]): WireframeCanvasState {
+  return {
+    capturedAt: 1,
+    viewport: { width: 1280, height: 800, docWidth: 1280, docHeight: 2400, scale: 2 },
+    blocks,
+  }
+}
+
+// The /planets shape: page header, filters toolbar, planet grid.
+function planetsBlocks(): WireframeBlock[] {
+  return [
+    captured('page-header', 0, 80, 85),
+    captured('filters', 100, 60, 94),
+    captured('grid', 180, 600, 128),
+  ]
+}
+
+describe('computeWireframeDirections', () => {
+  it('canvas jitter below thresholds produces zero directions', () => {
+    const blocks = planetsBlocks()
+    blocks[0].rect = { ...blocks[0].rect, x: 2, y: 1 } // 3px total
+    blocks[1].rect = { ...blocks[1].rect, width: 803 } // 3px, <2%
+    expect(computeWireframeDirections(canvasWith(blocks))).toEqual([])
+  })
+
+  it('a move past the threshold emits ONE direction with the order-flip relation', () => {
+    const blocks = planetsBlocks()
+    // Grid moves above the filters toolbar.
+    blocks[2].rect = { ...blocks[2].rect, y: 90 }
+    blocks[1].rect = { ...blocks[1].rect, y: 700 } // filters pushed below
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs).toHaveLength(2) // grid move + filters move
+    const grid = dirs.find((d) => d.block.label === 'grid')!
+    expect(grid.op).toBe('move')
+    expect(grid.file).toBe('src/pages/PlanetsPage.vue')
+    expect(grid.line).toBe(128)
+    expect(grid.measured?.relations).toContain('now above the filters (was below)')
+    expect(grid.measured?.dy).toBe(-90)
+    expect(grid.description).toMatch(/^MOVE the grid \(src\/pages\/PlanetsPage\.vue:128\)/)
+  })
+
+  it('moved AND resized collapses into one move direction carrying the resize facts', () => {
+    const blocks = planetsBlocks()
+    blocks[2].rect = { x: 0, y: 90, width: 1200, height: 300 }
+    blocks[1].rect = { ...blocks[1].rect, y: 700 }
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    const grid = dirs.find((d) => d.block.label === 'grid')!
+    expect(grid.op).toBe('move')
+    expect(grid.measured?.wPct).toBe(150)
+    expect(grid.measured?.hPct).toBe(50)
+    expect(dirs.filter((d) => d.block.label === 'grid')).toHaveLength(1)
+  })
+
+  it('resize-only emits px + % facts', () => {
+    const blocks = planetsBlocks()
+    blocks[1].rect = { ...blocks[1].rect, width: 400, height: 90 }
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs).toHaveLength(1)
+    expect(dirs[0].op).toBe('resize')
+    expect(dirs[0].measured).toMatchObject({ wPct: 50, hPct: 150 })
+    expect(dirs[0].description).toContain('800x60 → 400x90')
+    expect(dirs[0].description).toContain('(-50% w, +50% h)')
+  })
+
+  it('soft-deleted captured blocks emit delete anchored at their source', () => {
+    const blocks = planetsBlocks()
+    blocks[1].deleted = true
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs).toEqual([
+      expect.objectContaining({
+        op: 'delete',
+        file: 'src/pages/PlanetsPage.vue',
+        line: 94,
+        description: 'DELETE the filters (src/pages/PlanetsPage.vue:94)',
+      }),
+    ])
+  })
+
+  it('palette drops emit add with REAL component names, anchored at the nearest captured neighbor', () => {
+    const blocks = planetsBlocks()
+    blocks.push({
+      id: 'pal-1',
+      kind: 'palette',
+      rect: { x: 0, y: 800, width: 320, height: 140 }, // just below the grid
+      z: 9,
+      createdAt: 2,
+      component: { tag: 'planetcard', componentName: 'PlanetCard', module: './components/PlanetCard.vue', props: { compact: true } },
+      fidelity: 'isolated-preview',
+    })
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs).toHaveLength(1)
+    const add = dirs[0]
+    expect(add.op).toBe('add')
+    expect(add.added).toMatchObject({
+      kind: 'component',
+      componentName: 'PlanetCard',
+      module: './components/PlanetCard.vue',
+      props: { compact: true },
+      position: 'after', // neighbor (grid) is visually above → insert after it
+    })
+    expect(add.file).toBe('src/pages/PlanetsPage.vue')
+    expect(add.line).toBe(128) // grid anchor
+    expect(add.description).toContain('ADD component <PlanetCard>')
+  })
+
+  it('placeholders carry the user label verbatim and stay visibly placeholders', () => {
+    const blocks = planetsBlocks()
+    blocks.push({
+      id: 'ph-1',
+      kind: 'placeholder',
+      rect: { x: 60, y: 790, width: 360, height: 80 },
+      z: 9,
+      createdAt: 2,
+      label: 'pagination here',
+    })
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs).toHaveLength(1)
+    expect(dirs[0].added).toMatchObject({ kind: 'placeholder', label: 'pagination here', position: 'after' })
+    // Regression lock: a BARE placeholder's payload and description stay
+    // byte-stable — md/data must not leak empty fields or new phrasing in.
+    expect(dirs[0].added!.md).toBeUndefined()
+    expect(dirs[0].added!.data).toBeUndefined()
+    expect(dirs[0].description).toContain('placeholder "pagination here"')
+    expect(dirs[0].description).toContain('keep it visibly a placeholder')
+    expect(dirs[0].description).not.toContain('markdown spec')
+    expect(dirs[0].description).not.toContain('bind to the')
+  })
+
+  it('a section (md + binding) rides added.md/.data verbatim; the description summarizes honestly', () => {
+    const blocks = planetsBlocks()
+    const md = '## Related planets\n- name and type for each'
+    blocks.push({
+      id: 'sec-1',
+      kind: 'placeholder',
+      rect: { x: 60, y: 790, width: 360, height: 120 },
+      z: 9,
+      createdAt: 2,
+      label: 'related planets',
+      md,
+      data: {
+        kind: 'composable',
+        name: 'usePlanets',
+        module: 'src/composables/usePlanets.ts',
+        path: 'planets[]',
+        fields: ['name', 'type'],
+        shape_source: 'api-schema',
+      },
+    })
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs).toHaveLength(1)
+    // Verbatim channels — never paraphrased, never blended with geometry.
+    expect(dirs[0].added!.md).toBe(md)
+    expect(dirs[0].added!.data).toEqual({
+      kind: 'composable',
+      name: 'usePlanets',
+      module: 'src/composables/usePlanets.ts',
+      path: 'planets[]',
+      fields: ['name', 'type'],
+      shape_source: 'api-schema',
+    })
+    expect(dirs[0].measured!.after).toBeDefined()
+    // The description quotes only the md's first line + an honest binding summary.
+    expect(dirs[0].description).toContain('drawn section "related planets"')
+    expect(dirs[0].description).not.toContain('keep it visibly a placeholder') // the md spec IS the contract
+    expect(dirs[0].description).toContain('first line: "Related planets"')
+    expect(dirs[0].description).not.toContain('name and type for each')
+    expect(dirs[0].description).toContain('bind to the composable usePlanets → planets[] (show name, type)')
+    expect(dirs[0].description).toContain('[shape: api-schema]')
+    // A list path adds a v-for loop note (render all items, not the sketch count).
+    expect(dirs[0].description).toContain('render a v-for over planets[]')
+  })
+
+  it('a bound palette component carries added.data too', () => {
+    const blocks = planetsBlocks()
+    blocks.push({
+      id: 'pal-2',
+      kind: 'palette',
+      rect: { x: 60, y: 790, width: 320, height: 100 },
+      z: 9,
+      createdAt: 2,
+      component: { tag: 'planetcard', componentName: 'PlanetCard', module: './components/PlanetCard.vue' },
+      fidelity: 'isolated-preview',
+      data: { kind: 'composable', name: 'usePlanets', path: 'planets[]', shape_source: 'api-schema' },
+    })
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs).toHaveLength(1)
+    expect(dirs[0].added).toMatchObject({
+      kind: 'component',
+      componentName: 'PlanetCard',
+      data: { name: 'usePlanets', path: 'planets[]' },
+    })
+    expect(dirs[0].description).toContain('bind to the composable usePlanets')
+  })
+
+  it('a note on an otherwise-unchanged block emits op note with the verbatim text', () => {
+    const blocks = planetsBlocks()
+    blocks[1].note = 'make this a carousel'
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs).toEqual([
+      expect.objectContaining({
+        op: 'note',
+        note: 'make this a carousel',
+        description: 'NOTE on the filters (src/pages/PlanetsPage.vue:94): user said: "make this a carousel"',
+      }),
+    ])
+  })
+
+  it('a note on a moved block rides the move direction — never a second entry', () => {
+    const blocks = planetsBlocks()
+    blocks[2].rect = { ...blocks[2].rect, y: 90 }
+    blocks[2].note = 'keep the cards square'
+    blocks[1].deleted = true
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    const grid = dirs.filter((d) => d.block.label === 'grid')
+    expect(grid).toHaveLength(1)
+    expect(grid[0].op).toBe('move')
+    expect(grid[0].note).toBe('keep the cards square')
+    expect(grid[0].description).toContain('user said: "keep the cards square"')
+  })
+
+  it('growing to ≥95% of content width emits the full-width relation', () => {
+    const blocks = planetsBlocks()
+    // Toolbar moves AND grows to full content width (content width = 1280 viewport).
+    blocks[1].rect = { x: 0, y: 700, width: 1230, height: 60 }
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    const move = dirs.find((d) => d.block.label === 'filters')!
+    expect(move.measured?.relations).toContain('now spans the full content width')
+  })
+
+  it('duplicates diff as add kind=duplicate, anchored at the original block', () => {
+    const blocks = planetsBlocks()
+    blocks.push({
+      ...captured('grid-copy', 800, 600, 128),
+      id: 'dup-1',
+      duplicateOf: 'grid',
+    })
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs).toHaveLength(1)
+    expect(dirs[0].op).toBe('add')
+    expect(dirs[0].added).toMatchObject({ kind: 'duplicate', position: 'after' })
+    expect(dirs[0].file).toBe('src/pages/PlanetsPage.vue')
+    expect(dirs[0].line).toBe(128) // the original grid's anchor
+    expect(dirs[0].description).toContain("a duplicate of the grid block's markup")
+  })
+
+  it('an added-then-deleted block never appears', () => {
+    const blocks = planetsBlocks()
+    blocks.push({
+      id: 'ph-dead', kind: 'placeholder', rect: { x: 0, y: 900, width: 100, height: 50 },
+      z: 5, createdAt: 2, label: 'gone', deleted: true,
+    })
+    expect(computeWireframeDirections(canvasWith(blocks))).toEqual([])
+  })
+
+  it('directions come back top-down by current position (badge order)', () => {
+    const blocks = planetsBlocks()
+    blocks[0].deleted = true                              // header (was y0)
+    blocks[2].rect = { ...blocks[2].rect, y: 90 }         // grid now y90
+    blocks[1].rect = { ...blocks[1].rect, y: 700 }        // filters now y700
+    const dirs = computeWireframeDirections(canvasWith(blocks))
+    expect(dirs.map((d) => d.block.label)).toEqual(['page-header', 'grid', 'filters'])
+  })
+})
+
+describe('directionAnchor', () => {
+  it('prefers the nearest surviving captured donor; position describes the neighbor side', () => {
+    const blocks = planetsBlocks()
+    const above = { id: 'x', kind: 'placeholder' as const, rect: { x: 0, y: 60, width: 200, height: 30 }, z: 5, createdAt: 2, label: 'x' }
+    // Sits between header (above) and filters (below) but touches filters.
+    const near = directionAnchor({ ...above, rect: { x: 0, y: 95, width: 200, height: 30 } }, blocks)
+    expect(near.neighbor?.id).toBe('filters')
+    expect(near.position).toBe('before') // neighbor is below the block
+  })
+
+  it('returns append with no donors (placeholder-only canvas)', () => {
+    const lone = { id: 'p', kind: 'placeholder' as const, rect: { x: 0, y: 0, width: 100, height: 50 }, z: 1, createdAt: 1, label: 'p' }
+    expect(directionAnchor(lone, [lone])).toEqual({ neighbor: null, position: 'append' })
+  })
+})
diff --git a/src/shell/utils/__tests__/wireframeSnap.test.ts b/src/shell/utils/__tests__/wireframeSnap.test.ts
new file mode 100644
index 0000000..f37354f
--- /dev/null
+++ b/src/shell/utils/__tests__/wireframeSnap.test.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+import { computeSnap } from '../wireframeSnap'
+
+describe('computeSnap', () => {
+  const neighbor = { x: 100, y: 200, width: 300, height: 100 } // edges x: 100/250/400, y: 200/250/300
+
+  it('snaps a near-aligned left edge onto the neighbor edge and reports the guide', () => {
+    const dragged = { x: 104, y: 500, width: 50, height: 50 }
+    const r = computeSnap(dragged, [neighbor])
+    expect(r.x).toBe(100)
+    expect(r.y).toBe(500) // y is far from every candidate — untouched
+    expect(r.guides).toEqual([{ axis: 'x', at: 100 }])
+  })
+
+  it('snaps centers to centers', () => {
+    // dragged center x = 252 → neighbor center 250 (delta -2)
+    const dragged = { x: 227, y: 196, width: 50, height: 50 }
+    const r = computeSnap(dragged, [neighbor])
+    expect(r.x).toBe(225) // center 250
+    expect(r.y).toBe(200) // top edge 196 → 200
+  })
+
+  it('snaps right edge to left edge (adjacent placement)', () => {
+    const dragged = { x: 45, y: 600, width: 50, height: 50 } // right = 95, near neighbor left 100
+    const r = computeSnap(dragged, [neighbor])
+    expect(r.x).toBe(50)
+    expect(r.guides).toContainEqual({ axis: 'x', at: 100 })
+  })
+
+  it('beyond the threshold nothing snaps', () => {
+    const dragged = { x: 110, y: 500, width: 50, height: 50 }
+    const r = computeSnap(dragged, [neighbor])
+    expect(r).toEqual({ x: 110, y: 500, guides: [] })
+  })
+
+  it('the smallest delta wins per axis across multiple neighbors', () => {
+    const a = { x: 100, y: 0, width: 4, height: 4 } // x-lines 100/102/104
+    const b = { x: 108, y: 0, width: 4, height: 4 } // x-lines 108/110/112
+    const dragged = { x: 105, y: 500, width: 50, height: 50 }
+    const r = computeSnap(dragged, [a, b])
+    expect(r.x).toBe(104) // |Δ|=1 to a's right edge beats |Δ|=3 to b's left
+  })
+
+  it('respects a custom threshold', () => {
+    const dragged = { x: 92, y: 500, width: 50, height: 50 }
+    expect(computeSnap(dragged, [neighbor], 6).x).toBe(92)
+    expect(computeSnap(dragged, [neighbor], 10).x).toBe(100)
+  })
+})
diff --git a/src/shell/utils/bindingShape.ts b/src/shell/utils/bindingShape.ts
new file mode 100644
index 0000000..7e8e8d9
--- /dev/null
+++ b/src/shell/utils/bindingShape.ts
@@ -0,0 +1,176 @@
+/**
+ * Pure logic behind DataBindingPicker.vue — kept out of the component so the
+ * shape-tree flattening, field candidates, and binding construction are
+ * unit-testable (no @vue/test-utils in this repo).
+ *
+ * Path grammar (matches the WireframeDataBinding contract):
+ *   object child `k` of `parent`  →  `parent.k` (or `k` at the root)
+ *   array nodes append `[]`       →  `planets[]`, `data.items[]`
+ */
+import type { DataShapeNode, ProjectDataEntry } from '../../schema'
+import { isWireframeDataBinding, type WireframeDataBinding } from '../../shared/wireframe-types'
+
+export interface ShapeRow {
+  /** Drill-down path for the binding (e.g. "planets[]", "data.user"). */
+  path: string
+  /** Display key for the row ("planets", "user", "(items)"). */
+  key: string
+  depth: number
+  node: DataShapeNode
+  /** Rows the user can pick as the binding path. */
+  selectable: boolean
+  /** Rows that have children to expand into. */
+  expandable: boolean
+}
+
+/**
+ * Flatten a shape tree into ordered rows for the picker. `expanded` holds the
+ * paths the user has opened; the root row is always present, collapsed
+ * children are skipped. Arrays expand into their ITEM shape (one synthetic
+ * row), objects into their keys.
+ */
+export function flattenShape(root: DataShapeNode, expanded: ReadonlySet<string>, rootKey = '(response)'): ShapeRow[] {
+  const rows: ShapeRow[] = []
+  walk(root, rootKey, '', 0)
+  return rows
+
+  function walk(node: DataShapeNode, key: string, parentPath: string, depth: number): void {
+    const path = pathFor(node, key, parentPath, depth)
+    rows.push({
+      path,
+      key,
+      depth,
+      node,
+      selectable: node.kind === 'object' || node.kind === 'array' || node.kind === 'ref',
+      expandable: (node.kind === 'object' && !!node.children && Object.keys(node.children).length > 0)
+        || (node.kind === 'array' && !!node.item),
+    })
+    if (!expanded.has(path)) return
+    if (node.kind === 'array' && node.item) {
+      // The item shape rides under the array's own path — selecting a leaf
+      // inside it reads naturally: planets[].name
+      if (node.item.kind === 'object' && node.item.children) {
+        for (const [k, child] of Object.entries(node.item.children)) walk(child, k, path, depth + 1)
+      } else {
+        walk(node.item, '(item)', path, depth + 1)
+      }
+      return
+    }
+    if (node.kind === 'object' && node.children) {
+      for (const [k, child] of Object.entries(node.children)) walk(child, k, path, depth + 1)
+    }
+  }
+
+  function pathFor(node: DataShapeNode, key: string, parentPath: string, depth: number): string {
+    if (depth === 0) return node.kind === 'array' ? '[]' : ''
+    const joined = parentPath ? `${parentPath}.${key}` : key
+    return node.kind === 'array' ? `${joined}[]` : joined
+  }
+}
+
+/**
+ * Leaf keys of the node the user drilled to — the multi-select source for
+ * `fields`. Arrays offer their item-object's keys; objects their own.
+ * Scalars/refs count as displayable leaves.
+ */
+export function fieldCandidates(node: DataShapeNode): string[] {
+  const obj = node.kind === 'array' ? node.item : node
+  if (!obj || obj.kind !== 'object' || !obj.children) return []
+  return Object.entries(obj.children)
+    .filter(([, child]) => child.kind === 'scalar' || child.kind === 'ref')
+    .map(([key]) => key)
+}
+
+function asScalar(v: unknown): string | number | boolean | undefined {
+  return (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') ? v : undefined
+}
+
+/**
+ * Up to `n` REAL example rows for the picked node, drawn from the API contract's
+ * `example`/`default` values (never synthesized). Used to preview bound props on
+ * the wireframe canvas. Precedence: an array example of objects (distinct rows)
+ * → a single object example → per-field examples on the item's children. Returns
+ * [] when the contract carries no examples (the caller falls back to `{field}`
+ * tokens). Only scalar field values are kept, so a row is a flat prop bag.
+ */
+export function sampleRows(node: DataShapeNode | null | undefined, fields: string[], n: number): Record<string, unknown>[] {
+  if (!node || n <= 0) return []
+  const item = node.kind === 'array' ? node.item : node
+  const keys = fields.length > 0 ? fields : fieldCandidates(node)
+  if (keys.length === 0) return []
+
+  const pick = (obj: unknown): Record<string, unknown> | null => {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return null
+    const row: Record<string, unknown> = {}
+    let any = false
+    for (const k of keys) {
+      const v = asScalar((obj as Record<string, unknown>)[k])
+      if (v !== undefined) { row[k] = v; any = true }
+    }
+    return any ? row : null
+  }
+
+  // 1) Array example of objects — the richest source (distinct rows).
+  const arrEx = node.kind === 'array' ? node.example : undefined
+  if (Array.isArray(arrEx)) {
+    const rows = arrEx.slice(0, n).map(pick).filter((r): r is Record<string, unknown> => !!r)
+    if (rows.length) return rows
+  }
+  // 2) A single object example (the item shape, or the node itself).
+  const objRow = pick(item?.example ?? (node.kind === 'object' ? node.example : undefined))
+  if (objRow) return [objRow]
+  // 3) Per-field examples on the item's children.
+  if (item?.kind === 'object' && item.children) {
+    const row: Record<string, unknown> = {}
+    let any = false
+    for (const k of keys) {
+      const v = asScalar(item.children[k]?.example)
+      if (v !== undefined) { row[k] = v; any = true }
+    }
+    if (any) return [row]
+  }
+  return []
+}
+
+/**
+ * Assemble a plain-JSON WireframeDataBinding from a catalog entry + the
+ * picker's selection. Validates before returning — an invalid binding here is
+ * a programmer error (the validator at the PUT boundary would reject the
+ * whole doc), so throw loudly instead of persisting garbage.
+ */
+export function buildBinding(
+  entry: Pick<ProjectDataEntry, 'kind' | 'name' | 'file' | 'endpoint'>,
+  sel: {
+    path?: string
+    fields?: string[]
+    shape_source: WireframeDataBinding['shape_source']
+    /** REAL contract example rows (api-schema tier) for the preview. */
+    sample?: Record<string, unknown>[]
+    /** Sketch instance count for a list binding. */
+    repeat?: number
+    /** prop→field map (usually set later in the popover, preserved here). */
+    propMap?: Record<string, string>
+  },
+): WireframeDataBinding {
+  const fields = (sel.fields ?? []).map(f => f.trim()).filter(Boolean)
+  const path = sel.path?.trim()
+  const binding: WireframeDataBinding = {
+    kind: entry.kind,
+    name: entry.name,
+    // The catalog has no module field — the defining file IS the import
+    // identity the agent re-grounds against.
+    ...(entry.file ? { module: entry.file } : {}),
+    ...(entry.endpoint ? { endpoint: entry.endpoint } : {}),
+    ...(path ? { path } : {}),
+    ...(fields.length > 0 ? { fields } : {}),
+    shape_source: sel.shape_source,
+    ...(sel.sample && sel.sample.length > 0 ? { sample: sel.sample } : {}),
+    ...(sel.repeat && sel.repeat > 1 ? { repeat: sel.repeat } : {}),
+    ...(sel.propMap && Object.keys(sel.propMap).length > 0 ? { propMap: sel.propMap } : {}),
+  }
+  const plain = JSON.parse(JSON.stringify(binding)) as WireframeDataBinding
+  if (!isWireframeDataBinding(plain)) {
+    throw new Error(`buildBinding produced an invalid WireframeDataBinding for "${entry.name}"`)
+  }
+  return plain
+}
diff --git a/src/shell/utils/propWidgets.ts b/src/shell/utils/propWidgets.ts
new file mode 100644
index 0000000..e7ca914
--- /dev/null
+++ b/src/shell/utils/propWidgets.ts
@@ -0,0 +1,50 @@
+/**
+ * Prop-widget inference for ComponentPreview's sample-prop editor — the
+ * type-string heuristics that turn scanned prop metadata into input widgets.
+ */
+
+export interface WidgetProp {
+  name: string
+  type: string | null
+  required?: boolean
+  default?: unknown
+  description?: string | null
+}
+
+export type PropWidgetKind = 'boolean' | 'number' | 'enum' | 'string' | 'json'
+
+/** Parse a single-line default-value expression (e.g. `'small'`, `true`, `42`)
+ *  into a real JS value. Falls back to the raw string if parsing fails. Keeps
+ *  initial values honest to the extracted type. */
+export function parseDefault(raw: unknown, type: string | null): unknown {
+  if (raw == null) return undefined
+  const s = String(raw).trim()
+  if (!s || s === 'undefined' || s === 'null') return undefined
+  if (s === 'true') return true
+  if (s === 'false') return false
+  if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s)
+  // Quoted string
+  const m = s.match(/^['"`](.*)['"`]$/)
+  if (m) return m[1]
+  // For enum types like 'a' | 'b', use the first
+  if (type && /'[^']+'/.test(type)) {
+    const first = type.match(/'([^']+)'/)
+    if (first) return first[1]
+  }
+  return s
+}
+
+export function inferWidget(p: WidgetProp): PropWidgetKind {
+  const t = (p.type || '').toLowerCase()
+  if (t === 'boolean' || t === 'bool') return 'boolean'
+  if (t === 'number' || t === 'int' || t === 'float') return 'number'
+  if (/^(['"][\w-]+['"]\s*\|\s*)+['"][\w-]+['"]\s*$/.test(p.type || '')) return 'enum'
+  if (t === 'string' || t.startsWith('string')) return 'string'
+  // Complex types (objects, arrays, functions) — give the user a JSON escape hatch
+  return 'json'
+}
+
+export function enumValues(p: WidgetProp): string[] {
+  if (!p.type) return []
+  return [...p.type.matchAll(/'([^']+)'/g)].map(m => m[1])
+}
diff --git a/src/shell/utils/toolSummary.ts b/src/shell/utils/toolSummary.ts
new file mode 100644
index 0000000..c227795
--- /dev/null
+++ b/src/shell/utils/toolSummary.ts
@@ -0,0 +1,126 @@
+/**
+ * Humanize agent tool calls + results for the Conversation work-stream.
+ *
+ * The agent CLIs (claude, codex, opencode) emit raw tool invocations as
+ * `{name, input}` blobs. The UI surfaces a one-line summary per call
+ * (`"Reading App.vue:42-89"`) and lets the user expand to see the raw JSON
+ * input + full output. These templates produce the one-line summary.
+ *
+ * Unknown tools fall back to `name(key=value, …)` — never throw, never
+ * lose information.
+ */
+
+/** Truncate a string with an ellipsis to keep one-liners scannable. */
+function trunc(s: string, max = 60): string {
+  const t = s.replace(/\s+/g, ' ').trim()
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t
+}
+
+/** Render `file_path[:offset-end]` shorthand from a Read-style tool input. */
+function pathWithRange(input: Record<string, unknown>): string {
+  const file = typeof input.file_path === 'string' ? input.file_path : ''
+  const off = typeof input.offset === 'number' ? input.offset : null
+  const lim = typeof input.limit === 'number' ? input.limit : null
+  if (off != null && lim != null) return `${file}:${off}-${off + lim - 1}`
+  if (off != null) return `${file}:${off}+`
+  return file
+}
+
+/**
+ * Build the one-line summary for a tool call. Hand-tuned templates cover
+ * the tools the claude/codex/opencode CLIs commonly run (Read/Write/Edit/
+ * Bash/Grep/Glob/WebFetch/WebSearch/Task). Everything else falls through to
+ * the generic `name(args)` rendering.
+ */
+export function summarizeToolCall(name: string, input: unknown): string {
+  const args = (input && typeof input === 'object' && !Array.isArray(input))
+    ? (input as Record<string, unknown>)
+    : {}
+
+  switch (name) {
+    case 'Read': {
+      const p = pathWithRange(args)
+      return p ? `Reading ${p}` : 'Reading file'
+    }
+    case 'Write': {
+      const p = typeof args.file_path === 'string' ? args.file_path : ''
+      return p ? `Writing ${p}` : 'Writing file'
+    }
+    case 'Edit': {
+      const p = typeof args.file_path === 'string' ? args.file_path : ''
+      return p ? `Editing ${p}` : 'Editing file'
+    }
+    case 'MultiEdit': {
+      const p = typeof args.file_path === 'string' ? args.file_path : ''
+      const n = Array.isArray(args.edits) ? args.edits.length : 0
+      return p ? `Editing ${p} (${n} edit${n === 1 ? '' : 's'})` : 'Editing file'
+    }
+    case 'NotebookEdit': {
+      const p = typeof args.notebook_path === 'string' ? args.notebook_path : ''
+      return p ? `Editing notebook ${p}` : 'Editing notebook'
+    }
+    case 'Bash': {
+      const cmd = typeof args.command === 'string' ? args.command : ''
+      return cmd ? `Running ${trunc(cmd, 80)}` : 'Running shell command'
+    }
+    case 'Grep': {
+      const pat = typeof args.pattern === 'string' ? args.pattern : ''
+      const path = typeof args.path === 'string' ? ` in ${args.path}` : ''
+      return pat ? `Searching for "${trunc(pat, 40)}"${path}` : 'Searching'
+    }
+    case 'Glob': {
+      const pat = typeof args.pattern === 'string' ? args.pattern : ''
+      return pat ? `Listing ${pat}` : 'Listing files'
+    }
+    case 'WebFetch': {
+      const url = typeof args.url === 'string' ? args.url : ''
+      return url ? `Fetching ${trunc(url, 80)}` : 'Fetching URL'
+    }
+    case 'WebSearch': {
+      const q = typeof args.query === 'string' ? args.query : ''
+      return q ? `Searching the web for "${trunc(q, 60)}"` : 'Searching the web'
+    }
+    case 'Task': {
+      const desc = typeof args.description === 'string' ? args.description : ''
+      const agent = typeof args.subagent_type === 'string' ? args.subagent_type : ''
+      if (desc && agent) return `Delegating to ${agent}: ${trunc(desc, 60)}`
+      if (desc) return `Delegating: ${trunc(desc, 60)}`
+      return 'Delegating sub-task'
+    }
+    case 'TodoWrite':
+      return 'Updating todo list'
+    case 'KillShell':
+      return 'Killing shell'
+    case 'BashOutput':
+      return 'Reading shell output'
+    default:
+      return `${name}(${formatGenericArgs(args)})`
+  }
+}
+
+/**
+ * Build a short preview for a tool result. The full content is rendered in
+ * the expandable details panel; this is what shows on the collapsed row.
+ */
+export function summarizeToolResult(content: string, isError?: boolean): string {
+  const trimmed = content.trim()
+  if (!trimmed) return isError ? 'Error' : 'OK'
+  if (isError) return `Error: ${trunc(trimmed.split('\n')[0], 80)}`
+  const lines = trimmed.split('\n').length
+  if (lines > 3) return `${lines} lines returned`
+  return trunc(trimmed.split('\n')[0], 80)
+}
+
+function formatGenericArgs(args: Record<string, unknown>): string {
+  const entries = Object.entries(args).slice(0, 3)
+  if (entries.length === 0) return ''
+  return entries.map(([k, v]) => `${k}=${formatValue(v)}`).join(', ')
+}
+
+function formatValue(v: unknown): string {
+  if (typeof v === 'string') return `"${trunc(v, 30)}"`
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v)
+  if (v == null) return String(v)
+  if (Array.isArray(v)) return `[${v.length}]`
+  return '{…}'
+}
diff --git a/src/shell/utils/wireframeComposite.ts b/src/shell/utils/wireframeComposite.ts
new file mode 100644
index 0000000..8809c47
--- /dev/null
+++ b/src/shell/utils/wireframeComposite.ts
@@ -0,0 +1,203 @@
+import type { WireframeDirectionChange } from '../../schema'
+import type { WireframeBlock, WireframeCanvasState } from '../../shared/wireframe-types'
+
+/**
+ * Compose the labeled before/after PNG for a wireframe apply: left pane is
+ * the full-page capture (the rendered truth), right pane re-draws the sketch
+ * — block images at their current rects, placeholders as dashed boxes —
+ * with numbered badges matching the direction list 1:1. Honesty labels are
+ * burned into the pixels so the image can't outrun its caveats.
+ *
+ * Plain offscreen 2D canvas, not html2canvas: deterministic, no vendor load
+ * in the shell, no transform-capture quirks.
+ */
+
+const PANE_MAX_W = 1200
+const HEADER_H = 26
+const GUTTER = 16
+const MAX_BYTES = 3_500_000
+
+function loadImage(src: string): Promise<HTMLImageElement | null> {
+  return new Promise((resolve) => {
+    const img = new Image()
+    img.onload = () => resolve(img)
+    img.onerror = () => resolve(null)
+    img.src = src
+  })
+}
+
+function dataUrlBytes(dataUrl: string): number {
+  const i = dataUrl.indexOf(',')
+  return Math.floor((dataUrl.length - i - 1) * 3 / 4)
+}
+
+/** The block a direction talks about — direction ids are `wd-<blockId>-<op>`. */
+function blockIdOf(direction: WireframeDirectionChange): string {
+  return direction.id.replace(/^wd-/, '').replace(/-(move|resize|delete|add|note)$/, '')
+}
+
+export interface ComposeWireframeDiffOptions {
+  canvas: WireframeCanvasState
+  directions: WireframeDirectionChange[]
+  /** Resolves a block's image source (session dataUrl → sidecar URL → null). */
+  imageSrc: (block: WireframeBlock) => string | null
+  /** Full-page capture URL — the honest left pane. Null = stitch blocks. */
+  beforeSrc: string | null
+}
+
+export async function composeWireframeDiff(opts: ComposeWireframeDiffOptions): Promise<string | null> {
+  for (let scaleDown = 1; scaleDown >= 0.5; scaleDown *= 0.8) {
+    const dataUrl = await composeAt(opts, scaleDown)
+    if (!dataUrl) return null
+    if (dataUrlBytes(dataUrl) <= MAX_BYTES) return dataUrl
+  }
+  return null
+}
+
+async function composeAt(opts: ComposeWireframeDiffOptions, scaleDown: number): Promise<string | null> {
+  const { canvas: state, directions, imageSrc, beforeSrc } = opts
+  const docW = Math.max(state.viewport.docWidth, 1)
+  const docH = Math.max(state.viewport.docHeight, 1)
+  const scale = Math.min(PANE_MAX_W / docW, 1) * scaleDown
+  const paneW = Math.round(docW * scale)
+  const paneH = Math.round(docH * scale)
+  const totalW = paneW * 2 + GUTTER
+  const totalH = paneH + HEADER_H
+
+  const el = document.createElement('canvas')
+  el.width = totalW
+  el.height = totalH
+  const ctx = el.getContext('2d')
+  if (!ctx) return null
+
+  ctx.fillStyle = '#1c1c1f'
+  ctx.fillRect(0, 0, totalW, totalH)
+
+  // Header labels — burned in, not metadata.
+  ctx.fillStyle = '#e8e8ea'
+  ctx.font = `600 ${Math.max(11, Math.round(13 * scaleDown))}px system-ui, sans-serif`
+  ctx.textBaseline = 'middle'
+  ctx.fillText('BEFORE — captured render', 8, HEADER_H / 2)
+  ctx.fillText('AFTER — wireframe sketch (rearranged images, not real UI)', paneW + GUTTER + 8, HEADER_H / 2)
+
+  // ── BEFORE pane ──
+  const beforeX = 0
+  const paneY = HEADER_H
+  ctx.fillStyle = '#ffffff'
+  ctx.fillRect(beforeX, paneY, paneW, paneH)
+  const beforeImg = beforeSrc ? await loadImage(beforeSrc) : null
+  if (beforeImg) {
+    ctx.drawImage(beforeImg, beforeX, paneY, paneW, paneH)
+  } else {
+    // Fallback: stitch per-block images at their ORIGINAL rects.
+    for (const b of state.blocks) {
+      if (b.kind !== 'captured' || b.duplicateOf || !b.originalRect) continue
+      const src = imageSrc(b)
+      const r = b.originalRect
+      if (!src) continue
+      const img = await loadImage(src)
+      if (img) ctx.drawImage(img, beforeX + r.x * scale, paneY + r.y * scale, r.width * scale, r.height * scale)
+    }
+  }
+
+  // ── AFTER pane ──
+  const afterX = paneW + GUTTER
+  ctx.fillStyle = '#ffffff'
+  ctx.fillRect(afterX, paneY, paneW, paneH)
+  const survivors = state.blocks.filter((b) => !b.deleted).slice().sort((a, b) => a.z - b.z)
+  for (const b of survivors) {
+    const r = b.rect
+    const x = afterX + r.x * scale
+    const y = paneY + r.y * scale
+    const w = r.width * scale
+    const h = r.height * scale
+    const src = imageSrc(b)
+    const img = src ? await loadImage(src) : null
+    if (img) {
+      ctx.drawImage(img, x, y, w, h)
+    } else {
+      // Placeholder / failed capture: dashed labeled box — never fake pixels.
+      const isSection = b.kind === 'placeholder' && (!!b.md || !!b.data)
+      ctx.save()
+      ctx.strokeStyle = b.kind === 'placeholder' ? '#7c6ff0' : '#9a9aa2'
+      ctx.setLineDash([6, 4])
+      ctx.lineWidth = 2
+      ctx.strokeRect(x + 1, y + 1, Math.max(w - 2, 2), Math.max(h - 2, 2))
+      ctx.fillStyle = '#55555c'
+      ctx.font = `500 ${Math.max(10, Math.round(12 * scaleDown))}px system-ui, sans-serif`
+      ctx.textBaseline = 'middle'
+      ctx.textAlign = 'center'
+      const tag = b.kind !== 'placeholder' ? '' : isSection ? ' (section — user spec attached)' : ' (placeholder)'
+      const text = b.kind === 'placeholder' ? `${b.label ?? 'placeholder'}${tag}` : 'capture failed'
+      const lineH = Math.max(12, Math.round(14 * scaleDown))
+      const extraLines = (isSection ? 1 : 0) + (b.data ? 1 : 0)
+      const baseY = y + h / 2 - (extraLines * lineH) / 2
+      ctx.fillText(text, x + w / 2, baseY, Math.max(w - 8, 8))
+      // Honest summaries beneath the label — first md line + binding identity.
+      // The FULL spec rides the direction payload; pixels never fabricate UI.
+      ctx.font = `400 ${Math.max(9, Math.round(10 * scaleDown))}px system-ui, sans-serif`
+      ctx.fillStyle = '#7a7a82'
+      let lineY = baseY + lineH
+      if (b.md) {
+        const firstLine = b.md.split('\n')[0].replace(/^#+\s*/, '').slice(0, 120)
+        ctx.fillText(firstLine, x + w / 2, lineY, Math.max(w - 8, 8))
+        lineY += lineH
+      }
+      if (b.data) {
+        ctx.fillText(`data: ${b.data.name}${b.data.path ? ` → ${b.data.path}` : ''}`, x + w / 2, lineY, Math.max(w - 8, 8))
+      }
+      ctx.restore()
+    }
+  }
+  // Deleted blocks: a crossed dashed outline at the old spot — the sketch
+  // says "this is gone", the pane shows where it was.
+  for (const b of state.blocks) {
+    if (!b.deleted) continue
+    const r = b.originalRect ?? b.rect
+    const x = afterX + r.x * scale
+    const y = paneY + r.y * scale
+    const w = r.width * scale
+    const h = r.height * scale
+    ctx.save()
+    ctx.strokeStyle = '#d24545'
+    ctx.setLineDash([5, 4])
+    ctx.lineWidth = 1.5
+    ctx.strokeRect(x, y, w, h)
+    ctx.beginPath()
+    ctx.moveTo(x, y); ctx.lineTo(x + w, y + h)
+    ctx.moveTo(x + w, y); ctx.lineTo(x, y + h)
+    ctx.stroke()
+    ctx.restore()
+  }
+
+  // ── Numbered badges, 1:1 with the direction list ──
+  const byId = new Map(state.blocks.map((b) => [b.id, b]))
+  directions.forEach((d, i) => {
+    const block = byId.get(blockIdOf(d))
+    const r = block?.deleted ? (block.originalRect ?? block.rect) : (block?.rect ?? d.measured?.after ?? d.measured?.before)
+    if (!r) return
+    const bx = afterX + r.x * scale + 4
+    const by = paneY + r.y * scale + 4
+    const radius = 11
+    ctx.save()
+    ctx.beginPath()
+    ctx.arc(bx + radius, by + radius, radius, 0, Math.PI * 2)
+    ctx.fillStyle = '#4f46e5'
+    ctx.fill()
+    ctx.strokeStyle = '#ffffff'
+    ctx.lineWidth = 1.5
+    ctx.stroke()
+    ctx.fillStyle = '#ffffff'
+    ctx.font = '700 12px system-ui, sans-serif'
+    ctx.textAlign = 'center'
+    ctx.textBaseline = 'middle'
+    ctx.fillText(String(i + 1), bx + radius, by + radius + 0.5)
+    ctx.restore()
+  })
+
+  try {
+    return el.toDataURL('image/png')
+  } catch {
+    return null
+  }
+}
diff --git a/src/shell/utils/wireframeDirections.ts b/src/shell/utils/wireframeDirections.ts
new file mode 100644
index 0000000..dde4233
--- /dev/null
+++ b/src/shell/utils/wireframeDirections.ts
@@ -0,0 +1,330 @@
+import type { WireframeDirectionChange, WireframeRect } from '../../schema'
+import type { WireframeBlock, WireframeCanvasState } from '../../shared/wireframe-types'
+
+/**
+ * Diff the original capture against the current canvas into anchored,
+ * structured directions — ONE direction per changed block. Pixel geometry is
+ * a hint; the relational facts computed here are the contract the agent
+ * implements ("now above the filters toolbar"), so they must be derivable
+ * from box geometry alone — never invented, never blended with user notes.
+ */
+
+/** Canvas jitter below these thresholds is not a direction. */
+const MOVE_THRESHOLD_PX = 8
+const RESIZE_THRESHOLD_PX = 4
+const RESIZE_THRESHOLD_PCT = 2
+
+function label(b: WireframeBlock): string {
+  if (b.kind === 'placeholder') return b.label ?? 'placeholder'
+  if (b.kind === 'palette') return b.component?.componentName ?? b.component?.tag ?? 'component'
+  // cssClass first: a page's blocks all share the owning component name, and
+  // 'div' says nothing — '.toolbar'/'.layout' is the human-distinct identity.
+  return b.anchor?.cssClass || b.anchor?.sourceTag || b.anchor?.tag || b.anchor?.component || 'block'
+}
+
+function overlap1D(a0: number, a1: number, b0: number, b1: number): number {
+  return Math.max(0, Math.min(a1, b1) - Math.max(a0, b0))
+}
+
+function centerY(r: WireframeRect): number { return r.y + r.height / 2 }
+function centerX(r: WireframeRect): number { return r.x + r.width / 2 }
+
+/** Edge distance between two rects (0 when they touch/overlap). */
+function edgeDistance(a: WireframeRect, b: WireframeRect): number {
+  const dx = Math.max(0, Math.max(b.x - (a.x + a.width), a.x - (b.x + b.width)))
+  const dy = Math.max(0, Math.max(b.y - (a.y + a.height), a.y - (b.y + b.height)))
+  return Math.hypot(dx, dy)
+}
+
+/** Surviving captured blocks with a real source anchor — the only honest
+ *  anchor donors for added material. */
+function anchorDonors(blocks: WireframeBlock[]): WireframeBlock[] {
+  return blocks.filter((b) => b.kind === 'captured' && !b.deleted && !b.duplicateOf && !!b.anchor?.file)
+}
+
+/**
+ * Anchor an added block at its nearest anchored neighbor. Position describes
+ * where the new markup goes relative to the NEIGHBOR in source order:
+ * neighbor visually above → insert 'after' it; below → 'before' it;
+ * containing → 'append' into it.
+ */
+export function directionAnchor(
+  block: WireframeBlock,
+  blocks: WireframeBlock[],
+): { neighbor: WireframeBlock | null; position: 'before' | 'after' | 'append' | 'prepend' } {
+  const donors = anchorDonors(blocks).filter((d) => d.id !== block.id)
+  if (donors.length === 0) return { neighbor: null, position: 'append' }
+  let best = donors[0]
+  let bestDist = Infinity
+  for (const d of donors) {
+    const dist = edgeDistance(block.rect, d.rect)
+    if (dist < bestDist) { best = d; bestDist = dist }
+  }
+  const r = best.rect
+  const contains = block.rect.x >= r.x && block.rect.y >= r.y
+    && block.rect.x + block.rect.width <= r.x + r.width
+    && block.rect.y + block.rect.height <= r.y + r.height
+  if (contains) return { neighbor: best, position: 'append' }
+  return { neighbor: best, position: centerY(block.rect) >= centerY(r) ? 'after' : 'before' }
+}
+
+/** Relational facts for a moved block vs every other surviving block.
+ *  Priority: order flips → full content width → fresh alignment. Max 3. */
+function computeRelations(
+  moved: WireframeBlock,
+  others: WireframeBlock[],
+  contentWidth: number,
+): string[] {
+  const relations: string[] = []
+  const before = moved.originalRect!
+  const after = moved.rect
+
+  for (const o of others) {
+    if (relations.length >= 3) break
+    const oBefore = o.originalRect ?? o.rect
+    const oAfter = o.rect
+    const oLabel = label(o)
+    // Vertical order flip — only meaningful when the pair shares a column
+    // (≥30% horizontal overlap).
+    const hOverlap = overlap1D(after.x, after.x + after.width, oAfter.x, oAfter.x + oAfter.width)
+    if (hOverlap >= 0.3 * Math.min(after.width, oAfter.width)) {
+      const wasBelow = centerY(before) > centerY(oBefore)
+      const isAbove = centerY(after) < centerY(oAfter)
+      if (wasBelow && isAbove) { relations.push(`now above the ${oLabel} (was below)`); continue }
+      const wasAbove = centerY(before) < centerY(oBefore)
+      const isBelow = centerY(after) > centerY(oAfter)
+      if (wasAbove && isBelow) { relations.push(`now below the ${oLabel} (was above)`); continue }
+    }
+    // Horizontal order flip — only when the pair shares a row (≥50% vertical
+    // overlap).
+    const vOverlap = overlap1D(after.y, after.y + after.height, oAfter.y, oAfter.y + oAfter.height)
+    if (vOverlap >= 0.5 * Math.min(after.height, oAfter.height)) {
+      const wasRight = centerX(before) > centerX(oBefore)
+      const isLeft = centerX(after) < centerX(oAfter)
+      if (wasRight && isLeft) { relations.push(`now left of the ${oLabel} (was right)`); continue }
+      const wasLeft = centerX(before) < centerX(oBefore)
+      const isRight = centerX(after) > centerX(oAfter)
+      if (wasLeft && isRight) { relations.push(`now right of the ${oLabel} (was left)`); continue }
+    }
+  }
+
+  if (relations.length < 3
+    && after.width >= 0.95 * contentWidth && before.width < 0.9 * contentWidth) {
+    relations.push('now spans the full content width')
+  }
+
+  if (relations.length < 3) {
+    for (const o of others) {
+      if (relations.length >= 3) break
+      const oBefore = o.originalRect ?? o.rect
+      if (Math.abs(after.x - o.rect.x) <= 4 && Math.abs(before.x - oBefore.x) > 4) {
+        relations.push(`left-aligned with the ${label(o)}`)
+        break
+      }
+    }
+  }
+
+  return relations
+}
+
+function fileLine(b: WireframeBlock): string {
+  return b.anchor?.file ? ` (${b.anchor.file}:${b.anchor.line})` : ''
+}
+
+function rectStr(r: WireframeRect): string {
+  return `${Math.round(r.width)}x${Math.round(r.height)}`
+}
+
+export function computeWireframeDirections(canvas: WireframeCanvasState): WireframeDirectionChange[] {
+  const blocks = canvas.blocks
+  const survivors = blocks.filter((b) => !b.deleted)
+  const capturedOriginals = blocks.filter((b) => b.kind === 'captured' && !b.duplicateOf && b.originalRect)
+  const unionWidth = capturedOriginals.length
+    ? Math.max(...capturedOriginals.map((b) => b.originalRect!.x + b.originalRect!.width))
+      - Math.min(...capturedOriginals.map((b) => b.originalRect!.x))
+    : canvas.viewport.width
+  const contentWidth = Math.max(canvas.viewport.width, unionWidth)
+
+  const directions: WireframeDirectionChange[] = []
+
+  for (const b of blocks) {
+    const isAddition = b.kind !== 'captured' || !!b.duplicateOf
+
+    // Added sketch material (palette drops, placeholders, duplicates).
+    if (isAddition) {
+      if (b.deleted) continue // added then deleted — never existed
+      const ownLabel = label(b)
+      const original = b.duplicateOf ? blocks.find((x) => x.id === b.duplicateOf) : undefined
+      const isCapturedDup = !!original && original.kind === 'captured'
+      const kind: 'component' | 'placeholder' | 'duplicate' =
+        b.kind === 'palette' ? 'component' : isCapturedDup ? 'duplicate' : 'placeholder'
+
+      // A duplicate of a captured block anchors AT its original — the agent
+      // duplicates that exact markup. Everything else anchors at the nearest
+      // surviving captured neighbor.
+      let neighbor: WireframeBlock | null
+      let position: 'before' | 'after' | 'append' | 'prepend'
+      if (isCapturedDup && !original.deleted && original.anchor?.file) {
+        neighbor = original
+        position = centerY(b.rect) >= centerY(original.rect) ? 'after' : 'before'
+      } else {
+        ({ neighbor, position } = directionAnchor(b, blocks))
+      }
+
+      const componentName = b.component?.componentName
+      const where = neighbor
+        ? `${position === 'append' ? 'inside' : position} the ${label(neighbor)}${fileLine(neighbor)}`
+        : 'on the page'
+      // A duplicate whose original LEFT the sketch (deleted/exploded) has no
+      // anchor to copy from — say so honestly instead of claiming the user
+      // sketched a box. A placeholder WITH md is a drawn section: the spec in
+      // added.md is the contract, not "keep it visibly a placeholder".
+      const danglingDup = b.kind === 'captured' && !!b.duplicateOf && !original
+      const what = kind === 'component'
+        ? `component <${componentName ?? ownLabel}>`
+        : kind === 'duplicate'
+          ? `a duplicate of the ${label(original!)} block's markup`
+          : danglingDup
+            ? `a copy of the removed "${ownLabel}" block (its original left the sketch — the AFTER pane shows its content; re-anchor from the screenshot, never invent)`
+            : b.md
+              ? `drawn section "${ownLabel}" (user-sketched box ${rectStr(b.rect)})`
+              : `placeholder "${ownLabel}" (user-sketched box ${rectStr(b.rect)}; keep it visibly a placeholder)`
+      // Honest summaries only: the FULL md body rides added.md verbatim (the
+      // description quotes its first line); the binding summary names the
+      // real source + the shape_source honesty tag.
+      const mdFirstLine = b.md ? b.md.split('\n')[0].replace(/^#+\s*/, '').slice(0, 120) : ''
+      const mdNote = b.md ? `; user wrote a markdown spec (rides added.md verbatim) — first line: "${mdFirstLine}"` : ''
+      const mapNote = b.data?.propMap && Object.keys(b.data.propMap).length
+        ? `; map ${Object.entries(b.data.propMap).map(([prop, field]) => `${field}→${prop}`).join(', ')}`
+        : ''
+      const loopNote = b.data?.path && b.data.path.includes('[]')
+        ? `; render a v-for over ${b.data.path} — render ALL items (the ×${b.data.repeat ?? 'N'} on the canvas is a sketch hint)`
+        : ''
+      const dataNote = b.data
+        ? `; bind to the ${b.data.kind} ${b.data.name}${b.data.path ? ` → ${b.data.path}` : ''}${b.data.fields?.length ? ` (show ${b.data.fields.join(', ')})` : ''}${mapNote}${loopNote} [shape: ${b.data.shape_source}]`
+        : ''
+      // Multi-MFE: name the owning package so the agent imports from it and
+      // scopes example search there (see WIREFRAME_APPLY.md).
+      const mfeNote = b.component?.mfe ? `; import from MFE "${b.component.mfe}"` : ''
+      directions.push({
+        id: `wd-${b.id}-add`,
+        type: 'wireframe_direction',
+        op: 'add',
+        description: `ADD ${what} ${where}${mdNote}${dataNote}${mfeNote}${b.note ? ` — user said: "${b.note}"` : ''}`,
+        file: neighbor?.anchor?.file ?? '',
+        section: 'template',
+        line: neighbor?.anchor?.line ?? 0,
+        ...(neighbor?.anchor?.component ? { component: neighbor.anchor.component } : {}),
+        block: { label: ownLabel, ...(componentName ? { component: componentName } : {}), ...(b.component?.tag || b.anchor?.tag ? { tag: b.component?.tag ?? b.anchor?.tag } : {}) },
+        measured: { after: { ...b.rect } },
+        added: {
+          kind,
+          ...(componentName ? { componentName } : {}),
+          ...(b.component?.library ? { library: b.component.library } : {}),
+          ...(b.component?.module ? { module: b.component.module } : {}),
+          ...(b.component?.mfe ? { mfe: b.component.mfe } : {}),
+          ...(b.component?.props ? { props: b.component.props } : {}),
+          ...(b.component?.previewProps ? { previewProps: b.component.previewProps } : {}),
+          ...(kind === 'placeholder' ? { label: ownLabel } : {}),
+          ...(b.md ? { md: b.md } : {}),
+          ...(b.data ? { data: JSON.parse(JSON.stringify(b.data)) as typeof b.data } : {}),
+          position,
+        },
+        ...(b.note ? { note: b.note } : {}),
+      })
+      continue
+    }
+
+    // Captured blocks: delete / move / resize / note against the original.
+    const ownLabel = label(b)
+    const base = {
+      type: 'wireframe_direction' as const,
+      file: b.anchor?.file ?? '',
+      section: 'template' as const,
+      line: b.anchor?.line ?? 0,
+      ...(b.anchor?.component ? { component: b.anchor.component } : {}),
+      block: { label: ownLabel, ...(b.anchor?.component ? { component: b.anchor.component } : {}), ...(b.anchor?.tag ? { tag: b.anchor.tag } : {}) },
+    }
+
+    if (b.deleted) {
+      directions.push({
+        ...base,
+        id: `wd-${b.id}-delete`,
+        op: 'delete',
+        description: `DELETE the ${ownLabel}${fileLine(b)}${b.note ? ` — user said: "${b.note}"` : ''}`,
+        measured: { before: { ...(b.originalRect ?? b.rect) } },
+        ...(b.note ? { note: b.note } : {}),
+      })
+      continue
+    }
+
+    const before = b.originalRect ?? b.rect
+    const after = b.rect
+    const dx = after.x - before.x
+    const dy = after.y - before.y
+    const dw = after.width - before.width
+    const dh = after.height - before.height
+    const movedFar = Math.abs(dx) + Math.abs(dy) > MOVE_THRESHOLD_PX
+    const resized = (Math.abs(dw) > RESIZE_THRESHOLD_PX && Math.abs(dw) / Math.max(before.width, 1) * 100 > RESIZE_THRESHOLD_PCT)
+      || (Math.abs(dh) > RESIZE_THRESHOLD_PX && Math.abs(dh) / Math.max(before.height, 1) * 100 > RESIZE_THRESHOLD_PCT)
+    const wPct = Math.round((after.width / Math.max(before.width, 1)) * 100)
+    const hPct = Math.round((after.height / Math.max(before.height, 1)) * 100)
+
+    if (movedFar) {
+      // Moved (and possibly resized) — ONE direction so the agent never
+      // double-applies; resize facts ride the move.
+      const others = survivors.filter((o) => o.id !== b.id)
+      const relations = computeRelations(b, others, contentWidth)
+      const parts = [
+        ...(relations.length ? [relations.join('; ')] : []),
+        `position ${Math.round(before.x)},${Math.round(before.y)} → ${Math.round(after.x)},${Math.round(after.y)} (measured)`,
+        ...(resized ? [`size ${rectStr(before)} → ${rectStr(after)} (${wPct - 100 >= 0 ? '+' : ''}${wPct - 100}% w, ${hPct - 100 >= 0 ? '+' : ''}${hPct - 100}% h)`] : []),
+      ]
+      directions.push({
+        ...base,
+        id: `wd-${b.id}-move`,
+        op: 'move',
+        description: `MOVE the ${ownLabel}${fileLine(b)}: ${parts.join('; ')}${b.note ? ` — user said: "${b.note}"` : ''}`,
+        measured: {
+          before: { ...before }, after: { ...after },
+          dx: Math.round(dx), dy: Math.round(dy),
+          ...(resized ? { wPct, hPct } : {}),
+          ...(relations.length ? { relations } : {}),
+        },
+        ...(b.note ? { note: b.note } : {}),
+      })
+      continue
+    }
+
+    if (resized) {
+      directions.push({
+        ...base,
+        id: `wd-${b.id}-resize`,
+        op: 'resize',
+        description: `RESIZE the ${ownLabel}${fileLine(b)}: ${rectStr(before)} → ${rectStr(after)} (${wPct - 100 >= 0 ? '+' : ''}${wPct - 100}% w, ${hPct - 100 >= 0 ? '+' : ''}${hPct - 100}% h) (measured)${b.note ? ` — user said: "${b.note}"` : ''}`,
+        measured: { before: { ...before }, after: { ...after }, wPct, hPct },
+        ...(b.note ? { note: b.note } : {}),
+      })
+      continue
+    }
+
+    if (b.note) {
+      directions.push({
+        ...base,
+        id: `wd-${b.id}-note`,
+        op: 'note',
+        description: `NOTE on the ${ownLabel}${fileLine(b)}: user said: "${b.note}"`,
+        note: b.note,
+      })
+    }
+  }
+
+  // Stable, badge-friendly order: top-down by where the block sits now
+  // (deleted blocks by where they were).
+  directions.sort((a, c) => {
+    const ay = a.measured?.after?.y ?? a.measured?.before?.y ?? 0
+    const cy = c.measured?.after?.y ?? c.measured?.before?.y ?? 0
+    return ay - cy
+  })
+  return directions
+}
diff --git a/src/shell/utils/wireframeSnap.ts b/src/shell/utils/wireframeSnap.ts
new file mode 100644
index 0000000..26a144e
--- /dev/null
+++ b/src/shell/utils/wireframeSnap.ts
@@ -0,0 +1,72 @@
+/**
+ * Snap/align math for the wireframe canvas — pure so the thresholds and
+ * tie-breaking are testable without pointer choreography. Snapping adjusts
+ * the dragged rect's origin so one of its edges/centers lands exactly on a
+ * neighbor's edge/center; the returned guides are the lines the canvas draws
+ * while the snap is active.
+ */
+
+export interface SnapRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface SnapGuide {
+  axis: 'x' | 'y'
+  /** Document-coordinate position of the alignment line. */
+  at: number
+}
+
+export interface SnapResult {
+  x: number
+  y: number
+  guides: SnapGuide[]
+}
+
+const DEFAULT_THRESHOLD = 6
+
+function lines(rect: SnapRect, axis: 'x' | 'y'): number[] {
+  return axis === 'x'
+    ? [rect.x, rect.x + rect.width / 2, rect.x + rect.width]
+    : [rect.y, rect.y + rect.height / 2, rect.y + rect.height]
+}
+
+/**
+ * Snap `rect` against `others` (the rects it could align with). Per axis the
+ * smallest in-threshold delta wins; ties keep the first candidate in `others`
+ * order, which is z-stable. Returns the adjusted origin plus the guide lines.
+ */
+export function computeSnap(rect: SnapRect, others: SnapRect[], threshold = DEFAULT_THRESHOLD): SnapResult {
+  let bestX: { delta: number; at: number } | null = null
+  let bestY: { delta: number; at: number } | null = null
+
+  for (const other of others) {
+    for (const target of lines(other, 'x')) {
+      for (const own of lines(rect, 'x')) {
+        const delta = target - own
+        if (Math.abs(delta) <= threshold && (!bestX || Math.abs(delta) < Math.abs(bestX.delta))) {
+          bestX = { delta, at: target }
+        }
+      }
+    }
+    for (const target of lines(other, 'y')) {
+      for (const own of lines(rect, 'y')) {
+        const delta = target - own
+        if (Math.abs(delta) <= threshold && (!bestY || Math.abs(delta) < Math.abs(bestY.delta))) {
+          bestY = { delta, at: target }
+        }
+      }
+    }
+  }
+
+  const guides: SnapGuide[] = []
+  if (bestX) guides.push({ axis: 'x', at: bestX.at })
+  if (bestY) guides.push({ axis: 'y', at: bestY.at })
+  return {
+    x: rect.x + (bestX?.delta ?? 0),
+    y: rect.y + (bestY?.delta ?? 0),
+    guides,
+  }
+}
diff --git a/src/shell/wireframeFeatures.ts b/src/shell/wireframeFeatures.ts
new file mode 100644
index 0000000..cb7e22c
--- /dev/null
+++ b/src/shell/wireframeFeatures.ts
@@ -0,0 +1,19 @@
+/**
+ * Release-scope flags for the wireframe surface.
+ *
+ * This release ships the REDUCED wireframe surface — capture + sketch + the
+ * "implement this wireframe" directions loop — and DEFERS two areas that are
+ * built but not yet release-ready:
+ *
+ *   - Data binding: binding a palette component or drawn section to a real
+ *     catalog data source (the picker, shape drill-down, prop→field map, loop
+ *     repeat). Deferred while the shape-confidence honesty ladder is reworked.
+ *   - Explode-to-children: re-capturing one block a level deeper.
+ *
+ * The code paths stay in the tree (and existing persisted bindings still render
+ * read-only) — only the UI entry points are gated. Flip a flag to `true` to
+ * re-enable when the feature is ready for the next release.
+ */
+
+export const WIREFRAME_DATA_BINDING_ENABLED = false
+export const WIREFRAME_EXPLODE_ENABLED = false
diff --git a/src/skills/__tests__/loader.test.ts b/src/skills/__tests__/loader.test.ts
index 83dc08f..a4e1bb1 100644
--- a/src/skills/__tests__/loader.test.ts
+++ b/src/skills/__tests__/loader.test.ts
@@ -16,6 +16,7 @@ function mkTmpSkills(): string {
   fs.writeFileSync(path.join(root, 'annotask-apply', 'SKILL.md'), '# annotask-apply\n\nBody.\n')
   fs.writeFileSync(path.join(root, 'annotask-apply', 'A11Y_RULES.md'), '# A11Y\n\nRules.\n')
   fs.writeFileSync(path.join(root, 'annotask-apply', 'THEME_UPDATE.md'), '# Theme\n\nUpdate.\n')
+  fs.writeFileSync(path.join(root, 'annotask-apply', 'WIREFRAME_APPLY.md'), '# Wireframe Apply\n\nPlace.\n')
   fs.writeFileSync(path.join(root, 'annotask-apply', 'notes.txt'), 'ignored')
   fs.mkdirSync(path.join(root, 'annotask-init'), { recursive: true })
   fs.writeFileSync(path.join(root, 'annotask-init', 'SKILL.md'), '# annotask-init\n')
@@ -81,6 +82,11 @@ describe('skills/loader', () => {
     expect(prompt).toContain('# Theme')
   })
 
+  it('getSystemPrompt appends WIREFRAME_APPLY for wireframe_apply', () => {
+    const prompt = getSystemPrompt({ root, taskType: 'wireframe_apply' })
+    expect(prompt).toContain('# Wireframe Apply')
+  })
+
   it('getSystemPrompt ignores unknown task types', () => {
     const prompt = getSystemPrompt({ root, taskType: 'something_else' })
     expect(prompt).not.toContain('# A11Y')
@@ -110,4 +116,12 @@ describe('skills/loader', () => {
     expect(prompt.length).toBeGreaterThan(0)
     expect(prompt).toMatch(/annotask-apply/i)
   })
+
+  it('ships the real WIREFRAME_APPLY playbook for wireframe_apply (no override)', () => {
+    // Proves the TASK_TYPE_COMPANIONS registration + the bundled file ship
+    // together end-to-end via the same path the embedded runner uses.
+    const prompt = getSystemPrompt({ taskType: 'wireframe_apply' })
+    expect(prompt).toContain('# Wireframe Apply')
+    expect(prompt).toContain('annotask_get_component_examples')
+  })
 })
diff --git a/src/skills/loader.ts b/src/skills/loader.ts
index f3117d9..1378c80 100644
--- a/src/skills/loader.ts
+++ b/src/skills/loader.ts
@@ -99,9 +99,16 @@ export interface SystemPromptOptions extends LoaderOptions {
   taskType?: string
 }
 
-const TASK_TYPE_COMPANIONS: Record<string, string> = {
+/** Task type → companion playbook basename inside the `annotask-apply` skill
+ *  directory. Exported so the MCP `annotask_get_playbook` tool and the CLI
+ *  `playbook` command can serve the same files to pure-MCP clients that never
+ *  see the installed skill directory. */
+export const TASK_TYPE_COMPANIONS: Record<string, string> = {
   a11y_fix: 'A11Y_RULES.md',
   theme_update: 'THEME_UPDATE.md',
+  error_fix: 'ERROR_FIX.md',
+  perf_fix: 'PERF_FIX.md',
+  wireframe_apply: 'WIREFRAME_APPLY.md',
 }
 
 /** Assemble the agent-facing system prompt: `annotask-apply` SKILL.md, plus
diff --git a/src/webpack/__tests__/plugin-proxy.test.ts b/src/webpack/__tests__/plugin-proxy.test.ts
new file mode 100644
index 0000000..02b8207
--- /dev/null
+++ b/src/webpack/__tests__/plugin-proxy.test.ts
@@ -0,0 +1,152 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { AnnotaskWebpackPlugin } from '../plugin.js'
+
+// The plugin starts the standalone server from a compile hook — mock it so
+// invoking the tapped callback in tests never binds a real port.
+vi.mock('../../server/standalone.js', () => ({
+  startStandaloneServer: vi.fn(async () => ({ port: 24678, close: async () => {} })),
+}))
+vi.mock('../../server/discovery.js', () => ({
+  writeMfeServerInfo: vi.fn(),
+}))
+
+import { startStandaloneServer } from '../../server/standalone.js'
+
+interface FakeCompiler {
+  context: string
+  options: any
+  hooks: {
+    beforeCompile: { tapPromise: (name: string, fn: () => Promise<void>) => void }
+    compilation: { tap: (name: string, fn: (compilation: any) => void) => void }
+  }
+}
+
+/** Minimal compiler stub covering everything apply() touches. */
+function fakeCompiler(devServer?: any): FakeCompiler & { beforeCompileTaps: Array<() => Promise<void>> } {
+  const beforeCompileTaps: Array<() => Promise<void>> = []
+  return {
+    context: '/tmp/fake-project',
+    options: {
+      mode: 'development',
+      module: { rules: [] },
+      plugins: [],
+      ...(devServer !== undefined ? { devServer } : {}),
+    },
+    hooks: {
+      beforeCompile: { tapPromise: (_name, fn) => { beforeCompileTaps.push(fn) } },
+      compilation: { tap: () => {} },
+    },
+    beforeCompileTaps,
+  }
+}
+
+const ANNOTASK_RULE = { context: ['/__annotask'], target: 'http://127.0.0.1:24678', ws: true }
+
+beforeEach(() => {
+  vi.spyOn(console, 'log').mockImplementation(() => {})
+  vi.spyOn(console, 'warn').mockImplementation(() => {})
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.mocked(startStandaloneServer).mockResolvedValue({ port: 24678, close: async () => {} })
+})
+
+describe('AnnotaskWebpackPlugin devServer proxy injection', () => {
+  it('injects the proxy synchronously during apply() when devServer is undefined', () => {
+    const compiler = fakeCompiler()
+    new AnnotaskWebpackPlugin().apply(compiler)
+
+    // Must be set before any compile hook runs — webpack-cli snapshots
+    // devServer options right after createCompiler.
+    expect(compiler.options.devServer.proxy).toEqual([ANNOTASK_RULE])
+  })
+
+  it('prepends to an existing user proxy array (v5 form), preserving user entries', () => {
+    const userRule = { context: ['/api'], target: 'http://localhost:9000' }
+    const compiler = fakeCompiler({ port: 8090, proxy: [userRule] })
+    new AnnotaskWebpackPlugin().apply(compiler)
+
+    expect(compiler.options.devServer.proxy).toEqual([ANNOTASK_RULE, userRule])
+    expect(compiler.options.devServer.port).toBe(8090)
+  })
+
+  it('adds a keyed entry to the v4 legacy object form without converting it', () => {
+    const compiler = fakeCompiler({ proxy: { '/api': { target: 'http://localhost:9000' } } })
+    new AnnotaskWebpackPlugin().apply(compiler)
+
+    const proxy = compiler.options.devServer.proxy
+    expect(Array.isArray(proxy)).toBe(false)
+    expect(proxy['/api']).toEqual({ target: 'http://localhost:9000' })
+    expect(proxy['/__annotask']).toEqual({ target: 'http://127.0.0.1:24678', ws: true })
+  })
+
+  it('uses the configured port in the proxy target', () => {
+    const compiler = fakeCompiler()
+    new AnnotaskWebpackPlugin({ port: 30001 }).apply(compiler)
+
+    expect(compiler.options.devServer.proxy).toEqual([
+      { context: ['/__annotask'], target: 'http://127.0.0.1:30001', ws: true },
+    ])
+  })
+
+  it('does not duplicate the rule when one already covers /__annotask', () => {
+    const compiler = fakeCompiler({ proxy: [ANNOTASK_RULE] })
+    new AnnotaskWebpackPlugin().apply(compiler)
+
+    expect(compiler.options.devServer.proxy).toEqual([ANNOTASK_RULE])
+  })
+
+  it('does nothing outside development mode', () => {
+    const compiler = fakeCompiler()
+    compiler.options.mode = 'production'
+    new AnnotaskWebpackPlugin().apply(compiler)
+
+    expect(compiler.options.devServer).toBeUndefined()
+  })
+
+  it('does not inject a proxy when the remote server option is set', () => {
+    const compiler = fakeCompiler()
+    new AnnotaskWebpackPlugin({ server: 'http://localhost:5173' }).apply(compiler)
+
+    expect(compiler.options.devServer).toBeUndefined()
+  })
+
+  it('warns with the manual proxy block when devServer options are frozen', () => {
+    const compiler = fakeCompiler(Object.freeze({ port: 8090 }))
+    new AnnotaskWebpackPlugin().apply(compiler)
+
+    expect(compiler.options.devServer.proxy).toBeUndefined()
+    const warning = vi.mocked(console.warn).mock.calls.map(args => args.join(' ')).join('\n')
+    expect(warning).toContain('Could not auto-inject the /__annotask proxy')
+    expect(warning).toContain("context: ['/__annotask']")
+    expect(warning).toContain('http://127.0.0.1:24678')
+  })
+
+  it('warns about the locked proxy when the server falls back to another port', async () => {
+    vi.mocked(startStandaloneServer).mockResolvedValue({ port: 51234, close: async () => {} })
+    const compiler = fakeCompiler()
+    new AnnotaskWebpackPlugin().apply(compiler)
+
+    // Proxy was locked to the expected port at apply() time…
+    expect(compiler.options.devServer.proxy).toEqual([ANNOTASK_RULE])
+
+    // …then the server lands elsewhere (EADDRINUSE fallback) — too late to
+    // fix the snapshot, so the user gets the exact rule to add by hand.
+    expect(compiler.beforeCompileTaps).toHaveLength(1)
+    await compiler.beforeCompileTaps[0]()
+
+    const warning = vi.mocked(console.warn).mock.calls.map(args => args.join(' ')).join('\n')
+    expect(warning).toContain('locked to 24678')
+    expect(warning).toContain('http://127.0.0.1:51234')
+  })
+
+  it('does not warn when the server starts on the expected port', async () => {
+    const compiler = fakeCompiler()
+    new AnnotaskWebpackPlugin().apply(compiler)
+    await compiler.beforeCompileTaps[0]()
+
+    expect(console.warn).not.toHaveBeenCalled()
+    expect(compiler.options.devServer.proxy).toEqual([ANNOTASK_RULE])
+  })
+})
diff --git a/src/webpack/loader.ts b/src/webpack/loader.ts
index 79e2936..9386ba6 100644
--- a/src/webpack/loader.ts
+++ b/src/webpack/loader.ts
@@ -3,7 +3,7 @@
  * Injects data-annotask-* attributes into Vue, React, Svelte, and SolidJS templates.
  * Must run BEFORE framework-specific loaders (enforce: 'pre').
  */
-import { transformFile } from '../plugin/transform.js'
+import { transformFile, injectComponentRegistry } from '../plugin/transform.js'
 
 export default function annotaskLoader(this: any, source: string): string {
   const options = this.getOptions?.() || {}
@@ -33,25 +33,8 @@ export default function annotaskLoader(this: any, source: string): string {
   const result = transformFile(source, filePath, projectRoot, mfe)
   if (!result) return source
 
-  // Register imported PascalCase components globally
-  let output = result
-  const importRegex = /import\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g
-  let match
-  const registrations: string[] = []
-  while ((match = importRegex.exec(result)) !== null) {
-    const [, name, src] = match
-    if (name[0] === name[0].toUpperCase() && name[0] !== name[0].toLowerCase() && !src.startsWith('.')) {
-      registrations.push(`window.__ANNOTASK_COMPONENTS__['${name}'] = ${name}`)
-    }
-  }
-  if (registrations.length > 0) {
-    const regCode = `\nif (typeof window !== 'undefined') { window.__ANNOTASK_COMPONENTS__ = window.__ANNOTASK_COMPONENTS__ || {}; ${registrations.join('; ')} }\n`
-    if (filePath.endsWith('.vue') && output.includes('</script>')) {
-      output = output.replace(/<\/script>/, regCode + '</script>')
-    } else {
-      output += regCode
-    }
-  }
-
-  return output
+  // Register this file's imported components into window.__ANNOTASK_COMPONENTS__
+  // via the shared helper (covers named/aliased/relative imports — the old
+  // inline version here only handled default, non-relative imports).
+  return injectComponentRegistry(result, filePath)
 }
diff --git a/src/webpack/plugin.ts b/src/webpack/plugin.ts
index 5d407e4..e1ccf9f 100644
--- a/src/webpack/plugin.ts
+++ b/src/webpack/plugin.ts
@@ -17,6 +17,28 @@ export interface AnnotaskWebpackOptions {
   server?: string
 }
 
+/** Must match the default in startStandaloneServer — the proxy rule is built
+ * before the server starts, so both sides need to agree on the port. */
+const DEFAULT_SERVER_PORT = 24678
+
+function buildProxyRule(port: number) {
+  // 127.0.0.1 (not localhost): the standalone server binds 127.0.0.1, and on
+  // Node 17+ "localhost" can resolve to ::1 first, breaking the proxy.
+  return { context: ['/__annotask'], target: `http://127.0.0.1:${port}`, ws: true }
+}
+
+function manualProxyHint(port: number): string {
+  return [
+    '[Annotask] Add this to your webpack devServer config manually:',
+    '',
+    '  devServer: {',
+    '    proxy: [',
+    `      { context: ['/__annotask'], target: 'http://127.0.0.1:${port}', ws: true },`,
+    '    ],',
+    '  }',
+  ].join('\n')
+}
+
 export class AnnotaskWebpackPlugin {
   private options: AnnotaskWebpackOptions
   private serverUrl: string = ''
@@ -25,6 +47,54 @@ export class AnnotaskWebpackPlugin {
     this.options = options
   }
 
+  /**
+   * Inject the /__annotask proxy rule into compiler.options.devServer.
+   * Must run synchronously during apply(): webpack-dev-server v5 reads
+   * options.proxy in setupMiddlewares() BEFORE the first compile, and
+   * @webpack-cli/serve snapshots compiler.options.devServer (Object.assign)
+   * before server.start() — so mutating devServer from a compile hook can
+   * never land. apply() runs inside createCompiler, which is early enough.
+   */
+  private injectDevServerProxy(compiler: any, port: number) {
+    const rule = buildProxyRule(port)
+    try {
+      const devServer = compiler.options.devServer = compiler.options.devServer || {}
+      const existing = devServer.proxy
+      if (existing == null) {
+        devServer.proxy = [rule]
+      } else if (Array.isArray(existing)) {
+        // v5 array form (also accepted by v4). Prepend so /__annotask wins
+        // over any catch-all user entries; skip if a rule already covers it.
+        const covered = existing.some((entry: any) =>
+          Array.isArray(entry?.context) && entry.context.includes('/__annotask'))
+        if (!covered) devServer.proxy = [rule, ...existing]
+      } else if (typeof existing === 'object') {
+        // v4 legacy object form ({ '/api': {...} }). Converting the user's
+        // entries to the array form could change how dev-server v4 normalizes
+        // them, so add ours as another keyed entry instead.
+        if (!existing['/__annotask']) {
+          existing['/__annotask'] = { target: rule.target, ws: true }
+        }
+      }
+    } catch {
+      // Frozen/sealed options throw in strict mode — fall through to the
+      // verification below, which emits the actionable warning.
+    }
+
+    // Verify the mutation actually landed (sloppy-mode writes to frozen
+    // objects fail silently, so a try/catch alone isn't enough).
+    const proxy = compiler.options.devServer?.proxy
+    const landed = Array.isArray(proxy)
+      ? proxy.some((entry: any) => Array.isArray(entry?.context) && entry.context.includes('/__annotask'))
+      : !!(proxy && typeof proxy === 'object' && (proxy as any)['/__annotask'])
+    if (!landed) {
+      console.warn(
+        '[Annotask] Could not auto-inject the /__annotask proxy into devServer options '
+        + '(unsupported proxy shape or frozen config). Requests to /__annotask/* will 404 '
+        + 'on the app port until the proxy is configured.\n' + manualProxyHint(port))
+    }
+  }
+
   apply(compiler: any) {
     // Only activate in development
     if (compiler.options.mode !== 'development') return
@@ -43,6 +113,15 @@ export class AnnotaskWebpackPlugin {
       }],
     })
 
+    // Auto-inject the devServer proxy so /__annotask routes are forwarded to
+    // the standalone server. This must happen here, synchronously — by the
+    // time any compile hook fires, webpack-cli/dev-server have already
+    // snapshotted devServer options (see injectDevServerProxy).
+    const expectedPort = this.options.port || DEFAULT_SERVER_PORT
+    if (!this.options.server) {
+      this.injectDevServerProxy(compiler, expectedPort)
+    }
+
     // Start standalone server, or point to remote server when server option is set
     let serverStarted = false
     compiler.hooks.beforeCompile.tapPromise('AnnotaskWebpackPlugin', async () => {
@@ -63,11 +142,17 @@ export class AnnotaskWebpackPlugin {
           this.serverUrl = `http://localhost:${port}`
           console.log(`[Annotask] Server running at ${this.serverUrl}/__annotask/`)
 
-          // Auto-inject devServer proxy so /__annotask routes are forwarded
-          // to the standalone server (webpack-dev-server doesn't know about them)
-          const devServer = compiler.options.devServer = compiler.options.devServer || {}
-          const proxyRule = { context: ['/__annotask'], target: `http://127.0.0.1:${port}`, ws: true }
-          devServer.proxy = [...(Array.isArray(devServer.proxy) ? devServer.proxy : []), proxyRule]
+          // The proxy rule was locked in during apply(). If the preferred port
+          // was busy, the server fell back to a random port (EADDRINUSE path in
+          // startStandaloneServer) and the proxy now points at a dead port —
+          // too late to fix the snapshot, so tell the user exactly what to do.
+          if (port !== expectedPort) {
+            console.warn(
+              `[Annotask] Port ${expectedPort} was busy — server started on ${port} instead, `
+              + `but the devServer proxy was already locked to ${expectedPort} at startup. `
+              + `Free port ${expectedPort} (or pass an open port via the plugin's 'port' option) and restart, `
+              + `or configure the proxy yourself.\n` + manualProxyHint(port))
+          }
         } catch (err) {
           console.error('[Annotask] Failed to start server:', err)
         }