diff --git a/AgentHubStudio.md b/AgentHubStudio.md
new file mode 100644
index 00000000..6fe5be04
--- /dev/null
+++ b/AgentHubStudio.md
@@ -0,0 +1,308 @@
+# AgentHub Studio
+
+AgentHub renders **artifacts an agent generated during a session** — an HTML document, or a set of design variants laid out on an infinite canvas — in a dedicated side panel where the user can point at any element, comment, tweak it, and send that feedback back to the agent. The guiding principle:
+
+> **The agent renders into a scratch surface, never into the project. Everything the user does on that surface becomes a prompt, never a file write.**
+
+This is the "try it before you build it" counterpart to the web preview panel: web preview shows you the real app, Studio shows you things that do not exist in the codebase yet — and must not, until the user says so.
+
+## On the name
+
+`SidePanelContent.artifact` is already taken by the **claude.ai artifact** panel (a WKWebView over a published `claude.ai/public/artifacts/…` page — a *detection* feature, read-only, Claude-only). That feature and this one share a noun and nothing else. To keep them from being confused forever:
+
+- The existing claude.ai case is renamed `.claudeArtifact` (mechanical; the model is already `ClaudeArtifact` and the detector `ClaudeArtifactURLDetector`).
+- This feature is **Studio**, with one panel case, `.studio`: the panel lists every artifact and canvas for the project and the item's `kind` decides how it renders.
+
+The four agent-facing tools: `agenthub_artifact`, `agenthub_design`, `agenthub_list_artifacts`, `agenthub_get_artifact`.
+
+## The tools
+
+| | `agenthub_artifact` | `agenthub_design` |
+|---|---|---|
+| Renders | one self-contained HTML **document**, served verbatim | N **fragments** of one component, side by side |
+| Surface | single scrolling page | infinite pan/zoom canvas of artboards |
+| For | reports, diagrams, mockups, dashboards, "show me what this would look like" | "render 6 versions of this button" |
+| Panel | `.studio` (kind `.document`) | `.studio` (kind `.canvas`) |
+| Re-file | same `id` replaces in place, bumps `revision` | same `id` replaces the whole variant set |
+| Inputs | `id?`, `title`, `html` | `id?`, `component`, `sourcePath?`, `props?`, `variants[{name, html, css?, notes?, width?, height?}]` |
+| Tweaks | page calls `dc_set_props(...)` itself | one shared `props` schema for the whole canvas |
+
+`agenthub_list_artifacts` returns the project's index (see *Discovery*) so an agent refines an existing item instead of filing a near-duplicate. Both filing tools' descriptions instruct: *list first; when refining, pass the existing `id`.*
+
+`sourcePath` on `agenthub_design` is the real component the variants are exploring (e.g. `src/components/Button.tsx`). It is only used by *Promote* (below) so the promotion prompt can name the file; it never causes AgentHub to read or write it.
+
+### Tweaks — one schema per canvas, not per variant
+
+The Tweaks panel from web preview is ported, with one deliberate difference: on a canvas the schema is **shared by every variant**. The point of a canvas is comparing variants under the same knobs — radius 12 across all four buttons — so per-variant tweaks would defeat it, and sharing is also simpler.
+
+- `agenthub_design` accepts `props`: `{ name: { type: slider|color|select|toggle|text, value, label?, min?, max?, step?, unit?, options? } }` (or an ordered array of `{ name, … }`), validated by `StudioTweakPropParser` at the tool boundary (`maxProps` 24, CSS-identifier-safe names, value matches type, select value ∈ options, slider within range).
+- Every prop is exposed to every artboard as the CSS custom property `--<name>`; variants write `var(--radius)`. **A declared prop no variant references is a tool error** (`StudioTweakPropParser.unusedProps`): a control that moves nothing is exactly what a user reports as "tweaks don't work". Sliders carry their `unit`; toggles become `1`/`0`; text/select values are also written into elements marked `data-prop="<name>"`, so copy is tweakable without JS.
+- The host page renders defaults into a static `<style id="studio-props">` block (so Export / plain browser look right with no JS), then its script re-applies them, installs `dc_on_props_changed`, and hands the schema to the injected `dc_set_props` runtime — which is what the existing `TweaksPanelView` reads. Live changes go through `TweaksBridge.setProp` and every artboard updates at once.
+- **Save defaults** never touches the served cache: canvas → the `props` values in the payload are updated; document → the `dc_set_props` call in the stored HTML is spliced with `TweakPropsSourceEditor` (parser-verified, never a full-file rewrite). Both go through `StudioLibrary.store`, so SQLite stays the source of truth and the revision bump reloads the panel.
+- **Ideas / Custom / Delete all** do not spawn web preview's headless tweak agent (it edits a file on disk; Studio has no such file). They go to the *session* as re-file prompts (`StudioTweaksPromptBuilder`), same rails as Send; the spinner clears when the artifact's revision advances or after `rerunTimeout`.
+- `agenthub_artifact` documents get Tweaks for free by calling `window.dc_set_props(...)` themselves (the tool description says so, and to guard it with `if (window.dc_set_props)` for plain browsers).
+- Text/select values in the static style block are CSS-hex-escaped (`}`, `;`, `<`, `>`, …) so an authored value can never end the rule or the `<style>` element; the schema JSON inlined in the host `<script>` escapes `</`.
+
+### Payload limits (`StudioArtifact.Limits`, enforced at the tool boundary)
+
+| Limit | Value | Why |
+|---|---|---|
+| `maxDocumentBytes` | 1.5 MB | one artifact document |
+| `maxVariants` | 12 | more than that is a gallery, not a comparison |
+| `maxVariantBytes` | 256 KB | per variant, html + css combined |
+| `maxTitleLength` / `maxNameLength` | 120 / 40 | |
+| `StudioTweakPropParser.maxProps` | 24 | one shared schema per canvas |
+| variant CSS must parse | — | see *CSS scoping*; unparseable CSS is a tool error, not a rendered lie |
+
+Exceeding a limit is a tool-level error the agent can correct. Never truncate silently — a canvas that dropped two variants misrepresents its own coverage.
+
+## User behavior
+
+- A session's monitoring card shows a **Studio** button only after the agent has filed at least one artifact or design (no proactive UI — same rule as the MCP and Measurements buttons).
+- Clicking it opens the side panel. A picker switches between filed items when there is more than one.
+- The panel serves from `127.0.0.1`, so **Open in browser** works and the page is a real URL, not a `loadHTMLString` blob. A re-file bumps `revision`; an open panel observes it and reloads.
+- **Inspect mode** has the same three behaviours as web preview's strip (Context is omitted there too — Studio has no terminal-attachment queue): **Comment** (click an element, type an instruction, ⏎ sends an element-aware prompt), **Crop** (drag a region; ⏎ sends the region, a screenshot, and the elements inside it), and **Edit** (click an element, adjust it with the Canvas design toolbar — text, font, colour, size, spacing, radius, fit/delete). On a **canvas**, edits are the scratchpad's own business: they are **baked into the variant** — the artboard's `innerHTML` (inline styles/text from the toolbar) is serialized into the variant's `html` on a 500 ms debounce, stored quietly (no page reload; the DOM already equals the payload), and **Revert** restores the version the agent last filed. No agent round-trip: nobody cares how a scratch change is implemented, only that the variant the user eventually picks *is* what they see. On a **document**, edits still go to the agent (**Send to Agent** / **Discard**): serializing a whole scripted document would double its generated content on reload.
+- On a design canvas, comments, crops, and edits are stamped with the variant they landed on, so the agent is told *which* version the note is about.
+- **Implement** is the one step from scratch surface to code, and it is deliberately obvious: a labelled `Implement ▾` menu in the panel header *and* an "Implement" pill on every artboard caption (the pill posts `{type: "implement", variant}` to a native `agentHubStudio` message handler and is hidden in a plain browser/export). Either path flushes pending bakes first, so the prompt carries the *edited* markup. The same choice can be made in conversation — "let's go with the ghost one" — because the agent is told (guidance + skill) to call `agenthub_get_artifact(id, variant)` and implement exactly what it returns.
+- **Export…** saves the served HTML file via `NSSavePanel`; **Copy link** copies the localhost URL (tooltip: valid only while AgentHub is running).
+- The panel never auto-opens — button-only (`isAutoOpenableContent` returns `false`).
+- Artifacts persist across relaunch, scoped to the **project** (same rule and the same `MeasurementProjectScope` rollup as measurements — a design canvas outlives the conversation that produced it, and a worktree's canvases roll up to the parent repo).
+
+## Data flow
+
+```
+agent calls agenthub_artifact(title, html)
+       or  agenthub_design(component, variants[…])
+   │
+   ├─ AgentHubMCPServer validates (limits, CSS parses) + enqueues          ①
+   │     StudioArtifactQueue (JSON file, atomic write)
+   │     ~/Library/Application Support/AgentHub/studio-records/
+   │
+   ├─ App drains the queue                                                ②
+   │     StudioArtifactMonitor (poll) → StudioArtifactHandler
+   │     resolves AGENTHUB_SESSION_ID, else process→session mapping
+   │
+   ├─ App materializes + stores                                           ③
+   │     CLISessionsViewModel.storeStudioArtifact() resolves the project
+   │       bucket + branch, then StudioLibrary.store() (one instance shared
+   │       by the Claude and Codex view models):
+   │       in-memory first (button appears immediately)
+   │       → StudioDocumentWriter → studio/{project-hash}/{id}/index.html
+   │           document: agent HTML written verbatim
+   │           canvas:   host page + StudioCSSScoper-scoped artboards
+   │       → SessionMetadataStore.saveStudioArtifact (v18 studio_artifacts)
+   │       → StudioIndexStore publish (mirrored to worktree alias paths)
+   │
+   ├─ Static server                                                       ④
+   │     StudioStaticServer — in-process NWListener, GET/HEAD only, rooted
+   │     at studio/, 127.0.0.1:{ephemeral}, started lazily on first panel
+   │     open; item URL is /{project-hash}/{id}/index.html
+   │
+   └─ Panel renders + feeds back                                          ⑤
+         MonitoringCardView gates the button on studioArtifacts(for:)
+         → SidePanelContent.studio → StudioSidePanelView
+         → StudioPanelState (selection, reload token) + Canvas
+           InspectableWebView + webInspectorOverlay (.input mode)
+         → StudioFeedbackPromptBuilder / StudioPromotionPromptBuilder
+         → sendPromptToActiveTerminal / showTerminalWithPrompt
+```
+
+SQLite is the source of truth; the served `index.html` is a cache. `StudioLibrary.servedURL` rewrites a missing document from the payload before handing out a URL, and `StudioStorageReconciler` (run once at launch) drops directories no row vouches for.
+
+### Why an in-process server, not `python3 -m http.server`
+
+`DevServerManager` shells out to python for static project previews, which is right there — the project is the user's and its serving process belongs in `managed_processes`. Studio content is AgentHub's own directory, so a tiny native `NWListener` HTTP/1.1 server (GET/HEAD only, path-traversal guarded, `Content-Type` by extension, `Cache-Control: no-store`) is the smaller thing: no child process to track and reap, no python dependency, no port-parsing readiness heuristics, and re-file reload is free because nothing is cached. It binds `127.0.0.1` only and starts lazily on first panel open.
+
+## The canvas host page
+
+Artboards are **sibling `<section>` elements inside one document**, not iframes. This is forced by `ElementInspectorBridge.userScript`, which WKWebView injects with `forMainFrameOnly: true` — inside an iframe there is no hover highlight, no click-to-comment, and no element context, which is the entire point of the panel.
+
+```html
+<div id="studio-canvas" style="transform: translate(Xpx, Ypx) scale(Z)">
+  <figure class="studio-frame" data-variant="primary">
+    <figcaption>primary</figcaption>
+    <section class="studio-artboard" data-variant="primary">…</section>
+  </figure>
+  <figure class="studio-frame" data-variant="ghost">…</figure>
+</div>
+```
+
+- Pan/zoom is a CSS transform on `#studio-canvas`, driven by wheel/trackpad handlers in the host page. The inspector reads `getBoundingClientRect()`, which already accounts for ancestor transforms, so highlight rects stay correct at any zoom — but a transform never fires `scroll`, which is what the inspector bridge listens to for re-posting the selected rect. The host page dispatches a synthetic window `scroll` after every pan/zoom (and after a tweak resizes elements), so the highlight and the native comment box follow the element instead of staying behind.
+- The host page carries `<meta name="agenthub-studio-host" content="N">` (`StudioDocumentWriter.hostVersion`). `StudioLibrary.servedURL` regenerates any canvas whose file lacks the current marker, so host-page fixes reach canvases already on disk without waiting for the agent to re-file. Bump the version whenever the host CSS/JS changes behaviour.
+- Artboards flow in a row-wrapping grid, labelled by variant name; `width`/`height` from the tool set a fixed frame, otherwise the artboard sizes to content.
+- Each `.studio-artboard` gets `all: initial; display: block; contain: layout paint; isolation: isolate;` so nothing inherits *in* from the host page and nothing paints *out* past the artboard.
+- **Variant `<script>` is stripped.** Scripts run in the shared document, so a variant's `document.querySelector('.btn')` would find its neighbour's button. The canvas presents variants; CSS interactivity (`:hover`, `:focus`, transitions) is preserved, JS is not. Agents that need JS should file an `agenthub_artifact` instead. The tool description says so.
+- The panel resolves *which* variant a clicked element belongs to by evaluating `document.querySelector(cssSelector)?.closest('.studio-artboard')?.dataset.variant` from the element context Canvas already provides.
+
+### CSS scoping — `StudioCSSScoper`
+
+Because everything shares one document, **we own CSS isolation.** `@scope` would be the clean answer but is unavailable on the `macOS 14` deployment floor, so each variant's CSS is rewritten rule by rule. The scoper lives in `AgentHubCLIKit` so the tool boundary and the writer share one implementation and one set of tests.
+
+Input: the variant's `css` plus every `<style>` block hoisted from its `html`. `S` = `.studio-artboard[data-variant="{name}"]`.
+
+| Construct | Rewrite |
+|---|---|
+| plain rule `a, .b > c {…}` | each comma-separated selector prefixed: `S a, S .b > c {…}` |
+| `:root`, `html`, `body` (alone or as the leftmost compound) | replaced by `S` — so `body { background }` paints the artboard, and `:root { --x }` custom properties land on the artboard and inherit down |
+| `*` at leftmost | `S *` |
+| `@media`, `@supports`, `@container`, `@layer` | preserved; recurse into the block |
+| `@keyframes name` | renamed `name-{variant-slug}`; every `animation` / `animation-name` in that variant's declarations rewritten to match |
+| `@font-face` | hoisted unchanged (global by nature; identical families across variants share, differing `src` for the same family — last wins; documented) |
+| `@import`, `<link rel=stylesheet>` | dropped and reported: the tool returns a warning naming what was dropped, because remote CSS can't be scoped |
+| `!important` | preserved |
+| inline `style=""` | untouched — already element-scoped |
+| unbalanced braces / unparseable | **tool error** ("variant 'ghost' CSS did not parse at byte N") |
+
+Duplicate `id`s across variants are tolerated: `S #x` still resolves per artboard, and browsers cope with duplicate ids. Not rewritten.
+
+Tests are table-driven, one case per row above, plus a leak test: two variants each styling `button { color }` render with different computed colors.
+
+## `agenthub_get_artifact` — the agent's view of the current canvas
+
+`StudioDocumentWriter.write` also writes `artifact.json` beside `index.html` (the full `StudioArtifact` payload, including baked-in edits and saved tweak defaults), and the index entry carries `payloadPath`. `agenthub_get_artifact(id, variant?, includeContent?)` reads that sidecar — never SQLite — and returns metadata plus, for the named variant (case-insensitive) or with `includeContent`, the html/css. This is what makes choosing a variant *in chat* equivalent to clicking Implement, and it lets an agent re-file an existing canvas starting from what the user has rather than what it originally filed.
+
+## Codex approval mode for the bundled server
+
+Codex (0.1xx+) prompts per MCP tool call unless the server's tools are marked `auto` (`mcp_servers.<name>.default_tools_approval_mode`; values `auto | prompt | writes | approve`). Under `approval_policy = never` — a common global setting — a prompt is impossible and the call fails with *"MCP tool call requires approval, but approval policy is never"*, which is how Studio first surfaced this. AgentHub's Codex bootstrap now sets the bundled `agenthub` server to `auto` unconditionally (its tools are AgentHub's own and local), and XcodeBuildMCP to `auto` when the effective policy is `never` / `full-auto` — AgentHub's own Codex setting when one is chosen, otherwise the user's global `approval_policy` read from `~/.codex/config.toml` (`CodexGlobalConfigReader`, top-level key only, honours `CODEX_HOME`, read-only). Older Codex ignores the key; newer rejects unknown values, so only `auto` is emitted. Surfaced when Codex 0.148 (Aug 2026, "Enforce strict auto-review for MCP tool calls" / Guardian v2) introduced per-tool MCP approval; sessions on 0.134–0.147 ran the same tools under `never` without a prompt. Every tool on the bundled server also carries MCP annotations (`AgentHubMCPServer.toolAnnotationsByName`: `readOnlyHint` on the list/get/planning tools, `destructiveHint` only on worktree deletion, `openWorldHint: false` everywhere), so a host on Codex's `writes` mode — "prompts for tools that aren't marked read-only" — does not prompt just to list what exists.
+
+## Getting agents to reach for it
+
+Tool descriptions alone are advisory, and both of Studio's nouns are also claimed by surfaces the model knows well (Claude Code's `/design` skill and `Artifact` tool), so without help the model edits files or publishes elsewhere and nothing lands in the panel. Three layers, strongest first:
+
+1. **System-prompt guidance** — `StudioAgentGuidance.systemPrompt`, injected on the same channel as the simulator guidance (`combinedAppendSystemPrompt` → Claude `--append-system-prompt`, Codex `-c developer_instructions=`) whenever the bundled `agenthub` MCP server is attached. Default-on; Settings › Studio › *Nudge agents toward Studio* turns it off (`AgentHubDefaults.studioAgentGuidanceEnabled`). Never injected without the CLI present — guidance naming tools that do not exist misleads.
+2. **Bundled `agenthub-studio` skill** — installed alongside the task-manager skill into `~/.claude/skills/` and `~/.codex/skills/` (`AgentHubStudioSkillInstaller`, shared writer `AgentHubBundledSkillFiles`). Model-invocable from its description *and* an explicit `/agenthub-studio` trigger; the fuller playbook (which tool, how to shape variants and shared props, how to handle feedback and Promote).
+3. **Tool descriptions** lead with the user's phrasings ("show me 4 versions", "compare dense vs airy", "what would it look like").
+
+## Discovery — `agenthub_list_artifacts` and `StudioIndexStore`
+
+Same shape as `MeasurementIndexStore`. The app republishes a JSON index per project on every change (`CLISessionsViewModel.publishStudioIndex`), mirrored to every session path that resolves to the project (worktrees included), file names percent-encoded. Entry: `id`, `kind`, `title` / `component`, `variantNames`, `sourcePath`, `revision`, `updatedAt`, `url`. **The CLI reads the index; it never opens the app's SQLite database.**
+
+## Feedback prompts
+
+Two builders, two intents, never one button that does either:
+
+- **`StudioFeedbackPromptBuilder`** (Send) — element context from `ElementInspectorPromptBuilder`, stamped with `variant` when on a canvas, then the user's comment. Closes with: *re-file with `agenthub_design`/`agenthub_artifact` using id `{id}`. Do not edit project files.*
+- **`StudioPromotionPromptBuilder`** (Promote…) — names the variant, includes its **original** unscoped `html`/`css` fragment (never the scoped rewrite), the `component` name, and `sourcePath` when the agent supplied one. Asks the agent to implement it in the real component, preserving behaviour and props and changing presentation only, and to report the files it touched. Nothing else in Studio can produce this prompt.
+
+The agent's own permission model still gates any file write; Promote is a prompt, not a mutation.
+
+## Storage & lifecycle
+
+- **Overwrite in place.** A re-file writes `studio/{project}/{id}/index.html` over itself. Same `id` → same directory, so iterating on a canvas fifty times costs one directory. No on-disk revision history: HTML payloads are large, and the agent can re-file an earlier variant if asked. `revision` in the record is a counter for panel reload, not a history.
+- **Delete cascades.** Deleting a record (panel, or Settings) removes its directory. Deleting a project's items removes `studio/{project}/`.
+- **Reconcile on launch.** `StudioStorageReconciler` drops directories with no DB row and rows with no directory. A crash between the two writes never leaves either a phantom card or an orphan folder.
+- **Settings › Studio** mirrors `MeasurementsSettingsView`: items grouped by project with on-disk size, per-item and per-project delete (confirmed), including projects no longer open in the sidebar. Removing a repo from the sidebar never deletes anything on its own.
+- Per-item size is bounded by the tool limits, so total growth is `items × ≤1.5 MB` and visible in Settings. There is no automatic eviction — that would be a silent deletion of something the user may be about to look at.
+
+## Sharing (P3)
+
+- **Export…** writes the served `index.html` where the user chooses. It is self-contained by construction: the canvas host page inlines its own CSS/JS, and the inspector bridge is injected by WKWebView at load, so it never appears in the file. Remote references the agent put in its HTML (images, fonts) stay remote.
+- **Copy link** — the localhost URL, with the caveat visible that it dies with the app.
+- Hosting/publishing is out of scope. Any future publish path must say plainly, in the UI, that it uploads unreviewed agent-generated HTML.
+
+## Key files
+
+| Area | File |
+|---|---|
+| Domain model (`StudioArtifact`, `StudioVariant`, `Limits`) | `AgentHubCLI/Sources/AgentHubCLIKit/StudioArtifactModels.swift` |
+| Fragment normalizer (strip wrappers/scripts, hoist styles) | `AgentHubCLI/Sources/AgentHubCLIKit/StudioFragmentNormalizer.swift` |
+| Shared tweak schema model + parser + CSS value mapping | `AgentHubCLI/Sources/AgentHubCLIKit/StudioTweakProps.swift` |
+| CSS scoper (shared by tool boundary and writer) | `AgentHubCLI/Sources/AgentHubCLIKit/StudioCSSScoper.swift` |
+| CLI→app file queue (+ `StudioSupportDirectory`) | `AgentHubCLI/Sources/AgentHubCLIKit/StudioArtifactQueue.swift` |
+| Agent-readable index (list tool) | `AgentHubCLI/Sources/AgentHubCLIKit/StudioIndexStore.swift` |
+| Tool schemas, validation, enqueue, list | `AgentHubCLI/Sources/AgentHubCLI/AgentHubMCPServer.swift` (`fileArtifact`, `fileDesign`, `listStudioArtifacts`) |
+| Queue drain | `AgentHubCore/.../Services/StudioArtifactMonitor.swift` |
+| Session resolution (Claude/Codex targets) | `AgentHubCore/.../Services/StudioArtifactHandler.swift` |
+| Project-keyed model, store/load/delete, index publish, reconcile | `AgentHubCore/.../Services/StudioLibrary.swift` (`StudioPersisting` protocol) |
+| Host page composition, naming, delete | `AgentHubCore/.../Services/StudioDocumentWriter.swift` |
+| Static serving | `AgentHubCore/.../Services/StudioStaticServer.swift` |
+| Orphan reconcile + directory size | `AgentHubCore/.../Services/StudioStorageReconciler.swift` |
+| SQLite record (blob payload) | `AgentHubCore/.../Models/StudioArtifactRecord.swift` |
+| `v18_create_studio_artifacts` + CRUD | `AgentHubCore/.../Services/SessionMetadataStore.swift` |
+| Panel state (`@Observable`, tested) | `AgentHubCore/.../UI/StudioPanelState.swift` |
+| Edit-mode state (live edits batched per element) | `AgentHubCore/.../UI/StudioDesignEditState.swift` |
+| Panel, inspect toggle, Promote menu, Export / Copy link / Delete | `AgentHubCore/.../UI/StudioSidePanelView.swift` |
+| Feedback / promotion / tweaks prompts | `AgentHubCore/.../Services/StudioFeedbackPromptBuilder.swift`, `StudioPromotionPromptBuilder.swift`, `StudioTweaksPromptBuilder.swift` |
+| Save-defaults (`saveTweakDefaults`) | `AgentHubCore/.../Services/StudioLibrary.swift` |
+| View model glue (`storeStudioArtifact`, `loadStudioArtifacts`, `projectScopeKey`) | `AgentHubCore/.../ViewModels/CLISessionsViewModel.swift` |
+| Provider wiring (`studioLibrary`, monitor, handler, launch reconcile) | `AgentHubCore/.../Configuration/AgentHubProvider.swift` |
+| Panel case + routing | `AgentHubCore/.../UI/MultiProviderMonitoringPanelView.swift` |
+| Button gating + load-on-appear | `AgentHubCore/.../UI/MonitoringCardView.swift` |
+| Settings tab (storage + guidance toggle) | `AgentHubCore/.../UI/StudioSettingsView.swift`, `ViewModels/StudioSettingsViewModel.swift` |
+| Agent nudge (system prompt) | `AgentHubCore/.../Configuration/StudioAgentGuidance.swift`, wired in `UI/EmbeddedTerminalLaunchBuilder.swift` |
+| Bundled skill + installer | `AgentHubCore/.../Resources/AgentHubStudioSkill/`, `Services/AgentHubStudioSkillInstaller.swift` |
+
+## Invariants (preserve when editing)
+
+- **Studio never writes into the user's repo.** Artifacts live in Application Support. This is what makes "render 6 button variants" free of consequence — the moment a canvas can touch `src/`, the user has to review it like a diff instead of glancing at it.
+- **Tweaks are per canvas, never per variant.** One schema, one panel, every artboard reads the same `--<name>`. A per-variant knob would break the comparison the canvas exists for.
+- **Save defaults edits the payload, never the served file.** Canvas → `props`; document → a verified `dc_set_props` splice. Then `store`, so the cache is regenerated and SQLite stays authoritative.
+- **Send iterates the surface; Promote asks for code. Never one button that does either.** `StudioFeedbackPromptBuilder` forbids project edits; `StudioPromotionPromptBuilder` is the only path that requests them, and it is a distinct, explicitly labelled action.
+- **Canvas edits bake into the payload; documents go to the agent.** A canvas variant's `html` after Edit mode is the serialized artboard — Implement, `agenthub_get_artifact`, and the next re-file all see the user's edits. Never route canvas edits through the agent "for quality": it is a scratchpad, and an agent applying "make the padding 12px" to a fragment it will later re-file is pure ceremony.
+- **Quiet self-writes.** A bake produces a revision the panel expects (`quietRevisionExpectation`); the reload handler keeps the page for that revision and reloads for every other. Reloading under an in-progress edit would drop the selection and toolbar.
+- **Promotion sends the original fragment, never the scoped rewrite.** The scoped CSS is an artefact of the canvas; shipping `.studio-artboard[data-variant=…]` selectors into someone's codebase would be an embarrassment.
+- **A re-file must reuse the same `id`**, which replaces the item in place instead of stacking near-duplicates — same rule and reason as a measurement re-run. `createdAt` is preserved so the item holds its position under the user's cursor.
+- **Artifacts are documents, variants are fragments.** `agenthub_artifact` HTML is served verbatim — it needs no scoping, no pan/zoom, no host chrome, and it may need its own `<head>`. `agenthub_design` variants are stripped to fragments and composed into the host page, whose `<head>`, canvas transform, and layout AgentHub owns.
+- **Every artboard's CSS is scoped at wrap time, and unscopable CSS is rejected at the tool boundary.** Unscoped variant CSS silently restyles its neighbours, and the resulting canvas lies about what each variant looks like — the only thing the canvas is for.
+- **Variant scripts are stripped.** One document, N variants; JS cannot be scoped the way CSS can.
+- **Artboards are DOM sections, never iframes**, while `ElementInspectorBridge` is `forMainFrameOnly: true`. If that ever changes upstream in Canvas, revisit — but do not ship iframes and a broken inspector.
+- **Payload limits are enforced at the tool boundary**, not in the UI — an over-limit call is a correctable tool error, never a silent truncation.
+- **Never store against a `pending-` session id.** Unresolvable records stay queued and are retried (30s), same as `MeasurementRecordMonitor.shouldRetry`.
+- **Project-scoped, not session-scoped.** `sessionId` is provenance only. Worktrees roll up via `MeasurementProjectScope`.
+- **`webView` is captured deferred.** `onWebViewReady` fires from `makeNSView`; a synchronous `@State` write there is dropped by SwiftUI, and every `setProp`/snapshot then silently talks to nil. Same rule web preview follows.
+- **The static server binds `127.0.0.1` only, serves only under `studio/`, and refuses `..`.** Studio content is unreviewed agent-generated HTML; it must not be reachable off the machine, and the server must not be a file-read primitive.
+- **The CLI never opens the app's database.** `agenthub_list_artifacts` reads the JSON index.
+- **Overwrite in place; delete cascades; reconcile on launch.** Disk usage is `items × bounded size`, visible in Settings, and never silently evicted.
+- **Record stored as an encoded blob with `payloadVersion`** — the sanctioned per-table version column, because the item's shape will evolve independently of the schema.
+- **New migration only.** `v18_*`; never edit or reorder `v1`–`v17`. Migration-preservation tests anchor on an identifier via `seedMigrationBaseline(before:in:)` — never a positional `dropLast(n)`.
+
+## Tests
+
+| Suite | Package | Covers |
+|---|---|---|
+| `StudioCSSScoperTests` | CLI | one case per rewrite-table row; leak test; parse-failure error carries offset |
+| `StudioFragmentNormalizerTests` | CLI | wrapper stripping, style hoist, script/link drop + warnings |
+| `StudioArtifactQueueTests` | CLI | atomic write, drain order, tmp/failed handling, `replacing` semantics |
+| `StudioIndexStoreTests` | CLI | percent-encoded names, mirror to alias paths |
+| `StudioTweakPropsTests` | CLI | every prop type, array/object forms, bool-vs-1 disambiguation, rejections, CSS values, tolerant decoding |
+| `StudioDocumentWriterTests` | Core | document verbatim; canvas artboards in order, labels, sizes, escaping; unsafe ids hashed; cascade delete |
+| `StudioStaticServerTests` | Core | 127.0.0.1 only, index.html resolution, `..`/dotfile/escape → 404, HEAD/405, `no-store`, live socket |
+| `StudioArtifactHandlerTests` | Core | explicit id (Codex), process-group fallback, `pending-` fallback, retry window |
+| `StudioStorageReconcilerTests` | Core | orphan dirs dropped, empty projects removed, missing root no-op |
+| `StudioPromptBuilderTests` | Core | variant stamped; forbids project edits; promotion carries unscoped source + `sourcePath` |
+| `StudioPanelStateTests` | Core | default/explicit selection, reload token, follow-the-agent reconcile, variant-from-selector |
+| `StudioDesignEditStateTests` | Core | per-element batches with old→new deltas, last-wins, revert cancels, delete/fit, refresh keeps edited values, late variant stamp |
+| `StudioLibraryTests.updateVariantHTMLBakesEdits` | Core | bake replaces only named variants, bumps revision, republishes the payload sidecar + `payloadPath` |
+| `StudioLibraryTests` | Core | store/refile/load/delete/deleteAll, index publish, servedURL rewrite, allProjects, reconcile |
+| `StudioArtifactStoreTests` | Core | SQLite round trip, upsert, project scoping, v18 preserves the v17 baseline |
+| `StudioTweaksTests` | Core | host page CSS vars + schema + escaping; save-defaults canvas (revision bump, other props kept) and document (spliced call); tweaks prompts |
+| `CLISessionsViewModelStudioTests` | Core | Codex-filed artifact visible to a Claude session in the same project; re-file/delete through the view model; no-project drop |
+
+The view itself has no snapshot test; everything the view decides lives in `StudioPanelState`, which does.
+
+## Current state — works
+
+- All three tools on the bundled MCP server, available in every AgentHub-managed Claude and Codex session with no configuration (rides the existing `AGENTHUB_*` bootstrap for both providers).
+- Tool-boundary validation: limits, unique variant names, fragment normalization with warnings, CSS scoping check with character offset on failure.
+- Queue → monitor → handler (Claude/Codex targets, `pending-` retry) → shared `StudioLibrary` → SQLite (`v18`) + served document + JSON index.
+- In-process loopback server; canvas host page with pan/zoom (wheel, ⌘±/⌘0, drag on empty canvas, HUD with Fit); per-variant CSS isolation verified visually.
+- Panel: picker, Inspect toggle with element-anchored comment box, Send (variant-stamped feedback prompt), Promote… per variant, **Tweaks** (shared props on a canvas; `dc_set_props` in a document; live values, Reset, Save defaults, Ideas / Custom / Delete all through the session), Reload, Open in browser, Copy link, Export…, Delete, warnings banner, expand/collapse.
+- Shared canvas tweaks verified visually: one change moved radius, accent, label, and shadow across all variants at once.
+- Settings › Studio: per-project list with bytes on disk, per-item and per-project delete.
+- Launch reconcile of orphan directories; missing documents rewritten from the payload on demand.
+
+## Remaining work / gaps
+
+- [ ] **No auto-open, by design** — but there is also no *notification* that something landed. A subtle badge pulse on the Studio button when a new item arrives would help without violating the rule.
+- [ ] **Promote does not verify.** The agent is asked to report files touched; nothing checks that it stayed within `sourcePath`.
+- [ ] **Alias index staleness from Settings.** Deleting from Settings republishes the project key's index but not worktree aliases (no session context there); a worktree's `agenthub_list_artifacts` can name a deleted item until its project is next loaded.
+- [ ] **Tweaks in a document need cooperation from the agent.** A document only gets the panel if it calls `dc_set_props`; nothing enforces it. Canvas props need no agent cooperation beyond declaring them.
+- [ ] **CSS scoping edge cases.** `@font-face` collisions across variants (last wins), CSS nesting with `&` inside `@media` blocks, and duplicate `id`s across variants are tolerated, not solved.
+- [ ] **Canvas layout is flow-only.** Artboards wrap at the panel width at load; there is no persisted per-artboard position, no drag-to-arrange, and no zoom/pan persistence across reloads.
+- [ ] **Sharing beyond Export.** Hosting is out of scope; any future publish path must say in the UI it uploads unreviewed agent HTML.
+
+## Verification
+
+- CLI: `cd app/modules/AgentHubCLI && swift test --filter Studio`
+- Core: `cd app/modules/AgentHubCore && xcodebuild test -scheme AgentHubCore-Tests -destination 'platform=macOS' -test-timeouts-enabled YES -skipPackagePluginValidation -only-testing:AgentHubTests/StudioDocumentWriterTests -only-testing:AgentHubTests/StudioStaticServerTests -only-testing:AgentHubTests/StudioArtifactHandlerTests -only-testing:AgentHubTests/StudioStorageReconcilerTests -only-testing:AgentHubTests/StudioPromptBuilderTests -only-testing:AgentHubTests/StudioPanelStateTests -only-testing:AgentHubTests/StudioLibraryTests -only-testing:AgentHubTests/StudioArtifactStoreTests`
+- Manual tool drive (no app needed): set `AGENTHUB_PROVIDER=claude AGENTHUB_SESSION_ID=<id> AGENTHUB_PROJECT_PATH=<repo>` and pipe JSON-RPC `tools/call` lines into `agenthub mcp-server`; the record lands in `studio-records/` for the app to drain.
diff --git a/CLAUDE.md b/CLAUDE.md
index de0264de..9659ac67 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -296,13 +296,17 @@ Read **`Measurements.md`** before editing anything named `Measurement*`, the `Si
 
 ### Artifact Panel
 
-Artifacts an agent published to claude.ai during a session (`/design` canvases, reports, mockups) open in a dedicated side panel. Detection is passive and read-only, on the same rails as localhost web preview: `SessionJSONLParser` files an artifact from the `Artifact` tool's publish result (which carries the title and source path), from the `frame-link` entry Claude Code writes alongside it, or from a bare artifact URL in the transcript — into `SessionMonitorState.detectedArtifacts`. An **Artifact** button appears in the card header only once one has been detected, and toggles `SidePanelContent.artifact` open/closed.
+Artifacts an agent published to claude.ai during a session (`/design` canvases, reports, mockups) open in a dedicated side panel. Detection is passive and read-only, on the same rails as localhost web preview: `SessionJSONLParser` files an artifact from the `Artifact` tool's publish result (which carries the title and source path), from the `frame-link` entry Claude Code writes alongside it, or from a bare artifact URL in the transcript — into `SessionMonitorState.detectedArtifacts`. An **Artifact** button appears in the card header only once one has been detected, and toggles `SidePanelContent.claudeArtifact` open/closed (renamed from `.artifact` so it is never confused with the Studio panel below).
 
 - **Claude only.** `CodexSessionJSONLParser` never files artifacts, and the card gates the button on `providerKind == .claude`.
 - Artifacts are keyed by the id in the URL, so a republish updates the existing entry and bumps `revision` — which is what makes an open panel reload — instead of appending a duplicate. The canonical URL drops query/fragment (`?via=auto_preview` is provenance, not identity).
 - `ArtifactWebView` uses the **default (persistent)** website data store: artifact pages are private to the signed-in account, so the sign-in has to survive a panel close and a relaunch. Links leaving claude.ai open in the user's browser. A signed-out load lands on Anthropic's sign-in page (`ClaudeArtifactURLDetector.isSignInURL`); the panel banners it as Anthropic's, not AgentHub's, and tells the user to sign in **in the panel**. A browser session is a different cookie jar and never carries over, so that banner must not offer an open-in-browser escape.
 - Detection changes belong in `ClaudeArtifactURLDetector` and need unit tests.
 
+### Studio Panel
+
+Artifacts and design canvases an agent renders during a session (`agenthub_artifact` for one HTML document, `agenthub_design` for N variants of one component on an infinite canvas) open in a dedicated **Studio** side panel, served from AgentHub's own in-process loopback server and annotated with the Canvas inspector overlay. Works for Claude and Codex. Read **`AgentHubStudio.md`** before editing anything named `Studio*`, the `SidePanelContent.studio` case, the three `agenthub_artifact` / `agenthub_design` / `agenthub_list_artifacts` tools, or the `studio_artifacts` table. The short version: the agent renders into a scratch surface, never into the project — Send re-files by id and forbids project edits; Promote… is the only action that asks for code; every variant's CSS is scoped at the tool boundary (`StudioCSSScoper` in `AgentHubCLIKit`), artboards are DOM sections, never iframes, because the inspector bridge is main-frame-only, Tweaks are one shared `props` schema per canvas (CSS custom properties on every artboard), never per variant, and agents are steered to the tools by `StudioAgentGuidance` (system prompt, default-on) plus the bundled `agenthub-studio` skill.
+
 ### Command Palette
 
 `CommandPaletteView` — Cmd+K for quick session/repository/action access.
diff --git a/README.md b/README.md
index 3a45b808..34364a8b 100644
--- a/README.md
+++ b/README.md
@@ -113,6 +113,20 @@ Data sources are whatever the agent can already reach — local files, a CLI, or
 
 See **[`Measurements.md`](Measurements.md)** for the architecture, data flow, key files, invariants, and remaining work.
 
+## Studio
+
+Agents can render things that do not exist in the codebase yet — a report, a mockup, a diagram, or several variants of one component — with the bundled `agenthub_artifact` and `agenthub_design` tools. AgentHub materializes what they send into its own directory, serves it on `127.0.0.1`, and shows it in a dedicated **Studio** side panel that appears on the session card once the project has at least one. Works for Claude and Codex alike.
+
+- **`agenthub_artifact`** renders one self-contained HTML document, verbatim.
+- **`agenthub_design`** lays out N variants of one component side by side on an infinite pan/zoom canvas. Each variant's CSS is scoped to its own artboard (`body`, `:root` variables, `@media`, `@keyframes` all work per variant), so "show me four versions of this button" is a comparison, not a mess. Scripts are stripped; CSS that cannot be scoped is rejected at the tool boundary with a location.
+- **Point, comment, send.** The Canvas inspector overlay lets you click any element, describe a change, and send it to the agent — stamped with the variant it landed on. The prompt asks the agent to re-file with the same id (the panel updates in place) and forbids editing project files.
+- **Tweaks, shared across the canvas.** `agenthub_design` can declare a `props` schema (sliders, colors, selects, toggles, text) that every variant reads as `var(--name)`; the Tweaks panel moves all variants at once, so the same knob is compared across designs. Save defaults writes them back into the canvas; Ideas / Custom go to the agent as re-file requests. Documents get the same panel by calling `dc_set_props`.
+- **Promote…** is the one deliberate step from scratch surface to code: it asks the agent to implement a chosen variant in the real component, sending the original markup and CSS, never the scoped rewrite.
+- **Scoped to the project, not the session**, like measurements — a canvas outlives the conversation that produced it; worktrees roll up to their parent repo. `agenthub_list_artifacts` lets a session refine what is already on screen instead of filing near-duplicates.
+- **Never touches the repo.** Everything lives in Application Support (Settings › Studio shows per-project size and deletes); Export writes an HTML file wherever you choose.
+
+See **[`AgentHubStudio.md`](AgentHubStudio.md)** for the architecture, invariants, and remaining work.
+
 ## Storybook
 
 When AgentHub detects a Storybook configuration in a project, the regular **Preview** button on each session card is replaced by a dedicated **Storybook** button. Clicking it spawns the Storybook dev server (via `npm run storybook`) and opens the web preview pane pinned to the Storybook URL — independently of any other dev server the agent has running.
diff --git a/app/modules/AgentHubCLI/Sources/AgentHubCLI/AgentHubMCPServer.swift b/app/modules/AgentHubCLI/Sources/AgentHubCLI/AgentHubMCPServer.swift
index 7de071e7..f178da6f 100644
--- a/app/modules/AgentHubCLI/Sources/AgentHubCLI/AgentHubMCPServer.swift
+++ b/app/modules/AgentHubCLI/Sources/AgentHubCLI/AgentHubMCPServer.swift
@@ -10,6 +10,8 @@ struct AgentHubMCPServer {
   private let progressQueue = WorktreeProgressQueue()
   private let measurementQueue = MeasurementRecordQueue()
   private let measurementIndex = MeasurementIndexStore()
+  private let studioQueue = StudioArtifactQueue()
+  private let studioIndex = StudioIndexStore()
 
   /// Hard ceiling on any single `tools/call`. Worktree creation normally
   /// completes in seconds and each underlying `git` invocation has its own
@@ -61,16 +63,21 @@ struct AgentHubMCPServer {
 
       case "tools/list":
         guard let id else { return }
+        let schemas: [[String: Any]] = [
+          createWorktreeSessionsToolSchema(),
+          listWorktreesToolSchema(),
+          deleteWorktreeToolSchema(),
+          planningToolSchema(),
+          nameSessionToolSchema(),
+          recordMeasurementToolSchema(),
+          listMeasurementsToolSchema(),
+          artifactToolSchema(),
+          designToolSchema(),
+          listArtifactsToolSchema(),
+          getArtifactToolSchema(),
+        ]
         writeResponse(id: id, result: [
-          "tools": [
-            createWorktreeSessionsToolSchema(),
-            listWorktreesToolSchema(),
-            deleteWorktreeToolSchema(),
-            planningToolSchema(),
-            nameSessionToolSchema(),
-            recordMeasurementToolSchema(),
-            listMeasurementsToolSchema(),
-          ],
+          "tools": schemas.map(Self.annotated),
         ])
 
       case "tools/call":
@@ -174,6 +181,18 @@ struct AgentHubMCPServer {
     case "agenthub_list_measurements":
       return listMeasurements(arguments: arguments)
 
+    case "agenthub_artifact":
+      return try fileArtifact(arguments: arguments)
+
+    case "agenthub_design":
+      return try fileDesign(arguments: arguments)
+
+    case "agenthub_list_artifacts":
+      return listStudioArtifacts(arguments: arguments)
+
+    case "agenthub_get_artifact":
+      return try getStudioArtifact(arguments: arguments)
+
     default:
       throw MCPError.invalidRequest("Unknown AgentHub tool: \(name).")
     }
@@ -326,6 +345,369 @@ struct AgentHubMCPServer {
     )
   }
 
+
+  // MARK: - Studio
+
+  /// Files one HTML document into the session's Studio panel.
+  ///
+  /// The document is served verbatim from AgentHub's own directory — it never
+  /// touches the project. An explicit id re-files an existing artifact in place.
+  private func fileArtifact(arguments: [String: Any]) throws -> [String: Any] {
+    let provider = try studioProvider(toolName: "agenthub_artifact")
+    let title = try studioTitle("title", in: arguments)
+    let html = try requiredString("html", in: arguments)
+
+    let byteCount = html.utf8.count
+    guard byteCount <= StudioArtifact.Limits.maxDocumentBytes else {
+      throw MCPError.invalidRequest(
+        "agenthub_artifact html is \(byteCount) bytes but the limit is \(StudioArtifact.Limits.maxDocumentBytes). Trim embedded assets or split the document."
+      )
+    }
+
+    let artifact = StudioArtifact(
+      id: studioIdentifier(in: arguments),
+      kind: .document,
+      title: title,
+      html: html,
+      sourceProvider: provider,
+      sourceSessionId: ProcessInfo.processInfo.environment["AGENTHUB_SESSION_ID"],
+      sourceProjectPath: ProcessInfo.processInfo.environment["AGENTHUB_PROJECT_PATH"],
+      sourceProcessId: getppid()
+    )
+    try studioQueue.enqueue(artifact)
+
+    return toolResult(
+      text: "AgentHub is rendering \"\(title)\". It appears in this session's Studio panel momentarily. Re-file with id \(artifact.id) to update it in place.",
+      structuredContent: [
+        "queued": true,
+        "id": artifact.id,
+        "kind": StudioArtifactKind.document.rawValue,
+        "title": title,
+      ]
+    )
+  }
+
+  /// Files N variants of one component onto a design canvas.
+  ///
+  /// Every variant is normalized to a fragment and its CSS is checked to scope
+  /// cleanly *here*, at the tool boundary: CSS that cannot be isolated to one
+  /// artboard is a correctable error for the agent, never a canvas that quietly
+  /// restyles its neighbours.
+  private func fileDesign(arguments: [String: Any]) throws -> [String: Any] {
+    let provider = try studioProvider(toolName: "agenthub_design")
+    let component = try studioTitle("component", in: arguments)
+
+    guard let rawVariants = arguments["variants"] as? [[String: Any]], !rawVariants.isEmpty else {
+      throw MCPError.invalidRequest(
+        "agenthub_design needs variants: a non-empty array of { name, html, css?, notes?, width?, height? } objects."
+      )
+    }
+    guard rawVariants.count <= StudioArtifact.Limits.maxVariants else {
+      throw MCPError.invalidRequest(
+        "agenthub_design has \(rawVariants.count) variants but the limit is \(StudioArtifact.Limits.maxVariants). A canvas is a comparison, not a gallery — pick the ones worth comparing."
+      )
+    }
+
+    var variants: [StudioVariant] = []
+    var warnings: [String] = []
+    var seenNames: Set<String> = []
+    for (index, raw) in rawVariants.enumerated() {
+      guard let name = (raw["name"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines),
+            !name.isEmpty
+      else {
+        throw MCPError.invalidRequest("Variant \(index + 1) needs a non-empty name.")
+      }
+      guard name.count <= StudioArtifact.Limits.maxNameLength else {
+        throw MCPError.invalidRequest(
+          "Variant name \"\(name.prefix(20))…\" is longer than \(StudioArtifact.Limits.maxNameLength) characters."
+        )
+      }
+      guard seenNames.insert(name.lowercased()).inserted else {
+        throw MCPError.invalidRequest("Variant names must be unique; \"\(name)\" appears more than once.")
+      }
+      guard let rawHTML = raw["html"] as? String,
+            !rawHTML.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+      else {
+        throw MCPError.invalidRequest("Variant \"\(name)\" needs non-empty html.")
+      }
+
+      let normalized = StudioFragmentNormalizer.normalize(rawHTML)
+      warnings.append(contentsOf: normalized.warnings.map { "\(name): \($0)" })
+
+      let extraCSS = (raw["css"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+      let css = [normalized.css, extraCSS].filter { !$0.isEmpty }.joined(separator: "\n\n")
+
+      let byteCount = normalized.html.utf8.count + css.utf8.count
+      guard byteCount <= StudioArtifact.Limits.maxVariantBytes else {
+        throw MCPError.invalidRequest(
+          "Variant \"\(name)\" is \(byteCount) bytes but the limit is \(StudioArtifact.Limits.maxVariantBytes) per variant."
+        )
+      }
+
+      do {
+        let scoped = try StudioCSSScoper.scope(css, variantName: name)
+        warnings.append(contentsOf: scoped.warnings.map { "\(name): \($0)" })
+      } catch let error as StudioCSSScoper.ParseError {
+        throw MCPError.invalidRequest(
+          "Variant \"\(name)\" CSS did not parse — \(error.reason.lowercased()) at character \(error.offset). Fix the CSS and re-file."
+        )
+      }
+
+      let notes = (raw["notes"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+      if let notes, notes.count > StudioArtifact.Limits.maxNotesLength {
+        throw MCPError.invalidRequest(
+          "Variant \"\(name)\" notes are longer than \(StudioArtifact.Limits.maxNotesLength) characters."
+        )
+      }
+
+      variants.append(StudioVariant(
+        name: name,
+        html: normalized.html,
+        css: css,
+        notes: notes.flatMap { $0.isEmpty ? nil : $0 },
+        width: studioDimension(raw["width"], label: "width", variant: name),
+        height: studioDimension(raw["height"], label: "height", variant: name)
+      ))
+    }
+
+    let props: [StudioTweakProp]
+    do {
+      props = try StudioTweakPropParser.parse(arguments["props"])
+    } catch let error as StudioTweakPropParser.ValidationError {
+      throw MCPError.invalidRequest("agenthub_design props: \(error.message)")
+    }
+    let unused = StudioTweakPropParser.unusedProps(props, variants: variants)
+    guard unused.isEmpty else {
+      throw MCPError.invalidRequest(
+        "agenthub_design props \(unused.map { "\"\($0)\"" }.joined(separator: ", ")) are declared but no variant uses them, so the Tweaks panel would move nothing. Reference each prop from variant CSS as var(--\(unused[0])) (or mark an element data-prop=\"\(unused[0])\" for text/select), or drop the prop."
+      )
+    }
+
+    let artifact = StudioArtifact(
+      id: studioIdentifier(in: arguments),
+      kind: .canvas,
+      title: component,
+      sourcePath: optionalString("sourcePath", in: arguments).flatMap { $0.isEmpty ? nil : $0 },
+      variants: variants,
+      props: props,
+      warnings: warnings,
+      sourceProvider: provider,
+      sourceSessionId: ProcessInfo.processInfo.environment["AGENTHUB_SESSION_ID"],
+      sourceProjectPath: ProcessInfo.processInfo.environment["AGENTHUB_PROJECT_PATH"],
+      sourceProcessId: getppid()
+    )
+    try studioQueue.enqueue(artifact)
+
+    var text = "AgentHub is laying out \(variants.count) variant(s) of \"\(component)\" on the design canvas. It appears in this session's Studio panel momentarily. Re-file with id \(artifact.id) to update the canvas in place."
+    if !props.isEmpty {
+      text += " \(props.count) tweakable prop(s) are exposed to every variant as CSS custom properties: " + props.map { "var(\($0.cssVariableName))" }.joined(separator: ", ") + "."
+    }
+    if !warnings.isEmpty {
+      text += "\n\nWarnings:\n" + warnings.map { "• \($0)" }.joined(separator: "\n")
+    }
+
+    return toolResult(
+      text: text,
+      structuredContent: [
+        "queued": true,
+        "id": artifact.id,
+        "kind": StudioArtifactKind.canvas.rawValue,
+        "component": component,
+        "variants": variants.map(\.name),
+        "props": props.map(\.name),
+        "warnings": warnings,
+      ]
+    )
+  }
+
+  /// Lists the Studio artifacts already filed for this project.
+  ///
+  /// Without this an agent asked to "make the ghost button bolder" has no way
+  /// to learn the canvas's id, so it files a second canvas beside the first
+  /// instead of refining the one the user is looking at.
+  private func listStudioArtifacts(arguments: [String: Any]) -> [String: Any] {
+    let projectPath = optionalString("projectPath", in: arguments)
+      ?? ProcessInfo.processInfo.environment["AGENTHUB_PROJECT_PATH"]
+      ?? FileManager.default.currentDirectoryPath
+
+    guard let index = studioIndex.read(projectPath: projectPath), !index.artifacts.isEmpty else {
+      return toolResult(
+        text: "No Studio artifacts filed for this project yet.",
+        structuredContent: ["projectPath": projectPath, "artifacts": []]
+      )
+    }
+
+    let formatter = ISO8601DateFormatter()
+    let entries = index.artifacts.map { entry -> [String: Any] in
+      var object: [String: Any] = [
+        "id": entry.id,
+        "kind": entry.kind.rawValue,
+        "title": entry.title,
+        "revision": entry.revision,
+        "updatedAt": formatter.string(from: entry.updatedAt),
+      ]
+      if !entry.variantNames.isEmpty { object["variants"] = entry.variantNames }
+      if let sourcePath = entry.sourcePath { object["sourcePath"] = sourcePath }
+      if let documentPath = entry.documentPath { object["documentPath"] = documentPath }
+      return object
+    }
+
+    let summary = index.artifacts
+      .map { entry in
+        let detail = entry.kind == .canvas
+          ? "canvas: \(entry.variantNames.joined(separator: ", "))"
+          : "document"
+        return "• \(entry.title) — \(detail) (rev \(entry.revision), id \(entry.id))"
+      }
+      .joined(separator: "\n")
+
+    return toolResult(
+      text: summary,
+      structuredContent: ["projectPath": index.projectPath, "artifacts": entries]
+    )
+  }
+
+
+  /// Returns the current payload of one Studio artifact — the variants as they
+  /// are *now*, including edits the user baked in from the panel.
+  ///
+  /// This is what makes "let's go with the ghost one" work from the chat: the
+  /// agent fetches the variant the user means and implements exactly what they
+  /// see, rather than the version it originally filed. Reads the sidecar the
+  /// app writes beside the served document; never the app's database.
+  private func getStudioArtifact(arguments: [String: Any]) throws -> [String: Any] {
+    let id = try requiredString("id", in: arguments)
+    let projectPath = optionalString("projectPath", in: arguments)
+      ?? ProcessInfo.processInfo.environment["AGENTHUB_PROJECT_PATH"]
+      ?? FileManager.default.currentDirectoryPath
+    let variantFilter = optionalString("variant", in: arguments).flatMap { $0.isEmpty ? nil : $0 }
+    let includeContent = (arguments["includeContent"] as? Bool) ?? false
+
+    guard let index = studioIndex.read(projectPath: projectPath),
+          let entry = index.artifacts.first(where: { $0.id == id })
+    else {
+      throw MCPError.invalidRequest(
+        "No Studio artifact with id \(id) in this project. Call agenthub_list_artifacts to see what exists."
+      )
+    }
+    guard let payloadPath = entry.payloadPath,
+          let data = FileManager.default.contents(atPath: payloadPath)
+    else {
+      throw MCPError.invalidRequest(
+        "The payload for artifact \(id) is not available yet; open it in the Studio panel once, or re-file it."
+      )
+    }
+    let decoder = JSONDecoder()
+    decoder.dateDecodingStrategy = .iso8601
+    let artifact = try decoder.decode(StudioArtifact.self, from: data)
+
+    if let variantFilter, artifact.kind == .canvas,
+       !artifact.variants.contains(where: { $0.name.caseInsensitiveCompare(variantFilter) == .orderedSame })
+    {
+      throw MCPError.invalidRequest(
+        "Canvas \(id) has no variant named \"\(variantFilter)\". Variants: \(artifact.variantNames.joined(separator: ", "))."
+      )
+    }
+
+    var structured: [String: Any] = [
+      "id": artifact.id,
+      "kind": artifact.kind.rawValue,
+      "title": artifact.title,
+      "revision": artifact.revision,
+      "updatedAt": ISO8601DateFormatter().string(from: artifact.displayDate),
+    ]
+    if let sourcePath = artifact.sourcePath { structured["sourcePath"] = sourcePath }
+    if !artifact.props.isEmpty {
+      structured["props"] = artifact.props.map { prop -> [String: Any] in
+        var object = prop.declaration
+        object["name"] = prop.name
+        object["cssVariable"] = prop.cssVariableName
+        return object
+      }
+    }
+
+    var summaryLines: [String] = ["\(artifact.title) (\(artifact.kind.rawValue), rev \(artifact.revision), id \(artifact.id))"]
+    switch artifact.kind {
+    case .canvas:
+      structured["variants"] = artifact.variants.map { variant -> [String: Any] in
+        let selected = variantFilter.map { $0.caseInsensitiveCompare(variant.name) == .orderedSame } ?? false
+        var object: [String: Any] = [
+          "name": variant.name,
+          "htmlBytes": variant.html.utf8.count,
+          "cssBytes": variant.css.utf8.count,
+        ]
+        if let notes = variant.notes { object["notes"] = notes }
+        if selected || includeContent {
+          object["html"] = variant.html
+          object["css"] = variant.css
+        }
+        return object
+      }
+      for variant in artifact.variants {
+        let selected = variantFilter.map { $0.caseInsensitiveCompare(variant.name) == .orderedSame } ?? false
+        var line = "• \(variant.name)"
+        if let notes = variant.notes { line += " — \(notes)" }
+        if selected || includeContent {
+          line += "\n  html:\n\(variant.html)\n  css:\n\(variant.css)"
+        }
+        summaryLines.append(line)
+      }
+      if variantFilter == nil, !includeContent {
+        summaryLines.append("Pass variant=<name> for one variant's html/css, or includeContent=true for all. The markup includes any edits the user made in the Studio panel.")
+      }
+    case .document:
+      if includeContent, let html = artifact.html {
+        structured["html"] = html
+        summaryLines.append(html)
+      } else {
+        structured["htmlBytes"] = artifact.html?.utf8.count ?? 0
+        summaryLines.append("Pass includeContent=true for the document HTML.")
+      }
+    }
+
+    return toolResult(text: summaryLines.joined(separator: "\n"), structuredContent: structured)
+  }
+
+  private func studioProvider(toolName: String) throws -> WorktreeLaunchProvider {
+    guard let provider = ProcessInfo.processInfo.environment["AGENTHUB_PROVIDER"]
+      .flatMap(WorktreeLaunchProvider.init(commandLineValue:))
+    else {
+      throw MCPError.invalidRequest(
+        "\(toolName) is only available inside an AgentHub-managed Claude or Codex session."
+      )
+    }
+    return provider
+  }
+
+  private func studioTitle(_ key: String, in arguments: [String: Any]) throws -> String {
+    let value = try requiredString(key, in: arguments)
+    guard value.count <= StudioArtifact.Limits.maxTitleLength else {
+      throw MCPError.invalidRequest("\(key) is longer than \(StudioArtifact.Limits.maxTitleLength) characters.")
+    }
+    return value
+  }
+
+  /// An explicit id means this is a re-file of an artifact that already exists:
+  /// the app upserts on id, so the item refreshes in place instead of a
+  /// near-duplicate piling up beside it.
+  private func studioIdentifier(in arguments: [String: Any]) -> String {
+    optionalString("id", in: arguments).flatMap { $0.isEmpty ? nil : $0 } ?? UUID().uuidString
+  }
+
+  private func studioDimension(_ raw: Any?, label: String, variant: String) -> Double? {
+    guard let raw, !(raw is NSNull) else { return nil }
+    let value: Double?
+    if let number = raw as? NSNumber {
+      value = number.doubleValue
+    } else if let string = raw as? String {
+      value = Double(string.trimmingCharacters(in: .whitespacesAndNewlines))
+    } else {
+      value = nil
+    }
+    guard let value, value > 0, value.isFinite else { return nil }
+    return value
+  }
+
   private func parseMeasurementChart(_ raw: Any?) throws -> MeasurementChart? {
     guard let raw, !(raw is NSNull) else { return nil }
     guard let object = raw as? [String: Any] else {
@@ -1214,6 +1596,225 @@ struct AgentHubMCPServer {
     ]
   }
 
+
+  private func artifactToolSchema() -> [String: Any] {
+    [
+      "name": "agenthub_artifact",
+      "description": """
+        Use when the user wants to SEE something rendered rather than read code — "render this \
+        report", "mock up the landing page", "draw the flow", "show me a dashboard", "what would \
+        the onboarding screen look like" — and it is one page rather than side-by-side variants. \
+        Renders a self-contained HTML document in AgentHub's Studio panel beside this session. \
+        AgentHub serves the document from its own directory on localhost; nothing is written into \
+        the project, so this is the right tool for visual answers that must not touch the codebase. The user can point at any element in the rendered page, \
+        comment on it, and send that feedback back to you. Call agenthub_list_artifacts first \
+        and pass an existing id when you are refining something already on screen, so the \
+        panel updates in place instead of stacking a near-duplicate. Provide a complete document \
+        (inline CSS and JS; remote assets are allowed but not fetched by AgentHub). To make the \
+        document tweakable, call `window.dc_set_props({ name: { type: slider|color|select|toggle|text, \
+        value, label?, min?, max?, step?, options? } })` at load and read `window.props.<name>` (or \
+        implement `window.dc_on_props_changed(props)`) — AgentHub shows a Tweaks panel with live \
+        controls, and saving new defaults rewrites the values in your dc_set_props call. Guard the \
+        call with `if (window.dc_set_props)` so the page also works in a plain browser. For \
+        side-by-side variants of one component, use agenthub_design instead.
+        """,
+      "inputSchema": [
+        "type": "object",
+        "properties": [
+          "title": [
+            "type": "string",
+            "description": "Short name for the artifact, shown in the panel header (≤120 chars).",
+          ],
+          "html": [
+            "type": "string",
+            "description": "The full HTML document. Served verbatim. Limit \(StudioArtifact.Limits.maxDocumentBytes) bytes.",
+          ],
+          "id": [
+            "type": "string",
+            "description": "Pass the id of an existing artifact (from agenthub_list_artifacts or an earlier result) to replace it in place. Omit for a new artifact.",
+          ],
+        ],
+        "required": ["title", "html"],
+        "additionalProperties": false,
+      ],
+    ]
+  }
+
+  private func designToolSchema() -> [String: Any] {
+    [
+      "name": "agenthub_design",
+      "description": """
+        Use whenever the user asks to see, compare, mock up, or explore OPTIONS, VERSIONS, or \
+        VARIANTS of any UI — "show me 4 versions of this button", "give me a few directions for \
+        the card", "compare dense vs airy", "what would the CTA look like as outline vs filled" — \
+        instead of editing project files. Lays the variants out side by side on an infinite design \
+        canvas in AgentHub's Studio panel, without touching the project: the canvas is a scratch \
+        surface for deciding before anything is implemented. Each variant is an HTML fragment plus its CSS; AgentHub isolates each \
+        variant's CSS to its own artboard, so write ordinary selectors (`.btn`, `body`, `:root` \
+        custom properties all work per variant). Scripts are stripped: variants share one \
+        document, so use CSS for hover/focus states and agenthub_artifact for anything that needs \
+        JS. Optionally declare `props` — one shared tweak schema for the whole canvas (sliders, \
+        colors, selects, toggles, text). Each prop is exposed to every variant as the CSS custom \
+        property `--<name>` (write `var(--radius)` in variant CSS; slider values carry their `unit`), \
+        and text/select values are also written into elements marked `data-prop="<name>"`. The user \
+        moves the controls in AgentHub's Tweaks panel and every variant updates live, so the same \
+        knob can be compared across variants; when they save new defaults, AgentHub updates the \
+        canvas itself. The user can click any element on any variant, comment, and send that back \
+        to you stamped with the variant name; re-file with the same id to update the canvas in place. \
+        Call agenthub_list_artifacts first when refining an existing canvas. Do not edit project \
+        files in response to canvas feedback unless the user explicitly asks you to implement a \
+        variant.
+        """,
+      "inputSchema": [
+        "type": "object",
+        "properties": [
+          "component": [
+            "type": "string",
+            "description": "What is being explored, e.g. \"Primary button\" (≤120 chars). Shown as the canvas title.",
+          ],
+          "variants": [
+            "type": "array",
+            "description": "1–\(StudioArtifact.Limits.maxVariants) variants, each rendered on its own artboard.",
+            "items": [
+              "type": "object",
+              "properties": [
+                "name": ["type": "string", "description": "Short unique label, e.g. \"ghost\" (≤40 chars)."],
+                "html": ["type": "string", "description": "The variant's markup. A fragment; document wrappers and <script> are stripped, <style> is hoisted."],
+                "css": ["type": "string", "description": "Optional CSS for this variant (in addition to any <style> in html). Ordinary selectors; AgentHub scopes them."],
+                "notes": ["type": "string", "description": "Optional one-line rationale shown under the artboard (≤500 chars)."],
+                "width": ["type": "number", "description": "Optional fixed artboard width in CSS px. Defaults to content width."],
+                "height": ["type": "number", "description": "Optional fixed artboard height in CSS px. Defaults to content height."],
+              ],
+              "required": ["name", "html"],
+              "additionalProperties": false,
+            ],
+          ],
+          "props": [
+            "type": "object",
+            "description": "Optional shared tweak schema, keyed by prop name (a CSS-identifier-safe name, ≤40 chars; up to \(StudioTweakPropParser.maxProps) props). Each value is { type: slider|color|select|toggle|text, value, label?, min?, max?, step?, unit?, options? }. Every prop becomes `--<name>` on every artboard; write variant CSS against var(--<name>). Example: { \"radius\": { \"type\": \"slider\", \"value\": 12, \"min\": 0, \"max\": 32, \"unit\": \"px\" }, \"accent\": { \"type\": \"color\", \"value\": \"#0a84ff\" }, \"label\": { \"type\": \"text\", \"value\": \"Continue\" } }.",
+            "additionalProperties": true,
+          ],
+          "sourcePath": [
+            "type": "string",
+            "description": "Optional project-relative path of the real component these variants explore (e.g. src/components/Button.tsx). Only used to name the file if the user later asks to implement a variant.",
+          ],
+          "id": [
+            "type": "string",
+            "description": "Pass the id of an existing canvas to replace its variants in place. Omit for a new canvas.",
+          ],
+        ],
+        "required": ["component", "variants"],
+        "additionalProperties": false,
+      ],
+    ]
+  }
+
+  private func listArtifactsToolSchema() -> [String: Any] {
+    [
+      "name": "agenthub_list_artifacts",
+      "description": """
+        Lists the Studio artifacts and design canvases already filed for this project in AgentHub, \
+        with each one's id, kind, title, variant names, and revision. Call this before \
+        agenthub_artifact or agenthub_design when the user is refining something already on \
+        screen — match their words against the titles and re-file with that id — and whenever \
+        they ask what has been rendered or designed so far. Artifacts are shared across every \
+        session in the project, Claude and Codex alike.
+        """,
+      "inputSchema": [
+        "type": "object",
+        "properties": [
+          "projectPath": [
+            "type": "string",
+            "description": "Project to list artifacts for. Defaults to the current AgentHub session's project.",
+          ],
+        ],
+        "additionalProperties": false,
+      ],
+    ]
+  }
+
+
+  private func getArtifactToolSchema() -> [String: Any] {
+    [
+      "name": "agenthub_get_artifact",
+      "description": """
+        Fetches the current content of one Studio artifact or design canvas by id — the variants \
+        as they are right now, including edits the user made in the panel (inline styles, text, \
+        removed elements) and saved tweak defaults. Use this when the user picks a variant in \
+        conversation ("let's go with the ghost one", "use the second option", "implement that \
+        card") — call it with variant=<name>, then implement exactly that html/css in the real \
+        component, preserving behaviour and API. Also call it before re-filing an existing canvas \
+        so you start from what the user has, not from what you originally filed. Get ids and \
+        variant names from agenthub_list_artifacts.
+        """,
+      "inputSchema": [
+        "type": "object",
+        "properties": [
+          "id": [
+            "type": "string",
+            "description": "The artifact id (from agenthub_list_artifacts or an earlier agenthub_design / agenthub_artifact result).",
+          ],
+          "variant": [
+            "type": "string",
+            "description": "For a canvas: return this variant's html and css. Case-insensitive.",
+          ],
+          "includeContent": [
+            "type": "boolean",
+            "description": "Return the html/css of every variant (or the whole document). Default false: metadata and notes only.",
+          ],
+          "projectPath": [
+            "type": "string",
+            "description": "Project the artifact belongs to. Defaults to the current AgentHub session's project.",
+          ],
+        ],
+        "required": ["id"],
+        "additionalProperties": false,
+      ],
+    ]
+  }
+
+
+  // MARK: - Tool annotations
+
+  /// MCP tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
+  /// `openWorldHint`) for every tool. Hosts use them to decide how much to
+  /// ask: Codex's `writes` approval mode, for one, "prompts for tools that
+  /// aren't marked read-only" — so the read-only tools must say so, or a
+  /// user on that mode is prompted just to list what exists. All tools are
+  /// local (`openWorldHint: false`); only worktree deletion is destructive.
+  static let toolAnnotationsByName: [String: [String: Any]] = [
+    "agenthub_create_worktree_sessions": annotations(readOnly: false, destructive: false, idempotent: false),
+    "agenthub_list_worktrees": annotations(readOnly: true, destructive: false, idempotent: true),
+    "agenthub_delete_worktree": annotations(readOnly: false, destructive: true, idempotent: true),
+    "agent_hub_planning": annotations(readOnly: true, destructive: false, idempotent: true),
+    "agenthub_name_session": annotations(readOnly: false, destructive: false, idempotent: true),
+    "agenthub_record_measurement": annotations(readOnly: false, destructive: false, idempotent: true),
+    "agenthub_list_measurements": annotations(readOnly: true, destructive: false, idempotent: true),
+    "agenthub_artifact": annotations(readOnly: false, destructive: false, idempotent: true),
+    "agenthub_design": annotations(readOnly: false, destructive: false, idempotent: true),
+    "agenthub_list_artifacts": annotations(readOnly: true, destructive: false, idempotent: true),
+    "agenthub_get_artifact": annotations(readOnly: true, destructive: false, idempotent: true),
+  ]
+
+  private static func annotations(readOnly: Bool, destructive: Bool, idempotent: Bool) -> [String: Any] {
+    [
+      "readOnlyHint": readOnly,
+      "destructiveHint": destructive,
+      "idempotentHint": idempotent,
+      "openWorldHint": false,
+    ]
+  }
+
+  /// Attaches the annotations for a schema's tool name; unknown names pass through.
+  static func annotated(_ schema: [String: Any]) -> [String: Any] {
+    guard let name = schema["name"] as? String, let annotations = toolAnnotationsByName[name] else {
+      return schema
+    }
+    var annotatedSchema = schema
+    annotatedSchema["annotations"] = annotations
+    return annotatedSchema
+  }
+
   private func writeResponse(id: Any, result: [String: Any]) {
     writeJSON([
       "jsonrpc": "2.0",
diff --git a/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioArtifactModels.swift b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioArtifactModels.swift
new file mode 100644
index 00000000..81c61b90
--- /dev/null
+++ b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioArtifactModels.swift
@@ -0,0 +1,266 @@
+import Foundation
+
+/// What kind of surface a Studio artifact renders on.
+public enum StudioArtifactKind: String, Codable, Equatable, Sendable {
+  /// One self-contained HTML document, served verbatim (`agenthub_artifact`).
+  case document
+  /// N fragments of one component laid out on an infinite canvas (`agenthub_design`).
+  case canvas
+}
+
+/// One variant on a design canvas.
+///
+/// `html` and `css` are stored *normalized* — the fragment the agent sent with
+/// document wrappers and scripts stripped and its `<style>` blocks hoisted into
+/// `css` — but never *scoped*: scoping is an artefact of sharing one document,
+/// applied at write time. Promotion sends these fields, so they must stay the
+/// agent's own markup.
+public struct StudioVariant: Codable, Equatable, Sendable {
+  public let name: String
+  public let html: String
+  public let css: String
+  public let notes: String?
+  public let width: Double?
+  public let height: Double?
+
+  public init(
+    name: String,
+    html: String,
+    css: String = "",
+    notes: String? = nil,
+    width: Double? = nil,
+    height: Double? = nil
+  ) {
+    self.name = name
+    self.html = html
+    self.css = css
+    self.notes = notes
+    self.width = width
+    self.height = height
+  }
+}
+
+/// A single artifact an agent filed into the Studio panel — the unit the panel renders.
+///
+/// The agent renders into a scratch surface, never into the project: nothing in
+/// this record points at, or is written to, the user's repository.
+public struct StudioArtifact: Codable, Equatable, Identifiable, Sendable {
+  /// Caps on how much a single artifact may carry.
+  ///
+  /// These are guardrails: the artifact is persisted and served from disk, so an
+  /// agent that dumps a 40 MB report would bloat the store and stall the panel.
+  /// Exceeding a cap is a tool-level validation error the agent can see and
+  /// correct — never a silent truncation, which would make a canvas misrepresent
+  /// its own variant count.
+  public enum Limits {
+    public static let maxDocumentBytes = 1_500_000
+    public static let maxVariants = 12
+    public static let maxVariantBytes = 262_144
+    public static let maxTitleLength = 120
+    public static let maxNameLength = 40
+    public static let maxNotesLength = 500
+  }
+
+  public let id: String
+  public let kind: StudioArtifactKind
+  /// When this artifact was first filed. Preserved across re-files so a refreshed
+  /// item keeps its place in the panel instead of jumping to the top.
+  public let createdAt: Date
+  /// When the content was last replaced. `nil` for an artifact never re-filed.
+  public let updatedAt: Date?
+  /// Bumped on every re-file. Not a history — the document is overwritten in
+  /// place — but the signal an open panel reloads on.
+  public let revision: Int
+  /// Document title, or the component name for a canvas.
+  public let title: String
+  /// The real component the variants explore (e.g. `src/components/Button.tsx`).
+  /// Used only by Promote so the prompt can name the file; AgentHub never reads
+  /// or writes it.
+  public let sourcePath: String?
+  /// The document, for `.document`. Served verbatim.
+  public let html: String?
+  /// The variants, for `.canvas`.
+  public let variants: [StudioVariant]
+  /// The canvas's shared tweak schema (`.canvas` only). One schema for every
+  /// variant, exposed as CSS custom properties — see `StudioTweakProp`.
+  public let props: [StudioTweakProp]
+  /// What normalization dropped (an `@import`, an external stylesheet). Surfaced
+  /// to the agent in the tool result and kept here so the panel can show them.
+  public let warnings: [String]
+
+  /// The branch the filing session was on, stamped by the app.
+  public let branchName: String?
+
+  public let sourceProvider: WorktreeLaunchProvider
+  public let sourceSessionId: String?
+  public let sourceProjectPath: String?
+  public let sourceProcessId: Int32
+
+  public init(
+    id: String,
+    kind: StudioArtifactKind,
+    createdAt: Date = Date(),
+    updatedAt: Date? = nil,
+    revision: Int = 1,
+    title: String,
+    sourcePath: String? = nil,
+    html: String? = nil,
+    variants: [StudioVariant] = [],
+    props: [StudioTweakProp] = [],
+    warnings: [String] = [],
+    branchName: String? = nil,
+    sourceProvider: WorktreeLaunchProvider,
+    sourceSessionId: String?,
+    sourceProjectPath: String?,
+    sourceProcessId: Int32
+  ) {
+    self.id = id
+    self.kind = kind
+    self.createdAt = createdAt
+    self.updatedAt = updatedAt
+    self.revision = revision
+    self.title = title
+    self.sourcePath = sourcePath
+    self.html = html
+    self.variants = variants
+    self.props = props
+    self.warnings = warnings
+    self.branchName = branchName
+    self.sourceProvider = sourceProvider
+    self.sourceSessionId = sourceSessionId
+    self.sourceProjectPath = sourceProjectPath
+    self.sourceProcessId = sourceProcessId
+  }
+
+  /// The timestamp to show: when the content was last replaced.
+  public var displayDate: Date {
+    updatedAt ?? createdAt
+  }
+
+  public var variantNames: [String] {
+    variants.map(\.name)
+  }
+
+  /// Re-anchors an incoming re-file onto the artifact it replaces.
+  ///
+  /// The original filing date is kept (so the refreshed item holds its place),
+  /// the incoming timestamp becomes the update time, and the revision advances
+  /// so an open panel knows to reload.
+  public func replacing(_ previous: StudioArtifact) -> StudioArtifact {
+    StudioArtifact(
+      id: previous.id,
+      kind: kind,
+      createdAt: previous.createdAt,
+      updatedAt: createdAt,
+      revision: previous.revision + 1,
+      title: title,
+      sourcePath: sourcePath ?? previous.sourcePath,
+      html: html,
+      variants: variants,
+      props: props,
+      warnings: warnings,
+      branchName: branchName,
+      sourceProvider: sourceProvider,
+      sourceSessionId: sourceSessionId,
+      sourceProjectPath: sourceProjectPath,
+      sourceProcessId: sourceProcessId
+    )
+  }
+
+  /// Records which branch filed the current content. Stamped by the app, which
+  /// already knows the session's branch.
+  public func stamped(branchName: String?) -> StudioArtifact {
+    StudioArtifact(
+      id: id,
+      kind: kind,
+      createdAt: createdAt,
+      updatedAt: updatedAt,
+      revision: revision,
+      title: title,
+      sourcePath: sourcePath,
+      html: html,
+      variants: variants,
+      props: props,
+      warnings: warnings,
+      branchName: branchName,
+      sourceProvider: sourceProvider,
+      sourceSessionId: sourceSessionId,
+      sourceProjectPath: sourceProjectPath,
+      sourceProcessId: sourceProcessId
+    )
+  }
+
+  /// The artifact with replaced content (html and/or props), keeping identity
+  /// and provenance — what Save-defaults uses before re-storing.
+  public func withContent(html: String? = nil, props: [StudioTweakProp]? = nil) -> StudioArtifact {
+    StudioArtifact(
+      id: id,
+      kind: kind,
+      createdAt: createdAt,
+      updatedAt: updatedAt,
+      revision: revision,
+      title: title,
+      sourcePath: sourcePath,
+      html: html ?? self.html,
+      variants: variants,
+      props: props ?? self.props,
+      warnings: warnings,
+      branchName: branchName,
+      sourceProvider: sourceProvider,
+      sourceSessionId: sourceSessionId,
+      sourceProjectPath: sourceProjectPath,
+      sourceProcessId: sourceProcessId
+    )
+  }
+
+  /// The artifact with a replaced variant set (edits baked in from the panel).
+  public func withVariants(_ newVariants: [StudioVariant]) -> StudioArtifact {
+    StudioArtifact(
+      id: id,
+      kind: kind,
+      createdAt: createdAt,
+      updatedAt: updatedAt,
+      revision: revision,
+      title: title,
+      sourcePath: sourcePath,
+      html: html,
+      variants: newVariants,
+      props: props,
+      warnings: warnings,
+      branchName: branchName,
+      sourceProvider: sourceProvider,
+      sourceSessionId: sourceSessionId,
+      sourceProjectPath: sourceProjectPath,
+      sourceProcessId: sourceProcessId
+    )
+  }
+
+  // MARK: Codable
+
+  private enum CodingKeys: String, CodingKey {
+    case id, kind, createdAt, updatedAt, revision, title, sourcePath, html, variants, props, warnings
+    case branchName, sourceProvider, sourceSessionId, sourceProjectPath, sourceProcessId
+  }
+
+  /// `props` is optional on the wire so payloads written before it existed
+  /// still decode.
+  public init(from decoder: Decoder) throws {
+    let c = try decoder.container(keyedBy: CodingKeys.self)
+    id = try c.decode(String.self, forKey: .id)
+    kind = try c.decode(StudioArtifactKind.self, forKey: .kind)
+    createdAt = try c.decode(Date.self, forKey: .createdAt)
+    updatedAt = try c.decodeIfPresent(Date.self, forKey: .updatedAt)
+    revision = try c.decodeIfPresent(Int.self, forKey: .revision) ?? 1
+    title = try c.decode(String.self, forKey: .title)
+    sourcePath = try c.decodeIfPresent(String.self, forKey: .sourcePath)
+    html = try c.decodeIfPresent(String.self, forKey: .html)
+    variants = try c.decodeIfPresent([StudioVariant].self, forKey: .variants) ?? []
+    props = try c.decodeIfPresent([StudioTweakProp].self, forKey: .props) ?? []
+    warnings = try c.decodeIfPresent([String].self, forKey: .warnings) ?? []
+    branchName = try c.decodeIfPresent(String.self, forKey: .branchName)
+    sourceProvider = try c.decode(WorktreeLaunchProvider.self, forKey: .sourceProvider)
+    sourceSessionId = try c.decodeIfPresent(String.self, forKey: .sourceSessionId)
+    sourceProjectPath = try c.decodeIfPresent(String.self, forKey: .sourceProjectPath)
+    sourceProcessId = try c.decode(Int32.self, forKey: .sourceProcessId)
+  }
+}
diff --git a/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioArtifactQueue.swift b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioArtifactQueue.swift
new file mode 100644
index 00000000..16df83dd
--- /dev/null
+++ b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioArtifactQueue.swift
@@ -0,0 +1,117 @@
+import Foundation
+
+public struct QueuedStudioArtifact: Equatable, Sendable {
+  public let artifact: StudioArtifact
+  public let fileURL: URL
+
+  public init(artifact: StudioArtifact, fileURL: URL) {
+    self.artifact = artifact
+    self.fileURL = fileURL
+  }
+}
+
+/// File-backed handoff from the `agenthub` CLI's MCP server to the app.
+///
+/// The CLI runs as a separate process, so it cannot write the app's SQLite store
+/// or its document directory directly; it drops a JSON file here and the app
+/// drains it (same shape as `MeasurementRecordQueue`). Writes are atomic-then-move
+/// so the app never reads a half-written artifact.
+public struct StudioArtifactQueue: Sendable {
+  public let directoryURL: URL
+
+  public init(directoryURL: URL = StudioArtifactQueue.defaultDirectoryURL()) {
+    self.directoryURL = directoryURL
+  }
+
+  public static func defaultDirectoryURL(fileManager: FileManager = .default) -> URL {
+    StudioSupportDirectory.baseURL(fileManager: fileManager)
+      .appendingPathComponent("studio-records", isDirectory: true)
+  }
+
+  @discardableResult
+  public func enqueue(_ artifact: StudioArtifact) throws -> QueuedStudioArtifact {
+    try FileManager.default.createDirectory(at: directoryURL, withIntermediateDirectories: true)
+
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+    encoder.dateEncodingStrategy = .iso8601
+    let data = try encoder.encode(artifact)
+
+    let finalURL = directoryURL.appendingPathComponent("\(artifact.id).json", isDirectory: false)
+    let temporaryURL = directoryURL.appendingPathComponent(".\(artifact.id).tmp", isDirectory: false)
+
+    try data.write(to: temporaryURL, options: [.atomic])
+    if FileManager.default.fileExists(atPath: finalURL.path) {
+      try FileManager.default.removeItem(at: finalURL)
+    }
+    try FileManager.default.moveItem(at: temporaryURL, to: finalURL)
+
+    return QueuedStudioArtifact(artifact: artifact, fileURL: finalURL)
+  }
+
+  public func pendingArtifacts() throws -> [QueuedStudioArtifact] {
+    guard FileManager.default.fileExists(atPath: directoryURL.path) else {
+      return []
+    }
+
+    let files = try FileManager.default.contentsOfDirectory(
+      at: directoryURL,
+      includingPropertiesForKeys: nil
+    )
+
+    let decoder = JSONDecoder()
+    decoder.dateDecodingStrategy = .iso8601
+    return files
+      .filter { $0.pathExtension == "json" && !$0.lastPathComponent.hasPrefix(".") }
+      .compactMap { url in
+        guard let data = try? Data(contentsOf: url),
+              let artifact = try? decoder.decode(StudioArtifact.self, from: data)
+        else {
+          return nil
+        }
+        return QueuedStudioArtifact(artifact: artifact, fileURL: url)
+      }
+      .sorted {
+        if $0.artifact.createdAt == $1.artifact.createdAt {
+          return $0.artifact.id < $1.artifact.id
+        }
+        return $0.artifact.createdAt < $1.artifact.createdAt
+      }
+  }
+
+  public func remove(_ queued: QueuedStudioArtifact) throws {
+    guard FileManager.default.fileExists(atPath: queued.fileURL.path) else { return }
+    try FileManager.default.removeItem(at: queued.fileURL)
+  }
+
+  public func markFailed(_ queued: QueuedStudioArtifact) throws {
+    guard FileManager.default.fileExists(atPath: queued.fileURL.path) else { return }
+    let failedURL = queued.fileURL
+      .deletingPathExtension()
+      .appendingPathExtension("failed")
+    if FileManager.default.fileExists(atPath: failedURL.path) {
+      try FileManager.default.removeItem(at: failedURL)
+    }
+    try FileManager.default.moveItem(at: queued.fileURL, to: failedURL)
+  }
+}
+
+/// Where Studio's CLI↔app files live.
+///
+/// Honors `AGENTHUB_APP_SUPPORT_DIR` so a sandboxed app (tests, or an explicit
+/// redirect) and the CLI it launches agree on one directory; otherwise the real
+/// Application Support folder, same as every other queue in this kit.
+public enum StudioSupportDirectory {
+  public static func baseURL(fileManager: FileManager = .default) -> URL {
+    if let override = ProcessInfo.processInfo.environment["AGENTHUB_APP_SUPPORT_DIR"],
+       !override.isEmpty
+    {
+      return URL(fileURLWithPath: (override as NSString).expandingTildeInPath, isDirectory: true)
+    }
+    let appSupportURL = fileManager.urls(
+      for: .applicationSupportDirectory,
+      in: .userDomainMask
+    ).first ?? URL(fileURLWithPath: NSHomeDirectory()).appendingPathComponent("Library/Application Support")
+    return appSupportURL.appendingPathComponent("AgentHub", isDirectory: true)
+  }
+}
diff --git a/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioCSSScoper.swift b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioCSSScoper.swift
new file mode 100644
index 00000000..7ea6de13
--- /dev/null
+++ b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioCSSScoper.swift
@@ -0,0 +1,470 @@
+import Foundation
+
+/// Rewrites one variant's CSS so it applies only inside that variant's artboard.
+///
+/// A design canvas puts every variant in one document (the inspector bridge is
+/// main-frame-only, so iframes are out), which means AgentHub owns CSS
+/// isolation. `@scope` would be the clean answer but is unavailable on the
+/// macOS 14 floor, so each rule is prefixed with the artboard selector instead.
+///
+/// Lives in the CLI kit rather than the app so the tool boundary and the
+/// document writer share one implementation: CSS that cannot be scoped is
+/// rejected when the agent files it, never rendered as a canvas that quietly
+/// restyles its neighbours.
+///
+/// | Construct | Rewrite |
+/// |---|---|
+/// | `a, .b > c {…}` | `S a, S .b > c {…}` |
+/// | leading `:root`, `html`, `body` | replaced by `S` |
+/// | `@media`, `@supports`, `@container`, `@layer {}`, `@document` | kept; inner rules scoped |
+/// | `@keyframes name` | renamed `name-{slug}`; `animation`/`animation-name` rewritten |
+/// | `@font-face`, `@page`, `@property`, other block at-rules | kept verbatim |
+/// | `@import` | dropped with a warning |
+/// | unbalanced braces | `ParseError` |
+public enum StudioCSSScoper {
+  public struct Output: Equatable, Sendable {
+    public let css: String
+    public let warnings: [String]
+
+    public init(css: String, warnings: [String]) {
+      self.css = css
+      self.warnings = warnings
+    }
+  }
+
+  public struct ParseError: Error, Equatable, LocalizedError, Sendable {
+    /// Character offset into the CSS where the problem was detected.
+    public let offset: Int
+    public let reason: String
+
+    public var errorDescription: String? {
+      "\(reason) at character \(offset)."
+    }
+  }
+
+  /// The selector every rule of a variant is scoped under.
+  public static func artboardSelector(forVariantName name: String) -> String {
+    let escaped = name
+      .replacingOccurrences(of: "\\", with: "\\\\")
+      .replacingOccurrences(of: "\"", with: "\\\"")
+    return ".studio-artboard[data-variant=\"\(escaped)\"]"
+  }
+
+  /// A CSS-identifier-safe form of a variant name, for renamed keyframes.
+  public static func slug(_ name: String) -> String {
+    var result = ""
+    var lastWasDash = true
+    for scalar in name.lowercased().unicodeScalars {
+      if CharacterSet.alphanumerics.contains(scalar), scalar.isASCII {
+        result.unicodeScalars.append(scalar)
+        lastWasDash = false
+      } else if !lastWasDash {
+        result.append("-")
+        lastWasDash = true
+      }
+    }
+    while result.hasSuffix("-") { result.removeLast() }
+    return result.isEmpty ? "variant" : result
+  }
+
+  public static func scope(_ css: String, variantName: String) throws -> Output {
+    var parser = Parser(css: Array(css))
+    let nodes = try parser.parseRuleList(topLevel: true)
+
+    let slug = slug(variantName)
+    var keyframeNames: Set<String> = []
+    collectKeyframeNames(in: nodes, into: &keyframeNames)
+    let renames = Dictionary(uniqueKeysWithValues: keyframeNames.map { ($0, "\($0)-\(slug)") })
+
+    var serializer = Serializer(
+      scope: artboardSelector(forVariantName: variantName),
+      renames: renames
+    )
+    let output = serializer.serialize(nodes, depth: 0)
+    return Output(
+      css: output.trimmingCharacters(in: .whitespacesAndNewlines),
+      warnings: serializer.warnings
+    )
+  }
+
+  // MARK: - Nodes
+
+  indirect enum Node: Equatable {
+    case style(selectors: String, block: String)
+    case atBlock(prelude: String, children: [Node])
+    case atRaw(prelude: String, block: String)
+    case keyframes(prelude: String, name: String, block: String)
+    case atStatement(String)
+  }
+
+  private static func collectKeyframeNames(in nodes: [Node], into names: inout Set<String>) {
+    for node in nodes {
+      switch node {
+      case .keyframes(_, let name, _):
+        names.insert(name)
+      case .atBlock(_, let children):
+        collectKeyframeNames(in: children, into: &names)
+      case .style, .atRaw, .atStatement:
+        continue
+      }
+    }
+  }
+
+  // MARK: - Parser
+
+  struct Parser {
+    let css: [Character]
+    var index = 0
+
+    init(css: [Character]) {
+      self.css = css
+    }
+
+    private static let recursiveAtRules: Set<String> = [
+      "media", "supports", "container", "layer", "document", "-moz-document",
+    ]
+
+    mutating func parseRuleList(topLevel: Bool) throws -> [Node] {
+      var nodes: [Node] = []
+      while true {
+        try skipWhitespaceAndComments()
+        guard index < css.count else {
+          if topLevel { return nodes }
+          throw ParseError(offset: index, reason: "Unbalanced braces: missing '}'")
+        }
+        let char = css[index]
+        if char == "}" {
+          if topLevel {
+            throw ParseError(offset: index, reason: "Unbalanced braces: unexpected '}'")
+          }
+          index += 1
+          return nodes
+        }
+        if char == ";" {
+          index += 1
+          continue
+        }
+
+        let preludeStart = index
+        let (prelude, terminator) = try readPrelude()
+        switch terminator {
+        case ";":
+          index += 1
+          if prelude.hasPrefix("@") {
+            nodes.append(.atStatement(prelude + ";"))
+          }
+          // A bare declaration at rule level is not valid CSS; drop it.
+        case "{":
+          index += 1
+          nodes.append(try parseBlock(prelude: prelude, preludeStart: preludeStart))
+        default:
+          // End of input (or a closing brace) mid-prelude: nothing to keep.
+          if !prelude.isEmpty, !topLevel {
+            throw ParseError(offset: preludeStart, reason: "Unbalanced braces: missing '}'")
+          }
+        }
+      }
+    }
+
+    private mutating func parseBlock(prelude: String, preludeStart: Int) throws -> Node {
+      guard prelude.hasPrefix("@") else {
+        return .style(selectors: prelude, block: try readRawBlock(openedAt: preludeStart))
+      }
+
+      let name = atRuleName(prelude)
+      if Self.recursiveAtRules.contains(name) {
+        return .atBlock(prelude: prelude, children: try parseRuleList(topLevel: false))
+      }
+      if name == "keyframes" || name.hasSuffix("-keyframes") {
+        let keyframeName = prelude
+          .dropFirst(name.count + 1)
+          .trimmingCharacters(in: .whitespacesAndNewlines)
+        return .keyframes(
+          prelude: prelude,
+          name: keyframeName,
+          block: try readRawBlock(openedAt: preludeStart)
+        )
+      }
+      return .atRaw(prelude: prelude, block: try readRawBlock(openedAt: preludeStart))
+    }
+
+    private func atRuleName(_ prelude: String) -> String {
+      var name = ""
+      for char in prelude.dropFirst() {
+        if char.isLetter || char.isNumber || char == "-" || char == "_" {
+          name.append(char)
+        } else {
+          break
+        }
+      }
+      return name.lowercased()
+    }
+
+    /// Reads up to (not including) the next top-level `{`, `;`, or `}`.
+    private mutating func readPrelude() throws -> (String, Character?) {
+      var text = ""
+      var depth = 0
+      while index < css.count {
+        let char = css[index]
+        if char == "\"" || char == "'" {
+          text += try readString()
+          continue
+        }
+        if char == "/", index + 1 < css.count, css[index + 1] == "*" {
+          try skipComment()
+          continue
+        }
+        if char == "(" || char == "[" { depth += 1 }
+        if char == ")" || char == "]" { depth = max(0, depth - 1) }
+        if depth == 0, char == "{" || char == ";" || char == "}" {
+          return (text.trimmingCharacters(in: .whitespacesAndNewlines), char)
+        }
+        text.append(char)
+        index += 1
+      }
+      return (text.trimmingCharacters(in: .whitespacesAndNewlines), nil)
+    }
+
+    /// Reads a balanced block body. `index` must sit just past the opening `{`;
+    /// on return it sits just past the matching `}`.
+    private mutating func readRawBlock(openedAt: Int) throws -> String {
+      var text = ""
+      var depth = 1
+      while index < css.count {
+        let char = css[index]
+        if char == "\"" || char == "'" {
+          text += try readString()
+          continue
+        }
+        if char == "/", index + 1 < css.count, css[index + 1] == "*" {
+          try skipComment()
+          continue
+        }
+        if char == "{" { depth += 1 }
+        if char == "}" {
+          depth -= 1
+          if depth == 0 {
+            index += 1
+            return text.trimmingCharacters(in: .whitespacesAndNewlines)
+          }
+        }
+        text.append(char)
+        index += 1
+      }
+      throw ParseError(offset: openedAt, reason: "Unbalanced braces: missing '}'")
+    }
+
+    private mutating func readString() throws -> String {
+      let quote = css[index]
+      let start = index
+      var text = String(quote)
+      index += 1
+      while index < css.count {
+        let char = css[index]
+        text.append(char)
+        index += 1
+        if char == "\\", index < css.count {
+          text.append(css[index])
+          index += 1
+          continue
+        }
+        if char == quote { return text }
+        if char == "\n" { break }
+      }
+      throw ParseError(offset: start, reason: "Unterminated string")
+    }
+
+    private mutating func skipComment() throws {
+      let start = index
+      index += 2
+      while index + 1 < css.count {
+        if css[index] == "*", css[index + 1] == "/" {
+          index += 2
+          return
+        }
+        index += 1
+      }
+      throw ParseError(offset: start, reason: "Unterminated comment")
+    }
+
+    private mutating func skipWhitespaceAndComments() throws {
+      while index < css.count {
+        let char = css[index]
+        if char.isWhitespace {
+          index += 1
+        } else if char == "/", index + 1 < css.count, css[index + 1] == "*" {
+          try skipComment()
+        } else {
+          return
+        }
+      }
+    }
+  }
+
+  // MARK: - Serializer
+
+  struct Serializer {
+    let scope: String
+    let renames: [String: String]
+    var warnings: [String] = []
+
+    init(scope: String, renames: [String: String]) {
+      self.scope = scope
+      self.renames = renames
+    }
+
+    mutating func serialize(_ nodes: [Node], depth: Int) -> String {
+      let indent = String(repeating: "  ", count: depth)
+      var lines: [String] = []
+      for node in nodes {
+        switch node {
+        case .style(let selectors, let block):
+          let scoped = scopeSelectorList(selectors)
+          guard !scoped.isEmpty else { continue }
+          lines.append("\(indent)\(scoped) {\n\(indentBlock(rewriteAnimations(block), indent: indent))\n\(indent)}")
+        case .atBlock(let prelude, let children):
+          lines.append("\(indent)\(prelude) {\n\(serialize(children, depth: depth + 1))\n\(indent)}")
+        case .keyframes(let prelude, let name, let block):
+          let renamed = renames[name] ?? name
+          let head = prelude.hasSuffix(name)
+            ? String(prelude.dropLast(name.count)) + renamed
+            : prelude
+          lines.append("\(indent)\(head) {\n\(indentBlock(block, indent: indent))\n\(indent)}")
+        case .atRaw(let prelude, let block):
+          let name = prelude.dropFirst().prefix { $0.isLetter || $0 == "-" }.lowercased()
+          if !["font-face", "page", "property", "counter-style", "font-feature-values", "font-palette-values"].contains(name) {
+            warnings.append("Left \(prelude.prefix(40)) unscoped: AgentHub does not know how to scope this at-rule.")
+          }
+          lines.append("\(indent)\(prelude) {\n\(indentBlock(block, indent: indent))\n\(indent)}")
+        case .atStatement(let text):
+          let lower = text.lowercased()
+          if lower.hasPrefix("@import") {
+            warnings.append("Dropped \(text.prefix(80)): imported CSS cannot be scoped to one variant. Inline the rules you need.")
+          } else if lower.hasPrefix("@charset") || lower.hasPrefix("@namespace") {
+            continue
+          } else {
+            lines.append("\(indent)\(text)")
+          }
+        }
+      }
+      return lines.joined(separator: "\n")
+    }
+
+    private func indentBlock(_ block: String, indent: String) -> String {
+      block
+        .split(separator: "\n", omittingEmptySubsequences: false)
+        .map { "\(indent)  \($0.trimmingCharacters(in: .whitespaces))" }
+        .joined(separator: "\n")
+    }
+
+    // MARK: Selectors
+
+    private static let rootAncestorPattern = try! NSRegularExpression(
+      pattern: "^(?:html|:root)(?:[.#\\[:][^\\s>+~]*)?\\s*(?:>\\s*)?(?=(?:body|:root)(?:$|[\\s>+~.#\\[:]))",
+      options: [.caseInsensitive]
+    )
+    private static let rootPattern = try! NSRegularExpression(
+      pattern: "^(?:html|:root|body)(?=$|[\\s>+~.#\\[:(])",
+      options: [.caseInsensitive]
+    )
+
+    func scopeSelectorList(_ list: String) -> String {
+      var seen: Set<String> = []
+      var scoped: [String] = []
+      for raw in splitSelectors(list) {
+        let selector = scopeSelector(raw)
+        guard !selector.isEmpty, seen.insert(selector).inserted else { continue }
+        scoped.append(selector)
+      }
+      return scoped.joined(separator: ", ")
+    }
+
+    func scopeSelector(_ raw: String) -> String {
+      var selector = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+      guard !selector.isEmpty else { return "" }
+
+      // `html body .x` → drop the `html`, so the following `body` becomes the
+      // one scope instead of producing `S S .x`.
+      selector = Self.rootAncestorPattern.stringByReplacingMatches(
+        in: selector,
+        range: NSRange(selector.startIndex..., in: selector),
+        withTemplate: ""
+      )
+
+      let range = NSRange(selector.startIndex..., in: selector)
+      if Self.rootPattern.firstMatch(in: selector, range: range) != nil {
+        return Self.rootPattern.stringByReplacingMatches(
+          in: selector,
+          range: range,
+          withTemplate: NSRegularExpression.escapedTemplate(for: scope)
+        )
+      }
+      return "\(scope) \(selector)"
+    }
+
+    /// Splits on top-level commas — not the ones inside `:is(a, b)` or `[x="a,b"]`.
+    private func splitSelectors(_ list: String) -> [String] {
+      var parts: [String] = []
+      var current = ""
+      var depth = 0
+      var quote: Character?
+      var previous: Character?
+      for char in list {
+        if let openQuote = quote {
+          current.append(char)
+          if char == openQuote, previous != "\\" { quote = nil }
+        } else if char == "\"" || char == "'" {
+          quote = char
+          current.append(char)
+        } else if char == "(" || char == "[" {
+          depth += 1
+          current.append(char)
+        } else if char == ")" || char == "]" {
+          depth = max(0, depth - 1)
+          current.append(char)
+        } else if char == ",", depth == 0 {
+          parts.append(current)
+          current = ""
+        } else {
+          current.append(char)
+        }
+        previous = char
+      }
+      parts.append(current)
+      return parts
+    }
+
+    // MARK: Animations
+
+    private static let animationDeclarationPattern = try! NSRegularExpression(
+      pattern: "((?:-webkit-)?animation(?:-name)?\\s*:\\s*)([^;}]*)",
+      options: [.caseInsensitive]
+    )
+
+    private func rewriteAnimations(_ block: String) -> String {
+      guard !renames.isEmpty else { return block }
+      let nsBlock = block as NSString
+      var result = ""
+      var cursor = 0
+      for match in Self.animationDeclarationPattern.matches(in: block, range: NSRange(location: 0, length: nsBlock.length)) {
+        result += nsBlock.substring(with: NSRange(location: cursor, length: match.range.location - cursor))
+        result += nsBlock.substring(with: match.range(at: 1))
+        var value = nsBlock.substring(with: match.range(at: 2))
+        for (old, new) in renames {
+          guard let regex = try? NSRegularExpression(
+            pattern: "(?<![\\w-])\(NSRegularExpression.escapedPattern(for: old))(?![\\w-])"
+          ) else { continue }
+          value = regex.stringByReplacingMatches(
+            in: value,
+            range: NSRange(value.startIndex..., in: value),
+            withTemplate: NSRegularExpression.escapedTemplate(for: new)
+          )
+        }
+        result += value
+        cursor = match.range.location + match.range.length
+      }
+      result += nsBlock.substring(from: cursor)
+      return result
+    }
+  }
+}
diff --git a/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioFragmentNormalizer.swift b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioFragmentNormalizer.swift
new file mode 100644
index 00000000..dde1acf7
--- /dev/null
+++ b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioFragmentNormalizer.swift
@@ -0,0 +1,113 @@
+import Foundation
+
+/// Reduces whatever HTML an agent sent for a canvas variant to a body fragment
+/// plus the CSS it carried.
+///
+/// Variants share one document, so a variant is a *fragment*, whatever it claims
+/// to be: document wrappers are stripped, `<style>` is hoisted so it can be
+/// scoped, and `<script>` is removed because JS cannot be scoped the way CSS can
+/// (a variant's `document.querySelector('.btn')` would find its neighbour's
+/// button). External stylesheets are dropped and reported — remote CSS cannot be
+/// scoped either, and silently keeping it would let one variant restyle the
+/// canvas.
+public enum StudioFragmentNormalizer {
+  public struct Output: Equatable, Sendable {
+    public let html: String
+    public let css: String
+    public let warnings: [String]
+
+    public init(html: String, css: String, warnings: [String]) {
+      self.html = html
+      self.css = css
+      self.warnings = warnings
+    }
+  }
+
+  public static func normalize(_ raw: String) -> Output {
+    var html = raw
+    var warnings: [String] = []
+    var css: [String] = []
+
+    // Comments first, so a commented-out <script> is not "stripped" from inside
+    // a comment and reported as if it had been live.
+    html = removing(pattern: "<!--.*?-->", from: html)
+
+    // Hoist stylesheets before stripping <head>, which is where most of them live.
+    html = replacing(pattern: "<style\\b[^>]*>(.*?)</style\\s*>", in: html) { groups in
+      if let body = groups.first { css.append(body) }
+      return ""
+    }
+
+    let externalStylesheets = matches(
+      pattern: "<link\\b[^>]*rel\\s*=\\s*[\"']?stylesheet[\"']?[^>]*>",
+      in: html
+    )
+    if !externalStylesheets.isEmpty {
+      warnings.append(
+        "Dropped \(externalStylesheets.count) external stylesheet link(s): remote CSS cannot be scoped to one variant. Inline the rules you need."
+      )
+      html = removing(pattern: "<link\\b[^>]*rel\\s*=\\s*[\"']?stylesheet[\"']?[^>]*>", from: html)
+    }
+
+    let scripts = matches(pattern: "<script\\b[^>]*>.*?</script\\s*>", in: html)
+    if !scripts.isEmpty {
+      warnings.append(
+        "Dropped \(scripts.count) <script> block(s): variants share one document, so scripts cannot be scoped. Use agenthub_artifact for interactive HTML."
+      )
+      html = removing(pattern: "<script\\b[^>]*>.*?</script\\s*>", from: html)
+    }
+
+    // Document wrappers. <head> goes entirely (its stylesheets were hoisted above);
+    // <html>/<body>/<!DOCTYPE> tags are unwrapped, their content kept.
+    html = removing(pattern: "<!DOCTYPE\\b[^>]*>", from: html)
+    html = removing(pattern: "<head\\b[^>]*>.*?</head\\s*>", from: html)
+    html = removing(pattern: "</?html\\b[^>]*>", from: html)
+    html = removing(pattern: "</?body\\b[^>]*>", from: html)
+
+    return Output(
+      html: html.trimmingCharacters(in: .whitespacesAndNewlines),
+      css: css.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+        .filter { !$0.isEmpty }
+        .joined(separator: "\n\n"),
+      warnings: warnings
+    )
+  }
+
+  // MARK: - Regex helpers
+
+  private static let options: NSRegularExpression.Options = [.caseInsensitive, .dotMatchesLineSeparators]
+
+  private static func removing(pattern: String, from text: String) -> String {
+    replacing(pattern: pattern, in: text) { _ in "" }
+  }
+
+  private static func matches(pattern: String, in text: String) -> [NSTextCheckingResult] {
+    guard let regex = try? NSRegularExpression(pattern: pattern, options: options) else { return [] }
+    return regex.matches(in: text, range: NSRange(text.startIndex..., in: text))
+  }
+
+  private static func replacing(
+    pattern: String,
+    in text: String,
+    with replacement: ([String]) -> String
+  ) -> String {
+    guard let regex = try? NSRegularExpression(pattern: pattern, options: options) else { return text }
+    let nsText = text as NSString
+    var result = ""
+    var cursor = 0
+    for match in regex.matches(in: text, range: NSRange(location: 0, length: nsText.length)) {
+      result += nsText.substring(with: NSRange(location: cursor, length: match.range.location - cursor))
+      var groups: [String] = []
+      if match.numberOfRanges > 1 {
+        for index in 1..<match.numberOfRanges {
+          let range = match.range(at: index)
+          groups.append(range.location == NSNotFound ? "" : nsText.substring(with: range))
+        }
+      }
+      result += replacement(groups)
+      cursor = match.range.location + match.range.length
+    }
+    result += nsText.substring(from: cursor)
+    return result
+  }
+}
diff --git a/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioIndexStore.swift b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioIndexStore.swift
new file mode 100644
index 00000000..fdebb856
--- /dev/null
+++ b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioIndexStore.swift
@@ -0,0 +1,123 @@
+import Foundation
+
+/// A compact, agent-readable summary of one Studio artifact.
+public struct StudioIndexEntry: Codable, Equatable, Sendable, Identifiable {
+  public let id: String
+  public let kind: StudioArtifactKind
+  public let title: String
+  public let variantNames: [String]
+  public let sourcePath: String?
+  public let revision: Int
+  public let updatedAt: Date
+  /// The served document on disk, so an agent can open what it filed.
+  public let documentPath: String?
+  /// The current payload (`artifact.json`) beside it — variants with the
+  /// user's baked-in edits, props, sourcePath. What `agenthub_get_artifact` reads.
+  public let payloadPath: String?
+
+  public init(
+    id: String,
+    kind: StudioArtifactKind,
+    title: String,
+    variantNames: [String],
+    sourcePath: String?,
+    revision: Int,
+    updatedAt: Date,
+    documentPath: String?,
+    payloadPath: String? = nil
+  ) {
+    self.id = id
+    self.kind = kind
+    self.title = title
+    self.variantNames = variantNames
+    self.sourcePath = sourcePath
+    self.revision = revision
+    self.updatedAt = updatedAt
+    self.documentPath = documentPath
+    self.payloadPath = payloadPath
+  }
+
+  public init(artifact: StudioArtifact, documentPath: String?, payloadPath: String? = nil) {
+    self.init(
+      id: artifact.id,
+      kind: artifact.kind,
+      title: artifact.title,
+      variantNames: artifact.variantNames,
+      sourcePath: artifact.sourcePath,
+      revision: artifact.revision,
+      updatedAt: artifact.displayDate,
+      documentPath: documentPath,
+      payloadPath: payloadPath
+    )
+  }
+}
+
+public struct StudioIndex: Codable, Equatable, Sendable {
+  public let projectPath: String
+  public let updatedAt: Date
+  public let artifacts: [StudioIndexEntry]
+
+  public init(projectPath: String, updatedAt: Date, artifacts: [StudioIndexEntry]) {
+    self.projectPath = projectPath
+    self.updatedAt = updatedAt
+    self.artifacts = artifacts
+  }
+}
+
+/// A read-only view of a project's Studio artifacts, for the `agenthub` CLI.
+///
+/// Same contract as `MeasurementIndexStore`: the CLI never opens the app's
+/// SQLite database. The app republishes this JSON index whenever a project's
+/// artifacts change, mirrored to every session path that resolves to the
+/// project (worktrees included), and the CLI only ever reads it.
+public struct StudioIndexStore: Sendable {
+  public let directoryURL: URL
+
+  public init(directoryURL: URL = StudioIndexStore.defaultDirectoryURL()) {
+    self.directoryURL = directoryURL
+  }
+
+  public static func defaultDirectoryURL(fileManager: FileManager = .default) -> URL {
+    StudioSupportDirectory.baseURL(fileManager: fileManager)
+      .appendingPathComponent("studio-index", isDirectory: true)
+  }
+
+  /// Percent-encoded rather than separator-substituted: turning `/` into `-`
+  /// makes `/a/b-c` and `/a-b/c` collide, silently merging two projects.
+  public static func fileName(forProjectPath projectPath: String) -> String {
+    let encoded = projectPath.addingPercentEncoding(withAllowedCharacters: .alphanumerics) ?? projectPath
+    return "\(encoded).json"
+  }
+
+  public func fileURL(forProjectPath projectPath: String) -> URL {
+    directoryURL.appendingPathComponent(Self.fileName(forProjectPath: projectPath), isDirectory: false)
+  }
+
+  public func read(projectPath: String) -> StudioIndex? {
+    guard let data = try? Data(contentsOf: fileURL(forProjectPath: projectPath)) else { return nil }
+    let decoder = JSONDecoder()
+    decoder.dateDecodingStrategy = .iso8601
+    return try? decoder.decode(StudioIndex.self, from: data)
+  }
+
+  /// Publishes an index, mirroring it to every alias path so a worktree session
+  /// finds the same list its parent repo sees.
+  public func write(_ index: StudioIndex, aliasPaths: [String] = []) throws {
+    try FileManager.default.createDirectory(at: directoryURL, withIntermediateDirectories: true)
+
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+    encoder.dateEncodingStrategy = .iso8601
+    let data = try encoder.encode(index)
+
+    for path in Set([index.projectPath] + aliasPaths) where !path.isEmpty {
+      let finalURL = fileURL(forProjectPath: path)
+      let temporaryURL = directoryURL.appendingPathComponent(".\(UUID().uuidString).tmp", isDirectory: false)
+      try data.write(to: temporaryURL, options: [.atomic])
+      if FileManager.default.fileExists(atPath: finalURL.path) {
+        try FileManager.default.removeItem(at: finalURL)
+      }
+      try FileManager.default.moveItem(at: temporaryURL, to: finalURL)
+    }
+  }
+}
diff --git a/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioTweakProps.swift b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioTweakProps.swift
new file mode 100644
index 00000000..d94fdee2
--- /dev/null
+++ b/app/modules/AgentHubCLI/Sources/AgentHubCLIKit/StudioTweakProps.swift
@@ -0,0 +1,285 @@
+import Foundation
+
+/// A tweakable value on a design canvas.
+public enum StudioTweakValue: Equatable, Sendable, Codable {
+  case number(Double)
+  case string(String)
+  case boolean(Bool)
+
+  public init(from decoder: Decoder) throws {
+    let container = try decoder.singleValueContainer()
+    if let bool = try? container.decode(Bool.self) {
+      self = .boolean(bool)
+    } else if let number = try? container.decode(Double.self) {
+      self = .number(number)
+    } else {
+      self = .string(try container.decode(String.self))
+    }
+  }
+
+  public func encode(to encoder: Encoder) throws {
+    var container = encoder.singleValueContainer()
+    switch self {
+    case .number(let value): try container.encode(value)
+    case .string(let value): try container.encode(value)
+    case .boolean(let value): try container.encode(value)
+    }
+  }
+
+  /// The JSON-compatible value, for the `dc_set_props` schema the host page declares.
+  public var jsonValue: Any {
+    switch self {
+    case .number(let value): return value
+    case .string(let value): return value
+    case .boolean(let value): return value
+    }
+  }
+}
+
+/// One control in a canvas's shared tweak schema.
+///
+/// The schema is **per canvas, not per variant**: the point of a canvas is
+/// comparing variants under the same knobs. Every prop is exposed to every
+/// artboard as the CSS custom property `--{name}`; variants read it with
+/// `var(--name)`. `text` and `select` values are additionally written into any
+/// element carrying `data-prop="{name}"`, so copy can be tweaked without JS.
+///
+/// The shape mirrors the `dc_set_props` declaration the Tweaks panel already
+/// understands (`type`, `label`, `value`, `min`/`max`/`step`, `options`), plus
+/// `unit` for sliders whose CSS value needs one (`px`, `rem`, `%`, `ms`).
+public struct StudioTweakProp: Codable, Equatable, Sendable, Identifiable {
+  public enum Kind: String, Codable, Sendable, CaseIterable {
+    case slider, select, color, toggle, text
+  }
+
+  public let name: String
+  public let label: String
+  public let type: Kind
+  public var value: StudioTweakValue
+  public let minimum: Double?
+  public let maximum: Double?
+  public let step: Double?
+  public let options: [String]
+  public let unit: String?
+
+  public var id: String { name }
+
+  public init(
+    name: String,
+    label: String? = nil,
+    type: Kind,
+    value: StudioTweakValue,
+    minimum: Double? = nil,
+    maximum: Double? = nil,
+    step: Double? = nil,
+    options: [String] = [],
+    unit: String? = nil
+  ) {
+    self.name = name
+    self.label = label.flatMap { $0.isEmpty ? nil : $0 } ?? name
+    self.type = type
+    self.value = value
+    self.minimum = minimum
+    self.maximum = maximum
+    self.step = step
+    self.options = options
+    self.unit = unit
+  }
+
+  /// The CSS custom property this prop drives.
+  public var cssVariableName: String { "--\(name)" }
+
+  /// The CSS token for a value of this prop's type: sliders carry their unit,
+  /// toggles become `1`/`0` (usable in `calc()` and `opacity`), everything
+  /// else is injected raw so keyword values (`600`, `center`, `#0a84ff`) work.
+  public func cssValue(for value: StudioTweakValue) -> String {
+    switch (type, value) {
+    case (.slider, .number(let number)):
+      let text = number == number.rounded() && abs(number) < 1e15
+        ? String(Int(number))
+        : String(number)
+      return text + (unit ?? "")
+    case (.toggle, .boolean(let flag)):
+      return flag ? "1" : "0"
+    case (_, .number(let number)):
+      return number == number.rounded() ? String(Int(number)) : String(number)
+    case (_, .boolean(let flag)):
+      return flag ? "1" : "0"
+    case (_, .string(let string)):
+      return string
+    }
+  }
+
+  public var cssValue: String { cssValue(for: value) }
+
+  /// The prop with a new value, keeping everything else.
+  public func withValue(_ newValue: StudioTweakValue) -> StudioTweakProp {
+    var copy = self
+    copy.value = newValue
+    return copy
+  }
+
+  /// The `dc_set_props` declaration for this prop, for the host page.
+  public var declaration: [String: Any] {
+    var object: [String: Any] = [
+      "type": type.rawValue,
+      "label": label,
+      "value": value.jsonValue,
+    ]
+    if let minimum { object["min"] = minimum }
+    if let maximum { object["max"] = maximum }
+    if let step { object["step"] = step }
+    if !options.isEmpty { object["options"] = options }
+    if let unit { object["unit"] = unit }
+    return object
+  }
+}
+
+/// Validates the `props` argument of `agenthub_design` at the tool boundary.
+public enum StudioTweakPropParser {
+  public struct ValidationError: Error, Equatable, LocalizedError, Sendable {
+    public let message: String
+    public var errorDescription: String? { message }
+    public init(_ message: String) { self.message = message }
+  }
+
+  public static let maxProps = 24
+  private static let namePattern = try! NSRegularExpression(pattern: "^[A-Za-z_][A-Za-z0-9_-]{0,39}$")
+
+  /// `raw` is the JSON object the agent passed: `{ name: { type, value, … } }`.
+  /// Declaration order is preserved when the host serializes an ordered array;
+  /// a dictionary loses it, so an array of `{ name, … }` objects is accepted too.
+  public static func parse(_ raw: Any?) throws -> [StudioTweakProp] {
+    guard let raw, !(raw is NSNull) else { return [] }
+
+    var entries: [(String, [String: Any])] = []
+    if let array = raw as? [[String: Any]] {
+      for object in array {
+        guard let name = object["name"] as? String else {
+          throw ValidationError("Every props entry needs a name.")
+        }
+        entries.append((name, object))
+      }
+    } else if let object = raw as? [String: Any] {
+      // Dictionaries are unordered; sort by name for a stable panel order.
+      entries = object.keys.sorted().compactMap { key in
+        (object[key] as? [String: Any]).map { (key, $0) }
+      }
+      if entries.count != object.count {
+        throw ValidationError("Every props entry must be an object like { type, value }.")
+      }
+    } else {
+      throw ValidationError("props must be an object keyed by prop name, or an array of { name, type, value, … } objects.")
+    }
+
+    guard entries.count <= maxProps else {
+      throw ValidationError("props has \(entries.count) entries but the limit is \(maxProps).")
+    }
+
+    var seen: Set<String> = []
+    return try entries.map { name, declaration in
+      let trimmed = name.trimmingCharacters(in: .whitespacesAndNewlines)
+      guard namePattern.firstMatch(in: trimmed, range: NSRange(trimmed.startIndex..., in: trimmed)) != nil else {
+        throw ValidationError("Prop name \"\(name)\" must be a CSS-identifier-safe name (letters, digits, - and _; starts with a letter or _; ≤40 chars).")
+      }
+      guard seen.insert(trimmed).inserted else {
+        throw ValidationError("Prop \"\(trimmed)\" is declared more than once.")
+      }
+      guard let typeString = declaration["type"] as? String,
+            let type = StudioTweakProp.Kind(rawValue: typeString.lowercased())
+      else {
+        let supported = StudioTweakProp.Kind.allCases.map(\.rawValue).joined(separator: ", ")
+        throw ValidationError("Prop \"\(trimmed)\" needs a type: one of \(supported).")
+      }
+
+      let label = declaration["label"] as? String
+      let unit = (declaration["unit"] as? String).flatMap { $0.isEmpty ? nil : $0 }
+      let options = (declaration["options"] as? [Any])?.compactMap { $0 as? String } ?? []
+      let minimum = (declaration["min"] as? NSNumber)?.doubleValue
+      let maximum = (declaration["max"] as? NSNumber)?.doubleValue
+      let step = (declaration["step"] as? NSNumber)?.doubleValue
+
+      let value: StudioTweakValue
+      switch type {
+      case .slider:
+        guard let number = numberValue(declaration["value"]) else {
+          throw ValidationError("Slider prop \"\(trimmed)\" needs a numeric value.")
+        }
+        if let minimum, let maximum, minimum > maximum {
+          throw ValidationError("Slider prop \"\(trimmed)\" has min greater than max.")
+        }
+        if let minimum, number < minimum { throw ValidationError("Slider prop \"\(trimmed)\" value is below its min.") }
+        if let maximum, number > maximum { throw ValidationError("Slider prop \"\(trimmed)\" value is above its max.") }
+        value = .number(number)
+      case .toggle:
+        guard let flag = boolValue(declaration["value"]) else {
+          throw ValidationError("Toggle prop \"\(trimmed)\" needs a boolean value.")
+        }
+        value = .boolean(flag)
+      case .select:
+        guard !options.isEmpty else {
+          throw ValidationError("Select prop \"\(trimmed)\" needs a non-empty options array.")
+        }
+        guard let string = declaration["value"] as? String, options.contains(string) else {
+          throw ValidationError("Select prop \"\(trimmed)\" value must be one of its options.")
+        }
+        value = .string(string)
+      case .color, .text:
+        guard let string = declaration["value"] as? String else {
+          throw ValidationError("\(type == .color ? "Color" : "Text") prop \"\(trimmed)\" needs a string value.")
+        }
+        value = .string(string)
+      }
+
+      return StudioTweakProp(
+        name: trimmed,
+        label: label,
+        type: type,
+        value: value,
+        minimum: type == .slider ? minimum : nil,
+        maximum: type == .slider ? maximum : nil,
+        step: type == .slider ? step : nil,
+        options: type == .select ? options : [],
+        unit: type == .slider ? unit : nil
+      )
+    }
+  }
+
+  /// JSON `true`/`false` arrive as `NSNumber` too; `is Bool` is true for any
+  /// 0/1 NSNumber under bridging, so ask CoreFoundation which it really is.
+  private static func isBooleanNumber(_ raw: Any?) -> Bool {
+    guard let number = raw as? NSNumber else { return false }
+    return CFGetTypeID(number) == CFBooleanGetTypeID()
+  }
+
+  /// Props no variant references — neither `--<name>` in its CSS/markup nor a
+  /// `data-prop="<name>"` element. A control that moves nothing is exactly the
+  /// bug a user reports as "tweaks don't work", so the tool rejects it.
+  public static func unusedProps(_ props: [StudioTweakProp], variants: [StudioVariant]) -> [String] {
+    let haystack = variants.map { $0.css + "\n" + $0.html }.joined(separator: "\n")
+    return props.compactMap { prop in
+      let usesVariable = haystack.contains(prop.cssVariableName)
+      let usesDataProp = haystack.contains("data-prop=\"\(prop.name)\"") || haystack.contains("data-prop='\(prop.name)'")
+      return usesVariable || usesDataProp ? nil : prop.name
+    }
+  }
+
+  private static func numberValue(_ raw: Any?) -> Double? {
+    if let number = raw as? NSNumber, !isBooleanNumber(raw) { return number.doubleValue }
+    if let string = raw as? String { return Double(string) }
+    return nil
+  }
+
+  private static func boolValue(_ raw: Any?) -> Bool? {
+    if isBooleanNumber(raw), let number = raw as? NSNumber { return number.boolValue }
+    if let bool = raw as? Bool, !(raw is NSNumber) { return bool }
+    if let string = raw as? String {
+      switch string.lowercased() {
+      case "true", "yes", "on": return true
+      case "false", "no", "off": return false
+      default: return nil
+      }
+    }
+    return nil
+  }
+}
diff --git a/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioArtifactQueueTests.swift b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioArtifactQueueTests.swift
new file mode 100644
index 00000000..6f037925
--- /dev/null
+++ b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioArtifactQueueTests.swift
@@ -0,0 +1,87 @@
+import Foundation
+import Testing
+
+@testable import AgentHubCLIKit
+
+@Suite("StudioArtifactQueue")
+struct StudioArtifactQueueTests {
+  @Test("Enqueue writes the artifact and it reads back intact")
+  func enqueueRoundTrips() throws {
+    let directory = try temporaryStudioDirectory()
+    defer { try? FileManager.default.removeItem(at: directory.deletingLastPathComponent()) }
+
+    let queue = StudioArtifactQueue(directoryURL: directory)
+    let artifact = makeCanvas(id: "canvas-1")
+    let queued = try queue.enqueue(artifact)
+
+    #expect(FileManager.default.fileExists(atPath: queued.fileURL.path))
+    #expect(try queue.pendingArtifacts().map(\.artifact) == [artifact])
+  }
+
+  @Test("Pending artifacts are ordered oldest first")
+  func pendingOrderedOldestFirst() throws {
+    let directory = try temporaryStudioDirectory()
+    defer { try? FileManager.default.removeItem(at: directory.deletingLastPathComponent()) }
+
+    let queue = StudioArtifactQueue(directoryURL: directory)
+    try queue.enqueue(makeCanvas(id: "newer", createdAt: Date(timeIntervalSince1970: 9_000)))
+    try queue.enqueue(makeCanvas(id: "older", createdAt: Date(timeIntervalSince1970: 1_000)))
+
+    #expect(try queue.pendingArtifacts().map(\.artifact.id) == ["older", "newer"])
+  }
+
+  @Test("Temp files and failed files are ignored; remove and markFailed work")
+  func removeAndMarkFailed() throws {
+    let directory = try temporaryStudioDirectory()
+    defer { try? FileManager.default.removeItem(at: directory.deletingLastPathComponent()) }
+
+    let queue = StudioArtifactQueue(directoryURL: directory)
+    let a = try queue.enqueue(makeCanvas(id: "a"))
+    let b = try queue.enqueue(makeCanvas(id: "b"))
+    try Data("garbage".utf8).write(to: directory.appendingPathComponent(".c.tmp"))
+
+    try queue.remove(a)
+    try queue.markFailed(b)
+
+    #expect(try queue.pendingArtifacts().isEmpty)
+    #expect(FileManager.default.fileExists(atPath: directory.appendingPathComponent("b.failed").path))
+  }
+
+  @Test("Re-filing preserves createdAt, bumps revision, stamps updatedAt")
+  func replacingKeepsIdentity() {
+    let first = makeCanvas(id: "x", createdAt: Date(timeIntervalSince1970: 100))
+    let second = makeCanvas(id: "x", createdAt: Date(timeIntervalSince1970: 200))
+    let merged = second.replacing(first)
+    #expect(merged.createdAt == first.createdAt)
+    #expect(merged.updatedAt == second.createdAt)
+    #expect(merged.revision == 2)
+    #expect(merged.displayDate == second.createdAt)
+  }
+}
+
+func temporaryStudioDirectory() throws -> URL {
+  let root = FileManager.default.temporaryDirectory
+    .appendingPathComponent("agenthub-studio-tests-\(UUID().uuidString)", isDirectory: true)
+  let directory = root.appendingPathComponent("studio-records", isDirectory: true)
+  try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+  return directory
+}
+
+func makeCanvas(id: String, createdAt: Date = Date(timeIntervalSince1970: 1_000)) -> StudioArtifact {
+  StudioArtifact(
+    id: id,
+    kind: .canvas,
+    createdAt: createdAt,
+    title: "Primary button",
+    sourcePath: "src/Button.tsx",
+    variants: [
+      StudioVariant(name: "solid", html: "<button>Go</button>", css: "button { color: red; }", notes: "default"),
+      StudioVariant(name: "ghost", html: "<button>Go</button>", css: "button { color: blue; }", width: 320),
+    ],
+    warnings: ["ghost: dropped a script"],
+    sourceProvider: .claude,
+    sourceSessionId: "session-1",
+    sourceProjectPath: "/tmp/project",
+    sourceProcessId: 42
+  )
+}
diff --git a/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioCSSScoperTests.swift b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioCSSScoperTests.swift
new file mode 100644
index 00000000..53f391a9
--- /dev/null
+++ b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioCSSScoperTests.swift
@@ -0,0 +1,154 @@
+import Foundation
+import Testing
+
+@testable import AgentHubCLIKit
+
+@Suite("StudioCSSScoper")
+struct StudioCSSScoperTests {
+  private let scope = StudioCSSScoper.artboardSelector(forVariantName: "ghost")
+
+  private func scoped(_ css: String, variant: String = "ghost") throws -> String {
+    try StudioCSSScoper.scope(css, variantName: variant).css
+  }
+
+  @Test("Plain selectors are prefixed, including every member of a selector list")
+  func plainSelectorsArePrefixed() throws {
+    let out = try scoped("a, .b > c { color: red; }")
+    #expect(out == "\(scope) a, \(scope) .b > c {\n  color: red;\n}")
+  }
+
+  @Test(":root, html, and body become the artboard itself")
+  func rootSelectorsBecomeArtboard() throws {
+    #expect(try scoped(":root { --x: 1; }") == "\(scope) {\n  --x: 1;\n}")
+    #expect(try scoped("body { background: #111; }") == "\(scope) {\n  background: #111;\n}")
+    #expect(try scoped("html { font-size: 14px; }") == "\(scope) {\n  font-size: 14px;\n}")
+    #expect(try scoped("body.dark .card { color: white; }") == "\(scope).dark .card {\n  color: white;\n}")
+    #expect(try scoped("body > .app { margin: 0; }") == "\(scope) > .app {\n  margin: 0;\n}")
+  }
+
+  @Test("`html body .x` collapses to one scope, not two")
+  func htmlBodyCollapses() throws {
+    #expect(try scoped("html body .x { top: 0; }") == "\(scope) .x {\n  top: 0;\n}")
+    #expect(try scoped("html.dark body .x { top: 0; }") == "\(scope) .x {\n  top: 0;\n}")
+  }
+
+  @Test("`html, body` dedupes to a single artboard selector")
+  func htmlBodyListDedupes() throws {
+    #expect(try scoped("html, body { margin: 0; }") == "\(scope) {\n  margin: 0;\n}")
+  }
+
+  @Test("Tag names that merely start with body/html are ordinary selectors")
+  func lookalikeTagsAreOrdinary() throws {
+    #expect(try scoped("bodyguard { x: 1; }") == "\(scope) bodyguard {\n  x: 1;\n}")
+    #expect(try scoped(".body { x: 1; }") == "\(scope) .body {\n  x: 1;\n}")
+  }
+
+  @Test("Universal selector is scoped beneath the artboard")
+  func universalSelectorIsScoped() throws {
+    #expect(try scoped("* { box-sizing: border-box; }") == "\(scope) * {\n  box-sizing: border-box;\n}")
+  }
+
+  @Test("Commas inside :is() and attribute selectors do not split the list")
+  func nestedCommasDoNotSplit() throws {
+    let out = try scoped(":is(h1, h2), [data-x=\"a,b\"] { m: 0; }")
+    #expect(out == "\(scope) :is(h1, h2), \(scope) [data-x=\"a,b\"] {\n  m: 0;\n}")
+  }
+
+  @Test("@media, @supports, @container and @layer blocks recurse")
+  func conditionalGroupsRecurse() throws {
+    let out = try scoped("@media (max-width: 600px) { .a { x: 1; } body { y: 2; } }")
+    #expect(out == "@media (max-width: 600px) {\n  \(scope) .a {\n    x: 1;\n  }\n  \(scope) {\n    y: 2;\n  }\n}")
+    #expect(try scoped("@supports (display: grid) { .g { d: grid; } }").hasPrefix("@supports (display: grid) {\n  \(scope) .g"))
+    #expect(try scoped("@container card (min-width: 400px) { .g { d: grid; } }").contains("\(scope) .g"))
+    #expect(try scoped("@layer base { .g { d: grid; } }").contains("\(scope) .g"))
+  }
+
+  @Test("@keyframes are renamed per variant and animation references follow")
+  func keyframesAreRenamed() throws {
+    let out = try scoped("""
+      .btn { animation: pulse 1s infinite, fade-in 300ms; }
+      .x { animation-name: fade-in; }
+      @keyframes pulse { from { opacity: 0 } to { opacity: 1 } }
+      @keyframes fade-in { from { opacity: 0 } }
+      """)
+    #expect(out.contains("@keyframes pulse-ghost {"))
+    #expect(out.contains("@keyframes fade-in-ghost {"))
+    #expect(out.contains("animation: pulse-ghost 1s infinite, fade-in-ghost 300ms;"))
+    #expect(out.contains("animation-name: fade-in-ghost;"))
+    #expect(!out.contains("animation: pulse 1s"))
+  }
+
+  @Test("Keyframe renaming does not touch names that merely contain a keyframe name")
+  func keyframeRenameIsWholeWord() throws {
+    let out = try scoped(".a { animation: pulse-slow 1s; } @keyframes pulse { to { o: 1 } }")
+    #expect(out.contains("animation: pulse-slow 1s;"))
+  }
+
+  @Test("@font-face is hoisted verbatim")
+  func fontFaceIsVerbatim() throws {
+    let out = try scoped("@font-face { font-family: X; src: url(x.woff2); }")
+    #expect(out == "@font-face {\n  font-family: X; src: url(x.woff2);\n}")
+    #expect(try StudioCSSScoper.scope("@font-face { font-family: X; }", variantName: "g").warnings.isEmpty)
+  }
+
+  @Test("@import is dropped with a warning; @charset silently")
+  func importIsDroppedWithWarning() throws {
+    let out = try StudioCSSScoper.scope("@charset \"utf-8\"; @import url(\"x.css\"); .a { b: c; }", variantName: "ghost")
+    #expect(out.css == "\(scope) .a {\n  b: c;\n}")
+    #expect(out.warnings.count == 1)
+    #expect(out.warnings[0].contains("@import"))
+  }
+
+  @Test("!important, inline strings, and comments survive")
+  func declarationsSurvive() throws {
+    let out = try scoped("/* c */ .a { content: \"}\"; color: red !important; }")
+    #expect(out == "\(scope) .a {\n  content: \"}\"; color: red !important;\n}")
+  }
+
+  @Test("Nested rules inside a style rule are kept relative to the scoped parent")
+  func nestedRulesAreKept() throws {
+    let out = try scoped(".a { color: red; &:hover { color: blue; } }")
+    #expect(out == "\(scope) .a {\n  color: red; &:hover { color: blue; }\n}")
+  }
+
+  @Test("Unbalanced braces are a parse error carrying the offset")
+  func unbalancedBracesThrow() {
+    #expect(throws: StudioCSSScoper.ParseError.self) {
+      try StudioCSSScoper.scope(".a { color: red;", variantName: "g")
+    }
+    #expect(throws: StudioCSSScoper.ParseError.self) {
+      try StudioCSSScoper.scope(".a { color: red; } }", variantName: "g")
+    }
+    do {
+      _ = try StudioCSSScoper.scope(".ok { x: 1; } .broken { y: 2;", variantName: "g")
+      Issue.record("expected a parse error")
+    } catch let error as StudioCSSScoper.ParseError {
+      #expect(error.offset == 14)
+      #expect(error.reason.contains("missing '}'"))
+    } catch {
+      Issue.record("unexpected error \(error)")
+    }
+  }
+
+  @Test("Two variants styling the same tag get disjoint selectors")
+  func variantsGetDisjointSelectors() throws {
+    let a = try scoped("button { color: red; }", variant: "A")
+    let b = try scoped("button { color: blue; }", variant: "B")
+    #expect(a.hasPrefix(".studio-artboard[data-variant=\"A\"] button"))
+    #expect(b.hasPrefix(".studio-artboard[data-variant=\"B\"] button"))
+    #expect(a != b)
+  }
+
+  @Test("Variant names are escaped in the attribute selector and slugged for identifiers")
+  func namesAreEscapedAndSlugged() {
+    #expect(StudioCSSScoper.artboardSelector(forVariantName: "say \"hi\"") == ".studio-artboard[data-variant=\"say \\\"hi\\\"\"]")
+    #expect(StudioCSSScoper.slug("Primary CTA (v2)") == "primary-cta-v2")
+    #expect(StudioCSSScoper.slug("!!!") == "variant")
+  }
+
+  @Test("Empty CSS scopes to empty output")
+  func emptyCSS() throws {
+    #expect(try scoped("") == "")
+    #expect(try scoped("   \n /* nothing */ ") == "")
+  }
+}
diff --git a/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioFragmentNormalizerTests.swift b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioFragmentNormalizerTests.swift
new file mode 100644
index 00000000..e6c68ea6
--- /dev/null
+++ b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioFragmentNormalizerTests.swift
@@ -0,0 +1,64 @@
+import Foundation
+import Testing
+
+@testable import AgentHubCLIKit
+
+@Suite("StudioFragmentNormalizer")
+struct StudioFragmentNormalizerTests {
+  @Test("A full document is reduced to its body fragment with styles hoisted")
+  func documentBecomesFragment() {
+    let out = StudioFragmentNormalizer.normalize("""
+      <!DOCTYPE html>
+      <html lang="en">
+      <head>
+        <meta charset="utf-8">
+        <title>x</title>
+        <style>.btn { color: red; }</style>
+      </head>
+      <body class="dark">
+        <button class="btn">Go</button>
+      </body>
+      </html>
+      """)
+    #expect(out.html == "<button class=\"btn\">Go</button>")
+    #expect(out.css == ".btn { color: red; }")
+    #expect(out.warnings.isEmpty)
+  }
+
+  @Test("Scripts are stripped and reported")
+  func scriptsAreStripped() {
+    let out = StudioFragmentNormalizer.normalize("<div>a</div><script>alert(1)</script><SCRIPT src=\"x.js\"></SCRIPT>")
+    #expect(out.html == "<div>a</div>")
+    #expect(out.warnings.count == 1)
+    #expect(out.warnings[0].contains("2 <script>"))
+  }
+
+  @Test("External stylesheets are dropped and reported")
+  func externalStylesheetsAreDropped() {
+    let out = StudioFragmentNormalizer.normalize("<link rel=\"stylesheet\" href=\"a.css\"><p>x</p>")
+    #expect(out.html == "<p>x</p>")
+    #expect(out.warnings.count == 1)
+    #expect(out.warnings[0].contains("external stylesheet"))
+  }
+
+  @Test("Multiple style blocks are concatenated in order")
+  func multipleStylesConcatenate() {
+    let out = StudioFragmentNormalizer.normalize("<style>a{}</style><b>x</b><style media=\"screen\">b{}</style>")
+    #expect(out.html == "<b>x</b>")
+    #expect(out.css == "a{}\n\nb{}")
+  }
+
+  @Test("A commented-out script is not reported as stripped")
+  func commentedScriptIsNotReported() {
+    let out = StudioFragmentNormalizer.normalize("<!-- <script>x</script> --><i>y</i>")
+    #expect(out.html == "<i>y</i>")
+    #expect(out.warnings.isEmpty)
+  }
+
+  @Test("A bare fragment passes through untouched")
+  func fragmentPassesThrough() {
+    let out = StudioFragmentNormalizer.normalize("<button class=\"x\">Go</button>")
+    #expect(out.html == "<button class=\"x\">Go</button>")
+    #expect(out.css.isEmpty)
+  }
+}
diff --git a/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioIndexStoreTests.swift b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioIndexStoreTests.swift
new file mode 100644
index 00000000..264fdb5d
--- /dev/null
+++ b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioIndexStoreTests.swift
@@ -0,0 +1,39 @@
+import Foundation
+import Testing
+
+@testable import AgentHubCLIKit
+
+@Suite("StudioIndexStore")
+struct StudioIndexStoreTests {
+  @Test("Index round-trips and is mirrored to alias paths")
+  func indexRoundTripsAndMirrors() throws {
+    let root = FileManager.default.temporaryDirectory
+      .appendingPathComponent("agenthub-studio-index-\(UUID().uuidString)", isDirectory: true)
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = StudioIndexStore(directoryURL: root)
+    let entry = StudioIndexEntry(artifact: makeCanvas(id: "c1"), documentPath: "/tmp/studio/c1/index.html", payloadPath: "/tmp/studio/c1/artifact.json")
+    let index = StudioIndex(projectPath: "/repo", updatedAt: Date(timeIntervalSince1970: 5), artifacts: [entry])
+
+    try store.write(index, aliasPaths: ["/repo-wt-feature"])
+
+    #expect(store.read(projectPath: "/repo") == index)
+    #expect(store.read(projectPath: "/repo-wt-feature") == index)
+    #expect(store.read(projectPath: "/other") == nil)
+    #expect(store.read(projectPath: "/repo")?.artifacts.first?.variantNames == ["solid", "ghost"])
+    #expect(store.read(projectPath: "/repo")?.artifacts.first?.payloadPath == "/tmp/studio/c1/artifact.json")
+
+    // Older indexes without payloadPath still decode.
+    let legacy = """
+      {"projectPath":"/legacy","updatedAt":"2026-01-01T00:00:00Z","artifacts":[{"id":"x","kind":"canvas","title":"T","variantNames":["a"],"revision":1,"updatedAt":"2026-01-01T00:00:00Z"}]}
+      """
+    try Data(legacy.utf8).write(to: store.fileURL(forProjectPath: "/legacy"))
+    #expect(store.read(projectPath: "/legacy")?.artifacts.first?.payloadPath == nil)
+  }
+
+  @Test("File names are percent-encoded so separator-lookalikes never collide")
+  func fileNamesArePercentEncoded() {
+    #expect(StudioIndexStore.fileName(forProjectPath: "/a/b-c") != StudioIndexStore.fileName(forProjectPath: "/a-b/c"))
+    #expect(!StudioIndexStore.fileName(forProjectPath: "/a/b").contains("/"))
+  }
+}
diff --git a/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioTweakPropsTests.swift b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioTweakPropsTests.swift
new file mode 100644
index 00000000..e117d465
--- /dev/null
+++ b/app/modules/AgentHubCLI/Tests/AgentHubCLIKitTests/StudioTweakPropsTests.swift
@@ -0,0 +1,141 @@
+import Foundation
+import Testing
+
+@testable import AgentHubCLIKit
+
+@Suite("StudioTweakProps")
+struct StudioTweakPropsTests {
+  private func json(_ text: String) throws -> Any {
+    try JSONSerialization.jsonObject(with: Data(text.utf8))
+  }
+
+  @Test("Parses every type from a name-keyed object, sorted by name")
+  func parsesEveryType() throws {
+    let props = try StudioTweakPropParser.parse(try json("""
+      {
+        "radius": { "type": "slider", "value": 12, "min": 0, "max": 32, "step": 2, "unit": "px", "label": "Corner radius" },
+        "accent": { "type": "color", "value": "#0a84ff" },
+        "weight": { "type": "select", "value": "600", "options": ["400", "600", "700"] },
+        "shadow": { "type": "toggle", "value": true },
+        "cta":    { "type": "text", "value": "Continue" }
+      }
+      """))
+    #expect(props.map(\.name) == ["accent", "cta", "radius", "shadow", "weight"])
+    let radius = try #require(props.first { $0.name == "radius" })
+    #expect(radius.type == .slider)
+    #expect(radius.value == .number(12))
+    #expect(radius.minimum == 0 && radius.maximum == 32 && radius.step == 2)
+    #expect(radius.unit == "px")
+    #expect(radius.label == "Corner radius")
+    #expect(radius.cssValue == "12px")
+    #expect(radius.cssVariableName == "--radius")
+    #expect(props.first { $0.name == "shadow" }?.cssValue == "1")
+    #expect(props.first { $0.name == "weight" }?.options == ["400", "600", "700"])
+    #expect(props.first { $0.name == "cta" }?.label == "cta")
+  }
+
+  @Test("An array form preserves declaration order")
+  func arrayPreservesOrder() throws {
+    let props = try StudioTweakPropParser.parse(try json("""
+      [ { "name": "zeta", "type": "toggle", "value": false }, { "name": "alpha", "type": "text", "value": "x" } ]
+      """))
+    #expect(props.map(\.name) == ["zeta", "alpha"])
+  }
+
+  @Test("JSON true/false and 1/0 are told apart")
+  func booleansVersusNumbers() throws {
+    let props = try StudioTweakPropParser.parse(try json("""
+      { "size": { "type": "slider", "value": 1 }, "on": { "type": "toggle", "value": true } }
+      """))
+    #expect(props.first { $0.name == "size" }?.value == .number(1))
+    #expect(props.first { $0.name == "on" }?.value == .boolean(true))
+    #expect(throws: StudioTweakPropParser.ValidationError.self) {
+      _ = try StudioTweakPropParser.parse(try json("{ \"on\": { \"type\": \"toggle\", \"value\": 1 } }"))
+    }
+  }
+
+  @Test("Rejects bad names, unknown types, mismatched values, selects without options, out-of-range sliders")
+  func rejectsInvalid() throws {
+    let bad: [String] = [
+      "{ \"1st\": { \"type\": \"text\", \"value\": \"x\" } }",
+      "{ \"has space\": { \"type\": \"text\", \"value\": \"x\" } }",
+      "{ \"x\": { \"type\": \"knob\", \"value\": 1 } }",
+      "{ \"x\": { \"type\": \"slider\", \"value\": \"big\" } }",
+      "{ \"x\": { \"type\": \"select\", \"value\": \"a\" } }",
+      "{ \"x\": { \"type\": \"select\", \"value\": \"c\", \"options\": [\"a\", \"b\"] } }",
+      "{ \"x\": { \"type\": \"slider\", \"value\": 50, \"min\": 0, \"max\": 10 } }",
+      "{ \"x\": { \"type\": \"slider\", \"value\": 5, \"min\": 10, \"max\": 0 } }",
+      "{ \"x\": \"not an object\" }",
+      "[ { \"type\": \"text\", \"value\": \"no name\" } ]",
+    ]
+    for text in bad {
+      #expect(throws: StudioTweakPropParser.ValidationError.self, "\(text)") {
+        _ = try StudioTweakPropParser.parse(try json(text))
+      }
+    }
+    #expect(throws: StudioTweakPropParser.ValidationError.self) {
+      _ = try StudioTweakPropParser.parse("nope")
+    }
+    #expect(try StudioTweakPropParser.parse(nil).isEmpty)
+    #expect(try StudioTweakPropParser.parse(NSNull()).isEmpty)
+  }
+
+  @Test("Unused props are detected by CSS variable or data-prop reference")
+  func unusedProps() {
+    let props = [
+      StudioTweakProp(name: "radius", type: .slider, value: .number(1)),
+      StudioTweakProp(name: "cta", type: .text, value: .string("Go")),
+      StudioTweakProp(name: "ghost", type: .toggle, value: .boolean(true)),
+    ]
+    let variants = [
+      StudioVariant(name: "a", html: "<button data-prop=\"cta\">Go</button>", css: ".b { border-radius: var(--radius, 4px); }"),
+      StudioVariant(name: "b", html: "<i style=\"opacity: var(--radius)\">x</i>", css: ""),
+    ]
+    #expect(StudioTweakPropParser.unusedProps(props, variants: variants) == ["ghost"])
+    #expect(StudioTweakPropParser.unusedProps([], variants: variants).isEmpty)
+  }
+
+  @Test("Too many props is rejected")
+  func tooMany() throws {
+    let entries = (0..<(StudioTweakPropParser.maxProps + 1)).map { "\"p\($0)\": { \"type\": \"text\", \"value\": \"x\" }" }
+    #expect(throws: StudioTweakPropParser.ValidationError.self) {
+      _ = try StudioTweakPropParser.parse(try json("{ \(entries.joined(separator: ",")) }"))
+    }
+  }
+
+  @Test("CSS values: fractional sliders, unitless numbers, raw strings")
+  func cssValues() {
+    #expect(StudioTweakProp(name: "o", type: .slider, value: .number(0.5)).cssValue == "0.5")
+    #expect(StudioTweakProp(name: "o", type: .slider, value: .number(2), unit: "rem").cssValue == "2rem")
+    #expect(StudioTweakProp(name: "c", type: .color, value: .string("rgb(1 2 3)")).cssValue == "rgb(1 2 3)")
+    #expect(StudioTweakProp(name: "t", type: .toggle, value: .boolean(false)).cssValue == "0")
+    #expect(StudioTweakProp(name: "t", type: .toggle, value: .boolean(false)).cssValue(for: .boolean(true)) == "1")
+  }
+
+  @Test("Props round-trip through Codable and older payloads without props still decode")
+  func codable() throws {
+    let artifact = makeCanvas(id: "c").withContent(props: [
+      StudioTweakProp(name: "radius", type: .slider, value: .number(12), minimum: 0, maximum: 32, unit: "px"),
+      StudioTweakProp(name: "on", type: .toggle, value: .boolean(true)),
+      StudioTweakProp(name: "cta", type: .text, value: .string("Go")),
+    ])
+    let encoder = JSONEncoder(); encoder.dateEncodingStrategy = .iso8601
+    let decoder = JSONDecoder(); decoder.dateDecodingStrategy = .iso8601
+    let data = try encoder.encode(artifact)
+    #expect(try decoder.decode(StudioArtifact.self, from: data) == artifact)
+
+    var object = try #require(try JSONSerialization.jsonObject(with: data) as? [String: Any])
+    object.removeValue(forKey: "props")
+    object.removeValue(forKey: "warnings")
+    let legacy = try decoder.decode(StudioArtifact.self, from: try JSONSerialization.data(withJSONObject: object))
+    #expect(legacy.props.isEmpty)
+    #expect(legacy.warnings.isEmpty)
+    #expect(legacy.id == "c")
+
+    // Declaration is what the host page hands to dc_set_props.
+    let declaration = artifact.props[0].declaration
+    #expect(declaration["type"] as? String == "slider")
+    #expect(declaration["unit"] as? String == "px")
+    #expect((declaration["value"] as? Double) == 12)
+  }
+}
diff --git a/app/modules/AgentHubCore/Package.swift b/app/modules/AgentHubCore/Package.swift
index e4a93153..36b8bed0 100644
--- a/app/modules/AgentHubCore/Package.swift
+++ b/app/modules/AgentHubCore/Package.swift
@@ -156,6 +156,7 @@ let package = Package(
         .copy("Design/Theme/BundledThemes"),
         .copy("Resources/ClaudeHook"),
         .copy("Resources/AgentHubWorktreeSkill"),
+        .copy("Resources/AgentHubStudioSkill"),
       ],
       swiftSettings: [
         .swiftLanguageMode(.v5)
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Configuration/AgentHubDefaults.swift b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/AgentHubDefaults.swift
index 0e85675d..76bf74ec 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/Configuration/AgentHubDefaults.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/AgentHubDefaults.swift
@@ -255,6 +255,8 @@ public enum AgentHubDefaults {
   /// server (simulator build/run, UI automation, screenshots) configured.
   /// Type: Bool (default: true)
   public static let xcodeBuildMCPEnabled = "\(keyPrefix)features.xcodeBuildMCPEnabled"
+  /// Whether agent sessions get the Studio system-prompt nudge (default on).
+  public static let studioAgentGuidanceEnabled = "\(keyPrefix)features.studioAgentGuidanceEnabled"
 
   /// Inspector payload level used by debug web preview inspect flows
   /// Type: String (default: "regular")
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Configuration/AgentHubProvider.swift b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/AgentHubProvider.swift
index 4f96cd4b..9ba812de 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/Configuration/AgentHubProvider.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/AgentHubProvider.swift
@@ -55,6 +55,7 @@ public final class AgentHubProvider {
   private let worktreeDeletionRequestMonitorOverride: (any WorktreeDeletionRequestMonitorProtocol)?
   private let sessionNameRequestMonitorOverride: (any SessionNameRequestMonitorProtocol)?
   private let measurementRecordMonitorOverride: (any MeasurementRecordMonitorProtocol)?
+  private let studioArtifactMonitorOverride: (any StudioArtifactMonitorProtocol)?
 
   // MARK: - Lazy Services
 
@@ -198,6 +199,28 @@ public final class AgentHubProvider {
     codexTarget: codexSessionsViewModel
   )
 
+  /// Studio artifacts for every project, shared by both provider view models.
+  /// Paths resolve through `AgentHubApplicationSupport` so a test process never
+  /// touches the real index or document store; the CLI computes the same
+  /// directory from `AGENTHUB_APP_SUPPORT_DIR` / Application Support.
+  public private(set) lazy var studioLibrary: StudioLibrary = StudioLibrary(
+    persistence: metadataStore,
+    index: StudioIndexStore(
+      directoryURL: AgentHubApplicationSupport.baseDirectoryURL.appendingPathComponent("studio-index", isDirectory: true)
+    )
+  )
+
+  /// Watches Studio artifacts written by the bundled `agenthub` MCP server.
+  public private(set) lazy var studioArtifactMonitor: any StudioArtifactMonitorProtocol = studioArtifactMonitorOverride
+    ?? StudioArtifactMonitor(queue: StudioArtifactQueue(
+      directoryURL: AgentHubApplicationSupport.baseDirectoryURL.appendingPathComponent("studio-records", isDirectory: true)
+    ))
+
+  public private(set) lazy var studioArtifactHandler: any StudioArtifactHandlingProtocol = StudioArtifactHandler(
+    claudeTarget: claudeSessionsViewModel,
+    codexTarget: codexSessionsViewModel
+  )
+
   /// Watches the worktree-progress sidecar directory the `agenthub` CLI writes
   /// during MCP-initiated creations, so the app can surface live git progress.
   public private(set) lazy var worktreeProgressSidecarWatcher: any WorktreeProgressSidecarWatcherProtocol = WorktreeProgressSidecarWatcher()
@@ -216,6 +239,7 @@ public final class AgentHubProvider {
   private var isWorktreeDeletionRequestMonitoringStarted = false
   private var isSessionNameRequestMonitoringStarted = false
   private var isMeasurementRecordMonitoringStarted = false
+  private var isStudioArtifactMonitoringStarted = false
   private var isWorktreeProgressMonitoringStarted = false
 
   // MARK: - GitHub Integration
@@ -354,7 +378,8 @@ public final class AgentHubProvider {
     worktreeLaunchRequestMonitor: (any WorktreeLaunchRequestMonitorProtocol)? = nil,
     worktreeDeletionRequestMonitor: (any WorktreeDeletionRequestMonitorProtocol)? = nil,
     sessionNameRequestMonitor: (any SessionNameRequestMonitorProtocol)? = nil,
-    measurementRecordMonitor: (any MeasurementRecordMonitorProtocol)? = nil
+    measurementRecordMonitor: (any MeasurementRecordMonitorProtocol)? = nil,
+    studioArtifactMonitor: (any StudioArtifactMonitorProtocol)? = nil
   ) {
     self.configuration = configuration
     terminalBackend = .storedPreference
@@ -366,6 +391,7 @@ public final class AgentHubProvider {
     worktreeDeletionRequestMonitorOverride = worktreeDeletionRequestMonitor
     sessionNameRequestMonitorOverride = sessionNameRequestMonitor
     measurementRecordMonitorOverride = measurementRecordMonitor
+    studioArtifactMonitorOverride = studioArtifactMonitor
     if let metadataStore {
       Task {
         await TerminalProcessRegistry.shared.configure(store: metadataStore)
@@ -510,6 +536,7 @@ public final class AgentHubProvider {
       terminalWorkspaceStore: metadataStore
     )
     vm.agentHubProvider = self
+    vm.studioLibrary = studioLibrary
     return vm
   }
 
@@ -552,9 +579,27 @@ public final class AgentHubProvider {
     startWorktreeDeletionQueueMonitoring()
     startSessionNameQueueMonitoring()
     startMeasurementRecordMonitoring()
+    startStudioArtifactMonitoring()
     startWorktreeProgressMonitoring()
   }
 
+  private func startStudioArtifactMonitoring() {
+    guard !isStudioArtifactMonitoringStarted else { return }
+    isStudioArtifactMonitoringStarted = true
+
+    let monitor = studioArtifactMonitor
+    let library = studioLibrary
+    Task {
+      await library.reconcileStorage()
+      await monitor.start { [weak self] queued in
+        guard let self else {
+          throw StudioArtifactHandlingError.sessionUnavailable
+        }
+        try await self.studioArtifactHandler.handle(queued.artifact)
+      }
+    }
+  }
+
   private func startWorktreeProgressMonitoring() {
     guard !isWorktreeProgressMonitoringStarted else { return }
     isWorktreeProgressMonitoringStarted = true
@@ -669,6 +714,15 @@ public final class AgentHubProvider {
       }
     }
 
+    if isStudioArtifactMonitoringStarted {
+      isStudioArtifactMonitoringStarted = false
+
+      let monitor = studioArtifactMonitor
+      Task {
+        await monitor.stop()
+      }
+    }
+
   }
 
   /// Sweeps any previously-installed approval hooks, wipes stale claim files,
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Configuration/CLICommandConfiguration.swift b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/CLICommandConfiguration.swift
index a925a838..52c36cf3 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/Configuration/CLICommandConfiguration.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/CLICommandConfiguration.swift
@@ -125,6 +125,9 @@ public struct CLICommandConfiguration: Codable, Sendable {
     allowedTools: [String]? = nil,
     disallowedTools: [String]? = nil,
     codexApprovalPolicy: String? = nil,
+    /// The user's global `~/.codex/config.toml` approval policy, when AgentHub
+    /// passes none of its own. Only used to decide MCP tool approval modes.
+    codexGlobalApprovalPolicy: String? = nil,
     xcodeBuildMCPBootstrap: XcodeBuildMCPBootstrap? = nil,
     appendSystemPrompt: String? = nil
   ) -> [String] {
@@ -208,7 +211,8 @@ public struct CLICommandConfiguration: Codable, Sendable {
           providerArgs += codexMCPConfigArgs(
             agentHubCLIPath: agentHubMCPServerPath,
             agentHubEnvironment: agentHubMCPEnvironment,
-            xcodeBuildMCP: xcodeBuildMCPBootstrap
+            xcodeBuildMCP: xcodeBuildMCPBootstrap,
+            approvalPolicy: codexApprovalPolicy ?? codexGlobalApprovalPolicy
           )
         }
         // developer_instructions is a config override, not conversation
@@ -226,7 +230,8 @@ public struct CLICommandConfiguration: Codable, Sendable {
         providerArgs += codexMCPConfigArgs(
           agentHubCLIPath: agentHubMCPServerPath,
           agentHubEnvironment: agentHubMCPEnvironment,
-          xcodeBuildMCP: xcodeBuildMCPBootstrap
+          xcodeBuildMCP: xcodeBuildMCPBootstrap,
+          approvalPolicy: codexApprovalPolicy ?? codexGlobalApprovalPolicy
         )
       }
       if let appendSystemPrompt, !appendSystemPrompt.isEmpty {
@@ -395,10 +400,24 @@ public struct CLICommandConfiguration: Codable, Sendable {
     return encoded
   }
 
+  /// Codex prompts per MCP tool call unless the server's tools are marked
+  /// `auto` (`mcp_servers.<name>.default_tools_approval_mode`); under
+  /// `approval_policy = never` a prompt is not possible and the call fails with
+  /// "MCP tool call requires approval, but approval policy is never".
+  ///
+  /// The bundled `agenthub` server is always `auto`: its tools are AgentHub's
+  /// own, local, and scoped to AgentHub state (Studio, measurements, session
+  /// names, worktrees it manages) — a prompt per Studio render is noise, and a
+  /// hard failure defeats the feature. XcodeBuildMCP builds and drives
+  /// simulators, so it is `auto` only when the user already asked for
+  /// autonomy (`never` / `full-auto`); otherwise Codex's own default stands.
+  /// Older Codex ignores the key; newer rejects unknown *values*, so only the
+  /// documented `auto` is ever emitted.
   private func codexMCPConfigArgs(
     agentHubCLIPath: String?,
     agentHubEnvironment: [String: String],
-    xcodeBuildMCP: XcodeBuildMCPBootstrap?
+    xcodeBuildMCP: XcodeBuildMCPBootstrap?,
+    approvalPolicy: String? = nil
   ) -> [String] {
     var args: [String] = []
     if let agentHubCLIPath, !agentHubCLIPath.isEmpty {
@@ -408,7 +427,8 @@ public struct CLICommandConfiguration: Codable, Sendable {
       )
       args += [
         "-c", "mcp_servers.agenthub.command=\(tomlStringLiteral("/bin/sh"))",
-        "-c", "mcp_servers.agenthub.args=\(tomlStringArray(["-lc", script]))"
+        "-c", "mcp_servers.agenthub.args=\(tomlStringArray(["-lc", script]))",
+        "-c", "mcp_servers.agenthub.default_tools_approval_mode=\(tomlStringLiteral("auto"))"
       ]
     }
     if let xcodeBuildMCP {
@@ -417,6 +437,9 @@ public struct CLICommandConfiguration: Codable, Sendable {
         "-c", "mcp_servers.XcodeBuildMCP.args=\(tomlStringArray(["-lc", xcodeBuildMCPShellScript()]))",
         "-c", "mcp_servers.XcodeBuildMCP.tool_timeout_sec=600"
       ]
+      if approvalPolicy == "never" || approvalPolicy == "full-auto" {
+        args += ["-c", "mcp_servers.XcodeBuildMCP.default_tools_approval_mode=\(tomlStringLiteral("auto"))"]
+      }
       for (key, value) in xcodeBuildMCP.environment.sorted(by: { $0.key < $1.key }) {
         args += ["-c", "mcp_servers.XcodeBuildMCP.env.\(key)=\(tomlStringLiteral(value))"]
       }
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Configuration/CodexGlobalConfigReader.swift b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/CodexGlobalConfigReader.swift
new file mode 100644
index 00000000..7781626e
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/CodexGlobalConfigReader.swift
@@ -0,0 +1,74 @@
+//
+//  CodexGlobalConfigReader.swift
+//  AgentHub
+//
+//  Reads the few top-level keys of the user's `~/.codex/config.toml` that
+//  change how AgentHub must launch Codex. Read-only; AgentHub never writes it.
+//
+
+import Foundation
+
+public enum CodexGlobalConfigReader {
+  /// `~/.codex/config.toml`, honouring `CODEX_HOME` the way Codex does.
+  public static func defaultConfigURL(
+    environment: [String: String] = ProcessInfo.processInfo.environment,
+    homeDirectory: URL = FileManager.default.homeDirectoryForCurrentUser
+  ) -> URL {
+    if let codexHome = environment["CODEX_HOME"], !codexHome.isEmpty {
+      return URL(fileURLWithPath: (codexHome as NSString).expandingTildeInPath, isDirectory: true)
+        .appendingPathComponent("config.toml", isDirectory: false)
+    }
+    return homeDirectory
+      .appendingPathComponent(".codex", isDirectory: true)
+      .appendingPathComponent("config.toml", isDirectory: false)
+  }
+
+  /// The user's global `approval_policy` (`untrusted`, `on-request`,
+  /// `on-failure`, `never`), or nil when unset/unreadable.
+  ///
+  /// Codex 0.148+ prompts per MCP tool call unless a server is `auto`, and a
+  /// global `never` turns that prompt into a hard failure — a policy AgentHub
+  /// cannot see from its own settings. Only the top-level key counts: a value
+  /// inside a `[profiles.x]` or `[projects."…"]` table is scoped and ignored.
+  public static func approvalPolicy(configURL: URL = defaultConfigURL()) -> String? {
+    guard let content = try? String(contentsOf: configURL, encoding: .utf8) else { return nil }
+    return topLevelValue(forKey: "approval_policy", in: content)
+  }
+
+  static func topLevelValue(forKey key: String, in content: String) -> String? {
+    for rawLine in content.components(separatedBy: .newlines) {
+      let line = stripComment(rawLine).trimmingCharacters(in: .whitespaces)
+      guard !line.isEmpty else { continue }
+      if line.hasPrefix("[") { return nil } // first table header ends the top level
+      guard let equals = line.firstIndex(of: "=") else { continue }
+      let name = line[..<equals].trimmingCharacters(in: .whitespaces)
+      guard name == key else { continue }
+      let raw = line[line.index(after: equals)...].trimmingCharacters(in: .whitespaces)
+      return unquoted(raw)
+    }
+    return nil
+  }
+
+  private static func unquoted(_ value: String) -> String? {
+    guard value.count >= 2 else { return value.isEmpty ? nil : value }
+    if (value.hasPrefix("\"") && value.hasSuffix("\"")) || (value.hasPrefix("'") && value.hasSuffix("'")) {
+      return String(value.dropFirst().dropLast())
+    }
+    return value
+  }
+
+  private static func stripComment(_ line: String) -> String {
+    var result = ""
+    var quote: Character?
+    var previous: Character?
+    for character in line {
+      if character == "\"" || character == "'" {
+        if quote == nil { quote = character } else if quote == character, previous != "\\" { quote = nil }
+      }
+      if character == "#", quote == nil { break }
+      result.append(character)
+      previous = character
+    }
+    return result
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Configuration/StudioAgentGuidance.swift b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/StudioAgentGuidance.swift
new file mode 100644
index 00000000..d9fc37ae
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Configuration/StudioAgentGuidance.swift
@@ -0,0 +1,42 @@
+//
+//  StudioAgentGuidance.swift
+//  AgentHub
+//
+//  System-prompt-level guidance injected into agent sessions so they reach
+//  for the Studio tools when the user asks to *see* something. Tool
+//  descriptions alone are advisory, and both nouns Studio uses ("design",
+//  "artifact") are also claimed by other surfaces the model knows well
+//  (a /design skill, an Artifact tool), so without a system-prompt line the
+//  model routinely edits project files or publishes elsewhere instead — and
+//  the result never appears in the panel the user is watching.
+//
+
+import Foundation
+
+public enum StudioAgentGuidance {
+  /// Default-on; Settings › Studio can turn the nudge off for users who would
+  /// rather trigger Studio explicitly (the `/agenthub-studio` skill stays).
+  public static func isEnabled(defaults: UserDefaults = .standard) -> Bool {
+    defaults.object(forKey: AgentHubDefaults.studioAgentGuidanceEnabled) as? Bool ?? true
+  }
+
+  /// Appended to Claude sessions and passed as Codex developer instructions
+  /// whenever the bundled `agenthub` MCP server is attached. Kept compact:
+  /// which tool for which ask, list-first, and the one hard boundary.
+  public static let systemPrompt = """
+    This session runs inside AgentHub, which shows a Studio panel beside it. When the user asks to \
+    see, compare, mock up, or explore options, versions, or variants of any UI (a button, card, \
+    form, screen, landing page…), or asks "what would it look like", render them with the \
+    agenthub_design tool — a canvas of variants — instead of editing project files or publishing \
+    elsewhere. When they ask for something visual that is not a UI comparison (a report, diagram, \
+    dashboard, mockup page, rendered document), render it with agenthub_artifact. Call \
+    agenthub_list_artifacts first when refining something already on screen and re-file with its id \
+    so the panel updates in place. Inside AgentHub, prefer these over claude.ai artifacts or the \
+    /design skill so the result lands in the panel the user is watching. Feedback that arrives from \
+    the Studio panel (comments, crops, tweak requests) asks for a re-file, never for project edits. \
+    When the user picks a variant — in the panel (an "Implement" request) or in conversation ("let's \
+    go with the ghost one") — call agenthub_get_artifact with that variant and implement exactly \
+    the html/css it returns: it includes edits the user made in the panel. Before re-filing an \
+    existing canvas, fetch it the same way so you start from what the user has.
+    """
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Models/StudioArtifactRecord.swift b/app/modules/AgentHubCore/Sources/AgentHub/Models/StudioArtifactRecord.swift
new file mode 100644
index 00000000..53fed67a
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Models/StudioArtifactRecord.swift
@@ -0,0 +1,94 @@
+//
+//  StudioArtifactRecord.swift
+//  AgentHub
+//
+//  SQLite record for one artifact an agent filed into the Studio panel.
+//
+
+import AgentHubCLIKit
+import Foundation
+import GRDB
+
+/// Persisted Studio artifact.
+///
+/// The artifact is stored as an encoded `StudioArtifact` blob rather than a
+/// column per field: its shape (variants, warnings, future layout hints) evolves
+/// with the feature, and a blob keeps that evolution out of the migration list.
+/// `payloadVersion` is the table-specific version for that encoded payload — the
+/// one case the schema rules allow a per-table version column. Only the columns
+/// the app queries on are denormalized.
+///
+/// The database is the source of truth; the served `index.html` on disk is a
+/// cache derived from this row and can always be rewritten from it.
+public struct StudioArtifactRecord: Codable, Equatable, Identifiable, Sendable, FetchableRecord, PersistableRecord {
+  public static let currentPayloadVersion = 1
+
+  public var id: String
+  /// The project this artifact belongs to — the storage scope. Worktrees roll
+  /// up to their parent repo (see `MeasurementProjectScope`).
+  public var projectPath: String
+  /// Which session filed it. Provenance only; never used to decide what shows.
+  public var sessionId: String
+  public var provider: String
+  public var kind: String
+  public var createdAt: Date
+  public var updatedAt: Date
+  public var payloadVersion: Int
+  public var payloadData: Data
+
+  public static var databaseTableName: String { "studio_artifacts" }
+
+  private static var payloadEncoder: JSONEncoder {
+    let encoder = JSONEncoder()
+    encoder.dateEncodingStrategy = .iso8601
+    return encoder
+  }
+
+  private static var payloadDecoder: JSONDecoder {
+    let decoder = JSONDecoder()
+    decoder.dateDecodingStrategy = .iso8601
+    return decoder
+  }
+
+  public init(
+    id: String,
+    projectPath: String,
+    sessionId: String,
+    provider: String,
+    kind: String,
+    createdAt: Date,
+    updatedAt: Date,
+    payloadVersion: Int,
+    payloadData: Data
+  ) {
+    self.id = id
+    self.projectPath = projectPath
+    self.sessionId = sessionId
+    self.provider = provider
+    self.kind = kind
+    self.createdAt = createdAt
+    self.updatedAt = updatedAt
+    self.payloadVersion = payloadVersion
+    self.payloadData = payloadData
+  }
+
+  /// `projectPath` is normalized here so a trailing slash can never split one
+  /// project's artifacts across two keys.
+  public init(artifact: StudioArtifact, projectPath: String, sessionId: String) throws {
+    self.init(
+      id: artifact.id,
+      projectPath: MeasurementProjectScope.normalized(projectPath),
+      sessionId: sessionId,
+      provider: artifact.sourceProvider.commandLineValue,
+      kind: artifact.kind.rawValue,
+      createdAt: artifact.createdAt,
+      updatedAt: artifact.displayDate,
+      payloadVersion: Self.currentPayloadVersion,
+      payloadData: try Self.payloadEncoder.encode(artifact)
+    )
+  }
+
+  public func decodedArtifact() throws -> StudioArtifact {
+    try Self.payloadDecoder.decode(StudioArtifact.self, from: payloadData)
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Resources/AgentHubStudioSkill/SKILL.md b/app/modules/AgentHubCore/Sources/AgentHub/Resources/AgentHubStudioSkill/SKILL.md
new file mode 100644
index 00000000..ae4e5322
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Resources/AgentHubStudioSkill/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: agenthub-studio
+description: Render UI variants or any visual — mockups, reports, diagrams, dashboards — into AgentHub's Studio panel beside this session, on a scratch surface that never touches project files. Use when the user asks to see, compare, mock up, or explore options, versions, or variants of a component or screen, asks "what would it look like", or wants a rendered document. Also invoked explicitly as /agenthub-studio.
+user-invocable: true
+allowed-tools:
+  - mcp__agenthub__agenthub_design
+  - mcp__agenthub__agenthub_artifact
+  - mcp__agenthub__agenthub_list_artifacts
+  - mcp__agenthub__agenthub_get_artifact
+---
+
+# AgentHub Studio
+
+Studio is a scratch surface AgentHub renders beside this session. You render into it; the user points, comments, tweaks, and sends feedback back to you. Nothing you file here touches the project.
+
+## Which tool
+
+- **`agenthub_design`** — several variants of one component, side by side on an infinite canvas ("show me 4 versions of the primary button", "compare a dense vs airy card"). Each variant is an HTML fragment + CSS; AgentHub isolates each variant's CSS to its own artboard.
+- **`agenthub_artifact`** — one self-contained HTML document ("render this report", "mock up the landing page", "draw the flow"). Served verbatim; inline CSS/JS is fine.
+- **`agenthub_list_artifacts`** — call first when the user is refining something already on screen; re-file with that id so the panel updates in place instead of stacking a near-duplicate.
+- **`agenthub_get_artifact`** — the current content of one artifact, *including edits the user made in the panel*. Call it with `variant=<name>` when the user picks one, and before re-filing an existing canvas so you start from what they have.
+
+## Filing a canvas well
+
+1. Decide the axis of comparison (fill vs outline vs soft; density; tone) — 3–6 variants, each with a short `name` and a one-line `notes` rationale.
+2. Write plain CSS per variant (`.btn`, `body`, `:root` variables all work; scripts are stripped).
+3. Declare **shared `props`** for the knobs worth comparing across every variant — e.g. `radius` (slider, unit `px`), `accent` (color), `label` (text), `shadow` (toggle) — and reference each one from variant CSS as `var(--<name>)` (text/select props can also fill an element marked `data-prop="<name>"`). A declared prop no variant uses is rejected. The user moves one control and every variant updates.
+4. Pass `sourcePath` when you know the real component the variants explore; it is only used if the user later asks to implement one.
+5. After filing, say it is in the Studio panel and stop — do not also edit files.
+
+## Handling what comes back
+
+- **Comments, crops, tweak requests** arrive as prompts naming the artifact id (and the variant). Re-file with the same id and change only what was asked. Do not edit project files for these.
+- **Edits the user makes with the panel's Edit tool are already saved into the canvas** — you are not asked to apply them. They are simply part of the variant from then on.
+- **Choosing a variant** is the one request that asks for code. It arrives either as an "Implement" prompt from the panel (it carries the current html/css) or in conversation ("let's go with the ghost one", "the second option", "that card"). In the conversational case call `agenthub_get_artifact` with `variant=<name>` (map ordinals and descriptions to the variant names from the list), then implement exactly that html/css in the real component, preserving behaviour and public API, following project conventions rather than pasting the markup verbatim, and list the files you changed. If it is unclear which variant they mean, ask.
+
+## Boundaries
+
+Inside AgentHub, prefer Studio over claude.ai artifacts or the /design skill so the result appears in the panel the user is watching. Never write into the repository as part of iterating on a canvas or artifact.
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Resources/AgentHubStudioSkill/agents/openai.yaml b/app/modules/AgentHubCore/Sources/AgentHub/Resources/AgentHubStudioSkill/agents/openai.yaml
new file mode 100644
index 00000000..67f7cac7
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Resources/AgentHubStudioSkill/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+  display_name: "AgentHub Studio"
+  short_description: "Render UI variants and visuals into AgentHub's Studio panel"
+  default_prompt: "Use $agenthub-studio to render: "
+
+policy:
+  allow_implicit_invocation: true
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/AgentHubStudioSkillInstaller.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/AgentHubStudioSkillInstaller.swift
new file mode 100644
index 00000000..2b21f273
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/AgentHubStudioSkillInstaller.swift
@@ -0,0 +1,64 @@
+import Foundation
+
+/// Installs the bundled `agenthub-studio` skill for Claude and Codex, the same
+/// way the task-manager skill is installed: an explicit `/agenthub-studio`
+/// trigger, plus a description the model can match on its own. The
+/// system-prompt guidance (`StudioAgentGuidance`) does the everyday nudging;
+/// the skill is the user's explicit handle and the fuller playbook.
+enum AgentHubStudioSkillInstaller {
+  static let skillName = "agenthub-studio"
+
+  enum InstallError: LocalizedError {
+    case missingBundledSkill
+    case invalidBundledSkillEncoding
+    case missingBundledOpenAIMetadata
+    case invalidBundledOpenAIMetadataEncoding
+
+    var errorDescription: String? {
+      switch self {
+      case .missingBundledSkill: return "Missing bundled AgentHub Studio skill."
+      case .invalidBundledSkillEncoding: return "Bundled AgentHub Studio skill is not valid UTF-8."
+      case .missingBundledOpenAIMetadata: return "Missing bundled AgentHub Studio OpenAI metadata."
+      case .invalidBundledOpenAIMetadataEncoding: return "Bundled AgentHub Studio OpenAI metadata is not valid UTF-8."
+      }
+    }
+  }
+
+  static func installBundledSkillForAllProvidersBestEffort(
+    homeDirectory: URL = FileManager.default.homeDirectoryForCurrentUser,
+    bundle: Bundle = .module,
+    fileManager: FileManager = .default
+  ) {
+    do {
+      try installBundledSkillForAllProviders(homeDirectory: homeDirectory, bundle: bundle, fileManager: fileManager)
+    } catch {
+      AppLogger.session.error("Failed to install AgentHub Studio skill: \(error.localizedDescription)")
+    }
+  }
+
+  static func installBundledSkillForAllProviders(
+    homeDirectory: URL = FileManager.default.homeDirectoryForCurrentUser,
+    bundle: Bundle = .module,
+    fileManager: FileManager = .default
+  ) throws {
+    guard let skillURL = bundle.url(forResource: "SKILL", withExtension: "md", subdirectory: "AgentHubStudioSkill") else {
+      throw InstallError.missingBundledSkill
+    }
+    guard let skillMarkdown = String(data: try Data(contentsOf: skillURL), encoding: .utf8) else {
+      throw InstallError.invalidBundledSkillEncoding
+    }
+    guard let openAIYAMLURL = bundle.url(forResource: "openai", withExtension: "yaml", subdirectory: "AgentHubStudioSkill/agents") else {
+      throw InstallError.missingBundledOpenAIMetadata
+    }
+    guard let openAIYAML = String(data: try Data(contentsOf: openAIYAMLURL), encoding: .utf8) else {
+      throw InstallError.invalidBundledOpenAIMetadataEncoding
+    }
+    try AgentHubBundledSkillFiles.installForAllProviders(
+      skillName: skillName,
+      homeDirectory: homeDirectory,
+      fileManager: fileManager,
+      skillMarkdown: skillMarkdown,
+      openAIYAML: openAIYAML
+    )
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/AgentHubWorktreeSkillInstaller.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/AgentHubWorktreeSkillInstaller.swift
index 0e80ea7d..54449364 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/Services/AgentHubWorktreeSkillInstaller.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/AgentHubWorktreeSkillInstaller.swift
@@ -79,6 +79,27 @@ enum AgentHubWorktreeSkillInstaller {
     fileManager: FileManager = .default,
     skillMarkdown: String,
     openAIYAML: String
+  ) throws {
+    try AgentHubBundledSkillFiles.installForAllProviders(
+      skillName: skillName,
+      homeDirectory: homeDirectory,
+      fileManager: fileManager,
+      skillMarkdown: skillMarkdown,
+      openAIYAML: openAIYAML
+    )
+  }
+}
+
+/// Writes one bundled skill into every provider's user-level skills directory
+/// (`~/.claude/skills/<name>/SKILL.md`, `~/.codex/skills/<name>/SKILL.md` +
+/// `agents/openai.yaml`). Idempotent: unchanged files are left untouched.
+enum AgentHubBundledSkillFiles {
+  static func installForAllProviders(
+    skillName: String,
+    homeDirectory: URL,
+    fileManager: FileManager = .default,
+    skillMarkdown: String,
+    openAIYAML: String
   ) throws {
     let claudeSkillDirectory = homeDirectory
       .appendingPathComponent(".claude", isDirectory: true)
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/SessionMetadataStore.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/SessionMetadataStore.swift
index 9d53fc18..1d6989bb 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/Services/SessionMetadataStore.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/SessionMetadataStore.swift
@@ -32,6 +32,7 @@ public actor SessionMetadataStore: TerminalWorkspaceStoreProtocol, AgentWorkspac
     static let addMeasurementProjectPath = "v15_add_measurement_project_path"
     static let createContextProfiles = "v16_create_context_profiles"
     static let createSessionLaunchContext = "v17_create_session_launch_context"
+    static let createStudioArtifacts = "v18_create_studio_artifacts"
   }
 
   static let migrationIdentifiers = [
@@ -51,7 +52,8 @@ public actor SessionMetadataStore: TerminalWorkspaceStoreProtocol, AgentWorkspac
     MigrationID.createSessionMeasurements,
     MigrationID.addMeasurementProjectPath,
     MigrationID.createContextProfiles,
-    MigrationID.createSessionLaunchContext
+    MigrationID.createSessionLaunchContext,
+    MigrationID.createStudioArtifacts
   ]
 
   private let dbQueue: DatabaseQueue
@@ -348,6 +350,24 @@ public actor SessionMetadataStore: TerminalWorkspaceStoreProtocol, AgentWorkspac
       }
     }
 
+    // Artifacts an agent filed into the Studio panel (agenthub_artifact /
+    // agenthub_design). Keyed by the id the CLI generated so a re-file — or a
+    // queue entry drained twice — replaces rather than duplicates. Scoped to a
+    // project from day one, like measurements after v15.
+    migrator.registerMigration(MigrationID.createStudioArtifacts) { db in
+      try db.create(table: "studio_artifacts") { t in
+        t.column("id", .text).primaryKey(onConflict: .replace)
+        t.column("projectPath", .text).notNull().indexed()
+        t.column("sessionId", .text).notNull()
+        t.column("provider", .text).notNull()
+        t.column("kind", .text).notNull()
+        t.column("createdAt", .datetime).notNull()
+        t.column("updatedAt", .datetime).notNull()
+        t.column("payloadVersion", .integer).notNull()
+        t.column("payloadData", .blob).notNull()
+      }
+    }
+
     return migrator
   }
 
@@ -519,6 +539,7 @@ public actor SessionMetadataStore: TerminalWorkspaceStoreProtocol, AgentWorkspac
       _ = try SessionRepoMapping.deleteAll(db)
       _ = try PinnedSessionOrderRecord.deleteAll(db)
       _ = try SessionMeasurementRecord.deleteAll(db)
+      _ = try StudioArtifactRecord.deleteAll(db)
       _ = try SessionMetadata.deleteAll(db)
     }
   }
@@ -929,6 +950,53 @@ extension SessionMetadataStore {
   }
 }
 
+// MARK: - Studio Artifacts
+
+extension SessionMetadataStore: StudioPersisting {
+  /// Stores one artifact. `save` (upsert) so a re-file or a queue entry drained
+  /// twice is idempotent.
+  public func saveStudioArtifact(_ record: StudioArtifactRecord) throws {
+    try dbQueue.write { db in
+      try record.save(db)
+    }
+  }
+
+  /// Artifacts for a project, newest first. Spans every session and both providers.
+  public func getStudioArtifacts(forProjectPath projectPath: String) throws -> [StudioArtifactRecord] {
+    let key = MeasurementProjectScope.normalized(projectPath)
+    return try dbQueue.read { db in
+      try StudioArtifactRecord
+        .filter(Column("projectPath") == key)
+        .order(Column("createdAt").desc, Column("id").desc)
+        .fetchAll(db)
+    }
+  }
+
+  /// Every stored artifact, for the Settings management view and launch reconcile.
+  public func getAllStudioArtifacts() throws -> [StudioArtifactRecord] {
+    try dbQueue.read { db in
+      try StudioArtifactRecord
+        .order(Column("createdAt").desc, Column("id").desc)
+        .fetchAll(db)
+    }
+  }
+
+  public func deleteStudioArtifact(id: String) throws {
+    _ = try dbQueue.write { db in
+      try StudioArtifactRecord.deleteOne(db, key: id)
+    }
+  }
+
+  public func deleteAllStudioArtifacts(forProjectPath projectPath: String) throws {
+    let key = MeasurementProjectScope.normalized(projectPath)
+    _ = try dbQueue.write { db in
+      try StudioArtifactRecord
+        .filter(Column("projectPath") == key)
+        .deleteAll(db)
+    }
+  }
+}
+
 // MARK: - Context Profiles
 
 extension SessionMetadataStore {
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioArtifactHandler.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioArtifactHandler.swift
new file mode 100644
index 00000000..826a567d
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioArtifactHandler.swift
@@ -0,0 +1,67 @@
+import AgentHubCLIKit
+import Foundation
+
+@MainActor
+public protocol StudioArtifactTarget: AnyObject {
+  func activeSessionId(forProcessId processId: Int32) -> String?
+  func storeStudioArtifact(_ artifact: StudioArtifact, forSessionId sessionId: String)
+}
+
+@MainActor
+public protocol StudioArtifactHandlingProtocol: AnyObject {
+  func handle(_ artifact: StudioArtifact) async throws
+}
+
+enum StudioArtifactHandlingError: LocalizedError {
+  case sessionUnavailable
+
+  var errorDescription: String? {
+    switch self {
+    case .sessionUnavailable:
+      return "The AgentHub session that filed this artifact could not be found."
+    }
+  }
+}
+
+/// Routes a filed Studio artifact to the session it came from — Claude or Codex.
+///
+/// Resolution mirrors `MeasurementRecordHandler`: trust `AGENTHUB_SESSION_ID`
+/// when it names a real session, otherwise map the calling process back to a
+/// session. Never stored against a `pending-` id — that id is replaced once the
+/// session is real, which would strand the artifact.
+@MainActor
+public final class StudioArtifactHandler: StudioArtifactHandlingProtocol {
+  private let claudeTarget: any StudioArtifactTarget
+  private let codexTarget: any StudioArtifactTarget
+
+  public init(
+    claudeTarget: any StudioArtifactTarget,
+    codexTarget: any StudioArtifactTarget
+  ) {
+    self.claudeTarget = claudeTarget
+    self.codexTarget = codexTarget
+  }
+
+  public func handle(_ artifact: StudioArtifact) async throws {
+    let target: any StudioArtifactTarget
+    switch artifact.sourceProvider {
+    case .claude:
+      target = claudeTarget
+    case .codex:
+      target = codexTarget
+    }
+
+    let explicitSessionId = artifact.sourceSessionId.flatMap { sessionId in
+      sessionId.hasPrefix("pending-") ? nil : sessionId
+    }
+    let sessionId = explicitSessionId
+      ?? target.activeSessionId(forProcessId: artifact.sourceProcessId)
+    guard let sessionId, !sessionId.hasPrefix("pending-") else {
+      throw StudioArtifactHandlingError.sessionUnavailable
+    }
+
+    target.storeStudioArtifact(artifact, forSessionId: sessionId)
+  }
+}
+
+extension CLISessionsViewModel: StudioArtifactTarget {}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioArtifactMonitor.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioArtifactMonitor.swift
new file mode 100644
index 00000000..39a872b0
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioArtifactMonitor.swift
@@ -0,0 +1,91 @@
+import AgentHubCLIKit
+import Foundation
+
+public protocol StudioArtifactMonitorProtocol: AnyObject, Sendable {
+  func start(handler: @escaping @MainActor @Sendable (QueuedStudioArtifact) async throws -> Void) async
+  func stop() async
+}
+
+/// Drains Studio artifacts the `agenthub` CLI queued on disk into the app.
+///
+/// Same shape as `MeasurementRecordMonitor`: poll the queue directory, hand each
+/// artifact to the app, and only delete the file once the app has taken it. An
+/// artifact whose session cannot be resolved yet is left in place and retried,
+/// because the CLI can file one a moment before AgentHub has bound the session id.
+public actor StudioArtifactMonitor: StudioArtifactMonitorProtocol {
+  private let queue: StudioArtifactQueue
+  private let pollInterval: Duration
+  private var task: Task<Void, Never>?
+  private var activeIds: Set<String> = []
+
+  public init(
+    queue: StudioArtifactQueue = StudioArtifactQueue(),
+    pollInterval: Duration = .milliseconds(400)
+  ) {
+    self.queue = queue
+    self.pollInterval = pollInterval
+  }
+
+  public func start(
+    handler: @escaping @MainActor @Sendable (QueuedStudioArtifact) async throws -> Void
+  ) async {
+    guard task == nil else { return }
+
+    task = Task { [queue, pollInterval] in
+      while !Task.isCancelled {
+        await self.processPending(queue: queue, handler: handler)
+        try? await Task.sleep(for: pollInterval)
+      }
+    }
+  }
+
+  public func stop() async {
+    task?.cancel()
+    task = nil
+    activeIds.removeAll()
+  }
+
+  private func processPending(
+    queue: StudioArtifactQueue,
+    handler: @escaping @MainActor @Sendable (QueuedStudioArtifact) async throws -> Void
+  ) async {
+    let pending: [QueuedStudioArtifact]
+    do {
+      pending = try queue.pendingArtifacts()
+    } catch {
+      AppLogger.session.error("Failed to read AgentHub studio records: \(error.localizedDescription)")
+      return
+    }
+
+    for queued in pending {
+      guard activeIds.insert(queued.artifact.id).inserted else { continue }
+      defer { activeIds.remove(queued.artifact.id) }
+
+      do {
+        try await handler(queued)
+        try queue.remove(queued)
+      } catch {
+        if shouldRetry(error, artifact: queued.artifact) {
+          continue
+        }
+        AppLogger.session.error("Failed to handle AgentHub studio record: \(error.localizedDescription)")
+        do {
+          try queue.markFailed(queued)
+        } catch {
+          AppLogger.session.error("Failed to mark AgentHub studio record failed: \(error.localizedDescription)")
+        }
+      }
+    }
+  }
+
+  /// A session that is not bound yet is a timing problem, not a bad record —
+  /// keep retrying briefly before giving up on it.
+  func shouldRetry(_ error: Error, artifact: StudioArtifact) -> Bool {
+    guard let handlingError = error as? StudioArtifactHandlingError,
+          case .sessionUnavailable = handlingError
+    else {
+      return false
+    }
+    return Date.now.timeIntervalSince(artifact.createdAt) < 30
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioDocumentWriter.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioDocumentWriter.swift
new file mode 100644
index 00000000..362998c6
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioDocumentWriter.swift
@@ -0,0 +1,533 @@
+import AgentHubCLIKit
+import CryptoKit
+import Foundation
+
+public protocol StudioDocumentWriting: Sendable {
+  /// The directory every served document lives under.
+  var rootURL: URL { get }
+  /// Writes (or rewrites) the served document and returns its `index.html` URL.
+  func write(_ artifact: StudioArtifact, projectKey: String) throws -> URL
+  /// Where an artifact's `index.html` lives, whether or not it has been written.
+  func documentURL(forArtifactId id: String, projectKey: String) -> URL
+  /// The document's path relative to `rootURL`, for the static server.
+  func relativePath(forArtifactId id: String, projectKey: String) -> String
+  func delete(artifactId: String, projectKey: String) throws
+  func deleteAll(projectKey: String) throws
+  /// Whether the served file exists and was produced by the current host page.
+  /// A canvas written by an older writer is stale — host-page fixes must reach
+  /// existing canvases without waiting for the agent to re-file.
+  func isCurrent(_ artifact: StudioArtifact, projectKey: String) -> Bool
+}
+
+/// Materializes a Studio artifact into the file the static server serves.
+///
+/// Documents are served verbatim; canvases are composed into a host page that
+/// owns `<head>`, the pan/zoom transform, and the artboard layout, with every
+/// variant's CSS scoped by `StudioCSSScoper`. Nothing here ever writes into a
+/// user's repository: `rootURL` is AgentHub's own directory.
+public struct StudioDocumentWriter: StudioDocumentWriting {
+  public let rootURL: URL
+
+  public init(rootURL: URL = StudioDocumentWriter.defaultRootURL) {
+    self.rootURL = rootURL
+  }
+
+  public static var defaultRootURL: URL {
+    AgentHubApplicationSupport.baseDirectoryURL.appendingPathComponent("studio", isDirectory: true)
+  }
+
+  /// Bump whenever the canvas host page (CSS/JS below) changes behaviour, so
+  /// canvases already on disk are regenerated on next open.
+  public static let hostVersion = 3
+  static let hostVersionMarker = "<meta name=\"agenthub-studio-host\" content=\""
+
+  public func isCurrent(_ artifact: StudioArtifact, projectKey: String) -> Bool {
+    let url = documentURL(forArtifactId: artifact.id, projectKey: projectKey)
+    guard let handle = try? FileHandle(forReadingFrom: url) else { return false }
+    defer { try? handle.close() }
+    let head = String(decoding: (try? handle.read(upToCount: 4096)) ?? Data(), as: UTF8.self)
+    switch artifact.kind {
+    case .document:
+      return true
+    case .canvas:
+      return head.contains("\(Self.hostVersionMarker)\(Self.hostVersion)\"")
+    }
+  }
+
+  public func write(_ artifact: StudioArtifact, projectKey: String) throws -> URL {
+    let url = documentURL(forArtifactId: artifact.id, projectKey: projectKey)
+    try FileManager.default.createDirectory(
+      at: url.deletingLastPathComponent(),
+      withIntermediateDirectories: true
+    )
+    let html = try Self.render(artifact)
+    try Data(html.utf8).write(to: url, options: [.atomic])
+    // Sidecar the CLI reads for `agenthub_get_artifact`: the current payload,
+    // including any edits the user baked in from the panel. The CLI never
+    // opens SQLite; this file is the agent's view of "what is on the canvas".
+    let payloadURL = Self.payloadURL(besideDocument: url)
+    let encoder = JSONEncoder()
+    encoder.dateEncodingStrategy = .iso8601
+    encoder.outputFormatting = [.sortedKeys]
+    try (try encoder.encode(artifact)).write(to: payloadURL, options: [.atomic])
+    return url
+  }
+
+  public static let payloadFileName = "artifact.json"
+
+  public static func payloadURL(besideDocument documentURL: URL) -> URL {
+    documentURL.deletingLastPathComponent().appendingPathComponent(payloadFileName, isDirectory: false)
+  }
+
+  public func documentURL(forArtifactId id: String, projectKey: String) -> URL {
+    rootURL.appendingPathComponent(relativePath(forArtifactId: id, projectKey: projectKey), isDirectory: false)
+  }
+
+  public func relativePath(forArtifactId id: String, projectKey: String) -> String {
+    "\(Self.projectDirectoryName(forProjectKey: projectKey))/\(Self.artifactDirectoryName(forId: id))/index.html"
+  }
+
+  public func delete(artifactId: String, projectKey: String) throws {
+    let directory = documentURL(forArtifactId: artifactId, projectKey: projectKey).deletingLastPathComponent()
+    guard FileManager.default.fileExists(atPath: directory.path) else { return }
+    try FileManager.default.removeItem(at: directory)
+  }
+
+  public func deleteAll(projectKey: String) throws {
+    let directory = rootURL.appendingPathComponent(
+      Self.projectDirectoryName(forProjectKey: projectKey),
+      isDirectory: true
+    )
+    guard FileManager.default.fileExists(atPath: directory.path) else { return }
+    try FileManager.default.removeItem(at: directory)
+  }
+
+  // MARK: - Naming
+
+  /// A short, stable, filesystem-safe name for a project bucket. Not reversible
+  /// on purpose — the database holds the mapping — so long paths never hit the
+  /// 255-byte component limit and never leak into a served URL.
+  public static func projectDirectoryName(forProjectKey key: String) -> String {
+    let digest = SHA256.hash(data: Data(MeasurementProjectScope.normalized(key).utf8))
+    return digest.prefix(8).map { String(format: "%02x", $0) }.joined()
+  }
+
+  /// Agent-supplied ids are used as-is only when they are plainly safe as a
+  /// single path component; anything else is hashed. `..` and `/` never reach
+  /// the filesystem.
+  public static func artifactDirectoryName(forId id: String) -> String {
+    let allowed = CharacterSet.alphanumerics.union(CharacterSet(charactersIn: "-_."))
+    // Dot-prefixed names are hashed too: the static server refuses dotfiles.
+    let isSafe = !id.isEmpty
+      && id.count <= 80
+      && !id.hasPrefix(".")
+      && id.unicodeScalars.allSatisfy { allowed.contains($0) }
+    if isSafe { return id }
+    let digest = SHA256.hash(data: Data(id.utf8))
+    return "h-" + digest.prefix(12).map { String(format: "%02x", $0) }.joined()
+  }
+
+  // MARK: - Rendering
+
+  public static func render(_ artifact: StudioArtifact) throws -> String {
+    switch artifact.kind {
+    case .document:
+      return artifact.html ?? ""
+    case .canvas:
+      return try renderCanvas(artifact)
+    }
+  }
+
+  /// The canvas host page: one document, N artboards, pan/zoom on the container.
+  ///
+  /// Artboards are sibling sections rather than iframes because the inspector
+  /// bridge is main-frame-only. Each artboard resets inheritance (`all: initial`)
+  /// and contains its own paint, so the host chrome never leaks in and a
+  /// variant never paints out.
+  static func renderCanvas(_ artifact: StudioArtifact) throws -> String {
+    var variantStyles: [String] = []
+    var artboards: [String] = []
+
+    for variant in artifact.variants {
+      let scoped = try StudioCSSScoper.scope(variant.css, variantName: variant.name)
+      let selector = StudioCSSScoper.artboardSelector(forVariantName: variant.name)
+      var sizing: [String] = []
+      if let width = variant.width { sizing.append("width: \(Self.pixels(width))") }
+      if let height = variant.height { sizing.append("height: \(Self.pixels(height)); overflow: auto") }
+      var block = ""
+      if !sizing.isEmpty {
+        block += "\(selector) { \(sizing.joined(separator: "; ")); }\n"
+      }
+      block += scoped.css
+      variantStyles.append("<style data-variant=\"\(escape(variant.name))\">\n\(block)\n</style>")
+
+      let notes = variant.notes.map { "<p class=\"studio-notes\">\(escape($0))</p>" } ?? ""
+      artboards.append("""
+        <figure class="studio-frame" data-variant="\(escape(variant.name))">
+          <figcaption class="studio-caption">
+            <div class="studio-caption-row">
+              <span class="studio-name">\(escape(variant.name))</span>
+              <button type="button" class="studio-implement" data-variant="\(escape(variant.name))" title="Ask the agent to implement this variant in the project">Implement</button>
+            </div>
+            \(notes)
+          </figcaption>
+          <div class="studio-frame-body">
+            <section class="studio-artboard" data-variant="\(escape(variant.name))">
+        \(variant.html)
+            </section>
+          </div>
+        </figure>
+        """)
+    }
+
+    // Shared tweak props: defaults land in a stylesheet so the canvas renders
+    // correctly with no JS at all (export, plain browser); the script below
+    // re-applies them and wires live changes from the Tweaks panel.
+    let propsCSS = artifact.props.isEmpty ? "" : """
+      <style id="studio-props">
+      .studio-artboard {
+      \(artifact.props.map { "  \($0.cssVariableName): \(cssBlockValue($0.cssValue));" }.joined(separator: "\n"))
+      }
+      </style>
+      """
+    let propsJSON = try propsSchemaJSON(artifact.props)
+
+    return """
+      <!DOCTYPE html>
+      <html lang="en">
+      <head>
+      <meta charset="utf-8">
+      <meta name="viewport" content="width=device-width, initial-scale=1">
+      <meta name="agenthub-studio-host" content="\(Self.hostVersion)">
+      <title>\(escape(artifact.title))</title>
+      <style>
+      \(hostCSS)
+      </style>
+      \(propsCSS)
+      \(variantStyles.joined(separator: "\n"))
+      </head>
+      <body>
+      <div id="studio-viewport">
+        <div id="studio-canvas">
+      \(artboards.joined(separator: "\n"))
+        </div>
+      </div>
+      <div id="studio-hud" aria-label="Canvas zoom">
+        <button type="button" data-zoom="out" title="Zoom out">−</button>
+        <button type="button" data-zoom="reset" title="Reset zoom"><span id="studio-zoom-label">100%</span></button>
+        <button type="button" data-zoom="in" title="Zoom in">+</button>
+        <button type="button" data-zoom="fit" title="Fit all">Fit</button>
+      </div>
+      <script>
+      window.__studioProps = \(propsJSON);
+      \(hostScript)
+      </script>
+      </body>
+      </html>
+      """
+  }
+
+  /// A prop value as it may appear inside the static `<style>` block. Text and
+  /// select values are agent- or user-authored strings: `}` would end the rule,
+  /// `;` would start a declaration, and `</style>` would end the element. CSS
+  /// hex escapes keep the token stream intact and decode to the same characters
+  /// (`\3c ` → `<`), so `var(--x)` sees what the live `setProperty` path sets.
+  static func cssBlockValue(_ value: String) -> String {
+    var out = ""
+    for scalar in value.unicodeScalars {
+      switch scalar {
+      case "<", ">", "{", "}", ";", "\\", "\n", "\r", "\u{2028}", "\u{2029}":
+        out += String(format: "\\%x ", scalar.value)
+      default:
+        out.unicodeScalars.append(scalar)
+      }
+    }
+    return out
+  }
+
+  /// The ordered schema the host page hands to `dc_set_props`, as a JSON array
+  /// literal safe to inline in a `<script>`.
+  static func propsSchemaJSON(_ props: [StudioTweakProp]) throws -> String {
+    let objects: [[String: Any]] = props.map { prop in
+      var declaration = prop.declaration
+      declaration["name"] = prop.name
+      return declaration
+    }
+    let data = try JSONSerialization.data(withJSONObject: objects, options: [.sortedKeys])
+    return String(decoding: data, as: UTF8.self)
+      .replacingOccurrences(of: "</", with: "<\\/")
+      .replacingOccurrences(of: "\u{2028}", with: "\\u2028")
+      .replacingOccurrences(of: "\u{2029}", with: "\\u2029")
+  }
+
+  private static func pixels(_ value: Double) -> String {
+    value == value.rounded() ? "\(Int(value))px" : "\(value)px"
+  }
+
+  static func escape(_ text: String) -> String {
+    text
+      .replacingOccurrences(of: "&", with: "&amp;")
+      .replacingOccurrences(of: "<", with: "&lt;")
+      .replacingOccurrences(of: ">", with: "&gt;")
+      .replacingOccurrences(of: "\"", with: "&quot;")
+      .replacingOccurrences(of: "'", with: "&#39;")
+  }
+
+  private static let hostCSS = """
+    :root { color-scheme: light dark; }
+    html, body { margin: 0; height: 100%; overflow: hidden; }
+    body {
+      background: #ececef;
+      background-image: radial-gradient(rgba(0,0,0,0.10) 1px, transparent 1px);
+      background-size: 24px 24px;
+      font: 13px/1.4 -apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif;
+      color: #1d1d1f;
+    }
+    @media (prefers-color-scheme: dark) {
+      body {
+        background: #1c1c1e;
+        background-image: radial-gradient(rgba(255,255,255,0.09) 1px, transparent 1px);
+        color: #f2f2f7;
+      }
+    }
+    #studio-viewport { position: fixed; inset: 0; overflow: hidden; cursor: grab; }
+    #studio-viewport.panning { cursor: grabbing; }
+    #studio-canvas {
+      position: absolute; top: 0; left: 0;
+      transform-origin: 0 0;
+      display: flex; flex-wrap: wrap; align-items: flex-start; gap: 48px;
+      padding: 48px; box-sizing: border-box; width: 100vw;
+    }
+    .studio-frame { margin: 0; display: flex; flex-direction: column; gap: 8px; max-width: 100%; }
+    .studio-caption { display: flex; flex-direction: column; gap: 2px; padding: 0 2px; }
+    .studio-name { font-weight: 600; font-size: 12px; letter-spacing: 0.01em; }
+    .studio-notes { margin: 0; font-size: 12px; opacity: 0.7; max-width: 48ch; }
+    .studio-caption-row { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+    .studio-implement {
+      all: unset; cursor: pointer; display: none;
+      font: 600 11px -apple-system, system-ui, sans-serif; letter-spacing: 0.01em;
+      padding: 3px 9px; border-radius: 999px;
+      color: #1d1d1f; background: rgba(0,0,0,0.08);
+    }
+    .studio-implement:hover { background: #0a84ff; color: #fff; }
+    .studio-implement:active { transform: translateY(0.5px); }
+    body.studio-hosted .studio-implement { display: inline-block; }
+    @media (prefers-color-scheme: dark) {
+      .studio-implement { color: #f2f2f7; background: rgba(255,255,255,0.12); }
+    }
+    .studio-frame-body {
+      border-radius: 10px; overflow: hidden;
+      background: #fff;
+      box-shadow: 0 0 0 1px rgba(0,0,0,0.08), 0 8px 24px rgba(0,0,0,0.10);
+    }
+    @media (prefers-color-scheme: dark) {
+      .studio-frame-body { box-shadow: 0 0 0 1px rgba(255,255,255,0.10), 0 8px 24px rgba(0,0,0,0.5); }
+    }
+    .studio-artboard {
+      all: initial;
+      display: block;
+      contain: layout paint;
+      isolation: isolate;
+      box-sizing: border-box;
+      background: #fff;
+      color: #111;
+      font: 16px/1.4 -apple-system, BlinkMacSystemFont, system-ui, sans-serif;
+      min-width: 120px; min-height: 40px;
+    }
+    #studio-hud {
+      position: fixed; right: 12px; bottom: 12px; z-index: 2147483000;
+      display: flex; gap: 2px; padding: 3px;
+      background: rgba(255,255,255,0.85); backdrop-filter: blur(12px);
+      border-radius: 8px; box-shadow: 0 1px 4px rgba(0,0,0,0.18);
+    }
+    @media (prefers-color-scheme: dark) { #studio-hud { background: rgba(44,44,46,0.85); } }
+    #studio-hud button {
+      all: unset; cursor: pointer; font: 12px -apple-system, system-ui, sans-serif;
+      min-width: 24px; height: 24px; padding: 0 6px; border-radius: 6px; text-align: center;
+      color: inherit;
+    }
+    #studio-hud button:hover { background: rgba(127,127,127,0.18); }
+    """
+
+  private static let hostScript = """
+    (function () {
+      var viewport = document.getElementById('studio-viewport');
+      var canvas = document.getElementById('studio-canvas');
+      var label = document.getElementById('studio-zoom-label');
+      var scale = 1, tx = 0, ty = 0;
+      var MIN = 0.1, MAX = 6;
+
+      // The inspector overlay (highlight + native comment box) tracks the
+      // selected element by listening for window 'scroll'. Panning here is a
+      // CSS transform, which never scrolls, so tell it the viewport moved:
+      // getBoundingClientRect() already reflects the new transform.
+      function notifyViewportMoved() {
+        try { window.dispatchEvent(new Event('scroll')); } catch (err) {}
+      }
+      function apply() {
+        canvas.style.transform = 'translate(' + tx + 'px,' + ty + 'px) scale(' + scale + ')';
+        label.textContent = Math.round(scale * 100) + '%';
+        notifyViewportMoved();
+      }
+      function zoomAt(factor, cx, cy) {
+        var next = Math.min(MAX, Math.max(MIN, scale * factor));
+        var ratio = next / scale;
+        tx = cx - (cx - tx) * ratio;
+        ty = cy - (cy - ty) * ratio;
+        scale = next;
+        apply();
+      }
+      function fit() {
+        var rect = canvas.getBoundingClientRect();
+        var w = rect.width / scale, h = rect.height / scale;
+        if (!w || !h) return;
+        var s = Math.min(viewport.clientWidth / w, viewport.clientHeight / h, 1);
+        scale = Math.max(MIN, s);
+        tx = (viewport.clientWidth - w * scale) / 2;
+        ty = Math.max(0, (viewport.clientHeight - h * scale) / 2);
+        apply();
+      }
+
+      viewport.addEventListener('wheel', function (e) {
+        if (e.target.closest && e.target.closest('#studio-hud')) return;
+        e.preventDefault();
+        if (e.ctrlKey || e.metaKey) {
+          zoomAt(Math.exp(-e.deltaY * 0.01), e.clientX, e.clientY);
+        } else {
+          tx -= e.deltaX; ty -= e.deltaY; apply();
+        }
+      }, { passive: false });
+
+      var dragging = false, lastX = 0, lastY = 0;
+      viewport.addEventListener('mousedown', function (e) {
+        if (e.button !== 1 && !(e.button === 0 && (e.altKey || e.target === viewport || e.target === canvas))) return;
+        dragging = true; lastX = e.clientX; lastY = e.clientY;
+        viewport.classList.add('panning');
+        e.preventDefault();
+      });
+      window.addEventListener('mousemove', function (e) {
+        if (!dragging) return;
+        tx += e.clientX - lastX; ty += e.clientY - lastY;
+        lastX = e.clientX; lastY = e.clientY; apply();
+      });
+      window.addEventListener('mouseup', function () {
+        dragging = false; viewport.classList.remove('panning');
+      });
+
+      document.getElementById('studio-hud').addEventListener('click', function (e) {
+        var button = e.target.closest('button'); if (!button) return;
+        var cx = viewport.clientWidth / 2, cy = viewport.clientHeight / 2;
+        switch (button.getAttribute('data-zoom')) {
+          case 'in': zoomAt(1.25, cx, cy); break;
+          case 'out': zoomAt(0.8, cx, cy); break;
+          case 'reset': scale = 1; tx = 0; ty = 0; apply(); break;
+          case 'fit': fit(); break;
+        }
+      });
+
+      window.addEventListener('keydown', function (e) {
+        if (e.target && (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA' || e.target.isContentEditable)) return;
+        if ((e.metaKey || e.ctrlKey) && (e.key === '=' || e.key === '+')) { e.preventDefault(); zoomAt(1.25, viewport.clientWidth/2, viewport.clientHeight/2); }
+        if ((e.metaKey || e.ctrlKey) && e.key === '-') { e.preventDefault(); zoomAt(0.8, viewport.clientWidth/2, viewport.clientHeight/2); }
+        if ((e.metaKey || e.ctrlKey) && e.key === '0') { e.preventDefault(); scale = 1; tx = 0; ty = 0; apply(); }
+        if (e.key === '1' && (e.metaKey || e.ctrlKey)) { e.preventDefault(); fit(); }
+      });
+
+      // Shared tweak props → CSS custom properties on every artboard.
+      var propsSchema = Array.isArray(window.__studioProps) ? window.__studioProps : [];
+      var propsByName = {};
+      propsSchema.forEach(function (p) { propsByName[p.name] = p; });
+      function cssValueFor(p, value) {
+        if (p.type === 'slider' && typeof value === 'number') {
+          return (Number.isInteger(value) ? String(value) : String(value)) + (p.unit || '');
+        }
+        if (typeof value === 'boolean') return value ? '1' : '0';
+        return String(value);
+      }
+      function applyProp(name, value) {
+        var p = propsByName[name]; if (!p) return;
+        var css = cssValueFor(p, value);
+        var boards = document.querySelectorAll('.studio-artboard');
+        for (var i = 0; i < boards.length; i++) boards[i].style.setProperty('--' + name, css);
+        if (p.type === 'text' || p.type === 'select') {
+          var sel = '.studio-artboard [data-prop="' + (window.CSS && CSS.escape ? CSS.escape(name) : name) + '"]';
+          var targets = document.querySelectorAll(sel);
+          for (var j = 0; j < targets.length; j++) targets[j].textContent = String(value);
+        }
+        // A tweak can resize the selected element; keep the highlight on it.
+        if (typeof notifyViewportMoved === 'function') notifyViewportMoved();
+      }
+      if (propsSchema.length) {
+        propsSchema.forEach(function (p) { applyProp(p.name, p.value); });
+        window.dc_on_props_changed = function (props) {
+          Object.keys(props || {}).forEach(function (name) { applyProp(name, props[name]); });
+        };
+        if (typeof window.dc_set_props === 'function') {
+          var schema = {};
+          propsSchema.forEach(function (p) {
+            var d = { type: p.type, label: p.label, value: p.value };
+            if (p.min !== undefined) d.min = p.min;
+            if (p.max !== undefined) d.max = p.max;
+            if (p.step !== undefined) d.step = p.step;
+            if (p.options) d.options = p.options;
+            schema[p.name] = d;
+          });
+          window.dc_set_props(schema);
+        }
+      }
+
+      // Inside AgentHub the panel registers a message handler; the Implement
+      // buttons only show when it exists (a plain browser or an export has
+      // no agent to talk to).
+      var bridge = window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.agentHubStudio;
+      if (bridge) {
+        document.body.classList.add('studio-hosted');
+        document.addEventListener('click', function (e) {
+          var button = e.target && e.target.closest ? e.target.closest('.studio-implement') : null;
+          if (!button) return;
+          e.preventDefault(); e.stopPropagation();
+          try { bridge.postMessage({ type: 'implement', variant: button.getAttribute('data-variant') }); } catch (err) {}
+        }, true);
+      }
+
+      window.__agenthubStudio = {
+        variantForSelector: function (selector) {
+          try {
+            var el = document.querySelector(selector);
+            var board = el && el.closest ? el.closest('.studio-artboard') : null;
+            return board ? board.getAttribute('data-variant') : null;
+          } catch (err) { return null; }
+        },
+        fit: fit,
+        // Edit mode bakes changes back into the variant payload: the artboard's
+        // innerHTML *is* the edited variant (inline styles/text from the design
+        // toolbar), so serialize it. Returns { variantName: html }.
+        serializeArtboards: function (names) {
+          var out = {};
+          var boards = document.querySelectorAll('.studio-artboard');
+          for (var i = 0; i < boards.length; i++) {
+            var name = boards[i].getAttribute('data-variant');
+            if (!names || names.indexOf(name) !== -1) out[name] = boards[i].innerHTML.trim();
+          }
+          return out;
+        },
+        variantsForSelectors: function (selectors) {
+          var out = {};
+          (selectors || []).forEach(function (sel) {
+            try {
+              var el = document.querySelector(sel);
+              var board = el && el.closest ? el.closest('.studio-artboard') : null;
+              if (board) out[sel] = board.getAttribute('data-variant');
+            } catch (err) {}
+          });
+          return out;
+        },
+        removeElement: function (selector) {
+          try { var el = document.querySelector(selector); if (el) { el.remove(); return true; } } catch (err) {}
+          return false;
+        }
+      };
+      apply();
+    })();
+    """
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioFeedbackPromptBuilder.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioFeedbackPromptBuilder.swift
new file mode 100644
index 00000000..8deceddc
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioFeedbackPromptBuilder.swift
@@ -0,0 +1,124 @@
+import AgentHubCLIKit
+import Canvas
+import Foundation
+
+/// Composes the prompt sent when the user comments on an element in a Studio
+/// artifact and presses Send.
+///
+/// Send iterates the surface: the prompt tells the agent to re-file with the
+/// same id and explicitly forbids editing project files. Promotion — asking for
+/// real code — is a different builder and a different button, never this one.
+public enum StudioFeedbackPromptBuilder {
+  /// One element's batched Edit-mode changes, already stamped with its variant.
+  public struct ElementEdits: Equatable {
+    public let element: ElementInspectorData
+    public let variantName: String?
+    /// `WebPreviewDesignEditPromptComposer`-style delta lines ("- color: a → b").
+    public let changeLines: [String]
+
+    public init(element: ElementInspectorData, variantName: String?, changeLines: [String]) {
+      self.element = element
+      self.variantName = variantName
+      self.changeLines = changeLines
+    }
+  }
+
+  /// Prompt for a batch of live design edits made in Edit mode.
+  public static func editsPrompt(artifact: StudioArtifact, edits: [ElementEdits]) -> String? {
+    guard !edits.isEmpty else { return nil }
+    let tool = artifact.kind == .canvas ? "agenthub_design" : "agenthub_artifact"
+    let noun = artifact.kind == .canvas ? "design canvas" : "artifact"
+
+    var lines: [String] = [
+      "I made \(edits.count == 1 ? "a visual edit" : "visual edits") directly on the Studio \(noun) \"\(artifact.title)\" (id \(artifact.id)). Please make them permanent.",
+      "",
+    ]
+    for (index, entry) in edits.enumerated() {
+      var heading = "### Element \(index + 1)"
+      if let variantName = entry.variantName, !variantName.isEmpty {
+        heading += " — variant \"\(variantName)\""
+      }
+      lines.append(heading)
+      lines.append(ElementInspectorPromptBuilder.buildContextPrompt(element: entry.element))
+      lines.append("")
+      lines.append("Apply these design changes to this element:")
+      lines.append(contentsOf: entry.changeLines)
+      lines.append("")
+    }
+    lines.append("Re-file with \(tool) using id \(artifact.id) so it refreshes in place, keeping everything I did not touch exactly as it is.")
+    lines.append("This is a scratch surface: do not edit project files for this request.")
+    return lines.joined(separator: "\n")
+  }
+
+  /// Prompt for a crop-selected region (screenshot + the elements inside it).
+  public static func cropPrompt(
+    artifact: StudioArtifact,
+    variantName: String?,
+    cropRect: CGRect,
+    elements: [ElementInspectorData],
+    instruction: String,
+    screenshotPath: String?
+  ) -> String {
+    let tool = artifact.kind == .canvas ? "agenthub_design" : "agenthub_artifact"
+    let noun = artifact.kind == .canvas ? "design canvas" : "artifact"
+    var opening = "I'm looking at a region of the Studio \(noun) \"\(artifact.title)\" you rendered with \(tool) (id \(artifact.id))"
+    if let variantName, !variantName.isEmpty { opening += ", on variant \"\(variantName)\"" }
+    opening += "."
+    let body = ElementInspectorPromptBuilder.buildCropPrompt(
+      cropRect: cropRect,
+      elements: elements,
+      instruction: instruction,
+      screenshotPath: screenshotPath
+    )
+    // The Canvas builder opens with a web-preview line; keep its region/image/
+    // elements body under Studio's own framing.
+    let trimmedBody = body
+      .replacingOccurrences(of: "I'm looking at a selected region in the live web preview:\n\n", with: "")
+    return [
+      opening,
+      "",
+      trimmedBody,
+      "",
+      "Update the \(noun) and re-file it with \(tool) using id \(artifact.id) so it refreshes in place.",
+      "This is a scratch surface: do not edit project files for this request.",
+    ].joined(separator: "\n")
+  }
+
+  public static func prompt(
+    artifact: StudioArtifact,
+    variantName: String?,
+    element: ElementInspectorData?,
+    instruction: String
+  ) -> String {
+    let tool = artifact.kind == .canvas ? "agenthub_design" : "agenthub_artifact"
+    let noun = artifact.kind == .canvas ? "design canvas" : "artifact"
+
+    var lines: [String] = []
+    var opening = "I'm looking at the Studio \(noun) \"\(artifact.title)\" you rendered with \(tool) (id \(artifact.id))"
+    if let variantName, !variantName.isEmpty {
+      opening += ", variant \"\(variantName)\""
+    }
+    opening += "."
+    lines.append(opening)
+    lines.append("")
+
+    if let element {
+      lines.append(ElementInspectorPromptBuilder.buildContextPrompt(element: element))
+      lines.append("")
+    }
+
+    lines.append("User request: \(instruction)")
+    lines.append("")
+
+    if artifact.kind == .canvas {
+      var closing = "Update the canvas and re-file it with \(tool) using id \(artifact.id) so it refreshes in place"
+      closing += variantName != nil ? " — change the \"\(variantName!)\" variant, keep the other variants as they are unless the request says otherwise." : "."
+      lines.append(closing)
+    } else {
+      lines.append("Update the document and re-file it with \(tool) using id \(artifact.id) so it refreshes in place.")
+    }
+    lines.append("This is a scratch surface: do not edit project files for this request.")
+
+    return lines.joined(separator: "\n")
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioLibrary.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioLibrary.swift
new file mode 100644
index 00000000..0eeb765f
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioLibrary.swift
@@ -0,0 +1,344 @@
+import AgentHubCLIKit
+import Canvas
+import Foundation
+import Observation
+
+/// What the library needs from SQLite. `SessionMetadataStore` conforms.
+public protocol StudioPersisting: Sendable {
+  func saveStudioArtifact(_ record: StudioArtifactRecord) async throws
+  func getStudioArtifacts(forProjectPath projectPath: String) async throws -> [StudioArtifactRecord]
+  func getAllStudioArtifacts() async throws -> [StudioArtifactRecord]
+  func deleteStudioArtifact(id: String) async throws
+  func deleteAllStudioArtifacts(forProjectPath projectPath: String) async throws
+}
+
+/// The Studio panel's model — every artifact filed for every project, shared by
+/// the Claude and Codex view models.
+///
+/// Keyed by **project**, never by session: a design canvas outlives the
+/// conversation that produced it, and every session working on the project sees
+/// the same set. Both provider view models write into one instance, so a canvas
+/// filed from Codex is on screen for a Claude session in the same repo.
+///
+/// Storage discipline: SQLite is the source of truth; the served document under
+/// `documents.rootURL` is a cache rewritten from the payload whenever it is
+/// missing. Overwrite in place, delete cascades, reconcile on launch.
+@MainActor
+@Observable
+public final class StudioLibrary {
+  public private(set) var artifactsByProject: [String: [StudioArtifact]] = [:]
+  private var loadedProjectKeys: Set<String> = []
+  private var loadingProjectKeys: Set<String> = []
+
+  @ObservationIgnored private let persistence: (any StudioPersisting)?
+  @ObservationIgnored private let documents: any StudioDocumentWriting
+  @ObservationIgnored private let server: any StudioStaticServing
+  @ObservationIgnored private let index: StudioIndexStore
+
+  public init(
+    persistence: (any StudioPersisting)?,
+    documents: any StudioDocumentWriting = StudioDocumentWriter(),
+    server: (any StudioStaticServing)? = nil,
+    index: StudioIndexStore = StudioIndexStore()
+  ) {
+    self.persistence = persistence
+    self.documents = documents
+    self.server = server ?? StudioStaticServer(rootURL: documents.rootURL)
+    self.index = index
+  }
+
+  // MARK: - Reading
+
+  public func artifacts(forProjectKey key: String) -> [StudioArtifact] {
+    artifactsByProject[key] ?? []
+  }
+
+  public func artifact(id: String, projectKey key: String) -> StudioArtifact? {
+    artifactsByProject[key]?.first { $0.id == id }
+  }
+
+  /// The file the static server serves for an artifact.
+  public func documentURL(for artifact: StudioArtifact, projectKey key: String) -> URL {
+    documents.documentURL(forArtifactId: artifact.id, projectKey: key)
+  }
+
+  /// The localhost URL for an artifact, starting the server on first use and
+  /// rewriting the document if the cache is missing or from an older host page.
+  public func servedURL(for artifact: StudioArtifact, projectKey key: String) async -> URL? {
+    ensureDocumentIsCurrent(artifact, projectKey: key)
+    do {
+      let base = try await server.start()
+      let relative = documents.relativePath(forArtifactId: artifact.id, projectKey: key)
+      return URL(string: relative, relativeTo: base)?.absoluteURL
+    } catch {
+      AppLogger.session.error("Studio server failed to start: \(error.localizedDescription)")
+      return nil
+    }
+  }
+
+  // MARK: - Writing
+
+  /// Takes an artifact filed by the CLI. In-memory first so the button appears
+  /// immediately, then disk and SQLite. Returns the artifact as stored (with
+  /// its resolved revision) so callers that produced it can recognise it.
+  @discardableResult
+  public func store(
+    _ artifact: StudioArtifact,
+    projectKey key: String,
+    sessionId: String,
+    aliasPaths: [String]
+  ) async -> StudioArtifact {
+    let existing = artifactsByProject[key] ?? []
+    let resolved = existing.first { $0.id == artifact.id }.map { artifact.replacing($0) } ?? artifact
+    artifactsByProject[key] = Self.merged(existing: existing, incoming: [resolved])
+
+    do {
+      _ = try documents.write(resolved, projectKey: key)
+    } catch {
+      AppLogger.session.error("Failed to write studio document \(resolved.id): \(error.localizedDescription)")
+    }
+    publishIndex(forKey: key, aliasPaths: aliasPaths)
+
+    guard let persistence else { return resolved }
+    do {
+      try await persistence.saveStudioArtifact(
+        StudioArtifactRecord(artifact: resolved, projectPath: key, sessionId: sessionId)
+      )
+    } catch {
+      AppLogger.session.error("Failed to save studio artifact: \(error.localizedDescription)")
+    }
+    return resolved
+  }
+
+  /// Bakes Edit-mode changes into a canvas: replaces the named variants' `html`
+  /// with the serialized artboard markup (inline styles and text the user
+  /// applied) and re-stores. Studio is a scratch surface — what the user sees
+  /// is what the variant becomes, and Implement/Promote sends exactly this.
+  @discardableResult
+  public func updateVariantHTML(
+    artifactId: String,
+    htmlByVariant: [String: String],
+    projectKey key: String,
+    sessionId: String,
+    aliasPaths: [String]
+  ) async -> StudioArtifact? {
+    guard let artifact = artifact(id: artifactId, projectKey: key), artifact.kind == .canvas else { return nil }
+    let variants = artifact.variants.map { variant -> StudioVariant in
+      guard let html = htmlByVariant[variant.name] else { return variant }
+      return StudioVariant(
+        name: variant.name,
+        html: html,
+        css: variant.css,
+        notes: variant.notes,
+        width: variant.width,
+        height: variant.height
+      )
+    }
+    guard variants != artifact.variants else { return artifact }
+    return await store(artifact.withVariants(variants), projectKey: key, sessionId: sessionId, aliasPaths: aliasPaths)
+  }
+
+  /// Reads a project's persisted artifacts back once. Merges rather than
+  /// replaces: an artifact can arrive from the queue before this completes.
+  public func load(projectKey key: String, aliasPaths: [String]) async {
+    guard let persistence, !loadedProjectKeys.contains(key), loadingProjectKeys.insert(key).inserted else { return }
+    defer { loadingProjectKeys.remove(key) }
+
+    do {
+      let records = try await persistence.getStudioArtifacts(forProjectPath: key)
+      loadedProjectKeys.insert(key)
+      let decoded = records.compactMap { try? $0.decodedArtifact() }
+      guard !decoded.isEmpty else { return }
+      artifactsByProject[key] = Self.merged(existing: artifactsByProject[key] ?? [], incoming: decoded)
+      publishIndex(forKey: key, aliasPaths: aliasPaths)
+    } catch {
+      AppLogger.session.error("Failed to load studio artifacts: \(error.localizedDescription)")
+    }
+  }
+
+  public func delete(id: String, projectKey key: String, aliasPaths: [String]) async {
+    artifactsByProject[key]?.removeAll { $0.id == id }
+    if artifactsByProject[key]?.isEmpty == true {
+      artifactsByProject.removeValue(forKey: key)
+    }
+    publishIndex(forKey: key, aliasPaths: aliasPaths)
+    try? documents.delete(artifactId: id, projectKey: key)
+
+    guard let persistence else { return }
+    do {
+      try await persistence.deleteStudioArtifact(id: id)
+    } catch {
+      AppLogger.session.error("Failed to delete studio artifact: \(error.localizedDescription)")
+    }
+  }
+
+  /// Removes everything for a project — Settings only.
+  public func deleteAll(projectKey key: String) async {
+    artifactsByProject.removeValue(forKey: key)
+    loadedProjectKeys.remove(key)
+    publishIndex(forKey: key, aliasPaths: [])
+    try? documents.deleteAll(projectKey: key)
+
+    guard let persistence else { return }
+    do {
+      try await persistence.deleteAllStudioArtifacts(forProjectPath: key)
+    } catch {
+      AppLogger.session.error("Failed to delete studio artifacts for project: \(error.localizedDescription)")
+    }
+  }
+
+  // MARK: - Tweaks
+
+  public enum TweakDefaultsError: LocalizedError, Equatable {
+    case unknownArtifact
+    case unknownProp(String)
+    case documentEditFailed(String)
+
+    public var errorDescription: String? {
+      switch self {
+      case .unknownArtifact: return "The artifact is no longer available."
+      case .unknownProp(let name): return "The canvas has no prop named \(name)."
+      case .documentEditFailed(let reason): return "Couldn't rewrite the document's dc_set_props call: \(reason)"
+      }
+    }
+  }
+
+  /// Makes the panel's current tweak values the artifact's defaults and
+  /// re-stores it (revision bump, so the open panel reloads with them).
+  ///
+  /// Canvas: the shared `props` schema is updated in the payload — the host
+  /// page is regenerated from it. Document: the `dc_set_props` call in the
+  /// stored HTML is spliced with `TweakPropsSourceEditor` (parser-verified) —
+  /// never a full-file rewrite. Neither path touches the served cache directly;
+  /// both go through `store`, so SQLite stays the source of truth.
+  public func saveTweakDefaults(
+    artifactId: String,
+    values: [String: TweakPropValue],
+    projectKey key: String,
+    sessionId: String,
+    aliasPaths: [String]
+  ) async throws {
+    guard let artifact = artifact(id: artifactId, projectKey: key) else {
+      throw TweakDefaultsError.unknownArtifact
+    }
+
+    let updated: StudioArtifact
+    switch artifact.kind {
+    case .canvas:
+      var props = artifact.props
+      for (name, value) in values {
+        guard let index = props.firstIndex(where: { $0.name == name }) else {
+          throw TweakDefaultsError.unknownProp(name)
+        }
+        props[index] = props[index].withValue(Self.studioValue(value))
+      }
+      updated = artifact.withContent(props: props)
+    case .document:
+      var html = artifact.html ?? ""
+      for (name, value) in values.sorted(by: { $0.key < $1.key }) {
+        do {
+          html = try TweakPropsSourceEditor.applyingValueEdit(propName: name, newValue: value, toSource: html)
+        } catch {
+          throw TweakDefaultsError.documentEditFailed("\(error)")
+        }
+      }
+      updated = artifact.withContent(html: html)
+    }
+
+    // `store` re-anchors on the existing id: createdAt is kept, revision bumps.
+    await store(updated, projectKey: key, sessionId: sessionId, aliasPaths: aliasPaths)
+  }
+
+  static func studioValue(_ value: TweakPropValue) -> StudioTweakValue {
+    switch value {
+    case .number(let number): return .number(number)
+    case .string(let string): return .string(string)
+    case .boolean(let flag): return .boolean(flag)
+    }
+  }
+
+  // MARK: - Settings / lifecycle
+
+  public struct ProjectSummary: Identifiable, Equatable, Sendable {
+    public var id: String { projectKey }
+    public let projectKey: String
+    public let artifacts: [StudioArtifact]
+    public let bytesOnDisk: Int64
+  }
+
+  /// Every stored artifact grouped by project, including projects no longer
+  /// open in the sidebar, with the bytes each occupies on disk.
+  public func allProjects() async -> [ProjectSummary] {
+    guard let persistence else { return [] }
+    let records = (try? await persistence.getAllStudioArtifacts()) ?? []
+    var grouped: [String: [StudioArtifact]] = [:]
+    for record in records {
+      guard let artifact = try? record.decodedArtifact() else { continue }
+      grouped[record.projectPath, default: []].append(artifact)
+    }
+    return grouped
+      .map { key, artifacts in
+        let bytes = artifacts.reduce(Int64(0)) { total, artifact in
+          total + StudioStorageReconciler.directorySize(
+            at: documents.documentURL(forArtifactId: artifact.id, projectKey: key).deletingLastPathComponent()
+          )
+        }
+        return ProjectSummary(projectKey: key, artifacts: Self.merged(existing: [], incoming: artifacts), bytesOnDisk: bytes)
+      }
+      .sorted { $0.projectKey < $1.projectKey }
+  }
+
+  /// Drops served-document directories that no row vouches for. Call once at launch.
+  public func reconcileStorage() async {
+    guard let persistence else { return }
+    let records = (try? await persistence.getAllStudioArtifacts()) ?? []
+    let known = Set(records.map { StudioDocumentWriter.artifactDirectoryName(forId: $0.id) })
+    let root = documents.rootURL
+    _ = await Task.detached(priority: .utility) {
+      StudioStorageReconciler(rootURL: root).reconcile(knownDirectoryNames: known)
+    }.value
+  }
+
+  // MARK: - Helpers
+
+  private func ensureDocumentIsCurrent(_ artifact: StudioArtifact, projectKey key: String) {
+    guard !documents.isCurrent(artifact, projectKey: key) else { return }
+    do {
+      _ = try documents.write(artifact, projectKey: key)
+    } catch {
+      AppLogger.session.error("Failed to rewrite studio document \(artifact.id): \(error.localizedDescription)")
+    }
+  }
+
+  /// Republishes the agent-readable index for a project. This is how
+  /// `agenthub_list_artifacts` sees anything: the CLI never opens the database.
+  private func publishIndex(forKey key: String, aliasPaths: [String]) {
+    let entries = (artifactsByProject[key] ?? []).map { artifact in
+      let documentURL = documents.documentURL(forArtifactId: artifact.id, projectKey: key)
+      return StudioIndexEntry(
+        artifact: artifact,
+        documentPath: documentURL.path,
+        payloadPath: StudioDocumentWriter.payloadURL(besideDocument: documentURL).path
+      )
+    }
+    let index = StudioIndex(projectPath: key, updatedAt: .now, artifacts: entries)
+    let store = self.index
+    Task.detached(priority: .utility) {
+      do {
+        try store.write(index, aliasPaths: aliasPaths)
+      } catch {
+        AppLogger.session.error("Failed to publish studio index: \(error.localizedDescription)")
+      }
+    }
+  }
+
+  /// Union by id, newest-filed first. Incoming wins on collision.
+  static func merged(existing: [StudioArtifact], incoming: [StudioArtifact]) -> [StudioArtifact] {
+    let incomingIds = Set(incoming.map(\.id))
+    return (incoming + existing.filter { !incomingIds.contains($0.id) })
+      .sorted {
+        if $0.createdAt == $1.createdAt { return $0.id > $1.id }
+        return $0.createdAt > $1.createdAt
+      }
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioPromotionPromptBuilder.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioPromotionPromptBuilder.swift
new file mode 100644
index 00000000..221e3068
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioPromotionPromptBuilder.swift
@@ -0,0 +1,47 @@
+import AgentHubCLIKit
+import Foundation
+
+/// Composes the prompt for **Promote…** — the one action in Studio that asks
+/// the agent to write real code.
+///
+/// Sends the variant's *original* markup and CSS, never the scoped rewrite:
+/// `.studio-artboard[data-variant=…]` selectors are an artefact of the canvas
+/// and must never reach a codebase.
+public enum StudioPromotionPromptBuilder {
+  public static func prompt(artifact: StudioArtifact, variantName: String) -> String? {
+    guard artifact.kind == .canvas,
+          let variant = artifact.variants.first(where: { $0.name == variantName })
+    else {
+      return nil
+    }
+
+    var lines: [String] = []
+    var opening = "Implement the \"\(variant.name)\" variant from the Studio design canvas \"\(artifact.title)\" (id \(artifact.id)) in the real project"
+    if let sourcePath = artifact.sourcePath, !sourcePath.isEmpty {
+      opening += ", in \(sourcePath)"
+    }
+    opening += "."
+    lines.append(opening)
+    lines.append("")
+
+    lines.append("Variant markup:")
+    lines.append("```html")
+    lines.append(variant.html)
+    lines.append("```")
+    if !variant.css.isEmpty {
+      lines.append("")
+      lines.append("Variant CSS:")
+      lines.append("```css")
+      lines.append(variant.css)
+      lines.append("```")
+    }
+    if let notes = variant.notes, !notes.isEmpty {
+      lines.append("")
+      lines.append("Design notes: \(notes)")
+    }
+    lines.append("")
+    lines.append("Preserve the component's existing behaviour, props, and public API; change presentation only, and follow the project's conventions rather than pasting this markup verbatim. When done, list the files you changed.")
+
+    return lines.joined(separator: "\n")
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioStaticServer.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioStaticServer.swift
new file mode 100644
index 00000000..c0bfb207
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioStaticServer.swift
@@ -0,0 +1,252 @@
+import Foundation
+import Network
+
+public protocol StudioStaticServing: Sendable {
+  /// Starts the server if needed and returns its base URL (`http://127.0.0.1:{port}/`).
+  func start() async throws -> URL
+  func stop() async
+}
+
+/// A tiny loopback HTTP/1.1 file server for Studio documents.
+///
+/// In-process rather than `python3 -m http.server`: Studio content is AgentHub's
+/// own directory, so there is no child process to track and reap, no python
+/// dependency, and no readiness heuristics — and `Cache-Control: no-store` makes
+/// re-file reload free. GET/HEAD only, bound to `127.0.0.1`, serves only under
+/// `rootURL`, refuses anything that escapes it. Studio content is unreviewed
+/// agent-generated HTML: it must not be reachable off the machine, and this must
+/// never become a file-read primitive.
+public actor StudioStaticServer: StudioStaticServing {
+  public enum ServerError: Error, Equatable {
+    case failedToStart(String)
+  }
+
+  public let rootURL: URL
+  private var listener: NWListener?
+  private var baseURL: URL?
+  private var startContinuations: [CheckedContinuation<URL, Error>] = []
+  private let queue = DispatchQueue(label: "com.agenthub.studio-static-server")
+
+  public init(rootURL: URL) {
+    self.rootURL = rootURL.standardizedFileURL
+  }
+
+  public func start() async throws -> URL {
+    if let baseURL { return baseURL }
+    if listener != nil {
+      return try await withCheckedThrowingContinuation { continuation in
+        startContinuations.append(continuation)
+      }
+    }
+
+    let parameters = NWParameters.tcp
+    parameters.allowLocalEndpointReuse = true
+    parameters.requiredLocalEndpoint = .hostPort(host: .ipv4(.loopback), port: .any)
+
+    let listener: NWListener
+    do {
+      listener = try NWListener(using: parameters)
+    } catch {
+      throw ServerError.failedToStart(error.localizedDescription)
+    }
+    self.listener = listener
+
+    return try await withCheckedThrowingContinuation { continuation in
+      startContinuations.append(continuation)
+
+      listener.stateUpdateHandler = { [weak self] state in
+        guard let self else { return }
+        Task { await self.handleListenerState(state) }
+      }
+      listener.newConnectionHandler = { [weak self] connection in
+        guard let self else { return }
+        Task { await self.handle(connection) }
+      }
+      listener.start(queue: queue)
+    }
+  }
+
+  public func stop() async {
+    listener?.cancel()
+    listener = nil
+    baseURL = nil
+    let waiting = startContinuations
+    startContinuations.removeAll()
+    for continuation in waiting {
+      continuation.resume(throwing: ServerError.failedToStart("Server stopped."))
+    }
+  }
+
+  private func handleListenerState(_ state: NWListener.State) {
+    switch state {
+    case .ready:
+      guard let port = listener?.port?.rawValue else { return }
+      let url = URL(string: "http://127.0.0.1:\(port)/")!
+      baseURL = url
+      let waiting = startContinuations
+      startContinuations.removeAll()
+      for continuation in waiting { continuation.resume(returning: url) }
+    case .failed(let error):
+      listener?.cancel()
+      listener = nil
+      baseURL = nil
+      let waiting = startContinuations
+      startContinuations.removeAll()
+      for continuation in waiting {
+        continuation.resume(throwing: ServerError.failedToStart(error.localizedDescription))
+      }
+    case .cancelled:
+      baseURL = nil
+    default:
+      break
+    }
+  }
+
+  // MARK: - Connections
+
+  private func handle(_ connection: NWConnection) {
+    let root = rootURL
+    let handler = ConnectionHandler(connection: connection, rootURL: root)
+    connection.stateUpdateHandler = { state in
+      if case .ready = state { handler.receiveRequest() }
+    }
+    connection.start(queue: queue)
+  }
+
+  /// One request per connection; the response always closes it.
+  private final class ConnectionHandler: @unchecked Sendable {
+    private let connection: NWConnection
+    private let rootURL: URL
+    private var buffer = Data()
+
+    init(connection: NWConnection, rootURL: URL) {
+      self.connection = connection
+      self.rootURL = rootURL
+    }
+
+    func receiveRequest() {
+      connection.receive(minimumIncompleteLength: 1, maximumLength: 65_536) { [self] data, _, isComplete, error in
+        if let data { buffer.append(data) }
+        if let headerEnd = buffer.range(of: Data("\r\n\r\n".utf8)) {
+          let head = String(decoding: buffer[..<headerEnd.lowerBound], as: UTF8.self)
+          respond(to: head)
+          return
+        }
+        if error != nil || isComplete || buffer.count > 65_536 {
+          connection.cancel()
+          return
+        }
+        receiveRequest()
+      }
+    }
+
+    private func respond(to head: String) {
+      let requestLine = head.split(separator: "\r\n", maxSplits: 1).first.map(String.init) ?? ""
+      let response = StudioStaticServer.response(forRequestLine: requestLine, rootURL: rootURL)
+      connection.send(content: response, completion: .contentProcessed { [connection] _ in
+        connection.cancel()
+      })
+    }
+  }
+
+  // MARK: - Request handling (pure, testable)
+
+  struct Response: Equatable {
+    let status: Int
+    let reason: String
+    let contentType: String
+    let body: Data
+    let includeBody: Bool
+
+    var data: Data {
+      var head = "HTTP/1.1 \(status) \(reason)\r\n"
+      head += "Content-Type: \(contentType)\r\n"
+      head += "Content-Length: \(body.count)\r\n"
+      head += "Cache-Control: no-store\r\n"
+      head += "X-Content-Type-Options: nosniff\r\n"
+      head += "Connection: close\r\n\r\n"
+      var data = Data(head.utf8)
+      if includeBody { data.append(body) }
+      return data
+    }
+  }
+
+  static func response(forRequestLine line: String, rootURL: URL) -> Data {
+    resolve(requestLine: line, rootURL: rootURL).data
+  }
+
+  static func resolve(requestLine line: String, rootURL: URL) -> Response {
+    let parts = line.split(separator: " ")
+    guard parts.count >= 2 else {
+      return Response(status: 400, reason: "Bad Request", contentType: "text/plain", body: Data("Bad request".utf8), includeBody: true)
+    }
+    let method = String(parts[0])
+    guard method == "GET" || method == "HEAD" else {
+      return Response(status: 405, reason: "Method Not Allowed", contentType: "text/plain", body: Data("Method not allowed".utf8), includeBody: true)
+    }
+    let includeBody = method == "GET"
+
+    guard let fileURL = fileURL(forRequestPath: String(parts[1]), rootURL: rootURL) else {
+      return Response(status: 404, reason: "Not Found", contentType: "text/plain", body: Data("Not found".utf8), includeBody: includeBody)
+    }
+    guard let body = try? Data(contentsOf: fileURL) else {
+      return Response(status: 404, reason: "Not Found", contentType: "text/plain", body: Data("Not found".utf8), includeBody: includeBody)
+    }
+    return Response(
+      status: 200,
+      reason: "OK",
+      contentType: contentType(forExtension: fileURL.pathExtension),
+      body: body,
+      includeBody: includeBody
+    )
+  }
+
+  /// Maps a request path to a file strictly inside `rootURL`, or nil.
+  static func fileURL(forRequestPath rawPath: String, rootURL: URL) -> URL? {
+    var path = rawPath
+    if let query = path.firstIndex(of: "?") { path = String(path[..<query]) }
+    if let fragment = path.firstIndex(of: "#") { path = String(path[..<fragment]) }
+    guard let decoded = path.removingPercentEncoding, decoded.hasPrefix("/") else { return nil }
+    guard !decoded.contains("\0") else { return nil }
+
+    let components = decoded.split(separator: "/", omittingEmptySubsequences: true).map(String.init)
+    guard !components.contains(where: { $0 == ".." || $0 == "." || $0.hasPrefix(".") }) else { return nil }
+
+    var url = rootURL.standardizedFileURL
+    for component in components {
+      url.appendPathComponent(component)
+    }
+    var isDirectory: ObjCBool = false
+    if decoded.hasSuffix("/") || (FileManager.default.fileExists(atPath: url.path, isDirectory: &isDirectory) && isDirectory.boolValue) {
+      url.appendPathComponent("index.html")
+    }
+    let resolved = url.standardizedFileURL
+    let rootPath = rootURL.standardizedFileURL.path.hasSuffix("/") ? rootURL.standardizedFileURL.path : rootURL.standardizedFileURL.path + "/"
+    guard resolved.path.hasPrefix(rootPath) else { return nil }
+    guard FileManager.default.fileExists(atPath: resolved.path, isDirectory: &isDirectory), !isDirectory.boolValue else { return nil }
+    return resolved
+  }
+
+  static func contentType(forExtension ext: String) -> String {
+    switch ext.lowercased() {
+    case "html", "htm": return "text/html; charset=utf-8"
+    case "css": return "text/css; charset=utf-8"
+    case "js", "mjs": return "text/javascript; charset=utf-8"
+    case "json", "map": return "application/json; charset=utf-8"
+    case "svg": return "image/svg+xml"
+    case "png": return "image/png"
+    case "jpg", "jpeg": return "image/jpeg"
+    case "gif": return "image/gif"
+    case "webp": return "image/webp"
+    case "ico": return "image/x-icon"
+    case "woff2": return "font/woff2"
+    case "woff": return "font/woff"
+    case "ttf": return "font/ttf"
+    case "otf": return "font/otf"
+    case "mp4": return "video/mp4"
+    case "webm": return "video/webm"
+    case "txt", "md": return "text/plain; charset=utf-8"
+    default: return "application/octet-stream"
+    }
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioStorageReconciler.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioStorageReconciler.swift
new file mode 100644
index 00000000..5cffea57
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioStorageReconciler.swift
@@ -0,0 +1,78 @@
+import Foundation
+
+/// Keeps the served-document cache honest with the database.
+///
+/// The database is the source of truth and the `studio/{project}/{id}/` tree
+/// is derived from it, so reconcile means: drop directories with no row (a
+/// crash between the two deletes, or a row that vanished), and leave everything
+/// else alone. Missing documents for live rows are rewritten lazily by the
+/// library when the project loads — never here, which keeps this pure and cheap.
+public struct StudioStorageReconciler: Sendable {
+  public struct Report: Equatable, Sendable {
+    public var removedArtifactDirectories: Int = 0
+    public var removedEmptyProjectDirectories: Int = 0
+  }
+
+  public let rootURL: URL
+
+  public init(rootURL: URL) {
+    self.rootURL = rootURL
+  }
+
+  /// `knownDirectoryNames` are the on-disk artifact directory names the
+  /// database vouches for (`StudioDocumentWriter.artifactDirectoryName`).
+  @discardableResult
+  public func reconcile(knownDirectoryNames: Set<String>) -> Report {
+    var report = Report()
+    let fileManager = FileManager.default
+    guard let projects = try? fileManager.contentsOfDirectory(
+      at: rootURL,
+      includingPropertiesForKeys: [.isDirectoryKey],
+      options: [.skipsHiddenFiles]
+    ) else {
+      return report
+    }
+
+    for project in projects {
+      guard (try? project.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true else { continue }
+      let artifacts = (try? fileManager.contentsOfDirectory(
+        at: project,
+        includingPropertiesForKeys: [.isDirectoryKey],
+        options: [.skipsHiddenFiles]
+      )) ?? []
+
+      for artifact in artifacts {
+        guard (try? artifact.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true else { continue }
+        if !knownDirectoryNames.contains(artifact.lastPathComponent) {
+          if (try? fileManager.removeItem(at: artifact)) != nil {
+            report.removedArtifactDirectories += 1
+          }
+        }
+      }
+
+      let remaining = (try? fileManager.contentsOfDirectory(atPath: project.path)) ?? []
+      if remaining.filter({ !$0.hasPrefix(".") }).isEmpty {
+        if (try? fileManager.removeItem(at: project)) != nil {
+          report.removedEmptyProjectDirectories += 1
+        }
+      }
+    }
+    return report
+  }
+
+  /// Bytes on disk under one artifact directory, for the Settings view.
+  public static func directorySize(at url: URL) -> Int64 {
+    guard let enumerator = FileManager.default.enumerator(
+      at: url,
+      includingPropertiesForKeys: [.fileSizeKey],
+      options: [.skipsHiddenFiles]
+    ) else {
+      return 0
+    }
+    var total: Int64 = 0
+    for case let file as URL in enumerator {
+      total += Int64((try? file.resourceValues(forKeys: [.fileSizeKey]).fileSize) ?? 0)
+    }
+    return total
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioTweaksPromptBuilder.swift b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioTweaksPromptBuilder.swift
new file mode 100644
index 00000000..26c1cf68
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/Services/StudioTweaksPromptBuilder.swift
@@ -0,0 +1,59 @@
+import AgentHubCLIKit
+import Canvas
+import Foundation
+
+/// Prompts for the Tweaks panel's agent actions on a Studio artifact.
+///
+/// Web preview runs a headless agent that edits the previewed file on disk.
+/// Studio has no such file — the served document is a cache of the payload —
+/// so every action goes back through the *session* as a re-file request, on
+/// the same rails as Send. The agent re-files with the same id and the panel
+/// updates in place.
+public enum StudioTweaksPromptBuilder {
+  public static func ideasPrompt(artifact: StudioArtifact, existingProps: [TweakProp]) -> String {
+    let existing = existingProps.isEmpty
+      ? "There are no tweakable props yet."
+      : "Existing props (keep them exactly as they are): " + existingProps.map { "\($0.name) (\($0.type.rawValue))" }.joined(separator: ", ") + "."
+    return """
+    Add two or three new tweakable controls to the Studio \(noun(artifact)) "\(artifact.title)" (id \(artifact.id)) — expressive knobs that reshape the feel (density, tone, emphasis, motion), not single-pixel adjustments, and meaningfully different from every existing control.
+    \(existing)
+
+    \(contract(artifact))
+    """
+  }
+
+  public static func customPrompt(artifact: StudioArtifact, instruction: String) -> String {
+    """
+    Add tweakable controls to the Studio \(noun(artifact)) "\(artifact.title)" (id \(artifact.id)): \(instruction)
+
+    \(contract(artifact))
+    """
+  }
+
+  public static func deleteAllPrompt(artifact: StudioArtifact) -> String {
+    let how = artifact.kind == .canvas
+      ? "Re-file with agenthub_design using id \(artifact.id) with no `props`, and replace every var(--<name>) in the variants' CSS with the current default value so every variant looks exactly as it does now."
+      : "Re-file with agenthub_artifact using id \(artifact.id) with the dc_set_props call, dc_on_props_changed, and every prop read removed, hard-coding the current default values so the document looks and behaves exactly as it does now."
+    return """
+    Remove all tweakable controls from the Studio \(noun(artifact)) "\(artifact.title)" (id \(artifact.id)). \(how)
+    This is a scratch surface: do not edit project files.
+    """
+  }
+
+  private static func noun(_ artifact: StudioArtifact) -> String {
+    artifact.kind == .canvas ? "design canvas" : "artifact"
+  }
+
+  private static func contract(_ artifact: StudioArtifact) -> String {
+    switch artifact.kind {
+    case .canvas:
+      return """
+      Re-file the canvas with agenthub_design using id \(artifact.id): keep every variant and existing prop unchanged, extend `props` with the new controls (one shared schema for the whole canvas — each prop becomes the CSS custom property --<name> on every artboard, slider values carry their `unit`), and update the variants' CSS to read var(--<name>) so the controls visibly change every variant. Text/select props also fill elements marked data-prop="<name>". This is a scratch surface: do not edit project files.
+      """
+    case .document:
+      return """
+      Re-file the document with agenthub_artifact using id \(artifact.id): keep everything else unchanged, extend the existing dc_set_props object literal in place (preserve every existing prop's name, label, type, range/options, default, and order), read the new values via window.props.<name> or dc_on_props_changed, and drive them into the DOM/CSS so they visibly change the design. This is a scratch surface: do not edit project files.
+      """
+    }
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/UI/EmbeddedTerminalLaunchBuilder.swift b/app/modules/AgentHubCore/Sources/AgentHub/UI/EmbeddedTerminalLaunchBuilder.swift
index 1ee3dd5d..4a47dae8 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/UI/EmbeddedTerminalLaunchBuilder.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/UI/EmbeddedTerminalLaunchBuilder.swift
@@ -69,6 +69,7 @@ public enum EmbeddedTerminalLaunchBuilder {
       agentHubCLIPath: agentHubCLIPath,
       installAgentHubWorktreeSkill: {
         AgentHubWorktreeSkillInstaller.installBundledSkillForAllProvidersBestEffort()
+        AgentHubStudioSkillInstaller.installBundledSkillForAllProvidersBestEffort()
       },
       removeLegacyAgentHubSessionNamingSkill: {
         AgentHubSessionNamingSkillCleanup.removeInstalledSkillBestEffort()
@@ -90,6 +91,8 @@ public enum EmbeddedTerminalLaunchBuilder {
     installAgentHubWorktreeSkill: () -> Void,
     removeLegacyAgentHubSessionNamingSkill: () -> Void = {},
     xcodeBuildMCPEnabled: Bool = XcodeBuildMCPPreflight.isEnabled(),
+    studioGuidanceEnabled: Bool = StudioAgentGuidance.isEnabled(),
+    codexGlobalApprovalPolicy: String? = CodexGlobalConfigReader.approvalPolicy(),
     xcodeBuildMCPToolingAvailable: () -> Bool = { XcodeBuildMCPPreflight.nodeToolingAvailable() },
     notifyXcodeBuildMCPToolingMissing: () -> Void = { Task { @MainActor in XcodeBuildMCPNodeNotice.notifyOnce() } }
   ) -> Result<EmbeddedTerminalLaunch, EmbeddedTerminalLaunchError> {
@@ -150,6 +153,11 @@ public enum EmbeddedTerminalLaunchBuilder {
     // agents verify through the same live app surface the user is watching.
     // Tied to the bootstrap: guidance without the tools misleads agents.
     let simulatorGuidance = xcodeBuildMCPBootstrap == nil ? nil : SimulatorAgentGuidance.systemPrompt
+    // Studio guidance rides the same channel, tied to the bundled MCP server
+    // being attached: the tools it names must actually exist in the session.
+    let studioGuidance = studioGuidanceEnabled && resolvedAgentHubCLIPath?.isEmpty == false
+      ? StudioAgentGuidance.systemPrompt
+      : nil
     // Curated launch context rides the same out-of-band channel (Claude
     // `--append-system-prompt`, Codex `-c developer_instructions=`) instead of
     // the first user message. New sessions get it from the launch flow; resume
@@ -165,6 +173,7 @@ public enum EmbeddedTerminalLaunchBuilder {
     }
     let appendSystemPrompt = combinedAppendSystemPrompt(
       simulatorGuidance: simulatorGuidance,
+      studioGuidance: studioGuidance,
       launchContext: resolvedLaunchContext
     )
     let args = cliConfiguration.argumentsForSession(
@@ -189,6 +198,7 @@ public enum EmbeddedTerminalLaunchBuilder {
       allowedTools: allowedTools.isEmpty ? nil : allowedTools,
       disallowedTools: disallowedTools.isEmpty ? nil : disallowedTools,
       codexApprovalPolicy: aiConfig?.approvalPolicy,
+      codexGlobalApprovalPolicy: codexGlobalApprovalPolicy,
       xcodeBuildMCPBootstrap: xcodeBuildMCPBootstrap,
       appendSystemPrompt: appendSystemPrompt
     )
@@ -293,12 +303,16 @@ public enum EmbeddedTerminalLaunchBuilder {
   /// (short operational instructions), then the bulky context block.
   static func combinedAppendSystemPrompt(
     simulatorGuidance: String?,
+    studioGuidance: String? = nil,
     launchContext: String?
   ) -> String? {
     var parts: [String] = []
     if let simulatorGuidance, !simulatorGuidance.isEmpty {
       parts.append(simulatorGuidance)
     }
+    if let studioGuidance, !studioGuidance.isEmpty {
+      parts.append(studioGuidance)
+    }
     if let context = launchContext?.trimmingCharacters(in: .whitespacesAndNewlines), !context.isEmpty {
       parts.append(launchContextPreamble + "\n" + context)
     }
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/UI/MonitoringCardView.swift b/app/modules/AgentHubCore/Sources/AgentHub/UI/MonitoringCardView.swift
index 054cb478..395aa900 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/UI/MonitoringCardView.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/UI/MonitoringCardView.swift
@@ -44,6 +44,7 @@ public struct MonitoringCardView: View {
   let onShowMCPApp: ((CLISession, String) -> Void)?
   let onShowMeasurement: ((CLISession) -> Void)?
   let onShowArtifact: ((CLISession) -> Void)?
+  let onShowStudio: ((CLISession) -> Void)?
   let onShowSimulatorPreview: ((CLISession, String) -> Void)?
   let onFork: ((CLISession, SessionProviderKind) -> Void)?
   let onPromptConsumed: (() -> Void)?
@@ -101,6 +102,7 @@ public struct MonitoringCardView: View {
     onShowMCPApp: ((CLISession, String) -> Void)? = nil,
     onShowMeasurement: ((CLISession) -> Void)? = nil,
     onShowArtifact: ((CLISession) -> Void)? = nil,
+    onShowStudio: ((CLISession) -> Void)? = nil,
     onShowSimulatorPreview: ((CLISession, String) -> Void)? = nil,
     onFork: ((CLISession, SessionProviderKind) -> Void)? = nil,
     onPromptConsumed: (() -> Void)? = nil,
@@ -142,6 +144,7 @@ public struct MonitoringCardView: View {
     self.onShowMCPApp = onShowMCPApp
     self.onShowMeasurement = onShowMeasurement
     self.onShowArtifact = onShowArtifact
+    self.onShowStudio = onShowStudio
     self.onShowSimulatorPreview = onShowSimulatorPreview
     self.onFork = onFork
     self.onPromptConsumed = onPromptConsumed
@@ -237,6 +240,15 @@ public struct MonitoringCardView: View {
       : "Open \(detectedArtifacts.count) published artifacts"
   }
 
+  /// Studio items filed for this session's project — shared across both providers.
+  private var studioArtifactCount: Int {
+    viewModel?.studioArtifacts(for: session).count ?? 0
+  }
+
+  private var studioButtonAccessibilityLabel: String {
+    studioArtifactCount == 1 ? "Open 1 Studio artifact" : "Open \(studioArtifactCount) Studio artifacts"
+  }
+
   private var measurementButtonAccessibilityLabel: String {
     measurementCount == 1 ? "Open 1 recorded measurement" : "Open \(measurementCount) recorded measurements"
   }
@@ -349,6 +361,7 @@ public struct MonitoringCardView: View {
     // what this project already holds — not just what this session produced.
     .task(id: session.projectPath) {
       viewModel?.loadMeasurements(for: session)
+      viewModel?.loadStudioArtifacts(for: session)
     }
     .task(id: gitHubObservationTaskID) {
       if linkedPullRequests.isEmpty {
@@ -850,6 +863,28 @@ public struct MonitoringCardView: View {
           .accessibilityLabel(measurementButtonAccessibilityLabel)
         }
 
+        // Studio button — appears only once the agent has filed an artifact or
+        // design canvas for this project (Claude or Codex alike).
+        if onShowStudio != nil, studioArtifactCount > 0 {
+          Button(action: {
+            onShowStudio?(session)
+          }) {
+            HStack(spacing: 4) {
+              Image(systemName: "paintpalette")
+                .font(.caption2)
+              Text("Studio")
+              if studioArtifactCount > 1 {
+                Text("\(studioArtifactCount)")
+                  .font(.system(.caption2, design: .monospaced))
+                  .foregroundStyle(.secondary)
+              }
+            }
+          }
+          .buttonStyle(.agentHubOutlined)
+          .help("Open artifacts and design canvases the agent rendered")
+          .accessibilityLabel(studioButtonAccessibilityLabel)
+        }
+
         // Artifact button — only once the agent has actually published one to
         // claude.ai, and only where the panel can host it.
         if onShowArtifact != nil, !detectedArtifacts.isEmpty {
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/UI/MultiProviderMonitoringPanelView.swift b/app/modules/AgentHubCore/Sources/AgentHub/UI/MultiProviderMonitoringPanelView.swift
index 485e7f51..4ccf39b6 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/UI/MultiProviderMonitoringPanelView.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/UI/MultiProviderMonitoringPanelView.swift
@@ -23,7 +23,10 @@ enum SidePanelContent: Equatable {
   case mcpApp(sessionId: String, session: CLISession, projectPath: String)
   case simulator(sessionId: String, session: CLISession, projectPath: String)
   case measurements(sessionId: String, session: CLISession)
-  case artifact(sessionId: String, session: CLISession)
+  /// A claude.ai artifact the agent published (detected in the transcript).
+  case claudeArtifact(sessionId: String, session: CLISession)
+  /// AgentHub Studio: artifacts and design canvases filed with agenthub_artifact / agenthub_design.
+  case studio(sessionId: String, session: CLISession)
 
   static func == (lhs: SidePanelContent, rhs: SidePanelContent) -> Bool {
     switch (lhs, rhs) {
@@ -45,7 +48,9 @@ enum SidePanelContent: Equatable {
       return id1 == id2 && p1 == p2
     case (.measurements(let id1, _), .measurements(let id2, _)):
       return id1 == id2
-    case (.artifact(let id1, _), .artifact(let id2, _)):
+    case (.claudeArtifact(let id1, _), .claudeArtifact(let id2, _)):
+      return id1 == id2
+    case (.studio(let id1, _), .studio(let id2, _)):
       return id1 == id2
     default: return false
     }
@@ -611,7 +616,13 @@ public struct MultiProviderMonitoringPanelView: View {
             },
             onShowArtifact: { session in
               toggleSidePanel(
-                .artifact(sessionId: session.id, session: session),
+                .claudeArtifact(sessionId: session.id, session: session),
+                forItemID: item.id
+              )
+            },
+            onShowStudio: { session in
+              toggleSidePanel(
+                .studio(sessionId: session.id, session: session),
                 forItemID: item.id
               )
             },
@@ -717,7 +728,13 @@ public struct MultiProviderMonitoringPanelView: View {
             },
             onShowArtifact: { session in
               toggleSidePanel(
-                .artifact(sessionId: session.id, session: session),
+                .claudeArtifact(sessionId: session.id, session: session),
+                forItemID: item.id
+              )
+            },
+            onShowStudio: { session in
+              toggleSidePanel(
+                .studio(sessionId: session.id, session: session),
                 forItemID: item.id
               )
             },
@@ -910,7 +927,7 @@ public struct MultiProviderMonitoringPanelView: View {
     switch content {
     case .edits, .plan:
       return true
-    case .diff, .webPreview, .mermaid, .gitHub, .mcpApp, .simulator, .measurements, .artifact:
+    case .diff, .webPreview, .mermaid, .gitHub, .mcpApp, .simulator, .measurements, .claudeArtifact, .studio:
       return false
     }
   }
@@ -1156,7 +1173,7 @@ public struct MultiProviderMonitoringPanelView: View {
         onDismiss: closeEmbeddedSidePanel,
         isEmbedded: true
       )
-    case .artifact(let sessionId, _):
+    case .claudeArtifact(let sessionId, _):
       ArtifactSidePanelView(
         artifacts: viewModel.monitorStates[sessionId]?.detectedArtifacts ?? [],
         onDismiss: closeEmbeddedSidePanel,
@@ -1164,6 +1181,20 @@ public struct MultiProviderMonitoringPanelView: View {
         isExpanded: sidePanelExpansion.isExpanded(for: payload),
         onToggleExpanded: { toggleEmbeddedSidePanelExpansion(for: payload) }
       )
+    case .studio(_, let session):
+      StudioSidePanelView(
+        session: session,
+        viewModel: viewModel,
+        onDismiss: closeEmbeddedSidePanel,
+        isEmbedded: true,
+        isExpanded: sidePanelExpansion.isExpanded(for: payload),
+        onToggleExpanded: { toggleEmbeddedSidePanelExpansion(for: payload) },
+        onSendPrompt: { prompt, sess in
+          if !viewModel.sendPromptToActiveTerminal(forKey: sess.id, prompt: prompt) {
+            viewModel.showTerminalWithPrompt(for: sess, prompt: prompt)
+          }
+        }
+      )
     }
   }
 
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/UI/SettingsView.swift b/app/modules/AgentHubCore/Sources/AgentHub/UI/SettingsView.swift
index ae23ccb1..ca287d9c 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/UI/SettingsView.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/UI/SettingsView.swift
@@ -167,6 +167,11 @@ public struct SettingsView: View {
           Label("Measurements", systemImage: "chart.bar.doc.horizontal")
         }
 
+      StudioSettingsView()
+        .tabItem {
+          Label("Studio", systemImage: "paintpalette")
+        }
+
       appearanceSettingsForm
         .tabItem {
           Label("Appearance", systemImage: "paintpalette")
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioDesignEditState.swift b/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioDesignEditState.swift
new file mode 100644
index 00000000..694029a0
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioDesignEditState.swift
@@ -0,0 +1,160 @@
+//
+//  StudioDesignEditState.swift
+//  AgentHub
+//
+//  Edit-mode state for the Studio panel: live design edits applied to the
+//  scratch page and batched per element until the user sends them to the
+//  agent as a re-file request. Studio has no source files to map to, so this
+//  is deliberately the small subset of `WebPreviewInspectorViewModel` that
+//  matters here: apply live, remember the delta, compose the prompt.
+//
+
+import Canvas
+import Foundation
+import Observation
+import WebKit
+
+@MainActor
+@Observable
+final class StudioDesignEditState {
+  /// One element's pending changes plus what we know about where it sits.
+  struct ElementEdits: Equatable {
+    var batch: WebPreviewPendingDesignEditBatch
+    var variantName: String?
+    var fitToContent = false
+    var deleted = false
+
+    var isEmpty: Bool { batch.isEmpty && !fitToContent && !deleted }
+    var changeCount: Int { batch.changeCount + (fitToContent ? 1 : 0) + (deleted ? 1 : 0) }
+  }
+
+  private(set) var selectedElement: ElementInspectorData?
+  private(set) var toolbarValues: DesignToolbarValues?
+  /// Keyed by selector; insertion order preserved in `order`.
+  private(set) var edits: [String: ElementEdits] = [:]
+  private(set) var order: [String] = []
+
+  var pendingChangeCount: Int {
+    edits.values.reduce(0) { $0 + $1.changeCount }
+  }
+
+  var hasPendingEdits: Bool { pendingChangeCount > 0 }
+
+  var orderedEdits: [ElementEdits] {
+    order.compactMap { edits[$0] }.filter { !$0.isEmpty }
+  }
+
+  // MARK: Selection
+
+  func select(_ element: ElementInspectorData, variantName: String?) {
+    selectedElement = element
+    toolbarValues = DesignToolbarValues(element: element)
+    if edits[element.cssSelector] == nil {
+      edits[element.cssSelector] = ElementEdits(batch: WebPreviewPendingDesignEditBatch(element: element), variantName: variantName)
+      order.append(element.cssSelector)
+    } else if edits[element.cssSelector]?.variantName == nil {
+      edits[element.cssSelector]?.variantName = variantName
+    }
+  }
+
+  func deselect() {
+    selectedElement = nil
+    toolbarValues = nil
+  }
+
+  /// Refreshes toolbar controls in place from a new DOM capture. Replacing the
+  /// values object would reset bound editors mid-keystroke; properties the
+  /// user already edited keep their pending value so the page's normalized
+  /// read-back (`#fff` → `rgb(255, 255, 255)`) does not fight the controls.
+  func refresh(with element: ElementInspectorData) {
+    guard let selectedElement, selectedElement.cssSelector == element.cssSelector else { return }
+    self.selectedElement = element
+    let refreshed = DesignToolbarValues(element: element)
+    guard let values = toolbarValues, values.category == refreshed.category else {
+      toolbarValues = refreshed
+      return
+    }
+    let edited = Set(edits[element.cssSelector]?.batch.styleChanges.map(\.property) ?? [])
+    func adopt(_ property: String, _ apply: () -> Void) {
+      if !edited.contains(property) { apply() }
+    }
+    values.fontFamilyOptions = refreshed.fontFamilyOptions
+    adopt("font-family") { values.fontFamily = refreshed.fontFamily }
+    adopt("color") { values.color = refreshed.color }
+    adopt("background-color") { values.backgroundColor = refreshed.backgroundColor }
+    adopt("font-size") { values.fontSize = refreshed.fontSize }
+    adopt("font-weight") { values.isBold = refreshed.isBold }
+    adopt("font-style") { values.isItalic = refreshed.isItalic }
+    adopt("text-align") { values.textAlign = refreshed.textAlign }
+    adopt("letter-spacing") { values.letterSpacing = refreshed.letterSpacing }
+    adopt("line-height") { values.lineHeight = refreshed.lineHeight }
+    adopt("border-radius") { values.borderRadius = refreshed.borderRadius }
+    adopt("padding") { values.padding = refreshed.padding }
+    adopt("margin") { values.margin = refreshed.margin }
+    adopt("object-fit") { values.objectFit = refreshed.objectFit }
+    if edits[element.cssSelector]?.batch.textChange == nil {
+      values.textContent = refreshed.textContent
+    }
+  }
+
+  // MARK: Editing
+
+  /// Applies an edit live to the page and records the delta.
+  func apply(_ edit: DesignEdit, in webView: WKWebView?) {
+    guard let selectedElement, edit.element.cssSelector == selectedElement.cssSelector else { return }
+    if let webView {
+      ElementInspectorBridge.applyDesignEdit(edit, in: webView)
+    }
+    let key = selectedElement.cssSelector
+    switch edit.action {
+    case .updateProperty(let property, let value):
+      let old = Self.computedValue(for: property, in: selectedElement)
+      edits[key]?.batch.recordStyleChange(property: property.rawValue, oldValue: old, newValue: value)
+      Self.mirror(property, value: value, into: toolbarValues)
+    case .updateTextContent(let text):
+      edits[key]?.batch.recordTextChange(oldText: selectedElement.textContent, newText: text)
+      toolbarValues?.textContent = text
+    case .fitContent:
+      edits[key]?.fitToContent = true
+    case .deleteElement:
+      edits[key]?.deleted = true
+      deselect()
+    }
+  }
+
+  func clear() {
+    edits.removeAll()
+    order.removeAll()
+    deselect()
+  }
+
+  // MARK: Helpers
+
+  static func computedValue(for property: DesignEdit.Property, in element: ElementInspectorData) -> String? {
+    let parts = property.rawValue.split(separator: "-")
+    let camel = parts.enumerated().map { index, part in
+      index == 0 ? String(part) : part.prefix(1).uppercased() + part.dropFirst()
+    }.joined()
+    let value = element.computedStyles[camel]?.trimmingCharacters(in: .whitespacesAndNewlines)
+    return value?.isEmpty == false ? value : nil
+  }
+
+  private static func mirror(_ property: DesignEdit.Property, value: String, into values: DesignToolbarValues?) {
+    guard let values else { return }
+    switch property {
+    case .fontFamily: values.fontFamily = value
+    case .color: values.color = value
+    case .backgroundColor: values.backgroundColor = value
+    case .fontSize: values.fontSize = CSSParser.parsePixelValue(value) ?? values.fontSize
+    case .fontWeight: values.isBold = CSSParser.isBoldWeight(value)
+    case .fontStyle: values.isItalic = value == "italic"
+    case .textAlign: values.textAlign = DesignTextAlignment(rawValue: value) ?? values.textAlign
+    case .letterSpacing: values.letterSpacing = value
+    case .lineHeight: values.lineHeight = value
+    case .borderRadius: values.borderRadius = value
+    case .padding: values.padding = value
+    case .margin: values.margin = value
+    case .objectFit: values.objectFit = value
+    }
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioPanelState.swift b/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioPanelState.swift
new file mode 100644
index 00000000..9422ea70
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioPanelState.swift
@@ -0,0 +1,79 @@
+import AgentHubCLIKit
+import Foundation
+import Observation
+
+/// Everything the Studio panel decides, kept out of the view so it can be tested.
+@MainActor
+@Observable
+public final class StudioPanelState {
+  /// Explicit user selection. `nil` means "follow the agent" — the most recently
+  /// updated artifact.
+  public var selectedArtifactId: String?
+  public private(set) var manualReloadCount = 0
+  public var failureMessage: String?
+
+  public init() {}
+
+  /// The artifact on screen: the explicit selection when it still exists,
+  /// otherwise the most recently updated one — the thing the agent just filed.
+  public func selectedArtifact(in artifacts: [StudioArtifact]) -> StudioArtifact? {
+    if let selectedArtifactId, let match = artifacts.first(where: { $0.id == selectedArtifactId }) {
+      return match
+    }
+    return Self.mostRecentlyUpdated(in: artifacts)
+  }
+
+  /// Identity of what should be loaded: switching artifacts, the agent
+  /// re-filing the open one, and Reload each produce a new token.
+  public func reloadToken(for artifact: StudioArtifact?) -> String {
+    guard let artifact else { return "none" }
+    return "\(artifact.id)#\(artifact.revision)#\(manualReloadCount)"
+  }
+
+  public func reload() {
+    failureMessage = nil
+    manualReloadCount += 1
+  }
+
+  /// Follows the agent: a newly filed artifact takes the selection; an
+  /// existing selection survives re-files and reordering; a vanished selection
+  /// falls back to the most recent.
+  public func reconcileSelection(previous: [StudioArtifact], current: [StudioArtifact]) {
+    let previousIds = Set(previous.map(\.id))
+    let added = current.filter { !previousIds.contains($0.id) }
+    if let newest = Self.mostRecentlyUpdated(in: added) {
+      selectedArtifactId = newest.id
+      failureMessage = nil
+      return
+    }
+    if let selectedArtifactId, current.contains(where: { $0.id == selectedArtifactId }) {
+      return
+    }
+    selectedArtifactId = Self.mostRecentlyUpdated(in: current)?.id
+  }
+
+  /// Recovers the variant from a Canvas selector when the page can't be asked —
+  /// the scoped selector always names the artboard.
+  public static func variantName(fromSelector selector: String) -> String? {
+    guard let range = selector.range(of: ".studio-artboard[data-variant=\"") else { return nil }
+    let rest = selector[range.upperBound...]
+    var name = ""
+    var iterator = rest.makeIterator()
+    while let char = iterator.next() {
+      if char == "\\" {
+        if let next = iterator.next() { name.append(next) }
+        continue
+      }
+      if char == "\"" { return name }
+      name.append(char)
+    }
+    return nil
+  }
+
+  static func mostRecentlyUpdated(in artifacts: [StudioArtifact]) -> StudioArtifact? {
+    artifacts.max {
+      if $0.displayDate == $1.displayDate { return $0.id < $1.id }
+      return $0.displayDate < $1.displayDate
+    }
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioSettingsView.swift b/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioSettingsView.swift
new file mode 100644
index 00000000..40ac1faf
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioSettingsView.swift
@@ -0,0 +1,174 @@
+//
+//  StudioSettingsView.swift
+//  AgentHub
+//
+//  Settings tab for reviewing and deleting stored Studio artifacts.
+//
+
+import AgentHubCLIKit
+import SwiftUI
+
+public struct StudioSettingsView: View {
+  @Environment(\.agentHub) private var agentHub
+  @State private var viewModel: StudioSettingsViewModel?
+  @State private var expandedProjectKeys: Set<String> = []
+  @State private var projectPendingDeletion: StudioLibrary.ProjectSummary?
+
+  @AppStorage(AgentHubDefaults.studioAgentGuidanceEnabled)
+  private var studioAgentGuidanceEnabled: Bool = true
+
+  public init() {}
+
+  public var body: some View {
+    Form {
+      Section {
+        Toggle("Nudge agents toward Studio", isOn: $studioAgentGuidanceEnabled)
+      } footer: {
+        Text("Adds a short system-prompt note to new Claude and Codex sessions so \"show me three versions of this button\" renders on the Studio canvas instead of editing files or publishing elsewhere. The /agenthub-studio skill remains available either way. Applies to sessions launched after the change.")
+      }
+
+      if let viewModel {
+        if viewModel.isEmpty, !viewModel.isLoading {
+          Section {
+            ContentUnavailableView(
+              "No Studio Artifacts",
+              systemImage: "paintpalette",
+              description: Text("Artifacts and design canvases agents render with agenthub_artifact and agenthub_design are stored here, per project, and served only on this Mac.")
+            )
+          }
+        } else {
+          Section {
+            ForEach(viewModel.projects) { project in
+              StudioProjectRow(
+                project: project,
+                isExpanded: expandedProjectKeys.contains(project.projectKey),
+                onToggle: { toggle(project) },
+                onDeleteProject: { projectPendingDeletion = project },
+                onDeleteArtifact: { id in
+                  Task { await viewModel.delete(id: id, inProjectKey: project.projectKey) }
+                }
+              )
+            }
+          } header: {
+            Text("Stored artifacts")
+          } footer: {
+            Text("\(viewModel.totalCount) artifact(s), \(ByteCountFormatter.string(fromByteCount: viewModel.totalBytes, countStyle: .file)) on disk. Nothing here is ever written into a project; delete freely.")
+          }
+        }
+      }
+    }
+    .formStyle(.grouped)
+    .task {
+      if viewModel == nil {
+        viewModel = StudioSettingsViewModel(library: agentHub?.studioLibrary)
+      }
+      await viewModel?.load()
+    }
+    .confirmationDialog(
+      "Delete Studio artifacts?",
+      isPresented: Binding(
+        get: { projectPendingDeletion != nil },
+        set: { if !$0 { projectPendingDeletion = nil } }
+      ),
+      presenting: projectPendingDeletion
+    ) { project in
+      Button("Delete \(project.artifacts.count)", role: .destructive) {
+        let key = project.projectKey
+        projectPendingDeletion = nil
+        Task { await viewModel?.deleteAll(inProjectKey: key) }
+      }
+      Button("Cancel", role: .cancel) { projectPendingDeletion = nil }
+    } message: { project in
+      Text("This removes \(project.artifacts.count) artifact(s) from \(StudioSettingsViewModel.displayName(forProjectKey: project.projectKey)) and frees \(ByteCountFormatter.string(fromByteCount: project.bytesOnDisk, countStyle: .file)). The agent can file them again.")
+    }
+  }
+
+  private func toggle(_ project: StudioLibrary.ProjectSummary) {
+    if expandedProjectKeys.contains(project.projectKey) {
+      expandedProjectKeys.remove(project.projectKey)
+    } else {
+      expandedProjectKeys.insert(project.projectKey)
+    }
+  }
+}
+
+// MARK: - Rows
+
+private struct StudioProjectRow: View {
+  let project: StudioLibrary.ProjectSummary
+  let isExpanded: Bool
+  let onToggle: () -> Void
+  let onDeleteProject: () -> Void
+  let onDeleteArtifact: (String) -> Void
+
+  var body: some View {
+    VStack(alignment: .leading, spacing: 8) {
+      HStack(spacing: 8) {
+        Button(action: onToggle) {
+          HStack(spacing: 6) {
+            Image(systemName: "chevron.right")
+              .font(.caption2)
+              .rotationEffect(.degrees(isExpanded ? 90 : 0))
+            VStack(alignment: .leading, spacing: 2) {
+              Text(StudioSettingsViewModel.displayName(forProjectKey: project.projectKey))
+                .font(.body)
+              Text(project.projectKey)
+                .font(.caption2)
+                .foregroundStyle(.tertiary)
+                .lineLimit(1)
+                .truncationMode(.head)
+            }
+          }
+        }
+        .buttonStyle(.plain)
+
+        Spacer()
+
+        Text("\(project.artifacts.count) · \(ByteCountFormatter.string(fromByteCount: project.bytesOnDisk, countStyle: .file))")
+          .font(.caption)
+          .foregroundStyle(.secondary)
+
+        Button(role: .destructive, action: onDeleteProject) {
+          Image(systemName: "trash")
+        }
+        .buttonStyle(.borderless)
+        .help("Delete every artifact for this project")
+      }
+
+      if isExpanded {
+        ForEach(project.artifacts) { artifact in
+          HStack(spacing: 8) {
+            Image(systemName: artifact.kind == .canvas ? "square.grid.2x2" : "doc.richtext")
+              .foregroundStyle(.secondary)
+              .frame(width: 16)
+            VStack(alignment: .leading, spacing: 2) {
+              Text(artifact.title)
+                .font(.callout)
+              Text(detail(for: artifact))
+                .font(.caption2)
+                .foregroundStyle(.secondary)
+            }
+            Spacer()
+            Button(role: .destructive) {
+              onDeleteArtifact(artifact.id)
+            } label: {
+              Image(systemName: "xmark.circle")
+            }
+            .buttonStyle(.borderless)
+            .help("Delete this artifact")
+          }
+          .padding(.leading, 18)
+        }
+      }
+    }
+    .padding(.vertical, 2)
+  }
+
+  private func detail(for artifact: StudioArtifact) -> String {
+    var parts: [String] = []
+    parts.append(artifact.kind == .canvas ? "\(artifact.variants.count) variant(s)" : "document")
+    parts.append("rev \(artifact.revision)")
+    parts.append(artifact.displayDate.formatted(date: .abbreviated, time: .shortened))
+    return parts.joined(separator: " · ")
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioSidePanelView.swift b/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioSidePanelView.swift
new file mode 100644
index 00000000..f4100c68
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/UI/StudioSidePanelView.swift
@@ -0,0 +1,1188 @@
+//
+//  StudioSidePanelView.swift
+//  AgentHub
+//
+//  Embedded side panel that renders the artifacts and design canvases an agent
+//  filed with agenthub_artifact / agenthub_design, served from AgentHub's own
+//  localhost server, with the Canvas inspector for point-and-comment feedback.
+//
+
+import AgentHubCLIKit
+import AppKit
+import Canvas
+import SwiftUI
+import UniformTypeIdentifiers
+import WebKit
+
+/// What a click in inspect mode does. Mirrors web preview's strip: Comment
+/// (element-anchored instruction), Crop (region + screenshot), Edit (live
+/// visual edits batched into one re-file request). Context mode is omitted
+/// there too — Studio has no terminal-attachment queue to add context to.
+private enum StudioInspectBehavior: String, CaseIterable, Identifiable {
+  case comment, crop, edit
+
+  var id: String { rawValue }
+
+  var icon: String {
+    switch self {
+    case .comment: return "square.and.pencil"
+    case .crop: return "crop"
+    case .edit: return "character.cursor.ibeam"
+    }
+  }
+
+  var help: String {
+    switch self {
+    case .comment: return "Comment: click an element, describe the change, ⏎ sends it to the agent."
+    case .crop: return "Crop: drag a region, describe the change, ⏎ sends it with a screenshot."
+    case .edit: return "Edit: click an element and adjust it with the toolbar; Send hands the edits to the agent."
+    }
+  }
+
+  var accessibilityLabel: String {
+    switch self {
+    case .comment: return "Comment mode"
+    case .crop: return "Crop region mode"
+    case .edit: return "Visual edit mode"
+    }
+  }
+
+  var canvasMode: InspectMode {
+    switch self {
+    case .comment, .edit: return .input
+    case .crop: return .crop
+    }
+  }
+}
+
+struct StudioSidePanelView: View {
+  let session: CLISession
+  let viewModel: CLISessionsViewModel
+  let onDismiss: () -> Void
+  var isEmbedded = false
+  let isExpanded: Bool
+  var onToggleExpanded: (() -> Void)?
+  let onSendPrompt: (String, CLISession) -> Void
+
+  @State private var panelState = StudioPanelState()
+  @State private var inspectState = ElementInspectState()
+  @State private var inspectBehavior: StudioInspectBehavior = .comment
+  @State private var editState = StudioDesignEditState()
+  @State private var servedURL: URL?
+  @State private var reloadUUID = UUID()
+  @State private var isLoading = false
+  @State private var webView: WKWebView?
+  @State private var isConfirmingDelete = false
+  @State private var transientNotice: String?
+
+  // Canvas edits bake straight into the payload (Studio is a scratchpad):
+  // debounced auto-save, quiet reload suppression for the revision we wrote,
+  // and a baseline to revert to.
+  @State private var bakeTask: Task<Void, Never>?
+  @State private var quietRevisionExpectation: Int?
+  @State private var editBaseline: StudioArtifact?
+  @State private var bakeState: BakeState = .idle
+  @State private var pageMessageHandler = StudioPageMessageHandler()
+
+  private enum BakeState: Equatable { case idle, saving, saved, failed(String) }
+
+  // Tweaks — the page declares a schema (canvas host page from `props`, or a
+  // document calling dc_set_props); the panel edits values live in the page.
+  @State private var tweaksState = TweaksState()
+  @State private var tweaksAgentState: TweaksAgentState = .idle
+  @State private var tweaksDefaultsSaveState: TweaksDefaultsSaveState = .idle
+  @State private var tweakGenerationTimer = TweakGenerationTimer()
+  @State private var isTweaksPopoverPresented = false
+  @State private var hasDeclaredTweakProps = false
+  @State private var tweaksAgentRevisionBaseline: Int?
+  @Environment(\.openURL) private var openURL
+
+  private var artifacts: [StudioArtifact] {
+    viewModel.studioArtifacts(for: session)
+  }
+
+  private var selectedArtifact: StudioArtifact? {
+    panelState.selectedArtifact(in: artifacts)
+  }
+
+  private var reloadToken: String {
+    panelState.reloadToken(for: selectedArtifact)
+  }
+
+  var body: some View {
+    VStack(spacing: 0) {
+      header
+      Divider()
+      if let selectedArtifact {
+        content(for: selectedArtifact)
+      } else {
+        emptyState
+      }
+    }
+    .frame(
+      minWidth: 300, idealWidth: .infinity, maxWidth: .infinity,
+      minHeight: 300, idealHeight: .infinity, maxHeight: .infinity
+    )
+    .onChange(of: artifacts) { previous, current in
+      panelState.reconcileSelection(previous: previous, current: current)
+    }
+    .task(id: reloadToken) {
+      await resolveServedURL()
+    }
+    .onChange(of: reloadToken) {
+      // A revision we produced by baking edits: the DOM already equals the
+      // stored markup, so keep the page, the selection, and the toolbar.
+      if let expected = quietRevisionExpectation, selectedArtifact?.revision == expected {
+        quietRevisionExpectation = nil
+        return
+      }
+      quietRevisionExpectation = nil
+      inspectState.dismissInput()
+      inspectState.dismissCropRect()
+      editState.clear()
+      editBaseline = nil
+      bakeState = .idle
+      reloadUUID = UUID()
+      // A re-file after an agent tweak request means the agent came back.
+      if let selectedArtifact, let baseline = tweaksAgentRevisionBaseline,
+         selectedArtifact.revision > baseline {
+        tweaksAgentRevisionBaseline = nil
+        tweaksAgentState = .idle
+        tweakGenerationTimer.stop()
+      }
+      tweaksDefaultsSaveState = .idle
+    }
+    .onChange(of: selectedArtifact?.id) { previous, _ in
+      if let previous { flushPendingBake(artifactId: previous) }
+      editState.clear()
+      editBaseline = nil
+      bakeState = .idle
+      tweaksState.clear()
+      hasDeclaredTweakProps = false
+      tweaksAgentState = .idle
+      tweaksAgentRevisionBaseline = nil
+      isTweaksPopoverPresented = false
+    }
+    .onKeyPress(.escape) {
+      if inspectState.isActive {
+        deactivateInspect()
+        return .handled
+      }
+      guard !isEmbedded else { return .handled }
+      onDismiss()
+      return .handled
+    }
+    .onDisappear {
+      if let selectedArtifact { flushPendingBake(artifactId: selectedArtifact.id) }
+    }
+    .alert("Delete this artifact?", isPresented: $isConfirmingDelete) {
+      Button("Delete", role: .destructive, action: deleteSelected)
+      Button("Cancel", role: .cancel) {}
+    } message: {
+      Text("It is removed from every session in this project. The agent can file it again.")
+    }
+  }
+
+  // MARK: - Content
+
+  @ViewBuilder
+  private func content(for artifact: StudioArtifact) -> some View {
+    if let failureMessage = panelState.failureMessage {
+      failureState(message: failureMessage)
+    } else if let servedURL {
+      VStack(spacing: 0) {
+        if !artifact.warnings.isEmpty {
+          StudioWarningsBanner(warnings: artifact.warnings)
+          Divider()
+        }
+        webContent(url: servedURL, artifact: artifact)
+      }
+    } else {
+      ProgressView("Starting Studio server…")
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+    }
+  }
+
+  private func webContent(url: URL, artifact: StudioArtifact) -> some View {
+    InspectableWebView(
+      url: url,
+      isFileURL: false,
+      inspectorDataLevel: inspectBehavior == .edit ? .full : .regular,
+      onLoadingChange: { isLoading = $0 },
+      onError: { message in panelState.failureMessage = message },
+      reloadToken: reloadUUID,
+      onElementSelected: { element in handleElementSelected(element, artifact: artifact) },
+      onSelectedElementDataChange: { element in
+        inspectState.refreshSelectedElement(element)
+        editState.refresh(with: element)
+      },
+      onSelectedElementViewportRectChange: { rect in inspectState.updateSelectedElementViewportRect(rect) },
+      onCropRectSelected: { rect, elements in inspectState.selectCropRect(rect, elements: elements) },
+      onCropRectViewportChange: { rect in inspectState.updateCropRect(rect) },
+      isInspectModeActive: $inspectState.isActive,
+      inspectMode: inspectBehavior.canvasMode,
+      selectedElementId: inspectState.selectedElement?.id,
+      onWebViewReady: { readyWebView in
+        // The page's per-artboard Implement buttons post here. Registered
+        // synchronously (not a @State write) so it exists before the page
+        // script checks for it.
+        pageMessageHandler.onImplement = { variantName in
+          Task { @MainActor in
+            if let selectedArtifact { await promote(artifact: selectedArtifact, variantName: variantName) }
+          }
+        }
+        let controller = readyWebView.configuration.userContentController
+        controller.removeScriptMessageHandler(forName: StudioPageMessageHandler.name)
+        controller.add(WeakScriptMessageHandler(pageMessageHandler), name: StudioPageMessageHandler.name)
+        // Deferred: this fires from makeNSView, and a @State write during a
+        // view update is dropped — which leaves every setProp/snapshot call
+        // with no web view to talk to.
+        Task { @MainActor in webView = readyWebView }
+      },
+      onTweakPropsChange: handleTweakPropsChange,
+      onTweakSchemaAvailabilityChange: { hasDeclaredTweakProps = $0 }
+    )
+    .overlay {
+      if inspectBehavior != .edit {
+        Color.clear
+          .allowsHitTesting(false)
+          .webInspectorOverlay(
+            state: inspectState,
+            inputPlacement: .selectionAnchored,
+            onSubmit: { element, instruction in
+              sendFeedback(artifact: artifact, element: element, instruction: instruction)
+            },
+            onSubmitAndSend: { element, instruction in
+              sendFeedback(artifact: artifact, element: element, instruction: instruction)
+            },
+            onCropSubmit: { rect, elements, instruction in
+              sendCrop(artifact: artifact, rect: rect, elements: elements, instruction: instruction)
+            },
+            onCropSubmitAndSend: { rect, elements, instruction in
+              sendCrop(artifact: artifact, rect: rect, elements: elements, instruction: instruction)
+            },
+            deactivateOnSubmit: false
+          )
+      }
+    }
+    .overlay(alignment: .top) {
+      if isLoading {
+        ProgressView()
+          .progressViewStyle(.linear)
+          .frame(height: 2)
+          .accessibilityLabel("Loading artifact")
+      } else if inspectState.isActive, inspectBehavior == .edit {
+        editToolbar(for: artifact)
+      }
+    }
+    .overlay(alignment: .bottom) {
+      VStack(spacing: 8) {
+        if inspectState.isActive, inspectBehavior == .edit, editState.hasPendingEdits {
+          pendingEditsBar(for: artifact)
+        }
+        if let transientNotice {
+          Text(transientNotice)
+            .font(.caption)
+            .padding(.horizontal, 10)
+            .padding(.vertical, 6)
+            .background(.regularMaterial, in: Capsule())
+            .transition(.opacity)
+        }
+      }
+      .padding(.bottom, 12)
+    }
+    .overlay(alignment: .topLeading) {
+      if inspectState.isActive, inspectBehavior != .edit {
+        Text(inspectHint(for: artifact))
+          .font(.caption)
+          .padding(.horizontal, 10)
+          .padding(.vertical, 6)
+          .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 8))
+          .padding(10)
+          .allowsHitTesting(false)
+      }
+    }
+  }
+
+  private func inspectHint(for artifact: StudioArtifact) -> String {
+    switch inspectBehavior {
+    case .comment:
+      return artifact.kind == .canvas
+        ? "Click any element on a variant, describe the change, and press ⏎ to send it to the agent."
+        : "Click any element, describe the change, and press ⏎ to send it to the agent."
+    case .crop:
+      return "Drag a region, describe the change, and press ⏎ to send it with a screenshot."
+    case .edit:
+      return ""
+    }
+  }
+
+  /// Edit mode: the design toolbar for the selected element, floating at the top.
+  @ViewBuilder
+  private func editToolbar(for artifact: StudioArtifact) -> some View {
+    if let element = editState.selectedElement, let values = editState.toolbarValues {
+      VStack(alignment: .leading, spacing: 6) {
+        WebPreviewTextContentEditor(
+          elementKey: element.cssSelector,
+          sourceText: values.textContent,
+          onTextChange: { text in
+            applyEdit(DesignEdit(element: element, action: .updateTextContent(text)), artifact: artifact)
+          }
+        )
+        DesignToolbarContent(
+          values: values,
+          element: element,
+          isTextContentEditable: false,
+          onEdit: { edit in applyEdit(edit, artifact: artifact) }
+        )
+      }
+      .padding(8)
+      .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 10))
+      .padding(10)
+      .transition(.move(edge: .top).combined(with: .opacity))
+    } else {
+      Text(artifact.kind == .canvas
+           ? "Click any element to edit it. Changes save into the canvas as you go — Implement uses them."
+           : "Click any element to edit it. Send hands every change to the agent as one request.")
+        .font(.caption)
+        .padding(.horizontal, 10)
+        .padding(.vertical, 6)
+        .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 8))
+        .padding(10)
+        .allowsHitTesting(false)
+    }
+  }
+
+  @ViewBuilder
+  private func pendingEditsBar(for artifact: StudioArtifact) -> some View {
+    if artifact.kind == .canvas {
+      HStack(spacing: 10) {
+        switch bakeState {
+        case .saving:
+          ProgressView().controlSize(.mini)
+          Text("Saving edits into the canvas…").font(.caption)
+        case .failed(let message):
+          Image(systemName: "exclamationmark.triangle").foregroundStyle(.orange)
+          Text(message).font(.caption).lineLimit(1)
+        case .idle, .saved:
+          Image(systemName: "checkmark.circle.fill").foregroundStyle(Color.brandPrimary)
+          Text(editState.pendingChangeCount == 1 ? "1 edit saved into the canvas" : "\(editState.pendingChangeCount) edits saved into the canvas")
+            .font(.caption.weight(.medium))
+        }
+        if editBaseline != nil {
+          Button("Revert", role: .destructive) { revertBakedEdits() }
+            .controlSize(.small)
+            .help("Restore the canvas as the agent last filed it")
+        }
+        Text("Implement ▾ sends the edited variant")
+          .font(.caption2)
+          .foregroundStyle(.secondary)
+      }
+      .padding(.horizontal, 12)
+      .padding(.vertical, 8)
+      .background(.regularMaterial, in: Capsule())
+    } else {
+      HStack(spacing: 10) {
+        Image(systemName: "pencil.and.list.clipboard")
+          .foregroundStyle(Color.brandPrimary)
+        Text(editState.pendingChangeCount == 1 ? "1 pending edit" : "\(editState.pendingChangeCount) pending edits")
+          .font(.caption.weight(.medium))
+        Button("Discard", role: .destructive) { discardPendingEdits() }
+          .controlSize(.small)
+        Button("Send to Agent") { sendPendingEdits(for: artifact) }
+          .controlSize(.small)
+          .buttonStyle(.borderedProminent)
+          .keyboardShortcut(.return, modifiers: [.command])
+      }
+      .padding(.horizontal, 12)
+      .padding(.vertical, 8)
+      .background(.regularMaterial, in: Capsule())
+    }
+  }
+
+  private var emptyState: some View {
+    ContentUnavailableView(
+      "No Studio Artifacts",
+      systemImage: "paintpalette",
+      description: Text("The agent has not rendered an artifact or design canvas for this project yet.")
+    )
+    .frame(maxWidth: .infinity, maxHeight: .infinity)
+  }
+
+  private func failureState(message: String) -> some View {
+    VStack(spacing: DesignTokens.Spacing.md) {
+      ContentUnavailableView(
+        "Couldn't Load Artifact",
+        systemImage: "exclamationmark.triangle",
+        description: Text(message)
+      )
+      Button("Try Again") { panelState.reload() }
+    }
+    .frame(maxWidth: .infinity, maxHeight: .infinity)
+  }
+
+  // MARK: - Header
+
+  private var header: some View {
+    HStack(spacing: 10) {
+      Image(systemName: "paintpalette")
+        .foregroundStyle(Color.brandPrimary)
+        .accessibilityHidden(true)
+
+      Text("Studio")
+        .font(.headline)
+
+      if artifacts.count == 1, let selectedArtifact {
+        Text(selectedArtifact.title)
+          .font(.secondaryCaption)
+          .foregroundStyle(.secondary)
+          .lineLimit(1)
+          .truncationMode(.middle)
+      }
+
+      Spacer(minLength: 12)
+
+      if artifacts.count > 1 {
+        Picker("Artifact", selection: Binding(
+          get: { selectedArtifact?.id },
+          set: { panelState.selectedArtifactId = $0 }
+        )) {
+          ForEach(artifacts) { artifact in
+            Label(pickerLabel(for: artifact), systemImage: artifact.kind == .canvas ? "square.grid.2x2" : "doc.richtext")
+              .tag(Optional(artifact.id))
+          }
+        }
+        .labelsHidden()
+        .frame(maxWidth: 220)
+        .accessibilityLabel("Select artifact")
+      }
+
+      if let selectedArtifact {
+        inspectButton
+        if inspectState.isActive {
+          inspectModeStrip
+        }
+        if hasDeclaredTweakProps || tweaksState.hasProps || tweaksAgentState == .working {
+          tweaksButton(for: selectedArtifact)
+        }
+        if selectedArtifact.kind == .canvas {
+          promoteMenu(for: selectedArtifact)
+        }
+        moreMenu(for: selectedArtifact)
+      }
+
+      Button(action: { panelState.reload() }) {
+        Image(systemName: "arrow.clockwise")
+          .font(.system(size: 12, weight: .medium))
+          .foregroundStyle(.secondary)
+          .frame(width: 24, height: 24)
+          .contentShape(Rectangle())
+      }
+      .buttonStyle(.plain)
+      .disabled(selectedArtifact == nil)
+      .accessibilityLabel("Reload artifact")
+      .help("Reload")
+
+      if let onToggleExpanded {
+        Button(action: onToggleExpanded) {
+          Image(systemName: isExpanded ? "arrow.down.right.and.arrow.up.left" : "arrow.up.left.and.arrow.down.right")
+            .font(.system(size: 13, weight: .medium))
+            .foregroundStyle(.secondary)
+            .frame(width: 24, height: 24)
+            .contentShape(Rectangle())
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel(isExpanded ? "Collapse Studio" : "Expand Studio to full width")
+        .help(isExpanded ? "Collapse (⌘⇧O)" : "Expand to full width (⌘⇧O)")
+      }
+
+      closeButton
+    }
+    .overlay {
+      if let onToggleExpanded {
+        Button("") { onToggleExpanded() }
+          .keyboardShortcut("o", modifiers: [.command, .shift])
+          .hidden()
+          .frame(width: 0, height: 0)
+      }
+    }
+    .padding(.horizontal, 12)
+    .padding(.vertical, 8)
+  }
+
+  private var inspectModeStrip: some View {
+    HStack(spacing: 2) {
+      ForEach(StudioInspectBehavior.allCases) { behavior in
+        Button {
+          switchInspectBehavior(to: behavior)
+        } label: {
+          Image(systemName: behavior.icon)
+            .font(.system(size: 11, weight: .medium))
+            .foregroundStyle(inspectBehavior == behavior ? Color.white : Color.secondary)
+            .frame(width: 22, height: 22)
+            .background(
+              RoundedRectangle(cornerRadius: 5)
+                .fill(inspectBehavior == behavior ? Color.brandPrimary : Color.clear)
+            )
+            .contentShape(Rectangle())
+        }
+        .buttonStyle(.plain)
+        .accessibilityLabel(behavior.accessibilityLabel)
+        .help(behavior.help)
+      }
+    }
+    .padding(2)
+    .background(RoundedRectangle(cornerRadius: 7).fill(Color.secondary.opacity(0.12)))
+    .transition(.opacity.combined(with: .scale(scale: 0.95, anchor: .leading)))
+  }
+
+  private var inspectButton: some View {
+    Button {
+      if inspectState.isActive {
+        deactivateInspect()
+      } else {
+        inspectState.activate(mode: inspectBehavior.canvasMode)
+      }
+    } label: {
+      Image(systemName: "cursorarrow.click.2")
+        .font(.system(size: 12, weight: .medium))
+        .foregroundStyle(inspectState.isActive ? Color.brandPrimary : Color.secondary)
+        .frame(width: 24, height: 24)
+        .background(
+          RoundedRectangle(cornerRadius: 6)
+            .fill(inspectState.isActive ? Color.brandPrimary.opacity(0.15) : Color.clear)
+        )
+        .contentShape(Rectangle())
+    }
+    .buttonStyle(.plain)
+    .disabled(servedURL == nil)
+    .accessibilityLabel(inspectState.isActive ? "Stop inspecting" : "Inspect")
+    .help(inspectState.isActive ? "Stop inspecting (Esc)" : "Inspect: comment on, crop, or edit any element")
+  }
+
+  /// Live controls for the props the page declared. Value changes go straight
+  /// into the page; Save defaults re-stores the artifact; Ideas/Custom/Delete
+  /// go to the session agent as re-file prompts.
+  private func tweaksButton(for artifact: StudioArtifact) -> some View {
+    let presentation = TweaksButtonPresentation.resolve(agentState: tweaksAgentState)
+    return Button {
+      isTweaksPopoverPresented.toggle()
+    } label: {
+      ZStack {
+        Image(systemName: "slider.horizontal.3")
+          .font(.system(size: 12, weight: .medium))
+          .foregroundStyle(isTweaksPopoverPresented ? Color.brandPrimary : Color.secondary)
+          .opacity(presentation.isLoading ? 0 : 1)
+        if presentation.isLoading {
+          ProgressView().controlSize(.mini)
+        }
+      }
+      .frame(width: 24, height: 24)
+      .background(
+        RoundedRectangle(cornerRadius: 6)
+          .fill(isTweaksPopoverPresented ? Color.brandPrimary.opacity(0.15) : Color.clear)
+      )
+      .contentShape(Rectangle())
+    }
+    .buttonStyle(.plain)
+    .accessibilityLabel(presentation.accessibilityLabel)
+    .help(artifact.kind == .canvas ? "Tweak the shared props across every variant" : "Tweak this design with live controls")
+    .popover(isPresented: $isTweaksPopoverPresented, arrowEdge: .bottom) {
+      WebPreviewTweaksPanel(
+        state: tweaksState,
+        agentState: $tweaksAgentState,
+        defaultsSaveState: $tweaksDefaultsSaveState,
+        generationStartedAt: tweakGenerationTimer.startedAt,
+        onSubmitDescription: { instruction in
+          sendTweaksAgentPrompt(StudioTweaksPromptBuilder.customPrompt(artifact: artifact, instruction: instruction))
+        },
+        onIdeas: {
+          sendTweaksAgentPrompt(StudioTweaksPromptBuilder.ideasPrompt(artifact: artifact, existingProps: tweaksState.props))
+        },
+        onValueChange: handleTweakValueChange,
+        onDeleteAll: {
+          sendTweaksAgentPrompt(StudioTweaksPromptBuilder.deleteAllPrompt(artifact: artifact))
+        },
+        onReset: resetTweakValues,
+        onSaveDefaults: { saveTweakDefaults(for: artifact) }
+      )
+    }
+  }
+
+  /// The one action in Studio that asks for real code. Its own control, its own
+  /// prompt builder — never reachable from Send. Labelled, not icon-only: this
+  /// is the step users are looking for once they have picked a direction.
+  private func promoteMenu(for artifact: StudioArtifact) -> some View {
+    Menu {
+      Section("Ask the agent to build it") {
+        ForEach(artifact.variants, id: \.name) { variant in
+          Button {
+            Task { @MainActor in await promote(artifact: artifact, variantName: variant.name) }
+          } label: {
+            Label("Implement \u{201C}\(variant.name)\u{201D}", systemImage: "hammer")
+          }
+        }
+      }
+      if let sourcePath = artifact.sourcePath {
+        Text("Target: \(sourcePath)")
+      }
+      Text("Edits made in the panel are included.")
+    } label: {
+      HStack(spacing: 4) {
+        Image(systemName: "hammer.fill")
+          .font(.system(size: 11, weight: .medium))
+        Text("Implement")
+          .font(.system(size: 12, weight: .medium))
+        Image(systemName: "chevron.down")
+          .font(.system(size: 9, weight: .semibold))
+      }
+      .foregroundStyle(Color.brandPrimary)
+      .padding(.horizontal, 8)
+      .frame(height: 24)
+      .background(RoundedRectangle(cornerRadius: 6).fill(Color.brandPrimary.opacity(0.12)))
+      .contentShape(Rectangle())
+    }
+    .menuStyle(.borderlessButton)
+    .menuIndicator(.hidden)
+    .fixedSize()
+    .accessibilityLabel("Implement a variant in the project")
+    .help("Pick the variant to implement — the agent builds it in the real project, including your panel edits")
+  }
+
+  private func moreMenu(for artifact: StudioArtifact) -> some View {
+    Menu {
+      Button {
+        if let servedURL { openURL(servedURL) }
+      } label: {
+        Label("Open in Browser", systemImage: "safari")
+      }
+      .disabled(servedURL == nil)
+
+      Button {
+        copyLink()
+      } label: {
+        Label("Copy Link", systemImage: "link")
+      }
+      .disabled(servedURL == nil)
+
+      Button {
+        exportDocument(artifact)
+      } label: {
+        Label("Export HTML…", systemImage: "square.and.arrow.up")
+      }
+
+      Divider()
+
+      Button(role: .destructive) {
+        isConfirmingDelete = true
+      } label: {
+        Label("Delete Artifact", systemImage: "trash")
+      }
+    } label: {
+      Image(systemName: "ellipsis.circle")
+        .font(.system(size: 12, weight: .medium))
+        .foregroundStyle(.secondary)
+        .frame(width: 24, height: 24)
+        .contentShape(Rectangle())
+    }
+    .menuStyle(.borderlessButton)
+    .menuIndicator(.hidden)
+    .fixedSize()
+    .accessibilityLabel("More actions")
+  }
+
+  @ViewBuilder
+  private var closeButton: some View {
+    if isEmbedded {
+      Button("Close", action: onDismiss)
+    } else {
+      Button("Close", action: onDismiss)
+        .keyboardShortcut(.cancelAction)
+    }
+  }
+
+  // MARK: - Actions
+
+  private func resolveServedURL() async {
+    guard let selectedArtifact, let library = viewModel.studioLibrary else {
+      servedURL = nil
+      return
+    }
+    let key = viewModel.projectScopeKey(for: session)
+    let url = await library.servedURL(for: selectedArtifact, projectKey: key)
+    guard !Task.isCancelled else { return }
+    servedURL = url
+    if url == nil {
+      panelState.failureMessage = "AgentHub couldn't start its local Studio server."
+    }
+  }
+
+  private func handleElementSelected(_ element: ElementInspectorData, artifact: StudioArtifact) {
+    inspectState.selectElement(element)
+    guard inspectBehavior == .edit else { return }
+    // Selector parse gives an immediate (usually correct) variant; the page
+    // is asked next for the authoritative answer.
+    editState.select(element, variantName: StudioPanelState.variantName(fromSelector: element.cssSelector))
+    guard artifact.kind == .canvas else { return }
+    Task { @MainActor in
+      let variantName = await resolveVariantName(for: element)
+      // Re-select stamps the variant without disturbing an in-progress batch.
+      if editState.selectedElement?.cssSelector == element.cssSelector {
+        editState.select(element, variantName: variantName)
+      }
+    }
+  }
+
+  /// Edit-mode change: apply live, record, and (canvas) bake into the payload.
+  private func applyEdit(_ edit: DesignEdit, artifact: StudioArtifact) {
+    if artifact.kind == .canvas, editBaseline == nil {
+      editBaseline = artifact
+    }
+    editState.apply(edit, in: webView)
+    if case .deleteElement = edit.action, let webView {
+      // The Canvas bridge ignores delete; Studio removes it in the page itself.
+      let literal = Self.javaScriptStringLiteral(edit.element.cssSelector)
+      webView.evaluateJavaScript("window.__agenthubStudio && window.__agenthubStudio.removeElement(\(literal))") { _, _ in }
+    }
+    guard artifact.kind == .canvas else { return }
+    scheduleBake(artifactId: artifact.id)
+  }
+
+  private func scheduleBake(artifactId: String) {
+    bakeTask?.cancel()
+    bakeState = .saving
+    bakeTask = Task { @MainActor in
+      try? await Task.sleep(for: .milliseconds(500))
+      guard !Task.isCancelled else { return }
+      await bakeCanvasEdits(artifactId: artifactId)
+    }
+  }
+
+  /// Runs any pending bake now (mode/artifact switch, panel close, Implement).
+  private func flushPendingBake(artifactId: String) {
+    guard bakeTask != nil || bakeState == .saving else { return }
+    bakeTask?.cancel()
+    bakeTask = nil
+    Task { @MainActor in await bakeCanvasEdits(artifactId: artifactId) }
+  }
+
+  private func flushPendingBakeAndWait(artifactId: String) async {
+    guard bakeTask != nil || bakeState == .saving else { return }
+    bakeTask?.cancel()
+    bakeTask = nil
+    await bakeCanvasEdits(artifactId: artifactId)
+  }
+
+  /// Serializes every artboard the user touched and stores it as the
+  /// variant's markup — quietly, so the page is not reloaded under the edit.
+  private func bakeCanvasEdits(artifactId: String) async {
+    bakeTask = nil
+    guard let webView, let library = viewModel.studioLibrary,
+          viewModel.studioArtifacts(for: session).contains(where: { $0.id == artifactId })
+    else {
+      bakeState = .idle
+      return
+    }
+    let edits = editState.orderedEdits
+    guard !edits.isEmpty else {
+      bakeState = .idle
+      return
+    }
+    // Variants known from selection first (a deleted element's selector no
+    // longer resolves in the page); selectors only for the ones still unknown.
+    let knownNames = edits.compactMap(\.variantName)
+    let unresolvedSelectors = edits.filter { $0.variantName == nil }.map(\.batch.element.cssSelector)
+    let namesJSON = String(decoding: (try? JSONSerialization.data(withJSONObject: knownNames)) ?? Data("[]".utf8), as: UTF8.self)
+    let selectorsJSON = String(decoding: (try? JSONSerialization.data(withJSONObject: unresolvedSelectors)) ?? Data("[]".utf8), as: UTF8.self)
+    let script = """
+      (function () {
+        var s = window.__agenthubStudio; if (!s) return null;
+        var names = \(namesJSON);
+        var byVariant = s.variantsForSelectors(\(selectorsJSON));
+        Object.keys(byVariant).forEach(function (k) { if (names.indexOf(byVariant[k]) === -1) names.push(byVariant[k]); });
+        return names.length ? s.serializeArtboards(names) : {};
+      })()
+      """
+    let result = try? await webView.evaluateJavaScript(script)
+    guard let htmlByVariant = result as? [String: String], !htmlByVariant.isEmpty else {
+      bakeState = .failed("Couldn't read the edited artboards.")
+      return
+    }
+    let key = viewModel.projectScopeKey(for: session)
+    let before = library.artifact(id: artifactId, projectKey: key)?.revision ?? 0
+    // Expect the revision this store produces so the reload handler keeps the page.
+    quietRevisionExpectation = before + 1
+    let stored = await library.updateVariantHTML(
+      artifactId: artifactId,
+      htmlByVariant: htmlByVariant,
+      projectKey: key,
+      sessionId: session.id,
+      aliasPaths: []
+    )
+    if stored == nil || stored?.revision == before {
+      quietRevisionExpectation = nil
+    }
+    bakeState = .saved
+  }
+
+  /// Restores the canvas as it was before the first panel edit (a normal
+  /// store: the page reloads to the agent's version).
+  private func revertBakedEdits() {
+    guard let editBaseline, let library = viewModel.studioLibrary else { return }
+    bakeTask?.cancel()
+    bakeTask = nil
+    let key = viewModel.projectScopeKey(for: session)
+    let baseline = editBaseline
+    self.editBaseline = nil
+    editState.clear()
+    bakeState = .idle
+    Task { @MainActor in
+      await library.store(baseline.withVariants(baseline.variants), projectKey: key, sessionId: session.id, aliasPaths: [])
+      showNotice("Reverted to the agent's version")
+    }
+  }
+
+  private func switchInspectBehavior(to behavior: StudioInspectBehavior) {
+    guard behavior != inspectBehavior else { return }
+    if let selectedArtifact { flushPendingBake(artifactId: selectedArtifact.id) }
+    inspectState.dismissInput()
+    inspectState.dismissCropRect()
+    if let webView { ElementInspectorBridge.clearCropSelection(in: webView) }
+    if inspectBehavior == .edit { editState.deselect() }
+    inspectBehavior = behavior
+    inspectState.mode = behavior.canvasMode
+  }
+
+  private func deactivateInspect() {
+    inspectState.deactivate()
+    inspectState.dismissCropRect()
+    editState.deselect()
+  }
+
+  private func sendCrop(artifact: StudioArtifact, rect: CGRect, elements: [ElementInspectorData], instruction: String) {
+    Task { @MainActor in
+      var screenshotPath: String?
+      if let webView, let image = try? await ElementSnapshotCapture.captureSnapshot(of: rect, in: webView) {
+        screenshotPath = Self.saveCropScreenshot(image, sessionId: session.id)
+      }
+      let variantName: String? = artifact.kind == .canvas
+        ? await elements.first.asyncFlatMap { await resolveVariantName(for: $0) }
+        : nil
+      let prompt = StudioFeedbackPromptBuilder.cropPrompt(
+        artifact: artifact,
+        variantName: variantName,
+        cropRect: rect,
+        elements: elements,
+        instruction: instruction,
+        screenshotPath: screenshotPath
+      )
+      inspectState.dismissCropRect()
+      if let webView { ElementInspectorBridge.clearCropSelection(in: webView) }
+      onSendPrompt(prompt, session)
+      showNotice(screenshotPath == nil ? "Sent to the agent" : "Sent to the agent with a screenshot")
+    }
+  }
+
+  private static func saveCropScreenshot(_ image: NSImage, sessionId: String) -> String? {
+    guard let tiff = image.tiffRepresentation,
+          let bitmap = NSBitmapImageRep(data: tiff),
+          let png = bitmap.representation(using: .png, properties: [:])
+    else { return nil }
+    let directory = FileManager.default.temporaryDirectory
+      .appendingPathComponent("AgentHub/studio-crops", isDirectory: true)
+    try? FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+    let url = directory.appendingPathComponent("crop-\(sessionId.prefix(8))-\(Int(Date().timeIntervalSince1970)).png")
+    do {
+      try png.write(to: url)
+      return url.path
+    } catch {
+      return nil
+    }
+  }
+
+  private func sendPendingEdits(for artifact: StudioArtifact) {
+    guard artifact.kind == .document else { return }
+    let entries = editState.orderedEdits.map { entry -> StudioFeedbackPromptBuilder.ElementEdits in
+      var lines: [String] = []
+      for change in entry.batch.styleChanges {
+        lines.append(change.oldValue.map { "- \(change.property): \($0) → \(change.newValue)" } ?? "- \(change.property): \(change.newValue)")
+      }
+      if let text = entry.batch.textChange {
+        lines.append(text.oldText.map { "- text content: \"\($0)\" → \"\(text.newText)\"" } ?? "- text content: \"\(text.newText)\"")
+      }
+      if entry.fitToContent { lines.append("- size: fit to content (width and height auto)") }
+      if entry.deleted { lines.append("- remove this element") }
+      return StudioFeedbackPromptBuilder.ElementEdits(
+        element: entry.batch.element,
+        variantName: entry.variantName,
+        changeLines: lines
+      )
+    }
+    guard let prompt = StudioFeedbackPromptBuilder.editsPrompt(artifact: artifact, edits: entries) else { return }
+    editState.clear()
+    onSendPrompt(prompt, session)
+    showNotice("Edits sent to the agent")
+  }
+
+  /// Drops the live edits by reloading the page — the served document was
+  /// never touched, so a reload is the undo.
+  private func discardPendingEdits() {
+    editState.clear()
+    panelState.reload()
+  }
+
+  private func sendFeedback(artifact: StudioArtifact, element: ElementInspectorData, instruction: String) {
+    Task { @MainActor in
+      let variantName = artifact.kind == .canvas
+        ? await resolveVariantName(for: element)
+        : nil
+      let prompt = StudioFeedbackPromptBuilder.prompt(
+        artifact: artifact,
+        variantName: variantName,
+        element: element,
+        instruction: instruction
+      )
+      inspectState.dismissInput()
+      onSendPrompt(prompt, session)
+      showNotice("Sent to the agent")
+    }
+  }
+
+  /// Which artboard the element sits on. Asks the page (authoritative), falling
+  /// back to parsing the selector.
+  private func resolveVariantName(for element: ElementInspectorData) async -> String? {
+    if let webView {
+      let selectorLiteral = Self.javaScriptStringLiteral(element.cssSelector)
+      let script = "window.__agenthubStudio && window.__agenthubStudio.variantForSelector(\(selectorLiteral))"
+      if let result = try? await webView.evaluateJavaScript(script) as? String, !result.isEmpty {
+        return result
+      }
+    }
+    return StudioPanelState.variantName(fromSelector: element.cssSelector)
+  }
+
+  // MARK: Tweaks
+
+  private func handleTweakPropsChange(_ props: [TweakProp]) {
+    tweaksState.updateSchema(props)
+    hasDeclaredTweakProps = !props.isEmpty || hasDeclaredTweakProps
+    tweaksDefaultsSaveState = .idle
+  }
+
+  private func handleTweakValueChange(prop: TweakProp, value: TweakPropValue) {
+    tweaksState.updateValue(name: prop.name, value)
+    if case .failed = tweaksDefaultsSaveState { tweaksDefaultsSaveState = .idle }
+    if let webView {
+      TweaksBridge.setProp(name: prop.name, value: value, in: webView)
+    }
+  }
+
+  private func resetTweakValues() {
+    let reset = tweaksState.resetToDefaults()
+    tweaksDefaultsSaveState = .idle
+    guard let webView else { return }
+    for prop in reset {
+      TweaksBridge.setProp(name: prop.name, value: prop.value, in: webView)
+    }
+  }
+
+  private func saveTweakDefaults(for artifact: StudioArtifact) {
+    guard tweaksState.hasUnsavedChanges, tweaksDefaultsSaveState != .saving,
+          let library = viewModel.studioLibrary
+    else { return }
+    let values = Dictionary(uniqueKeysWithValues: tweaksState.props
+      .filter { $0.value != $0.defaultValue }
+      .map { ($0.name, $0.value) })
+    let key = viewModel.projectScopeKey(for: session)
+    tweaksDefaultsSaveState = .saving
+    Task { @MainActor in
+      do {
+        try await library.saveTweakDefaults(
+          artifactId: artifact.id,
+          values: values,
+          projectKey: key,
+          sessionId: session.id,
+          aliasPaths: []
+        )
+        tweaksState.commitCurrentValuesAsDefaults()
+        tweaksDefaultsSaveState = .idle
+        showNotice("Defaults saved")
+      } catch {
+        tweaksDefaultsSaveState = .failed(error.localizedDescription)
+      }
+    }
+  }
+
+  /// Ideas / Custom / Delete all: a re-file request into the session. The
+  /// spinner clears when the artifact's revision advances, or after a timeout —
+  /// the agent may simply never call back.
+  private func sendTweaksAgentPrompt(_ prompt: String) {
+    guard tweaksAgentState != .working, let selectedArtifact else { return }
+    tweaksAgentRevisionBaseline = selectedArtifact.revision
+    tweaksAgentState = .working
+    tweakGenerationTimer.start()
+    onSendPrompt(prompt, session)
+    let baseline = selectedArtifact.revision
+    let artifactId = selectedArtifact.id
+    Task { @MainActor in
+      try? await Task.sleep(for: CLISessionsViewModel.rerunTimeout)
+      guard tweaksAgentState == .working, tweaksAgentRevisionBaseline == baseline,
+            self.selectedArtifact?.id == artifactId
+      else { return }
+      tweaksAgentRevisionBaseline = nil
+      tweakGenerationTimer.stop()
+      tweaksAgentState = .failed("The agent didn't re-file the \(selectedArtifact.kind == .canvas ? "canvas" : "artifact") in time.")
+    }
+  }
+
+  /// Sends the implement request with the *current* variant markup — panel
+  /// edits are baked first, so what the agent gets is what the user sees.
+  private func promote(artifact: StudioArtifact, variantName: String) async {
+    await flushPendingBakeAndWait(artifactId: artifact.id)
+    let key = viewModel.projectScopeKey(for: session)
+    let current = viewModel.studioLibrary?.artifact(id: artifact.id, projectKey: key) ?? artifact
+    guard let prompt = StudioPromotionPromptBuilder.prompt(artifact: current, variantName: variantName) else { return }
+    onSendPrompt(prompt, session)
+    showNotice("Asked the agent to implement \u{201C}\(variantName)\u{201D}")
+  }
+
+  private func deleteSelected() {
+    guard let selectedArtifact else { return }
+    viewModel.deleteStudioArtifact(id: selectedArtifact.id, in: session)
+    panelState.selectedArtifactId = nil
+  }
+
+  private func copyLink() {
+    guard let servedURL else { return }
+    let pasteboard = NSPasteboard.general
+    pasteboard.clearContents()
+    pasteboard.setString(servedURL.absoluteString, forType: .string)
+    showNotice("Link copied — valid while AgentHub is running")
+  }
+
+  private func exportDocument(_ artifact: StudioArtifact) {
+    guard let library = viewModel.studioLibrary else { return }
+    let key = viewModel.projectScopeKey(for: session)
+    let source = library.documentURL(for: artifact, projectKey: key)
+    guard FileManager.default.fileExists(atPath: source.path) else {
+      showNotice("Nothing to export yet")
+      return
+    }
+
+    let panel = NSSavePanel()
+    panel.allowedContentTypes = [.html]
+    panel.nameFieldStringValue = Self.exportFileName(for: artifact)
+    panel.title = "Export Studio Artifact"
+    panel.message = "Saves the rendered HTML. It is agent-generated and unreviewed — treat it like any file the agent wrote."
+    guard panel.runModal() == .OK, let destination = panel.url else { return }
+    do {
+      if FileManager.default.fileExists(atPath: destination.path) {
+        try FileManager.default.removeItem(at: destination)
+      }
+      try FileManager.default.copyItem(at: source, to: destination)
+      showNotice("Exported")
+    } catch {
+      panelState.failureMessage = "Export failed: \(error.localizedDescription)"
+    }
+  }
+
+  private func showNotice(_ text: String) {
+    withAnimation { transientNotice = text }
+    Task { @MainActor in
+      try? await Task.sleep(for: .seconds(2))
+      if transientNotice == text {
+        withAnimation { transientNotice = nil }
+      }
+    }
+  }
+
+  private func pickerLabel(for artifact: StudioArtifact) -> String {
+    let sharesTitle = artifacts.filter { $0.title == artifact.title }.count > 1
+    return sharesTitle ? "\(artifact.title) · rev \(artifact.revision)" : artifact.title
+  }
+
+  static func exportFileName(for artifact: StudioArtifact) -> String {
+    let base = artifact.title
+      .components(separatedBy: CharacterSet.alphanumerics.union(CharacterSet(charactersIn: "-_ ")).inverted)
+      .joined()
+      .trimmingCharacters(in: .whitespaces)
+      .replacingOccurrences(of: " ", with: "-")
+    return (base.isEmpty ? "studio-artifact" : base) + ".html"
+  }
+
+  static func javaScriptStringLiteral(_ text: String) -> String {
+    let data = (try? JSONSerialization.data(withJSONObject: [text])) ?? Data()
+    let array = String(decoding: data, as: UTF8.self)
+    return String(array.dropFirst().dropLast())
+  }
+}
+
+// MARK: - StudioWarningsBanner
+
+/// What normalization dropped when the agent filed this artifact. Kept visible
+/// so a canvas missing its scripts or an @import is not mistaken for a
+/// rendering bug.
+private struct StudioWarningsBanner: View {
+  let warnings: [String]
+  @State private var isExpanded = false
+
+  var body: some View {
+    VStack(alignment: .leading, spacing: 4) {
+      Button {
+        withAnimation(.easeInOut(duration: 0.15)) { isExpanded.toggle() }
+      } label: {
+        HStack(spacing: 6) {
+          Image(systemName: "exclamationmark.triangle")
+            .foregroundStyle(.orange)
+          Text(warnings.count == 1 ? "1 note from the agent's markup" : "\(warnings.count) notes from the agent's markup")
+            .font(.caption.weight(.medium))
+          Spacer()
+          Image(systemName: isExpanded ? "chevron.up" : "chevron.down")
+            .font(.caption2)
+            .foregroundStyle(.secondary)
+        }
+        .contentShape(Rectangle())
+      }
+      .buttonStyle(.plain)
+
+      if isExpanded {
+        ForEach(Array(warnings.enumerated()), id: \.offset) { _, warning in
+          Text("• \(warning)")
+            .font(.caption2)
+            .foregroundStyle(.secondary)
+            .fixedSize(horizontal: false, vertical: true)
+        }
+      }
+    }
+    .padding(.horizontal, 12)
+    .padding(.vertical, 6)
+    .background(Color.orange.opacity(0.08))
+  }
+}
+
+
+private extension Optional {
+  func asyncFlatMap<T>(_ transform: (Wrapped) async -> T?) async -> T? {
+    guard let self else { return nil }
+    return await transform(self)
+  }
+}
+
+
+// MARK: - StudioPageMessageHandler
+
+/// Receives the canvas host page's Implement clicks
+/// (`window.webkit.messageHandlers.agentHubStudio`).
+final class StudioPageMessageHandler: NSObject, WKScriptMessageHandler {
+  static let name = "agentHubStudio"
+  var onImplement: ((String) -> Void)?
+
+  func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {
+    guard message.name == Self.name,
+          let body = message.body as? [String: Any],
+          body["type"] as? String == "implement",
+          let variant = body["variant"] as? String, !variant.isEmpty
+    else { return }
+    onImplement?(variant)
+  }
+}
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/ViewModels/CLISessionsViewModel.swift b/app/modules/AgentHubCore/Sources/AgentHub/ViewModels/CLISessionsViewModel.swift
index 93f506ea..7555031a 100644
--- a/app/modules/AgentHubCore/Sources/AgentHub/ViewModels/CLISessionsViewModel.swift
+++ b/app/modules/AgentHubCore/Sources/AgentHub/ViewModels/CLISessionsViewModel.swift
@@ -2096,6 +2096,77 @@ public final class CLISessionsViewModel {
     }
   }
 
+  // MARK: - Studio
+
+  /// The Studio panel's model, shared with the other provider's view model so a
+  /// canvas filed from Codex shows for a Claude session in the same project.
+  /// Set by `AgentHubProvider`; nil in isolated tests.
+  public var studioLibrary: StudioLibrary?
+
+  /// The project bucket a session's project-scoped state lives in — measurements
+  /// and Studio artifacts share it (worktrees roll up to their parent repo).
+  public func projectScopeKey(for session: CLISession) -> String {
+    measurementProjectKey(for: session)
+  }
+
+  public func studioArtifacts(for session: CLISession) -> [StudioArtifact] {
+    studioLibrary?.artifacts(forProjectKey: projectScopeKey(for: session)) ?? []
+  }
+
+  public func hasStudioArtifacts(for session: CLISession) -> Bool {
+    !studioArtifacts(for: session).isEmpty
+  }
+
+  /// Takes an artifact filed by the CLI (via `StudioArtifactHandler`).
+  public func storeStudioArtifact(_ artifact: StudioArtifact, forSessionId sessionId: String) {
+    guard let studioLibrary else {
+      AppLogger.session.error("Dropping studio artifact \(artifact.id): no library wired.")
+      return
+    }
+    let session = monitoredSession(withId: sessionId)
+    let projectPath = session?.projectPath ?? artifact.sourceProjectPath ?? ""
+    guard !projectPath.isEmpty else {
+      AppLogger.session.error("Dropping studio artifact \(artifact.id): no project path to file it under.")
+      return
+    }
+
+    Task {
+      let key = await resolveMeasurementProjectKey(for: sessionId, projectPath: projectPath)
+      await studioLibrary.store(
+        artifact.stamped(branchName: session?.branchName),
+        projectKey: key,
+        sessionId: sessionId,
+        aliasPaths: projectScopeAliasPaths(forKey: key)
+      )
+    }
+  }
+
+  /// Reads a project's persisted artifacts back once (idempotent in the library).
+  public func loadStudioArtifacts(for session: CLISession) {
+    guard let studioLibrary, !session.id.hasPrefix("pending-") else { return }
+    Task {
+      let key = await resolveMeasurementProjectKey(for: session.id, projectPath: session.projectPath)
+      await studioLibrary.load(projectKey: key, aliasPaths: projectScopeAliasPaths(forKey: key))
+    }
+  }
+
+  public func deleteStudioArtifact(id: String, in session: CLISession) {
+    guard let studioLibrary else { return }
+    let key = projectScopeKey(for: session)
+    Task {
+      await studioLibrary.delete(id: id, projectKey: key, aliasPaths: projectScopeAliasPaths(forKey: key))
+    }
+  }
+
+  /// Every monitored session path that resolves to this project bucket, so the
+  /// CLI can find the index from `AGENTHUB_PROJECT_PATH` inside a worktree.
+  private func projectScopeAliasPaths(forKey key: String) -> [String] {
+    measurementProjectKeys
+      .filter { $0.value == key }
+      .compactMap { monitoredSession(withId: $0.key)?.projectPath }
+      .map(MeasurementProjectScope.normalized)
+  }
+
   // MARK: Re-running a measurement
 
   /// Measurements whose refresh has been handed to a session and not yet come back.
diff --git a/app/modules/AgentHubCore/Sources/AgentHub/ViewModels/StudioSettingsViewModel.swift b/app/modules/AgentHubCore/Sources/AgentHub/ViewModels/StudioSettingsViewModel.swift
new file mode 100644
index 00000000..7b06ed2d
--- /dev/null
+++ b/app/modules/AgentHubCore/Sources/AgentHub/ViewModels/StudioSettingsViewModel.swift
@@ -0,0 +1,62 @@
+//
+//  StudioSettingsViewModel.swift
+//  AgentHub
+//
+//  Backs the Settings tab for reviewing and deleting stored Studio artifacts.
+//
+
+import AgentHubCLIKit
+import Foundation
+
+/// Lists and deletes stored Studio artifacts, grouped by project.
+///
+/// Settings exists for what the panel cannot reach: the panel only shows the
+/// project of a session you currently have open, so artifacts for a repository
+/// you have since removed are otherwise invisible and permanent. Grouped by
+/// project, never by worktree — worktrees roll up to their parent repo.
+@MainActor
+@Observable
+public final class StudioSettingsViewModel {
+  public private(set) var projects: [StudioLibrary.ProjectSummary] = []
+  public private(set) var isLoading = false
+
+  private let library: StudioLibrary?
+
+  public init(library: StudioLibrary?) {
+    self.library = library
+  }
+
+  public var isEmpty: Bool { projects.isEmpty }
+
+  public var totalCount: Int {
+    projects.reduce(0) { $0 + $1.artifacts.count }
+  }
+
+  public var totalBytes: Int64 {
+    projects.reduce(0) { $0 + $1.bytesOnDisk }
+  }
+
+  public func load() async {
+    guard let library else { return }
+    isLoading = true
+    defer { isLoading = false }
+    projects = await library.allProjects()
+  }
+
+  public func delete(id: String, inProjectKey key: String) async {
+    guard let library else { return }
+    await library.delete(id: id, projectKey: key, aliasPaths: [])
+    await load()
+  }
+
+  public func deleteAll(inProjectKey key: String) async {
+    guard let library else { return }
+    await library.deleteAll(projectKey: key)
+    await load()
+  }
+
+  public static func displayName(forProjectKey key: String) -> String {
+    let name = (key as NSString).lastPathComponent
+    return name.isEmpty ? key : name
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/AIConfigSettingsTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/AIConfigSettingsTests.swift
index 65fac571..406e5152 100644
--- a/app/modules/AgentHubCore/Tests/AgentHubTests/AIConfigSettingsTests.swift
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/AIConfigSettingsTests.swift
@@ -154,6 +154,44 @@ struct CLICommandConfigurationArgumentHandlingTests {
     #expect(!args.contains { $0.contains("xcodebuildmcp@latest") })
   }
 
+  /// Codex prompts per MCP tool call unless the server is `auto`; under
+  /// `approval_policy = never` that prompt becomes a hard failure ("MCP tool
+  /// call requires approval, but approval policy is never"). The bundled
+  /// server must never hit that; XcodeBuildMCP only when the user asked for
+  /// autonomy.
+  @Test("Codex marks the bundled agenthub server auto-approved; XcodeBuildMCP only under autonomy policies")
+  func codexMCPToolApprovalModes() {
+    let config = CLICommandConfiguration.codexDefault
+    let helper = "/Applications/AgentHub.app/Contents/Helpers/agenthub"
+    let bootstrap = XcodeBuildMCPBootstrap(workingDirectory: "/repo", workspacePath: nil, simulatorUDID: nil)
+
+    let plain = config.argumentsForSession(sessionId: nil, prompt: nil, agentHubMCPServerPath: helper, xcodeBuildMCPBootstrap: bootstrap)
+    #expect(plain.contains("mcp_servers.agenthub.default_tools_approval_mode=\"auto\""))
+    #expect(!plain.contains("mcp_servers.XcodeBuildMCP.default_tools_approval_mode=\"auto\""))
+
+    for policy in ["never", "full-auto"] {
+      let args = config.argumentsForSession(sessionId: nil, prompt: nil, agentHubMCPServerPath: helper, codexApprovalPolicy: policy, xcodeBuildMCPBootstrap: bootstrap)
+      #expect(args.contains("mcp_servers.agenthub.default_tools_approval_mode=\"auto\""), "\(policy)")
+      #expect(args.contains("mcp_servers.XcodeBuildMCP.default_tools_approval_mode=\"auto\""), "\(policy)")
+    }
+    let onRequest = config.argumentsForSession(sessionId: nil, prompt: nil, agentHubMCPServerPath: helper, codexApprovalPolicy: "on-request", xcodeBuildMCPBootstrap: bootstrap)
+    #expect(!onRequest.contains("mcp_servers.XcodeBuildMCP.default_tools_approval_mode=\"auto\""))
+
+    // A global `never` (from ~/.codex/config.toml) counts when AgentHub passes no policy of its own;
+    // an explicit AgentHub policy wins over it.
+    let globalNever = config.argumentsForSession(sessionId: nil, prompt: nil, agentHubMCPServerPath: helper, codexGlobalApprovalPolicy: "never", xcodeBuildMCPBootstrap: bootstrap)
+    #expect(globalNever.contains("mcp_servers.XcodeBuildMCP.default_tools_approval_mode=\"auto\""))
+    #expect(!globalNever.contains("-a"))
+    let explicitWins = config.argumentsForSession(sessionId: nil, prompt: nil, agentHubMCPServerPath: helper, codexApprovalPolicy: "on-request", codexGlobalApprovalPolicy: "never", xcodeBuildMCPBootstrap: bootstrap)
+    #expect(!explicitWins.contains("mcp_servers.XcodeBuildMCP.default_tools_approval_mode=\"auto\""))
+
+    // Resume re-passes the MCP config, approval mode included.
+    let resumed = config.argumentsForSession(sessionId: "codex-session", prompt: nil, agentHubMCPServerPath: helper, codexApprovalPolicy: "never", xcodeBuildMCPBootstrap: bootstrap)
+    #expect(resumed.contains("mcp_servers.agenthub.default_tools_approval_mode=\"auto\""))
+    #expect(resumed.contains("mcp_servers.XcodeBuildMCP.default_tools_approval_mode=\"auto\""))
+    #expect(resumed.contains("resume"))
+  }
+
   @Test("XcodeBuildMCP does not require the AgentHub MCP helper")
   func xcodeBuildMCPDoesNotRequireAgentHubHelper() {
     let bootstrap = XcodeBuildMCPBootstrap(
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/CLISessionsViewModelStudioTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/CLISessionsViewModelStudioTests.swift
new file mode 100644
index 00000000..bf5505c8
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/CLISessionsViewModelStudioTests.swift
@@ -0,0 +1,123 @@
+import AgentHubCLIKit
+import Combine
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+private final class StudioViewModelMonitorService: SessionMonitorServiceProtocol, @unchecked Sendable {
+  private let subject = PassthroughSubject<[SelectedRepository], Never>()
+  var repositoriesPublisher: AnyPublisher<[SelectedRepository], Never> { subject.eraseToAnyPublisher() }
+  func addRepository(_ path: String) async -> SelectedRepository? { nil }
+  func removeRepository(_ path: String) async {}
+  func getSelectedRepositories() async -> [SelectedRepository] { [] }
+  func setSelectedRepositories(_ repositories: [SelectedRepository]) async {}
+  func refreshSessions(skipWorktreeRedetection: Bool) async {}
+}
+
+private final class StudioViewModelFileWatcher: SessionFileWatcherProtocol, @unchecked Sendable {
+  private let subject = PassthroughSubject<SessionFileWatcher.StateUpdate, Never>()
+  var statePublisher: AnyPublisher<SessionFileWatcher.StateUpdate, Never> { subject.eraseToAnyPublisher() }
+  func startMonitoring(sessionId: String, projectPath: String, sessionFilePath: String?) async {}
+  func stopMonitoring(sessionId: String) async {}
+  func getState(sessionId: String) async -> SessionMonitorState? { nil }
+  func refreshState(sessionId: String) async {}
+  func setApprovalTimeout(_ seconds: Int) async {}
+}
+
+/// The glue between the handler and the shared library: both provider view
+/// models file into one `StudioLibrary`, keyed by project, so a canvas from
+/// Codex is on screen for a Claude session in the same repo.
+@Suite("CLISessionsViewModel Studio")
+struct CLISessionsViewModelStudioTests {
+  @MainActor
+  private func makeViewModel(provider: SessionProviderKind, library: StudioLibrary) -> CLISessionsViewModel {
+    let vm = CLISessionsViewModel(
+      monitorService: StudioViewModelMonitorService(),
+      fileWatcher: StudioViewModelFileWatcher(),
+      searchService: nil,
+      cliConfiguration: CLICommandConfiguration(
+        command: provider == .codex ? "codex" : "claude",
+        mode: provider == .codex ? .codex : .claude
+      ),
+      providerKind: provider,
+      approvalNotificationService: NoOpApprovalNotificationService()
+    )
+    vm.studioLibrary = library
+    return vm
+  }
+
+  @MainActor
+  private func makeLibrary() throws -> (StudioLibrary, URL) {
+    let root = try temporaryStudioRoot()
+    let library = StudioLibrary(
+      persistence: StudioPersistenceMock(),
+      documents: StudioDocumentWriter(rootURL: root.appendingPathComponent("docs")),
+      server: StudioServerMock(),
+      index: StudioIndexStore(directoryURL: root.appendingPathComponent("index"))
+    )
+    return (library, root)
+  }
+
+  @MainActor
+  private func waitUntil(_ condition: @MainActor () -> Bool) async {
+    for _ in 0..<200 where !condition() {
+      try? await Task.sleep(for: .milliseconds(10))
+    }
+  }
+
+  @Test("An artifact filed from a Codex session shows for a Claude session in the same project")
+  @MainActor
+  func sharedAcrossProviders() async throws {
+    let (library, root) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let claude = makeViewModel(provider: .claude, library: library)
+    let codex = makeViewModel(provider: .codex, library: library)
+    let claudeSession = CLISession(id: "claude-1", projectPath: "/tmp/proj/")
+    let codexSession = CLISession(id: "codex-1", projectPath: "/tmp/proj")
+
+    #expect(!claude.hasStudioArtifacts(for: claudeSession))
+    codex.storeStudioArtifact(makeStudioCanvas(id: "c1", provider: .codex, sessionId: "codex-1", projectPath: "/tmp/proj"), forSessionId: "codex-1")
+    await waitUntil { claude.hasStudioArtifacts(for: claudeSession) }
+
+    #expect(claude.studioArtifacts(for: claudeSession).map(\.id) == ["c1"])
+    #expect(codex.studioArtifacts(for: codexSession).map(\.id) == ["c1"])
+    #expect(claude.projectScopeKey(for: claudeSession) == codex.projectScopeKey(for: codexSession))
+  }
+
+  @Test("Re-filing under the same id replaces in place; delete removes it for every session")
+  @MainActor
+  func refileAndDelete() async throws {
+    let (library, root) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let vm = makeViewModel(provider: .claude, library: library)
+    let session = CLISession(id: "s1", projectPath: "/tmp/proj")
+
+    vm.storeStudioArtifact(makeStudioDocument(id: "d1", title: "v1", projectPath: "/tmp/proj"), forSessionId: "s1")
+    await waitUntil { vm.hasStudioArtifacts(for: session) }
+    vm.storeStudioArtifact(makeStudioDocument(id: "d1", title: "v2", createdAt: Date(timeIntervalSince1970: 5_000), projectPath: "/tmp/proj"), forSessionId: "s1")
+    await waitUntil { vm.studioArtifacts(for: session).first?.title == "v2" }
+
+    let stored = vm.studioArtifacts(for: session)
+    #expect(stored.count == 1)
+    #expect(stored.first?.revision == 2)
+    #expect(stored.first?.createdAt == Date(timeIntervalSince1970: 1_000))
+
+    vm.deleteStudioArtifact(id: "d1", in: session)
+    await waitUntil { !vm.hasStudioArtifacts(for: session) }
+    #expect(!vm.hasStudioArtifacts(for: session))
+  }
+
+  @Test("An artifact with no resolvable project is dropped, not stored under an empty key")
+  @MainActor
+  func dropsWithoutProject() async throws {
+    let (library, root) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let vm = makeViewModel(provider: .claude, library: library)
+
+    vm.storeStudioArtifact(makeStudioCanvas(id: "c1", projectPath: nil), forSessionId: "unknown-session")
+    try await Task.sleep(for: .milliseconds(100))
+
+    #expect(library.artifactsByProject.isEmpty)
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/CodexGlobalConfigReaderTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/CodexGlobalConfigReaderTests.swift
new file mode 100644
index 00000000..747caf34
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/CodexGlobalConfigReaderTests.swift
@@ -0,0 +1,59 @@
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@Suite("CodexGlobalConfigReader")
+struct CodexGlobalConfigReaderTests {
+  private func write(_ toml: String) throws -> URL {
+    let url = FileManager.default.temporaryDirectory
+      .appendingPathComponent("codex-config-\(UUID().uuidString).toml")
+    try toml.write(to: url, atomically: true, encoding: .utf8)
+    return url
+  }
+
+  @Test("Reads the top-level approval_policy, ignoring comments and quoting styles")
+  func readsTopLevelPolicy() throws {
+    let url = try write("""
+      model = "gpt-5" # comment with approval_policy = "untrusted" inside
+      approvals_reviewer = "user"
+      approval_policy = "never"   # global
+      sandbox_mode = "danger-full-access"
+      """)
+    defer { try? FileManager.default.removeItem(at: url) }
+    #expect(CodexGlobalConfigReader.approvalPolicy(configURL: url) == "never")
+
+    let single = try write("approval_policy = 'on-request'\n")
+    defer { try? FileManager.default.removeItem(at: single) }
+    #expect(CodexGlobalConfigReader.approvalPolicy(configURL: single) == "on-request")
+  }
+
+  @Test("A policy inside a table is scoped and does not count as global")
+  func tableScopedPolicyIgnored() throws {
+    let url = try write("""
+      model = "gpt-5"
+
+      [profiles.safe]
+      approval_policy = "untrusted"
+
+      [projects."/tmp/x"]
+      approval_policy = "never"
+      """)
+    defer { try? FileManager.default.removeItem(at: url) }
+    #expect(CodexGlobalConfigReader.approvalPolicy(configURL: url) == nil)
+    #expect(CodexGlobalConfigReader.topLevelValue(forKey: "model", in: try String(contentsOf: url, encoding: .utf8)) == "gpt-5")
+  }
+
+  @Test("Missing file or key yields nil; CODEX_HOME overrides the location")
+  func missingAndCodexHome() throws {
+    #expect(CodexGlobalConfigReader.approvalPolicy(configURL: URL(fileURLWithPath: "/nonexistent/\(UUID().uuidString).toml")) == nil)
+    let empty = try write("model = \"gpt-5\"\n")
+    defer { try? FileManager.default.removeItem(at: empty) }
+    #expect(CodexGlobalConfigReader.approvalPolicy(configURL: empty) == nil)
+
+    let url = CodexGlobalConfigReader.defaultConfigURL(environment: ["CODEX_HOME": "/tmp/codex-home"], homeDirectory: URL(fileURLWithPath: "/Users/nobody"))
+    #expect(url.path == "/tmp/codex-home/config.toml")
+    let home = CodexGlobalConfigReader.defaultConfigURL(environment: [:], homeDirectory: URL(fileURLWithPath: "/Users/nobody"))
+    #expect(home.path == "/Users/nobody/.codex/config.toml")
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/EmbeddedTerminalLaunchBuilderTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/EmbeddedTerminalLaunchBuilderTests.swift
index 64227eeb..de66f261 100644
--- a/app/modules/AgentHubCore/Tests/AgentHubTests/EmbeddedTerminalLaunchBuilderTests.swift
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/EmbeddedTerminalLaunchBuilderTests.swift
@@ -118,7 +118,8 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
       worktreeName: nil,
       metadataStore: nil,
       agentHubCLIPath: agentHubCLIPath,
-      installAgentHubWorktreeSkill: { installCount += 1 }
+      installAgentHubWorktreeSkill: { installCount += 1 },
+      studioGuidanceEnabled: false
     )
 
     guard case .success(let launch) = result else {
@@ -155,7 +156,8 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
       worktreeName: nil,
       metadataStore: nil,
       agentHubCLIPath: agentHubCLIPath,
-      installAgentHubWorktreeSkill: { installCount += 1 }
+      installAgentHubWorktreeSkill: { installCount += 1 },
+      studioGuidanceEnabled: false
     )
 
     guard case .success(let launch) = result else {
@@ -187,7 +189,8 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
       worktreeName: nil,
       metadataStore: nil,
       agentHubCLIPath: agentHubCLIPath,
-      installAgentHubWorktreeSkill: { installCount += 1 }
+      installAgentHubWorktreeSkill: { installCount += 1 },
+      studioGuidanceEnabled: false
     )
 
     guard case .success(let launch) = result else {
@@ -241,6 +244,7 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
       agentHubCLIPath: agentHubCLIPath,
       installAgentHubWorktreeSkill: { installCount += 1 },
       xcodeBuildMCPEnabled: true,
+      studioGuidanceEnabled: false,
       xcodeBuildMCPToolingAvailable: { true }
     )
 
@@ -284,6 +288,7 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
       agentHubCLIPath: agentHubCLIPath,
       installAgentHubWorktreeSkill: {},
       xcodeBuildMCPEnabled: true,
+      studioGuidanceEnabled: false,
       xcodeBuildMCPToolingAvailable: { false },
       notifyXcodeBuildMCPToolingMissing: { notifyCount += 1 }
     )
@@ -323,6 +328,7 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
       agentHubCLIPath: agentHubCLIPath,
       installAgentHubWorktreeSkill: {},
       xcodeBuildMCPEnabled: false,
+      studioGuidanceEnabled: false,
       xcodeBuildMCPToolingAvailable: { true },
       notifyXcodeBuildMCPToolingMissing: { notifyCount += 1 }
     )
@@ -352,7 +358,8 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
       metadataStore: nil,
       agentHubCLIPath: agentHubCLIPath,
       installAgentHubWorktreeSkill: { worktreeInstallCount += 1 },
-      removeLegacyAgentHubSessionNamingSkill: { namingSkillSweepCount += 1 }
+      removeLegacyAgentHubSessionNamingSkill: { namingSkillSweepCount += 1 },
+      studioGuidanceEnabled: false
     )
 
     guard case .success = result else {
@@ -376,7 +383,8 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
       worktreeName: nil,
       metadataStore: nil,
       agentHubCLIPath: agentHubCLIPath,
-      installAgentHubWorktreeSkill: {}
+      installAgentHubWorktreeSkill: {},
+      studioGuidanceEnabled: false
     )
 
     guard case .success(let launch) = result else {
@@ -405,7 +413,8 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
       worktreeName: nil,
       metadataStore: nil,
       agentHubCLIPath: agentHubCLIPath,
-      installAgentHubWorktreeSkill: {}
+      installAgentHubWorktreeSkill: {},
+      studioGuidanceEnabled: false
     )
 
     guard case .success(let launch) = result else {
@@ -465,6 +474,78 @@ struct EmbeddedTerminalLaunchBuilderAgentHubCLITests {
     #expect(try String(contentsOf: codexSkillURL, encoding: .utf8) == skillMarkdown)
   }
 
+  @Test("Studio guidance rides the system-prompt channel for both providers when enabled")
+  func studioGuidanceInjectedWhenEnabled() throws {
+    for mode in [CLICommandMode.claude, .codex] {
+      let result = EmbeddedTerminalLaunchBuilder.cliLaunch(
+        sessionId: nil,
+        projectPath: "/tmp",
+        cliConfiguration: CLICommandConfiguration(command: "echo", additionalPaths: ["/bin"], mode: mode),
+        initialPrompt: nil,
+        dangerouslySkipPermissions: false,
+        permissionModePlan: false,
+        worktreeName: nil,
+        metadataStore: nil,
+        agentHubCLIPath: agentHubCLIPath,
+        installAgentHubWorktreeSkill: {},
+        xcodeBuildMCPEnabled: false,
+        studioGuidanceEnabled: true
+      )
+      guard case .success(let launch) = result else {
+        Issue.record("Expected launch builder success")
+        return
+      }
+      let channel = mode == .claude ? "--append-system-prompt" : "developer_instructions="
+      #expect(launch.shellCommand.contains(channel))
+      #expect(launch.shellCommand.contains("agenthub_design"))
+      #expect(launch.shellCommand.contains("agenthub_list_artifacts"))
+    }
+
+    // No bundled CLI → the tools would not exist → no guidance either.
+    let withoutCLI = EmbeddedTerminalLaunchBuilder.cliLaunch(
+      sessionId: nil,
+      projectPath: "/tmp",
+      cliConfiguration: CLICommandConfiguration(command: "echo", additionalPaths: ["/bin"], mode: .claude),
+      initialPrompt: nil,
+      dangerouslySkipPermissions: false,
+      permissionModePlan: false,
+      worktreeName: nil,
+      metadataStore: nil,
+      agentHubCLIPath: "",
+      installAgentHubWorktreeSkill: {},
+      xcodeBuildMCPEnabled: false,
+      studioGuidanceEnabled: true
+    )
+    if case .success(let launch) = withoutCLI {
+      #expect(!launch.shellCommand.contains("agenthub_design"))
+    }
+  }
+
+  @Test("Bundled Studio skill installs for both providers and allows model invocation")
+  func bundledStudioSkillInstalls() throws {
+    let temporaryDirectory = FileManager.default.temporaryDirectory
+      .appendingPathComponent("AgentHubStudioSkillTests-\(UUID().uuidString)", isDirectory: true)
+    defer { try? FileManager.default.removeItem(at: temporaryDirectory) }
+
+    try AgentHubStudioSkillInstaller.installBundledSkillForAllProviders(homeDirectory: temporaryDirectory)
+
+    let claude = try String(contentsOf: temporaryDirectory.appendingPathComponent(".claude/skills/agenthub-studio/SKILL.md"), encoding: .utf8)
+    let codex = try String(contentsOf: temporaryDirectory.appendingPathComponent(".codex/skills/agenthub-studio/SKILL.md"), encoding: .utf8)
+    let yaml = try String(contentsOf: temporaryDirectory.appendingPathComponent(".codex/skills/agenthub-studio/agents/openai.yaml"), encoding: .utf8)
+
+    #expect(claude == codex)
+    #expect(claude.hasPrefix("---\nname: agenthub-studio\n"))
+    #expect(claude.contains("user-invocable: true"))
+    // The model may invoke it from the description — unlike the task manager, which is user-only.
+    #expect(!claude.contains("disable-model-invocation: true"))
+    #expect(claude.contains("mcp__agenthub__agenthub_design"))
+    #expect(claude.contains("mcp__agenthub__agenthub_artifact"))
+    #expect(claude.contains("mcp__agenthub__agenthub_list_artifacts"))
+    #expect(claude.contains("mcp__agenthub__agenthub_get_artifact"))
+    #expect(yaml.contains("allow_implicit_invocation: true"))
+    #expect(yaml.contains("$agenthub-studio"))
+  }
+
   @Test("Bundled task manager skill installs explicit invocation metadata")
   func bundledTaskManagerSkillInstallsExplicitInvocationMetadata() throws {
     let temporaryDirectory = FileManager.default.temporaryDirectory
@@ -566,7 +647,8 @@ struct EmbeddedTerminalLaunchBuilderLaunchContextTests {
       metadataStore: metadataStore,
       agentHubCLIPath: agentHubCLIPath,
       installAgentHubWorktreeSkill: {},
-      xcodeBuildMCPEnabled: false
+      xcodeBuildMCPEnabled: false,
+      studioGuidanceEnabled: false
     )
     guard case .success(let launch) = result else {
       throw NSError(domain: "LaunchContextTests", code: 1)
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/MultiSessionLaunchContextTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/MultiSessionLaunchContextTests.swift
index 39e721ac..3a85d19e 100644
--- a/app/modules/AgentHubCore/Tests/AgentHubTests/MultiSessionLaunchContextTests.swift
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/MultiSessionLaunchContextTests.swift
@@ -175,6 +175,20 @@ struct CombinedAppendSystemPromptTests {
     #expect(combined == EmbeddedTerminalLaunchBuilder.launchContextPreamble + "\n<context>x</context>")
   }
 
+  @Test("Studio guidance slots after simulator guidance and before the context block")
+  func studioGuidanceOrdering() {
+    #expect(EmbeddedTerminalLaunchBuilder.combinedAppendSystemPrompt(
+      simulatorGuidance: nil, studioGuidance: "use studio", launchContext: nil) == "use studio")
+    let combined = EmbeddedTerminalLaunchBuilder.combinedAppendSystemPrompt(
+      simulatorGuidance: "verify in the simulator", studioGuidance: "use studio", launchContext: "<context>x</context>")
+    #expect(combined == "verify in the simulator\n\nuse studio\n\n"
+      + EmbeddedTerminalLaunchBuilder.launchContextPreamble + "\n<context>x</context>")
+    #expect(StudioAgentGuidance.systemPrompt.contains("agenthub_design"))
+    #expect(StudioAgentGuidance.systemPrompt.contains("agenthub_artifact"))
+    #expect(StudioAgentGuidance.systemPrompt.contains("agenthub_list_artifacts"))
+    #expect(StudioAgentGuidance.systemPrompt.contains("agenthub_get_artifact"))
+  }
+
   @Test("Guidance comes first, then the context block")
   func guidanceThenContext() {
     let combined = EmbeddedTerminalLaunchBuilder.combinedAppendSystemPrompt(
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioArtifactHandlerTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioArtifactHandlerTests.swift
new file mode 100644
index 00000000..8d951b18
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioArtifactHandlerTests.swift
@@ -0,0 +1,76 @@
+import AgentHubCLIKit
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@MainActor
+@Suite("StudioArtifactHandler")
+struct StudioArtifactHandlerTests {
+  @Test("Routes to the filing provider using the explicit session id — Codex included")
+  func routesUsingExplicitSessionId() async throws {
+    let claude = StudioArtifactTargetMock()
+    let codex = StudioArtifactTargetMock()
+    let handler = StudioArtifactHandler(claudeTarget: claude, codexTarget: codex)
+
+    try await handler.handle(makeStudioDocument(id: "doc-1", provider: .codex, sessionId: "codex-session"))
+
+    #expect(claude.stored.isEmpty)
+    #expect(codex.stored.map(\.sessionId) == ["codex-session"])
+    #expect(codex.stored.first?.artifact.id == "doc-1")
+  }
+
+  @Test("Resolves the session by process id when the environment had none")
+  func resolvesSessionByProcessId() async throws {
+    let claude = StudioArtifactTargetMock(sessionIdsByProcessId: [42: "resolved-session"])
+    let handler = StudioArtifactHandler(claudeTarget: claude, codexTarget: StudioArtifactTargetMock())
+
+    try await handler.handle(makeStudioCanvas(provider: .claude, sessionId: nil, processId: 42))
+
+    #expect(claude.stored.map(\.sessionId) == ["resolved-session"])
+  }
+
+  @Test("Falls back from a pending session id to process resolution")
+  func fallsBackFromPendingSessionId() async throws {
+    let claude = StudioArtifactTargetMock(sessionIdsByProcessId: [42: "resolved-session"])
+    let handler = StudioArtifactHandler(claudeTarget: claude, codexTarget: StudioArtifactTargetMock())
+
+    try await handler.handle(makeStudioCanvas(provider: .claude, sessionId: "pending-123", processId: 42))
+
+    #expect(claude.stored.map(\.sessionId) == ["resolved-session"])
+  }
+
+  @Test("Throws sessionUnavailable when nothing resolves, so the monitor retries")
+  func throwsWhenUnresolvable() async {
+    let handler = StudioArtifactHandler(claudeTarget: StudioArtifactTargetMock(), codexTarget: StudioArtifactTargetMock())
+    await #expect(throws: StudioArtifactHandlingError.self) {
+      try await handler.handle(makeStudioCanvas(provider: .claude, sessionId: nil, processId: 1))
+    }
+    let monitor = StudioArtifactMonitor()
+    #expect(await monitor.shouldRetry(StudioArtifactHandlingError.sessionUnavailable, artifact: makeStudioCanvas(createdAt: .now)))
+    #expect(!(await monitor.shouldRetry(StudioArtifactHandlingError.sessionUnavailable, artifact: makeStudioCanvas(createdAt: Date(timeIntervalSince1970: 0)))))
+  }
+}
+
+@MainActor
+final class StudioArtifactTargetMock: StudioArtifactTarget {
+  struct Stored: Equatable {
+    let artifact: StudioArtifact
+    let sessionId: String
+  }
+
+  var sessionIdsByProcessId: [Int32: String]
+  private(set) var stored: [Stored] = []
+
+  init(sessionIdsByProcessId: [Int32: String] = [:]) {
+    self.sessionIdsByProcessId = sessionIdsByProcessId
+  }
+
+  func activeSessionId(forProcessId processId: Int32) -> String? {
+    sessionIdsByProcessId[processId]
+  }
+
+  func storeStudioArtifact(_ artifact: StudioArtifact, forSessionId sessionId: String) {
+    stored.append(Stored(artifact: artifact, sessionId: sessionId))
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioArtifactStoreTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioArtifactStoreTests.swift
new file mode 100644
index 00000000..341938f4
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioArtifactStoreTests.swift
@@ -0,0 +1,82 @@
+import AgentHubCLIKit
+import Foundation
+import GRDB
+import Testing
+
+@testable import AgentHubCore
+
+@Suite("Studio artifact store")
+struct StudioArtifactStoreTests {
+  @Test("An artifact round-trips through SQLite with its variants intact")
+  func roundTrips() async throws {
+    let store = try SessionMetadataStore(path: temporaryPath())
+    let artifact = makeStudioCanvas(id: "c1")
+    try await store.saveStudioArtifact(StudioArtifactRecord(artifact: artifact, projectPath: "/tmp/project", sessionId: "s1"))
+
+    let stored = try await store.getStudioArtifacts(forProjectPath: "/tmp/project")
+    #expect(stored.count == 1)
+    #expect(try stored.first?.decodedArtifact() == artifact)
+    #expect(stored.first?.kind == "canvas")
+  }
+
+  @Test("Re-saving the same id replaces; projects are isolated; both providers share a project")
+  func upsertAndScoping() async throws {
+    let store = try SessionMetadataStore(path: temporaryPath())
+    try await store.saveStudioArtifact(StudioArtifactRecord(artifact: makeStudioCanvas(id: "c1", title: "v1"), projectPath: "/p", sessionId: "s1"))
+    try await store.saveStudioArtifact(StudioArtifactRecord(artifact: makeStudioCanvas(id: "c1", title: "v2"), projectPath: "/p", sessionId: "s1"))
+    try await store.saveStudioArtifact(StudioArtifactRecord(artifact: makeStudioDocument(id: "d1", provider: .codex), projectPath: "/p/", sessionId: "codex"))
+    try await store.saveStudioArtifact(StudioArtifactRecord(artifact: makeStudioDocument(id: "other"), projectPath: "/q", sessionId: "s9"))
+
+    let p = try await store.getStudioArtifacts(forProjectPath: "/p")
+    #expect(Set(p.map(\.id)) == ["c1", "d1"])
+    #expect(try p.first { $0.id == "c1" }?.decodedArtifact().title == "v2")
+    #expect(try await store.getStudioArtifacts(forProjectPath: "/q").map(\.id) == ["other"])
+    #expect(try await store.getAllStudioArtifacts().count == 3)
+
+    try await store.deleteStudioArtifact(id: "d1")
+    try await store.deleteAllStudioArtifacts(forProjectPath: "/q")
+    #expect(try await store.getAllStudioArtifacts().map(\.id) == ["c1"])
+  }
+
+  @Test("v18 migration preserves existing metadata")
+  func v18MigrationPreservesExistingMetadata() async throws {
+    let path = temporaryPath()
+    let dbQueue = try DatabaseQueue(path: path)
+
+    try await dbQueue.write { db in
+      try seedMigrationBaseline(before: SessionMetadataStore.MigrationID.createStudioArtifacts, in: db)
+      try db.create(table: "session_metadata") { t in
+        t.column("sessionId", .text).primaryKey()
+        t.column("customName", .text)
+        t.column("createdAt", .datetime).notNull()
+        t.column("updatedAt", .datetime).notNull()
+        t.column("isPinned", .boolean).notNull().defaults(to: false)
+      }
+      try db.execute(
+        sql: "INSERT INTO session_metadata (sessionId, customName, createdAt, updatedAt, isPinned) VALUES (?, ?, ?, ?, ?)",
+        arguments: ["legacy-session", "legacy-name", Date(timeIntervalSince1970: 1_000), Date(timeIntervalSince1970: 2_000), true]
+      )
+      try db.create(table: "session_measurements") { t in
+        t.column("id", .text).primaryKey(onConflict: .replace)
+        t.column("sessionId", .text).notNull().indexed()
+        t.column("provider", .text).notNull()
+        t.column("createdAt", .datetime).notNull()
+        t.column("payloadVersion", .integer).notNull()
+        t.column("payloadData", .blob).notNull()
+        t.column("projectPath", .text).notNull().defaults(to: "")
+      }
+    }
+
+    let store = try SessionMetadataStore(path: path)
+    #expect(try await store.getCustomName(for: "legacy-session") == "legacy-name")
+    #expect(try await store.getPinnedSessionIds() == ["legacy-session"])
+    #expect(try await store.getStudioArtifacts(forProjectPath: "/tmp/project").isEmpty)
+    #expect(try await store.getMeasurements(forProjectPath: "/tmp/project").isEmpty)
+  }
+
+  private func temporaryPath() -> String {
+    FileManager.default.temporaryDirectory
+      .appending(path: "studio_artifacts_\(UUID().uuidString).sqlite")
+      .path
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioDesignEditStateTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioDesignEditStateTests.swift
new file mode 100644
index 00000000..ffb1f6d8
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioDesignEditStateTests.swift
@@ -0,0 +1,104 @@
+import AgentHubCLIKit
+import Canvas
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@MainActor
+@Suite("StudioDesignEditState")
+struct StudioDesignEditStateTests {
+  private func element(_ selector: String, text: String = "Go", color: String = "rgb(0, 0, 0)") -> ElementInspectorData {
+    ElementInspectorData(
+      tagName: "BUTTON", elementId: "", className: "btn", textContent: text,
+      outerHTML: "<button class=\"btn\">\(text)</button>", cssSelector: selector,
+      computedStyles: ["color": color, "backgroundColor": "rgb(255, 255, 255)", "fontSize": "16px", "borderRadius": "4px"],
+      boundingRect: CGRect(x: 0, y: 0, width: 80, height: 32)
+    )
+  }
+
+  @Test("Edits batch per element with old→new deltas, in selection order, stamped with variant")
+  func batchesPerElement() {
+    let state = StudioDesignEditState()
+    let a = element(".studio-artboard[data-variant=\"ghost\"] > button")
+    let b = element(".studio-artboard[data-variant=\"solid\"] > button", text: "Buy")
+
+    state.select(a, variantName: "ghost")
+    state.apply(DesignEdit(element: a, action: .updateProperty(.color, value: "#fff")), in: nil)
+    state.apply(DesignEdit(element: a, action: .updateProperty(.borderRadius, value: "12px")), in: nil)
+    state.apply(DesignEdit(element: a, action: .updateProperty(.color, value: "#eee")), in: nil)  // last wins, one entry
+    state.apply(DesignEdit(element: a, action: .updateTextContent("Continue")), in: nil)
+
+    state.select(b, variantName: "solid")
+    state.apply(DesignEdit(element: b, action: .fitContent), in: nil)
+    // Edits for an element that is not selected are ignored.
+    state.apply(DesignEdit(element: a, action: .updateProperty(.padding, value: "0")), in: nil)
+
+    #expect(state.pendingChangeCount == 4)
+    let ordered = state.orderedEdits
+    #expect(ordered.count == 2)
+    #expect(ordered[0].variantName == "ghost")
+    #expect(ordered[0].batch.styleChanges.map(\.property) == ["color", "border-radius"])
+    #expect(ordered[0].batch.styleChanges[0].oldValue == "rgb(0, 0, 0)")
+    #expect(ordered[0].batch.styleChanges[0].newValue == "#eee")
+    #expect(ordered[0].batch.styleChanges[1].oldValue == "4px")
+    #expect(ordered[0].batch.textChange?.oldText == "Go")
+    #expect(ordered[0].batch.textChange?.newText == "Continue")
+    #expect(ordered[1].variantName == "solid")
+    #expect(ordered[1].fitToContent)
+    #expect(state.toolbarValues?.textContent == "Buy")  // toolbar seeds from the selected element
+  }
+
+  @Test("Reverting to the original value cancels the pending change; delete deselects")
+  func revertAndDelete() {
+    let state = StudioDesignEditState()
+    let a = element("#a")
+    state.select(a, variantName: nil)
+    state.apply(DesignEdit(element: a, action: .updateProperty(.color, value: "#fff")), in: nil)
+    #expect(state.hasPendingEdits)
+    state.apply(DesignEdit(element: a, action: .updateProperty(.color, value: "rgb(0, 0, 0)")), in: nil)
+    #expect(!state.hasPendingEdits)
+
+    state.apply(DesignEdit(element: a, action: .deleteElement), in: nil)
+    #expect(state.selectedElement == nil)
+    #expect(state.orderedEdits.first?.deleted == true)
+    #expect(state.pendingChangeCount == 1)
+
+    state.clear()
+    #expect(!state.hasPendingEdits)
+    #expect(state.orderedEdits.isEmpty)
+  }
+
+  @Test("Refresh keeps edited toolbar values and adopts the rest; a variant is stamped late without losing the batch")
+  func refreshKeepsEditedValues() {
+    let state = StudioDesignEditState()
+    let a = element("#a", color: "rgb(0, 0, 0)")
+    state.select(a, variantName: nil)
+    state.apply(DesignEdit(element: a, action: .updateProperty(.color, value: "#123456")), in: nil)
+    #expect(state.toolbarValues?.color == "#123456")
+
+    // The page echoes back normalized values plus a changed font size.
+    var refreshedStyles = a.computedStyles
+    refreshedStyles["color"] = "rgb(18, 52, 86)"
+    refreshedStyles["fontSize"] = "18px"
+    let refreshed = ElementInspectorData(
+      id: a.id, tagName: a.tagName, elementId: a.elementId, className: a.className, textContent: a.textContent,
+      outerHTML: a.outerHTML, cssSelector: a.cssSelector, computedStyles: refreshedStyles, boundingRect: a.boundingRect
+    )
+    state.refresh(with: refreshed)
+    #expect(state.toolbarValues?.color == "#123456")
+    #expect(state.toolbarValues?.fontSize == 18)
+
+    state.select(refreshed, variantName: "ghost")
+    #expect(state.orderedEdits.first?.variantName == "ghost")
+    #expect(state.orderedEdits.first?.batch.styleChanges.count == 1)
+  }
+
+  @Test("Computed values map kebab properties to the bridge's camelCase keys")
+  func computedValueLookup() {
+    let a = element("#a")
+    #expect(StudioDesignEditState.computedValue(for: .backgroundColor, in: a) == "rgb(255, 255, 255)")
+    #expect(StudioDesignEditState.computedValue(for: .borderRadius, in: a) == "4px")
+    #expect(StudioDesignEditState.computedValue(for: .letterSpacing, in: a) == nil)
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioDocumentWriterTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioDocumentWriterTests.swift
new file mode 100644
index 00000000..a5ff4d93
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioDocumentWriterTests.swift
@@ -0,0 +1,146 @@
+import AgentHubCLIKit
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@Suite("StudioDocumentWriter")
+struct StudioDocumentWriterTests {
+  @Test("A document artifact is served verbatim")
+  func documentIsVerbatim() throws {
+    let artifact = makeStudioDocument(html: "<!DOCTYPE html><html><body><p>hi</p></body></html>")
+    #expect(try StudioDocumentWriter.render(artifact) == "<!DOCTYPE html><html><body><p>hi</p></body></html>")
+  }
+
+  @Test("A canvas renders one labelled artboard per variant, in order, with scoped CSS")
+  func canvasRendersArtboards() throws {
+    let html = try StudioDocumentWriter.render(makeStudioCanvas())
+
+    #expect(html.contains("<title>Primary button</title>"))
+    let solidRange = try #require(html.range(of: "class=\"studio-artboard\" data-variant=\"solid\""))
+    let ghostRange = try #require(html.range(of: "class=\"studio-artboard\" data-variant=\"ghost\""))
+    #expect(solidRange.lowerBound < ghostRange.lowerBound)
+    #expect(html.contains("<span class=\"studio-name\">solid</span>"))
+    #expect(html.contains("<p class=\"studio-notes\">default</p>"))
+    #expect(html.contains(".studio-artboard[data-variant=\"solid\"] .btn {\n  color: red;\n}"))
+    #expect(html.contains(".studio-artboard[data-variant=\"ghost\"] .btn {\n  color: blue;\n}"))
+    #expect(html.contains(".studio-artboard[data-variant=\"ghost\"] { width: 320px; height: 120px; overflow: auto; }"))
+    #expect(html.contains("window.__agenthubStudio"))
+    // Pan/zoom is a transform, not a scroll: the host must tell the inspector
+    // the viewport moved or the comment box stays behind.
+    #expect(html.contains("window.dispatchEvent(new Event('scroll'))"))
+    #expect(html.range(of: "label.textContent = Math.round\\(scale \\* 100\\) \\+ '%';\\s*notifyViewportMoved\\(\\);", options: .regularExpression) != nil)
+    // The host owns the document: exactly one <html> and no nested documents.
+    #expect(html.components(separatedBy: "<html").count == 2)
+  }
+
+  @Test("Variant names and notes are HTML-escaped in the host chrome")
+  func namesAreEscaped() throws {
+    let artifact = makeStudioCanvas(variants: [
+      StudioVariant(name: "a<b>", html: "<i>x</i>", css: "", notes: "use \"quotes\" & <tags>")
+    ])
+    let html = try StudioDocumentWriter.render(artifact)
+    #expect(html.contains("data-variant=\"a&lt;b&gt;\""))
+    #expect(html.contains("use &quot;quotes&quot; &amp; &lt;tags&gt;"))
+    #expect(!html.contains("<p class=\"studio-notes\">use \"quotes\""))
+  }
+
+  @Test("Unscopable variant CSS makes render throw rather than leak")
+  func unscopableCSSThrows() {
+    let artifact = makeStudioCanvas(variants: [StudioVariant(name: "x", html: "<i>x</i>", css: ".a { color: red;")])
+    #expect(throws: StudioCSSScoper.ParseError.self) {
+      try StudioDocumentWriter.render(artifact)
+    }
+  }
+
+  @Test("The canvas host page carries an Implement button per artboard and the edit-bake helpers")
+  func hostPageImplementAndBakeHelpers() throws {
+    let html = try StudioDocumentWriter.render(makeStudioCanvas())
+    #expect(html.contains("<button type=\"button\" class=\"studio-implement\" data-variant=\"solid\""))
+    #expect(html.contains("<button type=\"button\" class=\"studio-implement\" data-variant=\"ghost\""))
+    #expect(html.contains("messageHandlers.agentHubStudio"))
+    #expect(html.contains("postMessage({ type: 'implement', variant:"))
+    #expect(html.contains("serializeArtboards: function"))
+    #expect(html.contains("variantsForSelectors: function"))
+    #expect(html.contains("removeElement: function"))
+    // Hidden unless the AgentHub bridge is present (plain browser / export).
+    #expect(html.contains("body.studio-hosted .studio-implement { display: inline-block; }"))
+  }
+
+  @Test("Writing an artifact also writes the payload sidecar the CLI reads")
+  func writesPayloadSidecar() throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let writer = StudioDocumentWriter(rootURL: root)
+    let artifact = makeStudioCanvas(id: "canvas-1")
+
+    let url = try writer.write(artifact, projectKey: "/tmp/project")
+    let payloadURL = StudioDocumentWriter.payloadURL(besideDocument: url)
+    #expect(payloadURL.lastPathComponent == "artifact.json")
+    let decoder = JSONDecoder(); decoder.dateDecodingStrategy = .iso8601
+    #expect(try decoder.decode(StudioArtifact.self, from: Data(contentsOf: payloadURL)) == artifact)
+  }
+
+  @Test("Writes under root/{project}/{id}/index.html and deletes cascade")
+  func writesAndDeletes() throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let writer = StudioDocumentWriter(rootURL: root)
+
+    let url = try writer.write(makeStudioCanvas(id: "canvas-1"), projectKey: "/tmp/project")
+    #expect(url.lastPathComponent == "index.html")
+    #expect(url.deletingLastPathComponent().lastPathComponent == "canvas-1")
+    #expect(url.path.hasPrefix(root.path))
+    #expect(FileManager.default.fileExists(atPath: url.path))
+    #expect(writer.relativePath(forArtifactId: "canvas-1", projectKey: "/tmp/project").hasSuffix("/canvas-1/index.html"))
+
+    // Same key, trailing slash or not, lands in the same project directory.
+    #expect(
+      writer.documentURL(forArtifactId: "canvas-1", projectKey: "/tmp/project/")
+        == writer.documentURL(forArtifactId: "canvas-1", projectKey: "/tmp/project")
+    )
+
+    try writer.delete(artifactId: "canvas-1", projectKey: "/tmp/project")
+    #expect(!FileManager.default.fileExists(atPath: url.deletingLastPathComponent().path))
+
+    _ = try writer.write(makeStudioCanvas(id: "canvas-2"), projectKey: "/tmp/project")
+    try writer.deleteAll(projectKey: "/tmp/project")
+    #expect(!FileManager.default.fileExists(atPath: url.deletingLastPathComponent().deletingLastPathComponent().path))
+  }
+
+  @Test("A canvas written by an older host page is stale; documents are current whenever present")
+  func hostVersionStaleness() throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let writer = StudioDocumentWriter(rootURL: root)
+    let canvas = makeStudioCanvas(id: "c1")
+    let document = makeStudioDocument(id: "d1")
+
+    #expect(!writer.isCurrent(canvas, projectKey: "/p"))
+    let url = try writer.write(canvas, projectKey: "/p")
+    #expect(writer.isCurrent(canvas, projectKey: "/p"))
+    #expect(try String(contentsOf: url, encoding: .utf8).contains("<meta name=\"agenthub-studio-host\" content=\"\(StudioDocumentWriter.hostVersion)\">"))
+
+    // Simulate a file from an older writer.
+    try Data("<!DOCTYPE html><html><head><meta name=\"agenthub-studio-host\" content=\"1\"></head><body></body></html>".utf8).write(to: url)
+    #expect(!writer.isCurrent(canvas, projectKey: "/p"))
+    try Data("<!DOCTYPE html><html><body>no marker</body></html>".utf8).write(to: url)
+    #expect(!writer.isCurrent(canvas, projectKey: "/p"))
+
+    #expect(!writer.isCurrent(document, projectKey: "/p"))
+    _ = try writer.write(document, projectKey: "/p")
+    #expect(writer.isCurrent(document, projectKey: "/p"))
+  }
+
+  @Test("Unsafe ids never reach the filesystem as path components")
+  func unsafeIdsAreHashed() {
+    #expect(StudioDocumentWriter.artifactDirectoryName(forId: "canvas-1") == "canvas-1")
+    #expect(StudioDocumentWriter.artifactDirectoryName(forId: "A1B2-c3_d.4") == "A1B2-c3_d.4")
+    for unsafe in ["..", ".", "../etc/passwd", "a/b", "", String(repeating: "x", count: 81), "sp ace", "..hidden"] {
+      let name = StudioDocumentWriter.artifactDirectoryName(forId: unsafe)
+      #expect(name.hasPrefix("h-"), "\(unsafe) should hash, got \(name)")
+      #expect(!name.contains("/"))
+    }
+    #expect(StudioDocumentWriter.artifactDirectoryName(forId: "..hidden").hasPrefix("h-"))
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioLibraryTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioLibraryTests.swift
new file mode 100644
index 00000000..7b6c73f4
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioLibraryTests.swift
@@ -0,0 +1,236 @@
+import AgentHubCLIKit
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@MainActor
+@Suite("StudioLibrary")
+struct StudioLibraryTests {
+  private func makeLibrary() throws -> (StudioLibrary, StudioPersistenceMock, URL, StudioIndexStore) {
+    let root = try temporaryStudioRoot()
+    let persistence = StudioPersistenceMock()
+    let index = StudioIndexStore(directoryURL: root.appendingPathComponent("index"))
+    let library = StudioLibrary(
+      persistence: persistence,
+      documents: StudioDocumentWriter(rootURL: root.appendingPathComponent("docs")),
+      server: StudioServerMock(),
+      index: index
+    )
+    return (library, persistence, root, index)
+  }
+
+  @Test("Store puts the artifact in memory first, writes the document, persists, and publishes the index")
+  func storeRoundTrip() async throws {
+    let (library, persistence, root, index) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    await library.store(makeStudioCanvas(id: "c1"), projectKey: "/repo", sessionId: "s1", aliasPaths: ["/repo-wt"])
+
+    #expect(library.artifacts(forProjectKey: "/repo").map(\.id) == ["c1"])
+    #expect(persistence.saved.map(\.id) == ["c1"])
+    #expect(persistence.saved.first?.projectPath == "/repo")
+    #expect(FileManager.default.fileExists(atPath: library.documentURL(for: makeStudioCanvas(id: "c1"), projectKey: "/repo").path))
+
+    // Index publish is detached; poll briefly.
+    var entry: StudioIndexEntry?
+    for _ in 0..<50 where entry == nil {
+      try await Task.sleep(for: .milliseconds(20))
+      entry = index.read(projectPath: "/repo-wt")?.artifacts.first
+    }
+    #expect(entry?.id == "c1")
+    #expect(entry?.variantNames == ["solid", "ghost"])
+    #expect(entry?.documentPath?.hasSuffix("/c1/index.html") == true)
+  }
+
+  @Test("Re-filing the same id replaces in place, keeps createdAt, bumps revision")
+  func refileReplacesInPlace() async throws {
+    let (library, persistence, root, _) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let first = makeStudioCanvas(id: "c1", createdAt: Date(timeIntervalSince1970: 100))
+    await library.store(first, projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+    let second = makeStudioCanvas(id: "c1", title: "Primary button v2", createdAt: Date(timeIntervalSince1970: 200))
+    await library.store(second, projectKey: "/repo", sessionId: "s2", aliasPaths: [])
+
+    let stored = library.artifacts(forProjectKey: "/repo")
+    #expect(stored.count == 1)
+    #expect(stored[0].title == "Primary button v2")
+    #expect(stored[0].createdAt == first.createdAt)
+    #expect(stored[0].revision == 2)
+    #expect(persistence.saved.count == 1)
+    #expect(try persistence.saved.last?.decodedArtifact().revision == 2)
+    #expect(persistence.saved.last?.sessionId == "s2")
+  }
+
+  @Test("Load merges persisted artifacts without dropping ones that arrived first, and is idempotent")
+  func loadMerges() async throws {
+    let (library, persistence, root, _) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+    persistence.saved = [
+      try StudioArtifactRecord(artifact: makeStudioDocument(id: "persisted"), projectPath: "/repo", sessionId: "s0")
+    ]
+
+    await library.store(makeStudioCanvas(id: "fresh"), projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+    await library.load(projectKey: "/repo", aliasPaths: [])
+    await library.load(projectKey: "/repo", aliasPaths: [])
+
+    #expect(Set(library.artifacts(forProjectKey: "/repo").map(\.id)) == ["fresh", "persisted"])
+    #expect(persistence.getCalls == 1)
+  }
+
+  @Test("Delete cascades to memory, disk, and persistence; deleteAll clears the project")
+  func deleteCascades() async throws {
+    let (library, persistence, root, _) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let artifact = makeStudioCanvas(id: "c1")
+    await library.store(artifact, projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+    let doc = library.documentURL(for: artifact, projectKey: "/repo")
+
+    await library.delete(id: "c1", projectKey: "/repo", aliasPaths: [])
+    #expect(library.artifacts(forProjectKey: "/repo").isEmpty)
+    #expect(!FileManager.default.fileExists(atPath: doc.path))
+    #expect(persistence.deletedIds == ["c1"])
+
+    await library.store(makeStudioCanvas(id: "c2"), projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+    await library.deleteAll(projectKey: "/repo")
+    #expect(library.artifacts(forProjectKey: "/repo").isEmpty)
+    #expect(persistence.deletedProjects == ["/repo"])
+  }
+
+  @Test("servedURL regenerates a canvas written by an older host page")
+  func servedURLRegeneratesStaleCanvas() async throws {
+    let (library, _, root, _) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let canvas = makeStudioCanvas(id: "c1")
+    await library.store(canvas, projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+    let doc = library.documentURL(for: canvas, projectKey: "/repo")
+    try Data("<html><body>stale host page</body></html>".utf8).write(to: doc)
+
+    _ = await library.servedURL(for: canvas, projectKey: "/repo")
+
+    let html = try String(contentsOf: doc, encoding: .utf8)
+    #expect(html.contains("agenthub-studio-host"))
+    #expect(html.contains("class=\"studio-artboard\" data-variant=\"solid\""))
+  }
+
+  @Test("servedURL rewrites a missing document and resolves under the server base")
+  func servedURLRewritesMissingDocument() async throws {
+    let (library, _, root, _) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let artifact = makeStudioDocument(id: "d1")
+    await library.store(artifact, projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+    let doc = library.documentURL(for: artifact, projectKey: "/repo")
+    try FileManager.default.removeItem(at: doc)
+
+    let url = try #require(await library.servedURL(for: artifact, projectKey: "/repo"))
+    #expect(url.absoluteString.hasPrefix("http://127.0.0.1:1234/"))
+    #expect(url.absoluteString.hasSuffix("/d1/index.html"))
+    #expect(FileManager.default.fileExists(atPath: doc.path))
+  }
+
+  @Test("allProjects groups by project with bytes on disk; reconcile drops orphans")
+  func allProjectsAndReconcile() async throws {
+    let (library, persistence, root, _) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+    await library.store(makeStudioCanvas(id: "c1"), projectKey: "/repo-a", sessionId: "s1", aliasPaths: [])
+    await library.store(makeStudioDocument(id: "d1"), projectKey: "/repo-b", sessionId: "s1", aliasPaths: [])
+
+    let projects = await library.allProjects()
+    #expect(projects.map(\.projectKey) == ["/repo-a", "/repo-b"])
+    #expect(projects.allSatisfy { $0.bytesOnDisk > 0 })
+
+    // An orphan directory nobody vouches for.
+    let orphan = root.appendingPathComponent("docs/zzzz/orphan", isDirectory: true)
+    try FileManager.default.createDirectory(at: orphan, withIntermediateDirectories: true)
+    try Data("x".utf8).write(to: orphan.appendingPathComponent("index.html"))
+    persistence.deletedIds = []
+    await library.reconcileStorage()
+    #expect(!FileManager.default.fileExists(atPath: orphan.path))
+    #expect(FileManager.default.fileExists(atPath: library.documentURL(for: makeStudioCanvas(id: "c1"), projectKey: "/repo-a").path))
+  }
+
+  @Test("Baking edits replaces only the named variants' html, bumps the revision, and republishes the payload")
+  func updateVariantHTMLBakesEdits() async throws {
+    let (library, persistence, root, index) = try makeLibrary()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let canvas = makeStudioCanvas(id: "c1")
+    await library.store(canvas, projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+
+    let stored = await library.updateVariantHTML(
+      artifactId: "c1",
+      htmlByVariant: ["ghost": "<button class=\"btn\" style=\"color: red;\">Buy now</button>"],
+      projectKey: "/repo",
+      sessionId: "s1",
+      aliasPaths: []
+    )
+
+    #expect(stored?.revision == 2)
+    #expect(stored?.variants.first { $0.name == "ghost" }?.html == "<button class=\"btn\" style=\"color: red;\">Buy now</button>")
+    #expect(stored?.variants.first { $0.name == "ghost" }?.css == canvas.variants[1].css)
+    #expect(stored?.variants.first { $0.name == "solid" } == canvas.variants[0])
+    #expect(try persistence.saved.first?.decodedArtifact().variants.first { $0.name == "ghost" }?.html.contains("Buy now") == true)
+
+    // Sidecar the CLI reads reflects the bake, and the index points at it.
+    let payloadURL = StudioDocumentWriter.payloadURL(besideDocument: library.documentURL(for: canvas, projectKey: "/repo"))
+    let decoder = JSONDecoder(); decoder.dateDecodingStrategy = .iso8601
+    #expect(try decoder.decode(StudioArtifact.self, from: Data(contentsOf: payloadURL)).revision == 2)
+    var entry: StudioIndexEntry?
+    for _ in 0..<50 where entry?.revision != 2 {
+      try await Task.sleep(for: .milliseconds(20))
+      entry = index.read(projectPath: "/repo")?.artifacts.first
+    }
+    #expect(entry?.payloadPath == payloadURL.path)
+
+    // No-op when nothing changes; unknown artifact returns nil.
+    let unchanged = await library.updateVariantHTML(artifactId: "c1", htmlByVariant: [:], projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+    #expect(unchanged?.revision == 2)
+    #expect(await library.updateVariantHTML(artifactId: "nope", htmlByVariant: [:], projectKey: "/repo", sessionId: "s1", aliasPaths: []) == nil)
+  }
+
+  @Test("Merged keeps newest-filed first and lets incoming win")
+  func mergedOrdering() {
+    let a = makeStudioCanvas(id: "a", createdAt: Date(timeIntervalSince1970: 1))
+    let b = makeStudioCanvas(id: "b", createdAt: Date(timeIntervalSince1970: 2))
+    let a2 = makeStudioCanvas(id: "a", title: "A2", createdAt: Date(timeIntervalSince1970: 1))
+    let merged = StudioLibrary.merged(existing: [b, a], incoming: [a2])
+    #expect(merged.map(\.id) == ["b", "a"])
+    #expect(merged[1].title == "A2")
+  }
+}
+
+final class StudioPersistenceMock: StudioPersisting, @unchecked Sendable {
+  var saved: [StudioArtifactRecord] = []
+  var deletedIds: [String] = []
+  var deletedProjects: [String] = []
+  var getCalls = 0
+
+  func saveStudioArtifact(_ record: StudioArtifactRecord) async throws {
+    saved.removeAll { $0.id == record.id }
+    saved.append(record)
+  }
+
+  func getStudioArtifacts(forProjectPath projectPath: String) async throws -> [StudioArtifactRecord] {
+    getCalls += 1
+    return saved.filter { $0.projectPath == projectPath }
+  }
+
+  func getAllStudioArtifacts() async throws -> [StudioArtifactRecord] {
+    saved
+  }
+
+  func deleteStudioArtifact(id: String) async throws {
+    deletedIds.append(id)
+    saved.removeAll { $0.id == id }
+  }
+
+  func deleteAllStudioArtifacts(forProjectPath projectPath: String) async throws {
+    deletedProjects.append(projectPath)
+    saved.removeAll { $0.projectPath == projectPath }
+  }
+}
+
+struct StudioServerMock: StudioStaticServing {
+  func start() async throws -> URL { URL(string: "http://127.0.0.1:1234/")! }
+  func stop() async {}
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioPanelStateTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioPanelStateTests.swift
new file mode 100644
index 00000000..4413f75a
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioPanelStateTests.swift
@@ -0,0 +1,72 @@
+import AgentHubCLIKit
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@MainActor
+@Suite("StudioPanelState")
+struct StudioPanelStateTests {
+  private let older = makeStudioCanvas(id: "older", createdAt: Date(timeIntervalSince1970: 100))
+  private let newer = makeStudioDocument(id: "newer", createdAt: Date(timeIntervalSince1970: 200))
+
+  @Test("With no explicit selection, the most recently updated artifact is shown")
+  func defaultsToMostRecentlyUpdated() {
+    let state = StudioPanelState()
+    #expect(state.selectedArtifact(in: [older, newer])?.id == "newer")
+
+    let refiled = makeStudioCanvas(id: "older", createdAt: Date(timeIntervalSince1970: 300)).replacing(older)
+    #expect(refiled.displayDate == Date(timeIntervalSince1970: 300))
+    #expect(state.selectedArtifact(in: [refiled, newer])?.id == "older")
+  }
+
+  @Test("An explicit selection wins while it exists, then falls back")
+  func explicitSelectionWins() {
+    let state = StudioPanelState()
+    state.selectedArtifactId = "older"
+    #expect(state.selectedArtifact(in: [older, newer])?.id == "older")
+    #expect(state.selectedArtifact(in: [newer])?.id == "newer")
+    #expect(state.selectedArtifact(in: []) == nil)
+  }
+
+  @Test("Reload token changes on artifact switch, revision bump, and manual reload")
+  func reloadToken() {
+    let state = StudioPanelState()
+    #expect(state.reloadToken(for: nil) == "none")
+    let base = state.reloadToken(for: older)
+    #expect(state.reloadToken(for: newer) != base)
+    let bumped = makeStudioCanvas(id: "older", createdAt: older.createdAt).replacing(older)
+    #expect(state.reloadToken(for: bumped) != base)
+    state.failureMessage = "x"
+    state.reload()
+    #expect(state.reloadToken(for: older) != base)
+    #expect(state.failureMessage == nil)
+  }
+
+  @Test("Selection follows a newly filed artifact, survives re-files, falls back when deleted")
+  func reconcileSelection() {
+    let state = StudioPanelState()
+    state.selectedArtifactId = "older"
+
+    // Re-file of the selected item: selection sticks.
+    let refiled = makeStudioCanvas(id: "older", createdAt: Date(timeIntervalSince1970: 500)).replacing(older)
+    state.reconcileSelection(previous: [older, newer], current: [refiled, newer])
+    #expect(state.selectedArtifactId == "older")
+
+    // A brand-new artifact takes over.
+    let brandNew = makeStudioDocument(id: "brand-new", createdAt: Date(timeIntervalSince1970: 50))
+    state.reconcileSelection(previous: [refiled, newer], current: [refiled, newer, brandNew])
+    #expect(state.selectedArtifactId == "brand-new")
+
+    // Deleting the selected one falls back to the most recently updated.
+    state.reconcileSelection(previous: [refiled, newer, brandNew], current: [refiled, newer])
+    #expect(state.selectedArtifactId == "older")
+  }
+
+  @Test("Variant name is recovered from a scoped selector, including escaped quotes")
+  func variantFromSelector() {
+    #expect(StudioPanelState.variantName(fromSelector: ".studio-artboard[data-variant=\"ghost\"] > button.btn") == "ghost")
+    #expect(StudioPanelState.variantName(fromSelector: ".studio-artboard[data-variant=\"say \\\"hi\\\"\"] i") == "say \"hi\"")
+    #expect(StudioPanelState.variantName(fromSelector: "body > div > button") == nil)
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioPromptBuilderTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioPromptBuilderTests.swift
new file mode 100644
index 00000000..847face1
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioPromptBuilderTests.swift
@@ -0,0 +1,115 @@
+import AgentHubCLIKit
+import Canvas
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@Suite("Studio prompt builders")
+struct StudioPromptBuilderTests {
+  private let element = ElementInspectorData(
+    tagName: "BUTTON",
+    elementId: "",
+    className: "btn",
+    textContent: "Go",
+    outerHTML: "<button class=\"btn\">Go</button>",
+    cssSelector: ".studio-artboard[data-variant=\"ghost\"] > button.btn",
+    computedStyles: ["color": "rgb(0, 0, 255)"],
+    boundingRect: CGRect(x: 0, y: 0, width: 80, height: 32)
+  )
+
+  @Test("Canvas feedback names the variant, carries element context, re-files by id, forbids project edits")
+  func canvasFeedback() {
+    let prompt = StudioFeedbackPromptBuilder.prompt(
+      artifact: makeStudioCanvas(id: "canvas-9"),
+      variantName: "ghost",
+      element: element,
+      instruction: "more padding"
+    )
+    #expect(prompt.contains("design canvas \"Primary button\""))
+    #expect(prompt.contains("agenthub_design (id canvas-9), variant \"ghost\""))
+    #expect(prompt.contains("<button class=\"btn\">Go</button>"))
+    #expect(prompt.contains("User request: more padding"))
+    #expect(prompt.contains("re-file it with agenthub_design using id canvas-9"))
+    #expect(prompt.contains("change the \"ghost\" variant, keep the other variants"))
+    #expect(prompt.contains("do not edit project files"))
+    #expect(!prompt.contains("Implement"))
+  }
+
+  @Test("Document feedback uses agenthub_artifact and no variant")
+  func documentFeedback() {
+    let prompt = StudioFeedbackPromptBuilder.prompt(
+      artifact: makeStudioDocument(id: "doc-3"),
+      variantName: nil,
+      element: nil,
+      instruction: "bigger headline"
+    )
+    #expect(prompt.contains("artifact \"Q3 report\" you rendered with agenthub_artifact (id doc-3)."))
+    #expect(!prompt.contains("variant"))
+    #expect(prompt.contains("re-file it with agenthub_artifact using id doc-3"))
+    #expect(prompt.contains("do not edit project files"))
+  }
+
+  @Test("Edit-mode batch prompt lists every element with its variant and deltas, re-files by id, forbids project edits")
+  func editsPrompt() throws {
+    let prompt = try #require(StudioFeedbackPromptBuilder.editsPrompt(
+      artifact: makeStudioCanvas(id: "canvas-9"),
+      edits: [
+        .init(element: element, variantName: "ghost", changeLines: ["- color: rgb(0, 0, 255) → #fff", "- text content: \"Go\" → \"Continue\""]),
+        .init(element: element, variantName: nil, changeLines: ["- remove this element"]),
+      ]
+    ))
+    #expect(prompt.hasPrefix("I made visual edits directly on the Studio design canvas \"Primary button\" (id canvas-9). Please make them permanent."))
+    #expect(prompt.contains("### Element 1 — variant \"ghost\""))
+    #expect(prompt.contains("### Element 2\n"))
+    #expect(prompt.contains("- color: rgb(0, 0, 255) → #fff"))
+    #expect(prompt.contains("- remove this element"))
+    #expect(prompt.contains("re-file with agenthub_design using id canvas-9".lowercased()) || prompt.contains("Re-file with agenthub_design using id canvas-9"))
+    #expect(prompt.contains("do not edit project files"))
+    #expect(StudioFeedbackPromptBuilder.editsPrompt(artifact: makeStudioCanvas(), edits: []) == nil)
+  }
+
+  @Test("Crop prompt carries region, screenshot path, elements, variant, and re-file framing")
+  func cropPrompt() {
+    let prompt = StudioFeedbackPromptBuilder.cropPrompt(
+      artifact: makeStudioCanvas(id: "canvas-9"),
+      variantName: "ghost",
+      cropRect: CGRect(x: 10, y: 20, width: 300, height: 120),
+      elements: [element],
+      instruction: "tighten this group",
+      screenshotPath: "/tmp/crop.png"
+    )
+    #expect(prompt.hasPrefix("I'm looking at a region of the Studio design canvas \"Primary button\" you rendered with agenthub_design (id canvas-9), on variant \"ghost\"."))
+    #expect(!prompt.contains("live web preview"))
+    #expect(prompt.contains("**Region**: 300px × 120px at (10, 20)"))
+    #expect(prompt.contains("/tmp/crop.png"))
+    #expect(prompt.contains("**Elements in region** (1)"))
+    #expect(prompt.contains("User request: tighten this group"))
+    #expect(prompt.contains("re-file it with agenthub_design using id canvas-9"))
+    #expect(prompt.contains("do not edit project files"))
+  }
+
+  @Test("Promotion sends the original fragment and CSS, names the source path, and never the scoped selector")
+  func promotion() throws {
+    let prompt = try #require(StudioPromotionPromptBuilder.prompt(artifact: makeStudioCanvas(id: "canvas-9"), variantName: "ghost"))
+    #expect(prompt.hasPrefix("Implement the \"ghost\" variant from the Studio design canvas \"Primary button\" (id canvas-9) in the real project, in src/Button.tsx."))
+    #expect(prompt.contains("```html\n<button class=\"btn\">Go</button>\n```"))
+    #expect(prompt.contains("```css\n.btn { color: blue; }\n```"))
+    #expect(!prompt.contains(".studio-artboard"))
+    #expect(prompt.contains("Preserve the component's existing behaviour"))
+    #expect(prompt.contains("list the files you changed"))
+  }
+
+  @Test("Promotion is unavailable for documents and unknown variants")
+  func promotionUnavailable() {
+    #expect(StudioPromotionPromptBuilder.prompt(artifact: makeStudioDocument(), variantName: "x") == nil)
+    #expect(StudioPromotionPromptBuilder.prompt(artifact: makeStudioCanvas(), variantName: "nope") == nil)
+  }
+
+  @Test("Promotion without a source path omits the target clause and includes notes")
+  func promotionWithoutSourcePath() throws {
+    let prompt = try #require(StudioPromotionPromptBuilder.prompt(artifact: makeStudioCanvas(sourcePath: nil), variantName: "solid"))
+    #expect(prompt.hasPrefix("Implement the \"solid\" variant from the Studio design canvas \"Primary button\" (id canvas-1) in the real project."))
+    #expect(prompt.contains("Design notes: default"))
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioStaticServerTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioStaticServerTests.swift
new file mode 100644
index 00000000..cc91278a
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioStaticServerTests.swift
@@ -0,0 +1,97 @@
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@Suite("StudioStaticServer")
+struct StudioStaticServerTests {
+  @Test("Serves files under the root, resolves directories to index.html, sets no-store")
+  func servesFilesUnderRoot() throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let dir = root.appendingPathComponent("p/a", isDirectory: true)
+    try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+    try Data("<h1>hi</h1>".utf8).write(to: dir.appendingPathComponent("index.html"))
+
+    let response = StudioStaticServer.resolve(requestLine: "GET /p/a/ HTTP/1.1", rootURL: root)
+    #expect(response.status == 200)
+    #expect(response.contentType.hasPrefix("text/html"))
+    #expect(String(decoding: response.body, as: UTF8.self) == "<h1>hi</h1>")
+    #expect(String(decoding: response.data, as: UTF8.self).contains("Cache-Control: no-store"))
+
+    #expect(StudioStaticServer.resolve(requestLine: "GET /p/a HTTP/1.1", rootURL: root).status == 200)
+    #expect(StudioStaticServer.resolve(requestLine: "GET /p/a/index.html?v=2 HTTP/1.1", rootURL: root).status == 200)
+    #expect(StudioStaticServer.resolve(requestLine: "GET /p/a/index.html#x HTTP/1.1", rootURL: root).status == 200)
+  }
+
+  @Test("HEAD returns headers only; other methods are rejected")
+  func headAndMethods() throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    try Data("x".utf8).write(to: root.appendingPathComponent("f.txt"))
+
+    let head = StudioStaticServer.resolve(requestLine: "HEAD /f.txt HTTP/1.1", rootURL: root)
+    #expect(head.status == 200)
+    #expect(!head.includeBody)
+    #expect(String(decoding: head.data, as: UTF8.self).hasSuffix("\r\n\r\n"))
+
+    #expect(StudioStaticServer.resolve(requestLine: "POST /f.txt HTTP/1.1", rootURL: root).status == 405)
+    #expect(StudioStaticServer.resolve(requestLine: "garbage", rootURL: root).status == 400)
+  }
+
+  @Test("Paths that escape the root, dotfiles, and missing files are 404")
+  func escapesAndMissingAre404() throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let sibling = root.deletingLastPathComponent().appendingPathComponent("secret-\(UUID().uuidString).txt")
+    try Data("secret".utf8).write(to: sibling)
+    defer { try? FileManager.default.removeItem(at: sibling) }
+    try Data("hidden".utf8).write(to: root.appendingPathComponent(".env"))
+
+    for path in [
+      "/../\(sibling.lastPathComponent)",
+      "/%2e%2e/\(sibling.lastPathComponent)",
+      "/a/../../\(sibling.lastPathComponent)",
+      "/.env",
+      "/missing.html",
+      "relative/no/leading/slash",
+    ] {
+      let response = StudioStaticServer.resolve(requestLine: "GET \(path) HTTP/1.1", rootURL: root)
+      #expect(response.status == 404, "\(path) → \(response.status)")
+    }
+    #expect(StudioStaticServer.fileURL(forRequestPath: "/../x", rootURL: root) == nil)
+  }
+
+  @Test("Content types follow the extension")
+  func contentTypes() {
+    #expect(StudioStaticServer.contentType(forExtension: "css").hasPrefix("text/css"))
+    #expect(StudioStaticServer.contentType(forExtension: "SVG") == "image/svg+xml")
+    #expect(StudioStaticServer.contentType(forExtension: "woff2") == "font/woff2")
+    #expect(StudioStaticServer.contentType(forExtension: "bin") == "application/octet-stream")
+  }
+
+  @Test("Starts on loopback and serves over a real socket")
+  func servesOverLoopback() async throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let dir = root.appendingPathComponent("p/a", isDirectory: true)
+    try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+    try Data("<h1>live</h1>".utf8).write(to: dir.appendingPathComponent("index.html"))
+
+    let server = StudioStaticServer(rootURL: root)
+    let base = try await server.start()
+    defer { Task { await server.stop() } }
+    #expect(base.host == "127.0.0.1")
+    #expect(try await server.start() == base, "start is idempotent")
+
+    let url = try #require(URL(string: "p/a/", relativeTo: base)?.absoluteURL)
+    let (data, response) = try await URLSession.shared.data(from: url)
+    let http = try #require(response as? HTTPURLResponse)
+    #expect(http.statusCode == 200)
+    #expect(http.value(forHTTPHeaderField: "Cache-Control") == "no-store")
+    #expect(String(decoding: data, as: UTF8.self) == "<h1>live</h1>")
+
+    let (_, missing) = try await URLSession.shared.data(from: URL(string: "nope.html", relativeTo: base)!.absoluteURL)
+    #expect((missing as? HTTPURLResponse)?.statusCode == 404)
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioStorageReconcilerTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioStorageReconcilerTests.swift
new file mode 100644
index 00000000..49c9a9e7
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioStorageReconcilerTests.swift
@@ -0,0 +1,43 @@
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@Suite("StudioStorageReconciler")
+struct StudioStorageReconcilerTests {
+  @Test("Orphan artifact directories are removed; known ones and empty projects are handled")
+  func reconcileRemovesOrphans() throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let fm = FileManager.default
+    for path in ["proj1/known/index.html", "proj1/orphan/index.html", "proj2/orphan2/index.html", "proj3/.DS_Store"] {
+      let url = root.appendingPathComponent(path)
+      try fm.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
+      try Data("x".utf8).write(to: url)
+    }
+
+    let report = StudioStorageReconciler(rootURL: root).reconcile(knownDirectoryNames: ["known"])
+
+    #expect(report.removedArtifactDirectories == 2)
+    #expect(report.removedEmptyProjectDirectories == 2)
+    #expect(fm.fileExists(atPath: root.appendingPathComponent("proj1/known/index.html").path))
+    #expect(!fm.fileExists(atPath: root.appendingPathComponent("proj1/orphan").path))
+    #expect(!fm.fileExists(atPath: root.appendingPathComponent("proj2").path))
+    #expect(!fm.fileExists(atPath: root.appendingPathComponent("proj3").path))
+  }
+
+  @Test("A missing root is a no-op")
+  func missingRootIsNoop() {
+    let report = StudioStorageReconciler(rootURL: URL(fileURLWithPath: "/nonexistent/\(UUID().uuidString)")).reconcile(knownDirectoryNames: [])
+    #expect(report == StudioStorageReconciler.Report())
+  }
+
+  @Test("Directory size sums files")
+  func directorySize() throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    try Data(repeating: 0, count: 100).write(to: root.appendingPathComponent("a"))
+    try Data(repeating: 0, count: 50).write(to: root.appendingPathComponent("b"))
+    #expect(StudioStorageReconciler.directorySize(at: root) == 150)
+  }
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioTestSupport.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioTestSupport.swift
new file mode 100644
index 00000000..351bdfe8
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioTestSupport.swift
@@ -0,0 +1,65 @@
+import AgentHubCLIKit
+import Foundation
+
+@testable import AgentHubCore
+
+func makeStudioCanvas(
+  id: String = "canvas-1",
+  title: String = "Primary button",
+  createdAt: Date = Date(timeIntervalSince1970: 1_000),
+  revision: Int = 1,
+  sourcePath: String? = "src/Button.tsx",
+  variants: [StudioVariant] = [
+    StudioVariant(name: "solid", html: "<button class=\"btn\">Go</button>", css: ".btn { color: red; }", notes: "default"),
+    StudioVariant(name: "ghost", html: "<button class=\"btn\">Go</button>", css: ".btn { color: blue; }", width: 320, height: 120),
+  ],
+  warnings: [String] = [],
+  provider: WorktreeLaunchProvider = .claude,
+  sessionId: String? = "session-1",
+  projectPath: String? = "/tmp/project",
+  processId: Int32 = 42
+) -> StudioArtifact {
+  StudioArtifact(
+    id: id,
+    kind: .canvas,
+    createdAt: createdAt,
+    revision: revision,
+    title: title,
+    sourcePath: sourcePath,
+    variants: variants,
+    warnings: warnings,
+    sourceProvider: provider,
+    sourceSessionId: sessionId,
+    sourceProjectPath: projectPath,
+    sourceProcessId: processId
+  )
+}
+
+func makeStudioDocument(
+  id: String = "doc-1",
+  title: String = "Q3 report",
+  html: String = "<!DOCTYPE html><html><head><title>R</title></head><body><h1>Report</h1></body></html>",
+  createdAt: Date = Date(timeIntervalSince1970: 1_000),
+  provider: WorktreeLaunchProvider = .codex,
+  sessionId: String? = "session-2",
+  projectPath: String? = "/tmp/project"
+) -> StudioArtifact {
+  StudioArtifact(
+    id: id,
+    kind: .document,
+    createdAt: createdAt,
+    title: title,
+    html: html,
+    sourceProvider: provider,
+    sourceSessionId: sessionId,
+    sourceProjectPath: projectPath,
+    sourceProcessId: 7
+  )
+}
+
+func temporaryStudioRoot() throws -> URL {
+  let url = FileManager.default.temporaryDirectory
+    .appendingPathComponent("agenthub-studio-\(UUID().uuidString)", isDirectory: true)
+  try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+  return url
+}
diff --git a/app/modules/AgentHubCore/Tests/AgentHubTests/StudioTweaksTests.swift b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioTweaksTests.swift
new file mode 100644
index 00000000..6a3f543f
--- /dev/null
+++ b/app/modules/AgentHubCore/Tests/AgentHubTests/StudioTweaksTests.swift
@@ -0,0 +1,132 @@
+import AgentHubCLIKit
+import Canvas
+import Foundation
+import Testing
+
+@testable import AgentHubCore
+
+@Suite("Studio tweaks")
+struct StudioTweaksTests {
+  private let props = [
+    StudioTweakProp(name: "radius", label: "Corner radius", type: .slider, value: .number(12), minimum: 0, maximum: 32, step: 1, unit: "px"),
+    StudioTweakProp(name: "accent", type: .color, value: .string("#0a84ff")),
+    StudioTweakProp(name: "cta", type: .text, value: .string("Continue</script>")),
+    StudioTweakProp(name: "shadow", type: .toggle, value: .boolean(true)),
+  ]
+
+  @Test("The canvas host page exposes props as CSS variables and declares the schema")
+  func hostPageExposesProps() throws {
+    let artifact = makeStudioCanvas().withContent(props: props)
+    let html = try StudioDocumentWriter.render(artifact)
+
+    #expect(html.contains("<style id=\"studio-props\">"))
+    #expect(html.contains("  --radius: 12px;"))
+    #expect(html.contains("  --accent: #0a84ff;"))
+    #expect(html.contains("  --shadow: 1;"))
+    #expect(html.contains("window.__studioProps = ["))
+    #expect(html.contains("\"name\":\"radius\""))
+    #expect(html.contains("\"unit\":\"px\""))
+    #expect(html.contains("\"label\":\"Corner radius\""))
+    // A closing tag inside a value must terminate neither the host <script>
+    // (JSON escape) nor the props <style> block (CSS hex escape).
+    #expect(!html.contains("Continue</script>"))
+    #expect(html.contains("Continue<\\/script>"))
+    #expect(html.contains("--cta: Continue\\3c /script\\3e ;"))
+    #expect(StudioDocumentWriter.cssBlockValue("a } b; </style>") == "a \\7d  b\\3b  \\3c /style\\3e ")
+    #expect(html.contains("window.dc_set_props(schema)"))
+    #expect(html.contains("window.dc_on_props_changed = function"))
+  }
+
+  @Test("A canvas without props emits no props block and an empty schema")
+  func hostPageWithoutProps() throws {
+    let html = try StudioDocumentWriter.render(makeStudioCanvas())
+    #expect(!html.contains("studio-props"))
+    #expect(html.contains("window.__studioProps = [];"))
+  }
+
+  @MainActor
+  @Test("Save defaults on a canvas updates the shared schema and re-stores with a revision bump")
+  func saveDefaultsCanvas() async throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let persistence = StudioPersistenceMock()
+    let library = StudioLibrary(
+      persistence: persistence,
+      documents: StudioDocumentWriter(rootURL: root.appendingPathComponent("docs")),
+      server: StudioServerMock(),
+      index: StudioIndexStore(directoryURL: root.appendingPathComponent("index"))
+    )
+    await library.store(makeStudioCanvas(id: "c1").withContent(props: props), projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+
+    try await library.saveTweakDefaults(
+      artifactId: "c1",
+      values: ["radius": .number(20), "shadow": .boolean(false)],
+      projectKey: "/repo",
+      sessionId: "s1",
+      aliasPaths: []
+    )
+
+    let stored = try #require(library.artifact(id: "c1", projectKey: "/repo"))
+    #expect(stored.revision == 2)
+    #expect(stored.props.first { $0.name == "radius" }?.value == .number(20))
+    #expect(stored.props.first { $0.name == "shadow" }?.value == .boolean(false))
+    #expect(stored.props.first { $0.name == "accent" }?.value == .string("#0a84ff"))
+    #expect(stored.variants == makeStudioCanvas().variants)
+    let html = try String(contentsOf: library.documentURL(for: stored, projectKey: "/repo"), encoding: .utf8)
+    #expect(html.contains("--radius: 20px;"))
+    #expect(try persistence.saved.first?.decodedArtifact().props.first { $0.name == "radius" }?.value == .number(20))
+
+    await #expect(throws: StudioLibrary.TweakDefaultsError.self) {
+      try await library.saveTweakDefaults(artifactId: "c1", values: ["nope": .number(1)], projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+    }
+  }
+
+  @MainActor
+  @Test("Save defaults on a document splices the dc_set_props call, never the whole file")
+  func saveDefaultsDocument() async throws {
+    let root = try temporaryStudioRoot()
+    defer { try? FileManager.default.removeItem(at: root) }
+    let library = StudioLibrary(
+      persistence: StudioPersistenceMock(),
+      documents: StudioDocumentWriter(rootURL: root.appendingPathComponent("docs")),
+      server: StudioServerMock(),
+      index: StudioIndexStore(directoryURL: root.appendingPathComponent("index"))
+    )
+    let html = """
+      <!DOCTYPE html><html><body><h1 id="t">Hi</h1>
+      <script>
+      if (window.dc_set_props) dc_set_props({ radius: { type: "slider", value: 12, min: 0, max: 40 }, accent: { type: "color", value: "#0a84ff" } });
+      </script></body></html>
+      """
+    await library.store(makeStudioDocument(id: "d1", html: html), projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+
+    try await library.saveTweakDefaults(artifactId: "d1", values: ["radius": .number(24)], projectKey: "/repo", sessionId: "s1", aliasPaths: [])
+
+    let stored = try #require(library.artifact(id: "d1", projectKey: "/repo"))
+    #expect(stored.revision == 2)
+    #expect(stored.html?.contains("radius: { type: \"slider\", value: 24, min: 0, max: 40 }") == true)
+    #expect(stored.html?.contains("accent: { type: \"color\", value: \"#0a84ff\" }") == true)
+    #expect(stored.html?.hasPrefix("<!DOCTYPE html><html><body><h1 id=\"t\">Hi</h1>") == true)
+  }
+
+  @Test("Tweaks prompts re-file by id and forbid project edits")
+  func prompts() {
+    let canvas = makeStudioCanvas(id: "c9")
+    let existing = [TweakProp(name: "radius", label: "Radius", type: .slider, value: .number(12))]
+    let ideas = StudioTweaksPromptBuilder.ideasPrompt(artifact: canvas, existingProps: existing)
+    #expect(ideas.contains("design canvas \"Primary button\" (id c9)"))
+    #expect(ideas.contains("radius (slider)"))
+    #expect(ideas.contains("agenthub_design using id c9"))
+    #expect(ideas.contains("var(--<name>)"))
+    #expect(ideas.contains("do not edit project files"))
+
+    let custom = StudioTweaksPromptBuilder.customPrompt(artifact: makeStudioDocument(id: "d9"), instruction: "a density knob")
+    #expect(custom.contains("artifact \"Q3 report\" (id d9): a density knob"))
+    #expect(custom.contains("agenthub_artifact using id d9"))
+    #expect(custom.contains("dc_set_props"))
+
+    let delete = StudioTweaksPromptBuilder.deleteAllPrompt(artifact: canvas)
+    #expect(delete.contains("with no `props`"))
+    #expect(delete.contains("do not edit project files"))
+  }
+}