diff --git a/.changeset/proxy-allowed-paths.md b/.changeset/proxy-allowed-paths.md
new file mode 100644
index 0000000..9f209f9
--- /dev/null
+++ b/.changeset/proxy-allowed-paths.md
@@ -0,0 +1,5 @@
+---
+"@runflow-io/proxy": minor
+---
+
+Add `allowedPaths` — an extensible, strictly-matched route allow-list on top of the built-ins (dispatch, run polling, health). Defaults cover what `rf.assets.upload`/`rf.assets.get` need (`POST /v1/asset-uploads`, `POST /v1/asset-uploads/:id/confirmations`, `GET /v1/assets/:id`). Like `allowedModels`, a custom list **replaces** the defaults — spread the exported `DEFAULT_ALLOWED_PATHS` to extend, or pass `[]` to disable the asset routes. Rules support method arrays and `:param` segments, reject traversal (including percent-encoded) and empty segments. 403/415 bodies now carry actionable messages plus machine-readable `code`s (`path_not_allowed`, `model_not_allowed`, `origin_not_allowed`, `json_content_type_required`). The handler also exposes `PUT`/`PATCH`/`DELETE` for framework route exports. `RateLimitResult`'s `void` member is now `undefined` (type-level only).
diff --git a/.changeset/sdk-assets-pin.md b/.changeset/sdk-assets-pin.md
new file mode 100644
index 0000000..02a6560
--- /dev/null
+++ b/.changeset/sdk-assets-pin.md
@@ -0,0 +1,9 @@
+---
+"@runflow-io/sdk": minor
+---
+
+Add `rf.assets.upload(file)` — the browser-safe presigned upload flow (create session → PUT to storage → confirm) with transient-failure retry and a size-scaled PUT timeout, returning a model-ready signed HTTPS `url` plus the stable `runflow://assets/{id}` `ref`. Fixes the most common external-fork failure: browser file uploads ending up as `data:` URIs that models reject with a 422. Add `rf.assets.get(id)` to re-mint an expired signed url (store the `id`, not the `url`).
+
+Export `composePinPrompt`, `composeRegionPrompt`, `pinRegion`, and `PinPoint` — the pin→region prompt convention (3×3 grid baked into the edit prompt) that previously existed only as private copies inside the studio bundle.
+
+Hardening: proxy mode (`baseUrl`) now never sends `Authorization`, even when `apiKey` is also passed (the documented contract); presigned-URL query strings are redacted from error messages; non-https `upload_url`s are refused. New `RunflowErrorCode` union for autocompletable `catch` handling.
diff --git a/.changeset/studio-props-mask.md b/.changeset/studio-props-mask.md
new file mode 100644
index 0000000..54fa31e
--- /dev/null
+++ b/.changeset/studio-props-mask.md
@@ -0,0 +1,9 @@
+---
+"@runflow-io/studio": minor
+---
+
+`<StudioShell>` accepts four optional customization props — `tools` (workflow catalogue), `source` (initial asset URL or sample list, read at mount), `sentinel` (`{ enabled, taskDescription }`), and `copy` (brand/labels) — making vertical forks possible without rebuilding on `./headless`. Zero props renders exactly as before. `mount()` forwards them via the new `props` option.
+
+`./headless` now exports `createMaskController` — the framework-free dual-canvas brush engine (stroke interpolation, coverage, full-resolution thresholded mask blob, guarded against unattached use and bad brush sizes) the shell itself uses, so headless consumers get working mask creation for inpaint workflows without rebuilding it.
+
+The shell's file uploads now default to the SDK's presigned flow through `runflowProxy` (zero-config — no separate `upload` endpoint needed); hosts that explicitly set `urls.upload` keep the legacy multipart path. `unmount()` now also clears theme CSS variables, and blob preview URLs are revoked on unmount.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..195315a
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: build · typecheck · test · lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.10
+
+      - name: Install
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Test
+        run: bun run test
+
+      - name: Lint
+        run: bun run lint
+
+      # Warning ratchet: biome warnings (mostly the studio components'
+      # downgraded a11y/hooks rules) must not grow past the checked-in
+      # budget. Lower the budget as warnings get fixed; raising it is a
+      # conscious review decision.
+      - name: Lint warning ratchet
+        run: |
+          BUDGET=45
+          count=$(bunx biome check . 2>&1 | grep -oE 'Found [0-9]+ warnings' | grep -oE '[0-9]+' | head -1 || true)
+          count=${count:-0}
+          echo "biome warnings: $count (budget: $BUDGET)"
+          if [ "$count" -gt "$BUDGET" ]; then
+            echo "::error::Warning count $count exceeds the budget of $BUDGET — fix the new warnings or consciously raise the budget in ci.yml."
+            exit 1
+          fi
+
+      # The live e2e proof (examples/e2e-proof) needs RUNFLOW_API_KEY and
+      # spends real credits, so it stays a local/manual gate — see
+      # `bun run proof`.
diff --git a/README.md b/README.md
index b13b0f3..f42ccb2 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,20 @@ Add a changeset for every user-visible change:
 bun changeset
 ```
 
+## End-to-end proof
+
+`bun run proof` exercises the real customer chain — browser SDK →
+`@runflow-io/proxy` → api.runflow.io — across every modality, including
+file upload via `rf.assets.upload` and the proxy allow-list. It needs
+`RUNFLOW_API_KEY` and spends real credits, so it's a local/manual gate
+(not CI). Results land in `.proof/`.
+
+For a worked example of a vertical fork (customize `<StudioShell>` via
+its `tools` / `source` / `sentinel` / `copy` props, or build a custom UI
+on `./headless`), see the
+[real-estate-studio-sdk](https://github.com/runflow-io/real-estate-studio-sdk)
+reference repo.
+
 ## License
 
 MIT
diff --git a/biome.json b/biome.json
index 4efd033..fd6f82e 100644
--- a/biome.json
+++ b/biome.json
@@ -27,6 +27,26 @@
       }
     }
   },
+  "overrides": [
+    {
+      "include": ["packages/studio/src/components/**"],
+      "linter": {
+        "rules": {
+          "a11y": {
+            "noLabelWithoutControl": "warn",
+            "noAutofocus": "warn",
+            "useSemanticElements": "warn"
+          },
+          "suspicious": {
+            "noArrayIndexKey": "warn"
+          },
+          "correctness": {
+            "useExhaustiveDependencies": "warn"
+          }
+        }
+      }
+    }
+  ],
   "javascript": {
     "formatter": {
       "quoteStyle": "double",
diff --git a/bun.lock b/bun.lock
index c8da09a..2e2c864 100644
--- a/bun.lock
+++ b/bun.lock
@@ -22,7 +22,7 @@
     },
     "packages/proxy": {
       "name": "@runflow-io/proxy",
-      "version": "0.0.2",
+      "version": "0.0.3",
       "devDependencies": {
         "@types/node": "^22.10.1",
         "tsup": "^8.3.5",
@@ -32,7 +32,7 @@
     },
     "packages/sdk": {
       "name": "@runflow-io/sdk",
-      "version": "0.0.2",
+      "version": "0.0.3",
       "devDependencies": {
         "tsup": "^8.3.5",
         "typescript": "^5.7.2",
@@ -41,12 +41,12 @@
     },
     "packages/studio": {
       "name": "@runflow-io/studio",
-      "version": "0.0.2",
+      "version": "0.0.3",
       "dependencies": {
         "jszip": "^3.10.1",
       },
       "devDependencies": {
-        "@runflow-io/sdk": "^0.0.2",
+        "@runflow-io/sdk": "^0.0.3",
         "@types/react": "^18.3.12",
         "@types/react-dom": "^18.3.1",
         "react": "^18.3.1",
@@ -56,7 +56,7 @@
         "vitest": "^2.1.8",
       },
       "peerDependencies": {
-        "@runflow-io/sdk": "^0.0.2",
+        "@runflow-io/sdk": "^0.0.3",
         "react": "^18.0.0 || ^19.0.0",
         "react-dom": "^18.0.0 || ^19.0.0",
       },
diff --git a/docs/plans/run-384-sdk-gaps/backend-contract.md b/docs/plans/run-384-sdk-gaps/backend-contract.md
new file mode 100644
index 0000000..87b8e72
--- /dev/null
+++ b/docs/plans/run-384-sdk-gaps/backend-contract.md
@@ -0,0 +1,75 @@
+# Backend contract: resolve `runflow://` asset refs at dispatch (RUN-384 gaps 2 + 6)
+
+**Target repo:** `runflow-monorepo` (api.runflow.io). **Not** implemented in `runflow-js` —
+this document is the companion spec for the backend ticket.
+
+## Current behavior (verified in code)
+
+- **Writes** (`POST /v1/models/{owner}/{slug}/runs`, `POST /v1/comfyui-workflows/.../runs`,
+  batches, admin retries): inline `data:` URIs in `body.input`/`body.metadata` are
+  auto-materialized to R2 and stored as `runflow://assets/{uuid}` refs. This is correct
+  and should stay.
+- **Reads** (`GET /v1/runs`, `GET /v1/runs/{id}`, batch/canonical listings): asset-backed
+  URLs are re-signed and `runflow://assets/{uuid}` refs are resolved to short-TTL signed
+  HTTPS URLs. Also correct.
+- **The gap:** at **model dispatch**, the materialized `runflow://` ref is forwarded to the
+  model worker **as-is**. Worker media validators accept only HTTP(S)/`data:` URIs —
+  `google/nano-banana-pro/edit` (and most non-ComfyUI models) reject with
+  `422: media URL must use HTTP(S) or data URI, got 'runflow'`. ComfyUI workflow file
+  inputs already accept the refs; singleton model dispatch does not.
+
+So the `data:`-materialization *convenience* currently breaks the exact requests it
+rewrites. (The original ticket framed this as "make materialization opt-in"; the better
+fix below removes the need for any flag.)
+
+## Requested change
+
+At the dispatch layer — after materialization, before the input reaches the model
+worker / provider transport — apply the **same resolution the read path already does**:
+
+1. Walk `body.input` (and `metadata` where it feeds workers) for strings of scheme
+   `runflow://assets/{uuid}`.
+2. Resolve each ref org-scoped (existing read-side resolver semantics: load asset, check
+   `access_expires_at`, sign `r2_key`) into a signed HTTPS URL whose TTL comfortably
+   covers worker pull + retries (suggest ≥ the worker's max queue+run window).
+3. Forward the signed HTTPS URL to the worker. Persist the **ref** (not the signed URL)
+   on the run record, as today.
+4. Unknown/foreign-org/expired refs → 422 with a precise message
+   (`asset not found or expired: runflow://assets/{uuid}`) — fail at dispatch, not in
+   the worker.
+
+### Acceptance criteria
+
+- `POST /v1/models/google/nano-banana-pro/edit/runs` with `input.image_urls:
+  ["runflow://assets/{uuid}"]` succeeds end to end (no 422), for both an explicit ref
+  and one produced by `data:` auto-materialization.
+- Read-side responses are unchanged (refs still resolve on read).
+- ComfyUI dispatch behavior unchanged.
+- A run whose ref points at a foreign org's asset 404s/422s without leaking existence
+  details beyond the standard non-leaky pattern.
+
+### Why dispatch-side resolution (not validator changes, not an opt-in flag)
+
+- One implementation point instead of N model-validator changes across providers.
+- Asset refs become first-class on the write path, matching the read path — the SDK can
+  then hand `UploadedAsset.ref` (stable, no TTL) to any model instead of the signed `url`.
+- The `data:` materialization default stays a pure convenience with no footgun, so no
+  config flag is needed.
+
+## Interim state (already shipped in runflow-js)
+
+`rf.assets.upload(file)` returns the **signed HTTPS** url from the confirmation response
+(`routers/asset_uploads.py` signs it server-side), so external forks are unblocked today
+without this change. Once dispatch-side resolution lands, the SDK will document `ref` as
+the preferred long-lived input.
+
+## Suggested ticket
+
+> **Title:** Resolve `runflow://assets/{uuid}` refs to signed HTTPS at model dispatch
+> **Parent:** RUN-384
+> **Why:** Auto-materialized `data:` inputs currently 422 on most singleton models
+> (worker media validators only accept HTTP(S)/data:). Read path already resolves refs;
+> dispatch must do the same so asset refs are first-class across the stack.
+> **Scope:** dispatch layer for `POST /v1/models/.../runs` (+ batches, retries);
+> resolver reuse from the read path; 422 on unknown/expired refs; tests per acceptance
+> criteria above. ComfyUI unchanged.
diff --git a/docs/plans/run-384-sdk-gaps/design.md b/docs/plans/run-384-sdk-gaps/design.md
new file mode 100644
index 0000000..385098a
--- /dev/null
+++ b/docs/plans/run-384-sdk-gaps/design.md
@@ -0,0 +1,140 @@
+# RUN-384 — Close SDK gaps blocking external Studio forks
+
+**Repo:** `runflow-js` (this monorepo). **Branch:** `mr/bb13-sdk-gaps-https-l`.
+**Scope:** A — five in-repo gaps (1, 3, 4, 5, 7) implemented + proven end-to-end;
+two backend gaps (2, 6) delivered as a contract spec + companion ticket, **not** coded here.
+
+## Why (grounded in the actual code, which diverges from the ticket)
+
+The ticket attributes `data:`→`runflow://` materialization and a flat-403 path filter to
+`@runflow-io/proxy`. **Neither is in this package.** The JS proxy forwards bodies verbatim and
+gates on a *model* allow-list (`handler.ts:140`, `classify()` at `:277`). The materialization is a
+**backend** feature (`api.runflow.io`) and is, per the API contract, *correct*: `data:` URIs
+materialize to R2 and **reads return signed HTTPS**. The real defect (gaps 2/6) is narrower:
+`runflow://assets/{uuid}` refs are resolved on **reads** (`GET /v1/runs`) but **not at dispatch**
+before a model worker's media validator runs — so `google/nano-banana-pro/edit` 422s on
+`runflow://`.
+
+Consequently the *real-world* browser breakage is fixed entirely in-repo by **gap 1 + gap 4**,
+with no backend change required:
+
+- `rf.assets.upload(file)` returns a **signed HTTPS** url (confirmed: `routers/asset_uploads.py:94-96`
+  signs the confirm payload via `storage.sign_asset_payloads`). HTTPS ⇒ no 422.
+- The proxy's default allow-list is widened to reach the asset-upload endpoints those calls need.
+
+## In-repo changes
+
+### Gap 1 — `rf.assets.upload(file)`  ·  `@runflow-io/sdk`
+New `AssetsResource`, wired in `Runflow` constructor (`client.ts:39-42`) as `rf.assets`.
+`upload(file: File | Blob, opts?: { filename?: string; folderId?: string }): Promise<UploadedAsset>`
+lifts `assetService.uploadFile` (`runflow-monorepo/frontend/platform/src/services/api/asset.ts:29`):
+
+1. `POST /v1/asset-uploads` `{ filename, mime_type, size_bytes }` → `{ asset_id, upload_url }`
+2. **raw** `fetch(upload_url, { method:"PUT", headers:{ "Content-Type": mime }, body: file })`
+   — absolute storage URL, must bypass `client.request()` (no base prefix, no `Authorization`).
+3. `POST /v1/asset-uploads/{asset_id}/confirmations` `{ folder_id: opts.folderId ?? null }` → `Asset`.
+
+Returns `{ id, url /* signed https */, ref: "runflow://assets/{id}", name, mimeType, sizeBytes, thumbnailUrl, createdAt }`.
+- 50 MB guard (matches backend `MAX_FILE_SIZE`). Server callers pass a `Blob` + explicit `filename`.
+- `request()` already passes `FormData` through (`client.ts:61`); here we use JSON for steps 1/3 and
+  a direct `fetcher` call for step 2 (add a minimal internal `rawFetch` on the client).
+- Errors surface as `RunflowError` with the failing step + status.
+- New exports: `AssetsResource`, type `UploadedAsset`, from `index.ts`.
+
+### Gap 4 — proxy `allowedPaths`  ·  `@runflow-io/proxy`
+Add `allowedPaths?: ReadonlyArray<AllowedPath>` to `ProxyConfig` (`types.ts:55`):
+```ts
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+interface AllowedPath { method: HttpMethod | HttpMethod[]; path: string; } // path may use :param
+```
+- New `matchAllowedPath()`: **strict, full-path** segment match; `:param` matches exactly one
+  non-empty segment that is not `.`/`..`; method must match. No prefix/wildcard matching.
+- Integrate into the gate at `handler.ts:140`: a request that matches an allowed path is forwarded
+  (still through CSRF + `authenticate` + `rateLimit` + body-cap). It is **not** dispatch, so the
+  model allow-list and `onRun` are untouched.
+- `DEFAULT_ALLOWED_PATHS` (so `rf.assets.upload`/`rf.assets.get` work **zero-config**):
+  `POST /v1/asset-uploads`, `POST /v1/asset-uploads/:id/confirmations`, `GET /v1/assets/:id`.
+  *(Revised in review round 1: a customer `allowedPaths` **replaces** the defaults — same
+  semantics as `allowedModels`; spread the exported `DEFAULT_ALLOWED_PATHS` to extend, pass `[]`
+  to disable. The first draft said "additive", which made the defaults impossible to turn off.)*
+  Built-in dispatch/runs/health stay always-on.
+- **Security (council P0):** the proxy forwards with the org's secret key. Allowing *reads* like
+  `GET /v1/runs` or `GET /v1/billing/balance` exposes org-wide data to any same-origin browser —
+  therefore those are **opt-in only**, never defaulted. SSRF is bounded (upstream host is fixed to
+  `apiBase`); the risk is method/path scope, which strict matching controls. Documented in README +
+  JSDoc with an explicit warning.
+
+### Gap 5 — `composePinPrompt`  ·  `@runflow-io/sdk` (+ de-dupe)
+Export from SDK:
+```ts
+export function pinRegion(pin: { x: number; y: number }): string;        // "upper-left" … "lower-right"
+export function composePinPrompt(pin: { x:number;y:number }, instruction: string): string;
+```
+`pinRegion` = `${y<.33?"upper":y<.66?"middle":"lower"}-${x<.33?"left":x<.66?"center":"right"}`.
+`composePinPrompt` returns the **exact** existing template (behavior-preserving):
+`Edit the ${region} area of this image: ${instruction}. Photoreal product photography, preserve the rest of the image, true colors and lighting.`
+Replace all four copies: `studio/src/lib/runflow.ts:49,150`; `studio/src/tools/index.ts:78`;
+`examples/e2e-proof/run.ts:104` (hardcoded) and `:513` (inline). The "no pin ⇒ center" fallback in
+`runflow.ts:150` stays in the caller.
+
+### Gap 3 — `<StudioShell>` props  ·  `@runflow-io/studio`
+`StudioShell` takes **zero** props today (`StudioShell.tsx:104`). Add four **optional** props,
+preserving the zero-prop default exactly:
+- `tools?` — override/extend the workflow catalogue (defaults to module `WORKFLOWS`).
+- `source?` — initial source image(s) (defaults to `SAMPLES`).
+- `sentinel?` — sentinel config: `{ enabled?, taskDescription?, judges? }` (defaults to current hardcoded call).
+- `copy?` — UI copy overrides (headings/labels/CTA), shallow-merged over defaults.
+`mount()` forwards an optional props arg. Internal `useState` seeds from props once; no behavior
+change when omitted. (Full prop wiring decided against `StudioShell.tsx` during implementation.)
+
+### Gap 7 — brush + mask creation in `./headless`  ·  `@runflow-io/studio`
+Lift the dual-canvas mask logic out of `StudioShell.tsx` (`paintAt`/`updateCoverage`/`clearMask`/
+`generateMaskBlob`) — and the richer `runflow-prototypes/runflow-studio-v2` version — into a
+**framework-agnostic** controller exported from `@runflow-io/studio/headless`:
+```ts
+createMaskController(opts): {
+  attach(visible: HTMLCanvasElement, hidden: HTMLCanvasElement, image: HTMLImageElement): void;
+  setBrushSize(px): void; strokeTo(x,y): void; beginStroke(x,y): void; endStroke(): void;
+  clear(): void; coverage(): number; toBlob(): Promise<Blob | null>; // full-res B&W PNG
+}
+```
+React-free (so forks in any framework reuse it). `StudioShell` refactors to consume it — that
+refactor is the proof it's reusable. `useMaskController` React hook ships from the main entry, not headless.
+
+### E2E proof — the gate  ·  `examples/e2e-proof/run.ts`
+`npm run proof` already runs browser SDK → in-process `@runflow-io/proxy` → **real api.runflow.io**.
+Extend it so the five gaps are proven live (only `RUNFLOW_API_KEY` needed):
+- **New `asset-upload` modality:** `rf.assets.upload(File)` **through the proxy** (proves gap 1 +
+  gap 4 defaults) → feed the returned **https** url to `google/nano-banana-pro/edit` → assert no 422
+  + success. This is the direct repro of Fred's bug, now green.
+- **Replace the R2 side-channel:** the `mask-reference` flow currently needs `R2_*` creds
+  (absent here). Re-upload source/mask/reference via `rf.assets.upload` instead → proof becomes
+  self-sufficient on the API key alone. (`uploads.ts` SigV4 helper retired; `buildSampleMask` kept.)
+- **Gap-4 assertions (in-process):** a non-allowed path still 403s; asset-upload paths pass; a
+  custom `allowedPaths` entry (e.g. `GET /v1/runs`) passes only when configured.
+- **Gap-5:** pin modality + chat-agent section call `composePinPrompt` (shared contract).
+- All existing modalities stay green. Also add proxy/SDK **vitest** unit tests for each new surface.
+
+## Backend contract spec + companion ticket (gaps 2 & 6 — not coded here)
+Deliver `docs/plans/run-384-sdk-gaps/backend-contract.md` + a ready-to-file ticket for
+`runflow-monorepo`:
+- **Gap 2:** resolve `runflow://assets/{uuid}` (and re-sign `{org}/assets|inline/...`) in
+  `body.input`/`metadata` at the **dispatch write path**, before the model worker's media
+  validator — mirroring the existing read-side resolver (`GET /v1/runs`). Makes asset refs
+  first-class so the SDK can eventually return `ref` instead of a TTL-bound signed url.
+- **Gap 6:** reframed — `data:` materialization is **correct** (reads sign to https); the missing
+  piece is the same dispatch-side resolution as gap 2. Recommend that over a `data:` opt-out flag.
+- Until shipped, gap 1 returns signed **https** so forks are unblocked today.
+
+## Cross-cutting
+- **Docs:** README note — the worked-example story today is "consume headless primitives + build
+  UI"; link this repo's `examples/`. Mention `./headless` could later split into a minimal package.
+- **Versioning:** changesets — `@runflow-io/sdk` **minor** (new `rf.assets`, `composePinPrompt`),
+  `@runflow-io/proxy` **minor** (`allowedPaths`), `@runflow-io/studio` **minor** (props + headless
+  mask). (Pre-1.0 minor = 0.0.3 → 0.1.0; flag if patch preferred.)
+- **Quality gates:** `bun run typecheck`, `bun run test`, `bun run lint` (biome), then `npm run proof`
+  live. No `--no-verify`.
+
+## Out of scope
+Backend code in `runflow-monorepo`; model-card doc edits; splitting `./headless` into its own
+package; any change to the model allow-list semantics.
diff --git a/examples/e2e-proof/fixtures.ts b/examples/e2e-proof/fixtures.ts
new file mode 100644
index 0000000..eba0037
--- /dev/null
+++ b/examples/e2e-proof/fixtures.ts
@@ -0,0 +1,76 @@
+/**
+ * Proof fixtures — sample bytes the e2e run uploads through
+ * `rf.assets.upload`. (The previous R2 Sig V4 side-channel lived here;
+ * it's gone now that the SDK's presigned upload flow covers the same
+ * need with only the Runflow API key.)
+ */
+
+import { deflateSync } from "node:zlib";
+
+/**
+ * Download `url` and return its bytes. Used to fetch sample images so
+ * we can re-upload them as Runflow assets the model workers can reach.
+ */
+export async function fetchBytes(url: string): Promise<Buffer> {
+  const r = await fetch(url);
+  if (!r.ok) throw new Error(`fetch ${r.status} for ${url}`);
+  return Buffer.from(await r.arrayBuffer());
+}
+
+/**
+ * Build a 512×512 PNG mask: a white centered rectangle on black. Marks
+ * the central ~45% of the image as the inpaint region, leaving the
+ * borders preserved.
+ */
+export function buildSampleMask(): Buffer {
+  // Minimal PNG encoder for an 8-bit greyscale 512×512 image. Built
+  // inline to avoid a runtime dep — the proof script needs to stay
+  // self-contained.
+  const W = 512;
+  const H = 512;
+  const data = Buffer.alloc(H * (1 + W)); // each row: filter byte + W bytes
+  for (let y = 0; y < H; y++) {
+    data[y * (1 + W)] = 0; // filter: None
+    const inner = y > H * 0.27 && y < H * 0.72;
+    for (let x = 0; x < W; x++) {
+      const px = inner && x > W * 0.27 && x < W * 0.72 ? 0xff : 0x00;
+      data[y * (1 + W) + 1 + x] = px;
+    }
+  }
+
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(W, 0);
+  ihdr.writeUInt32BE(H, 4);
+  ihdr[8] = 8; // bit depth
+  ihdr[9] = 0; // grayscale
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+
+  const idat = deflateSync(data);
+
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", idat),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+function chunk(type: string, data: Buffer): Buffer {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length, 0);
+  const typeBuf = Buffer.from(type, "ascii");
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
+  return Buffer.concat([len, typeBuf, data, crc]);
+}
+
+function crc32(buf: Buffer): number {
+  let c = 0xffffffff;
+  for (const b of buf) {
+    c ^= b;
+    for (let k = 0; k < 8; k++) c = (c >>> 1) ^ (0xedb88320 & -(c & 1));
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
diff --git a/examples/e2e-proof/run.ts b/examples/e2e-proof/run.ts
index 89c23dd..5642dc8 100644
--- a/examples/e2e-proof/run.ts
+++ b/examples/e2e-proof/run.ts
@@ -8,10 +8,10 @@
  * so no HTTP listener is needed. Upstream calls to api.runflow.io are
  * real.
  *
- * Covers one run per modality that doesn't require additional customer
- * infrastructure (uploads / sentinel / chat depend on customer-side
- * services — those modalities are exercised in @runflow-io/sdk's unit
- * tests via mergeToolValues + buildRequest assertions).
+ * Covers one run per modality, file uploads via rf.assets.upload
+ * (through the proxy's default allow-list), the proxy allow-list gate
+ * itself, and the packaged workflows. Only RUNFLOW_API_KEY is needed —
+ * the former R2 side-channel for mask/reference uploads is gone.
  *
  * Loads RUNFLOW_API_KEY (or RUNFLOW_API_TOKEN) from env. Run with:
  *
@@ -24,9 +24,9 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { Runflow, RunFailedError } from "@runflow-io/sdk";
-import { runflowProxy } from "@runflow-io/proxy";
-import { buildSampleMask, fetchBytes, uploadAndPresign } from "./uploads.js";
+import { DEFAULT_ALLOWED_PATHS, runflowProxy } from "@runflow-io/proxy";
+import { RunFailedError, Runflow, composePinPrompt } from "@runflow-io/sdk";
+import { buildSampleMask, fetchBytes } from "./fixtures.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROOF_DIR = resolve(__dirname, "../../.proof");
@@ -38,13 +38,7 @@ const SOURCE_URL =
 
 interface Modality {
   name: string;
-  modality:
-    | "simple"
-    | "prompt"
-    | "color"
-    | "select"
-    | "pin"
-    | "text-to-image";
+  modality: "simple" | "prompt" | "color" | "select" | "pin" | "text-to-image";
   model: string;
   body: Record<string, unknown>;
   /** Some workflows take longer; bump the timeout where needed. */
@@ -98,11 +92,10 @@ const MODALITIES: Modality[] = [
     model: "google/nano-banana-pro/edit",
     body: {
       input: {
-        // The pin builder in @runflow-io/studio's ai-edit tool produces this
-        // exact preamble; we match it here to prove the dispatched body
-        // shape works upstream.
-        prompt:
-          "Edit the upper-center area of this image: remove the price tag. Photoreal product photography, preserve the rest of the image, true colors and lighting.",
+        // composePinPrompt is the same helper @runflow-io/studio's ai-edit
+        // tool uses, so this dispatch proves the shared pin contract works
+        // upstream. {x: 0.5, y: 0.2} → "upper-center".
+        prompt: composePinPrompt({ x: 0.5, y: 0.2 }, "remove the price tag"),
         image_urls: [SOURCE_URL],
       },
     },
@@ -140,9 +133,21 @@ async function main() {
     },
   });
 
+  // Route same-origin proxy calls into the in-process handler — exactly
+  // what a browser does against /api/runflow — while absolute URLs to
+  // other hosts (the presigned storage PUT inside rf.assets.upload) go
+  // out over the real network.
+  const proofFetch: typeof fetch = (input, init) => {
+    const url =
+      typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    if (url.startsWith("http://proof.local/")) {
+      return handler(new Request(input as RequestInfo, init));
+    }
+    return fetch(input as RequestInfo, init);
+  };
   const rf = new Runflow({
     baseUrl: "http://proof.local/api/runflow",
-    fetch: (input, init) => handler(new Request(input as RequestInfo, init)),
+    fetch: proofFetch,
   });
 
   const summary: Array<{
@@ -160,8 +165,6 @@ async function main() {
     const start = Date.now();
     try {
       const dispatched = await rf.models.run(mod.model, mod.body);
-      const enrichedBody = { ...mod.body, client_ref: `e2e-${mod.modality}-${start}` };
-      void enrichedBody;
       const final = await rf.runs.wait(dispatched.id, {
         pollIntervalMs: 2_000,
         timeoutMs: mod.timeoutMs ?? 3 * 60_000,
@@ -217,6 +220,179 @@ async function main() {
     await log("");
   }
 
+  // ── Asset upload — rf.assets.upload through the proxy ───────────────
+  // THE regression test for RUN-384 gaps 1+4: a browser-style file
+  // upload via the SDK's presigned flow (allowed through the proxy by
+  // default), whose signed https URL then feeds google/nano-banana-pro/
+  // edit — the model that 422s on runflow:// refs. Green here means the
+  // external-fork upload path works end to end with no extra plumbing.
+  await log("▶ asset-upload — rf.assets.upload → nano-banana-pro/edit");
+  const upStart = Date.now();
+  try {
+    const srcBytes = await fetchBytes(SOURCE_URL);
+    const file = new File([new Uint8Array(srcBytes)], "proof-source.jpg", { type: "image/jpeg" });
+    const uploaded = await rf.assets.upload(file);
+    if (!uploaded.url.startsWith("https://")) {
+      throw new Error(`expected a signed https url, got ${uploaded.url.slice(0, 60)}`);
+    }
+    if (uploaded.ref !== `runflow://assets/${uploaded.id}`) {
+      throw new Error(`unexpected asset ref ${uploaded.ref}`);
+    }
+    await log(`    uploaded asset ${uploaded.id} (${uploaded.sizeBytes} bytes, signed https url)`);
+    const d = await rf.models.run("google/nano-banana-pro/edit", {
+      input: {
+        prompt: composePinPrompt({ x: 0.5, y: 0.5 }, "remove the price tag"),
+        image_urls: [uploaded.url],
+      },
+    });
+    const r = await rf.runs.wait(d.id, { pollIntervalMs: 2_000, timeoutMs: 5 * 60_000 });
+    const elapsed = +((Date.now() - upStart) / 1000).toFixed(1);
+    const url = extractImage(r.output);
+    await log(`  ✓ SUCCEEDED in ${elapsed}s — ${url}`);
+    await writeFile(
+      resolve(PROOF_DIR, `asset-upload-${d.id}.json`),
+      JSON.stringify(
+        {
+          ok: true,
+          modality: "asset-upload",
+          name: "rf.assets.upload → nano-banana-pro/edit",
+          asset: { id: uploaded.id, ref: uploaded.ref, sizeBytes: uploaded.sizeBytes },
+          runId: d.id,
+          output: { image: url },
+          elapsedSeconds: elapsed,
+          completedAt: new Date().toISOString(),
+        },
+        null,
+        2,
+      ),
+    );
+    summary.push({
+      modality: "asset-upload",
+      name: "rf.assets.upload → nano-banana-pro/edit",
+      ok: true,
+      runId: d.id,
+      output: url ?? undefined,
+      elapsedSeconds: elapsed,
+    });
+  } catch (err) {
+    const elapsed = +((Date.now() - upStart) / 1000).toFixed(1);
+    const msg = err instanceof Error ? err.message : String(err);
+    await log(`  ✗ FAILED in ${elapsed}s — ${msg}`);
+    if (err instanceof RunFailedError) {
+      await log(`    raw: ${JSON.stringify(err.run.error)}`);
+    }
+    summary.push({
+      modality: "asset-upload",
+      name: "rf.assets.upload → nano-banana-pro/edit",
+      ok: false,
+      elapsedSeconds: elapsed,
+      error: msg,
+    });
+  }
+  await log("");
+
+  // ── Proxy allow-list — allowedPaths gate assertions ─────────────────
+  // In-process checks (no model spend) plus one live read: the gate
+  // still hard-403s unknown routes, the default asset-upload rules and
+  // a customer-opted GET /v1/runs forward, and run listing works against
+  // the real API through an opted-in proxy.
+  await log("▶ proxy allow-list — allowedPaths gate assertions");
+  const gateStart = Date.now();
+  try {
+    const denied = await handler(new Request("http://proof.local/api/runflow/v1/secrets"));
+    if (denied.status !== 403) {
+      throw new Error(`expected 403 for /v1/secrets, got ${denied.status}`);
+    }
+
+    const seen: string[] = [];
+    const mockProxy = runflowProxy({
+      apiKey,
+      basePath: "/api/runflow",
+      // Replacement semantics (same as allowedModels): spread the
+      // defaults to extend them with a run-listing read.
+      allowedPaths: [...DEFAULT_ALLOWED_PATHS, { method: "GET", path: "/v1/runs" }],
+      fetch: (async (input: RequestInfo | URL, init?: RequestInit) => {
+        seen.push(new Request(input as RequestInfo, init).url);
+        return new Response(JSON.stringify({ ok: true }), {
+          headers: { "Content-Type": "application/json" },
+        });
+      }) as typeof fetch,
+    });
+    const up = await mockProxy(
+      new Request("http://proof.local/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ filename: "x.png", mime_type: "image/png", size_bytes: 1 }),
+      }),
+    );
+    if (up.status !== 200) throw new Error(`default asset-uploads rule failed: ${up.status}`);
+    const list = await mockProxy(new Request("http://proof.local/api/runflow/v1/runs?limit=1"));
+    if (list.status !== 200) throw new Error(`custom GET /v1/runs rule failed: ${list.status}`);
+    const refused = await mockProxy(
+      new Request("http://proof.local/api/runflow/v1/billing/balance"),
+    );
+    if (refused.status !== 403) throw new Error(`expected 403 for billing, got ${refused.status}`);
+    if (seen.length !== 2) throw new Error(`expected exactly 2 upstream calls, saw ${seen.length}`);
+
+    // A bare custom list REPLACES the defaults — forks can switch the
+    // asset routes off.
+    const optOutProxy = runflowProxy({
+      apiKey,
+      basePath: "/api/runflow",
+      allowedPaths: [],
+      fetch: (async () =>
+        new Response(JSON.stringify({ ok: true }), {
+          headers: { "Content-Type": "application/json" },
+        })) as typeof fetch,
+    });
+    const optedOut = await optOutProxy(
+      new Request("http://proof.local/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      }),
+    );
+    if (optedOut.status !== 403) {
+      throw new Error(`allowedPaths: [] should disable uploads, got ${optedOut.status}`);
+    }
+
+    const liveListProxy = runflowProxy({
+      apiKey,
+      basePath: "/api/runflow",
+      allowedPaths: [...DEFAULT_ALLOWED_PATHS, { method: "GET", path: "/v1/runs" }],
+    });
+    const live = await liveListProxy(new Request("http://proof.local/api/runflow/v1/runs?limit=3"));
+    if (live.status !== 200) {
+      throw new Error(`live GET /v1/runs through the proxy: HTTP ${live.status}`);
+    }
+    const liveBody = (await live.json()) as { items?: unknown[] };
+    if (!Array.isArray(liveBody.items)) {
+      throw new Error("live run listing: no items[] in response");
+    }
+    await log(`    live run listing through allowedPaths: ${liveBody.items.length} runs`);
+
+    const elapsed = +((Date.now() - gateStart) / 1000).toFixed(1);
+    await log(`  ✓ allow-list assertions passed in ${elapsed}s`);
+    summary.push({
+      modality: "proxy-allowlist",
+      name: "allowedPaths gate",
+      ok: true,
+      elapsedSeconds: elapsed,
+    });
+  } catch (err) {
+    const elapsed = +((Date.now() - gateStart) / 1000).toFixed(1);
+    const msg = err instanceof Error ? err.message : String(err);
+    await log(`  ✗ FAILED in ${elapsed}s — ${msg}`);
+    summary.push({
+      modality: "proxy-allowlist",
+      name: "allowedPaths gate",
+      ok: false,
+      elapsedSeconds: elapsed,
+      error: msg,
+    });
+  }
+  await log("");
+
   // ── Package single-output (zalando) ─────────────────────────────────
   // Walks tag-removal → model-removal → background-color in sequence,
   // feeding each step's output into the next. Mirrors the
@@ -273,25 +449,30 @@ async function main() {
   await log("");
 
   // ── Mask + reference (runflow/reference-inpaint) ────────────────────
-  // Mirrors the prototype's mask-ref flow: upload source + mask + ref to
-  // R2 (using the same Sig V4 path /demos/api/upload uses), then dispatch
-  // reference-inpaint with three URLs in the body.
+  // Uploads source + mask + reference as Runflow assets via
+  // rf.assets.upload (through the proxy's default allow-list), then
+  // dispatches reference-inpaint with the three signed URLs.
   await log("▶ mask + reference — reference-inpaint");
   const maskStart = Date.now();
   try {
-    const sessId = `e2e-${maskStart}`;
     const srcBytes = await fetchBytes(SOURCE_URL);
     const refBytes = await fetchBytes(
       // Second prototype sample, used as the reference image.
       "https://v3b.fal.media/files/b/0a991a67/wspXRxZt1H_09O0vv1_88_8c0fd4daa8444042b2df13df274e0f6a.jpg",
     );
     const maskBytes = buildSampleMask();
-    const [imageUrl, maskUrl, referenceUrl] = await Promise.all([
-      uploadAndPresign(`demos/${sessId}/source.jpg`, srcBytes, "image/jpeg"),
-      uploadAndPresign(`demos/${sessId}/mask.png`, maskBytes, "image/png"),
-      uploadAndPresign(`demos/${sessId}/reference.jpg`, refBytes, "image/jpeg"),
-    ]);
-    await log(`    uploaded source + mask + reference to R2`);
+    const [imageUrl, maskUrl, referenceUrl] = (
+      await Promise.all([
+        rf.assets.upload(
+          new File([new Uint8Array(srcBytes)], "source.jpg", { type: "image/jpeg" }),
+        ),
+        rf.assets.upload(new File([new Uint8Array(maskBytes)], "mask.png", { type: "image/png" })),
+        rf.assets.upload(
+          new File([new Uint8Array(refBytes)], "reference.jpg", { type: "image/jpeg" }),
+        ),
+      ])
+    ).map((a) => a.url);
+    await log("    uploaded source + mask + reference via rf.assets.upload");
 
     const dispatched = await rf.models.run("runflow/reference-inpaint", {
       input: {
@@ -301,7 +482,10 @@ async function main() {
         prompt: "match the reference style in the masked area",
       },
     });
-    const final = await rf.runs.wait(dispatched.id, { pollIntervalMs: 2_000, timeoutMs: 5 * 60_000 });
+    const final = await rf.runs.wait(dispatched.id, {
+      pollIntervalMs: 2_000,
+      timeoutMs: 5 * 60_000,
+    });
     const elapsed = +((Date.now() - maskStart) / 1000).toFixed(1);
     const outputUrl = extractImage(final.output);
     await log(`  ✓ SUCCEEDED in ${elapsed}s — ${outputUrl}`);
@@ -313,7 +497,12 @@ async function main() {
           modality: "mask-reference",
           name: "reference-inpaint",
           model: "runflow/reference-inpaint",
-          inputs: { image: imageUrl, mask: maskUrl, reference: referenceUrl, prompt: "match the reference style in the masked area" },
+          inputs: {
+            image: imageUrl,
+            mask: maskUrl,
+            reference: referenceUrl,
+            prompt: "match the reference style in the masked area",
+          },
           runId: dispatched.id,
           output: { image: outputUrl },
           rawOutput: final.output,
@@ -358,8 +547,14 @@ async function main() {
   try {
     const prep = await runChain(rf, SOURCE_URL, [
       { model: "runflow/tag-removal", extra: {} },
-      { model: "runflow/product-isolation", extra: { aspect_ratio: "1:1", resolution: "2K", prompt: "the sneaker" } },
-      { model: "runflow/background-color", extra: { color_red: 255, color_green: 255, color_blue: 255 } },
+      {
+        model: "runflow/product-isolation",
+        extra: { aspect_ratio: "1:1", resolution: "2K", prompt: "the sneaker" },
+      },
+      {
+        model: "runflow/background-color",
+        extra: { color_red: 255, color_green: 255, color_blue: 255 },
+      },
     ]);
     await log(`    prep done → ${prep.outputUrl.slice(0, 80)}…`);
 
@@ -375,7 +570,12 @@ async function main() {
           input: { image_url: prep.outputUrl, aspect_ratio: v.aspect_ratio, resolution: "2K" },
         });
         const r = await rf.runs.wait(d.id, { pollIntervalMs: 2_000, timeoutMs: 5 * 60_000 });
-        return { variant: v.id, ratio: v.aspect_ratio, runId: d.id, output: extractImage(r.output) };
+        return {
+          variant: v.id,
+          ratio: v.aspect_ratio,
+          runId: d.id,
+          output: extractImage(r.output),
+        };
       }),
     );
 
@@ -383,7 +583,7 @@ async function main() {
     await log(`  ✓ SUCCEEDED in ${elapsed}s — 4 variants`);
     for (const v of variantRuns) await log(`    · ${v.variant} (${v.ratio}): ${v.output}`);
     await writeFile(
-      resolve(PROOF_DIR, `package-fanout-omnichannel.json`),
+      resolve(PROOF_DIR, "package-fanout-omnichannel.json"),
       JSON.stringify(
         {
           ok: true,
@@ -432,24 +632,36 @@ async function main() {
       "on a sun-warmed cobblestone street at golden hour, mid-stride pose, low three-quarter angle, soft long shadows, blurred city backdrop, editorial photoreal product photography, true colors and materials preserved";
     const prep = await runChain(rf, SOURCE_URL, [
       { model: "runflow/tag-removal", extra: {} },
-      { model: "runflow/product-isolation", extra: { aspect_ratio: "1:1", resolution: "2K", prompt: "the sneaker" } },
-      { model: "runflow/background-color", extra: { color_red: 255, color_green: 255, color_blue: 255 } },
+      {
+        model: "runflow/product-isolation",
+        extra: { aspect_ratio: "1:1", resolution: "2K", prompt: "the sneaker" },
+      },
+      {
+        model: "runflow/background-color",
+        extra: { color_red: 255, color_green: 255, color_blue: 255 },
+      },
     ]);
-    await log(`    prep done`);
+    await log("    prep done");
     const sceneDispatched = await rf.models.run("google/nano-banana-pro/edit", {
       input: {
         prompt: `Place the subject of this image ${direction}.`,
         image_urls: [prep.outputUrl],
       },
     });
-    const scene = await rf.runs.wait(sceneDispatched.id, { pollIntervalMs: 2_000, timeoutMs: 5 * 60_000 });
+    const scene = await rf.runs.wait(sceneDispatched.id, {
+      pollIntervalMs: 2_000,
+      timeoutMs: 5 * 60_000,
+    });
     const sceneUrl = extractImage(scene.output);
     if (!sceneUrl) throw new Error("ai-scene returned no image");
-    await log(`    creative direction injected, scene generated`);
+    await log("    creative direction injected, scene generated");
     const variantD = await rf.models.run("runflow/smart-resize", {
       input: { image_url: sceneUrl, aspect_ratio: "1:1", resolution: "2K" },
     });
-    const variant = await rf.runs.wait(variantD.id, { pollIntervalMs: 2_000, timeoutMs: 5 * 60_000 });
+    const variant = await rf.runs.wait(variantD.id, {
+      pollIntervalMs: 2_000,
+      timeoutMs: 5 * 60_000,
+    });
     const elapsed = +((Date.now() - cdStart) / 1000).toFixed(1);
     const finalUrl = extractImage(variant.output);
     await log(`  ✓ SUCCEEDED in ${elapsed}s — ${finalUrl}`);
@@ -505,16 +717,16 @@ async function main() {
   const chatStart = Date.now();
   try {
     // Simulate the chat agent's plan: one ai-edit step with pin coords.
-    const planSteps = [{ workflow_id: "ai-edit", description: "Remove the price tag in the upper-left" }];
+    const planSteps = [
+      { workflow_id: "ai-edit", description: "Remove the price tag in the upper-left" },
+    ];
     const pin = { x: 0.25, y: 0.25 };
     const instruction = "remove the price tag";
-    // Build the ai-edit prompt exactly the way @runflow-io/studio's ai-edit
-    // tool does (positional words from normalized coords).
-    const yLabel = pin.y < 0.33 ? "upper" : pin.y < 0.66 ? "middle" : "lower";
-    const xLabel = pin.x < 0.33 ? "left" : pin.x < 0.66 ? "center" : "right";
+    // composePinPrompt is the exact helper @runflow-io/studio's ai-edit
+    // tool uses (positional words from normalized coords).
     const body = {
       input: {
-        prompt: `Edit the ${yLabel}-${xLabel} area of this image: ${instruction}. Photoreal product photography, preserve the rest of the image, true colors and lighting.`,
+        prompt: composePinPrompt(pin, instruction),
         image_urls: [SOURCE_URL],
       },
     };
@@ -583,7 +795,11 @@ async function main() {
         );
         await writeFile(
           resolve(PROOF_DIR, `sentinel-${verdict.evalId}.json`),
-          JSON.stringify({ ok: true, modality: "sentinel", ...verdict, elapsedSeconds: elapsed }, null, 2),
+          JSON.stringify(
+            { ok: true, modality: "sentinel", ...verdict, elapsedSeconds: elapsed },
+            null,
+            2,
+          ),
         );
         summary.push({
           modality: "sentinel",
@@ -608,12 +824,16 @@ async function main() {
       await log("");
     }
   } else {
-    await log("▶ sentinel — skipped (SENTINEL_API_KEY missing or no successful output to evaluate)");
+    await log(
+      "▶ sentinel — skipped (SENTINEL_API_KEY missing or no successful output to evaluate)",
+    );
     await log("");
   }
 
   const ok = summary.every((s) => s.ok);
-  await log(`== summary: ${summary.filter((s) => s.ok).length}/${summary.length} modalities succeeded ==`);
+  await log(
+    `== summary: ${summary.filter((s) => s.ok).length}/${summary.length} modalities succeeded ==`,
+  );
   await writeFile(
     resolve(PROOF_DIR, "summary.json"),
     JSON.stringify({ ok, summary, completedAt: new Date().toISOString() }, null, 2),
@@ -634,7 +854,10 @@ async function runChain(
     const dispatched = await rf.models.run(step.model, {
       input: { image_url: current, ...step.extra },
     });
-    const final = await rf.runs.wait(dispatched.id, { pollIntervalMs: 2_000, timeoutMs: 3 * 60_000 });
+    const final = await rf.runs.wait(dispatched.id, {
+      pollIntervalMs: 2_000,
+      timeoutMs: 3 * 60_000,
+    });
     const url = extractImage(final.output);
     if (!url) throw new Error(`No output URL from ${step.model} run ${dispatched.id}`);
     current = url;
@@ -648,7 +871,13 @@ async function runSentinel(
   apiKey: string,
   inputUrl: string,
   outputUrl: string,
-): Promise<{ evalId: string; state: string; judgesPassed: number; judgesTotal: number; summary?: string }> {
+): Promise<{
+  evalId: string;
+  state: string;
+  judgesPassed: number;
+  judgesTotal: number;
+  summary?: string;
+}> {
   const SENTINEL = "https://sentinel.runflow.io/api/v1";
   const post = await fetch(`${SENTINEL}/evaluate?sync=false`, {
     method: "POST",
@@ -661,11 +890,15 @@ async function runSentinel(
       generated_image_url: outputUrl,
       task_type: "product_photography",
       task_description: "Background removed and replaced with the requested backdrop.",
-      reference_images: [{ url: inputUrl, role: "reference_image", description: "Original source image" }],
+      reference_images: [
+        { url: inputUrl, role: "reference_image", description: "Original source image" },
+      ],
     }),
   });
   if (!post.ok) {
-    throw new Error(`sentinel dispatch ${post.status}: ${await post.text().then((s) => s.slice(0, 200))}`);
+    throw new Error(
+      `sentinel dispatch ${post.status}: ${await post.text().then((s) => s.slice(0, 200))}`,
+    );
   }
   const dispatched = (await post.json()) as { eval_id: string };
   const evalId = dispatched.eval_id;
diff --git a/examples/e2e-proof/uploads.ts b/examples/e2e-proof/uploads.ts
deleted file mode 100644
index 879c9de..0000000
--- a/examples/e2e-proof/uploads.ts
+++ /dev/null
@@ -1,190 +0,0 @@
-/**
- * R2 upload helpers — used by the e2e proof to push the masks /
- * references that file-modality runs need.
- *
- * This is a TypeScript port of the prototype's `lib/r2.mjs` (AWS Sig V4
- * S3-compatible upload + presign). The chain it exercises is the same
- * one `/demos/api/upload` runs in production.
- */
-
-import { createHash, createHmac } from "node:crypto";
-
-function endpoint(): string {
-  if (process.env.R2_ENDPOINT) return process.env.R2_ENDPOINT;
-  const accountId = process.env.R2_ACCOUNT_ID;
-  if (!accountId) return "";
-  const raw = process.env.R2_JURISDICTION || "eu";
-  const jur = raw && raw !== "default" ? `${raw}.` : "";
-  return `https://${accountId}.${jur}r2.cloudflarestorage.com`;
-}
-
-function bucket(): string {
-  return process.env.R2_BUCKET_NAME || process.env.R2_BUCKET || "";
-}
-
-const REGION = "auto";
-
-function hmacSha256(key: Buffer | string, data: string): Buffer {
-  return createHmac("sha256", key).update(data).digest();
-}
-
-function sha256(data: Buffer | string): string {
-  return createHash("sha256").update(data).digest("hex");
-}
-
-function awsUriEncode(s: string): string {
-  return encodeURIComponent(s).replace(
-    /[!'()*]/g,
-    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
-  );
-}
-
-function encodeKeyPath(key: string): string {
-  return key.split("/").map(awsUriEncode).join("/");
-}
-
-/**
- * Upload a Buffer to R2 and return a 30-minute presigned GET URL.
- * Mirrors the prototype's `/demos/api/upload` contract.
- */
-export async function uploadAndPresign(
-  key: string,
-  body: Buffer,
-  contentType: string,
-  expiresInSeconds = 30 * 60,
-): Promise<string> {
-  const accessKey = process.env.R2_ACCESS_KEY_ID || "";
-  const secretKey = process.env.R2_SECRET_ACCESS_KEY || "";
-  const ENDPOINT = endpoint();
-  const BUCKET = bucket();
-  if (!accessKey || !secretKey || !ENDPOINT || !BUCKET) {
-    throw new Error("R2 not configured (missing R2_* env vars).");
-  }
-
-  const now = new Date();
-  const dateStamp = `${now.toISOString().replace(/[-:]/g, "").split(".")[0]}Z`;
-  const shortDate = dateStamp.slice(0, 8);
-  const payloadHash = sha256(body);
-  const host = ENDPOINT.replace("https://", "").replace(`/${BUCKET}`, "");
-  const path = `/${BUCKET}/${key}`;
-
-  // PUT
-  const putHeaders: Record<string, string> = {
-    host,
-    "x-amz-date": dateStamp,
-    "x-amz-content-sha256": payloadHash,
-    "content-type": contentType,
-    "content-length": String(body.length),
-  };
-  const signedHeaderKeys = Object.keys(putHeaders).sort();
-  const signedHeaders = signedHeaderKeys.join(";");
-  const canonicalHeaders = signedHeaderKeys.map((k) => `${k}:${putHeaders[k]}\n`).join("");
-  const canonicalRequest = ["PUT", path, "", canonicalHeaders, signedHeaders, payloadHash].join("\n");
-  const scope = `${shortDate}/${REGION}/s3/aws4_request`;
-  const stringToSign = ["AWS4-HMAC-SHA256", dateStamp, scope, sha256(canonicalRequest)].join("\n");
-  const kDate = hmacSha256(`AWS4${secretKey}`, shortDate);
-  const kRegion = hmacSha256(kDate, REGION);
-  const kService = hmacSha256(kRegion, "s3");
-  const kSigning = hmacSha256(kService, "aws4_request");
-  const signature = hmacSha256(kSigning, stringToSign).toString("hex");
-  const authorization = `AWS4-HMAC-SHA256 Credential=${accessKey}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
-
-  const url = `${ENDPOINT.replace(`/${BUCKET}`, "")}${path}`;
-  const res = await fetch(url, {
-    method: "PUT",
-    headers: { ...putHeaders, authorization },
-    body: new Uint8Array(body) as unknown as BodyInit,
-  });
-  if (!res.ok) throw new Error(`R2 upload ${res.status}: ${await res.text().then((s) => s.slice(0, 200))}`);
-
-  // Presign GET
-  const params: Array<[string, string]> = [
-    ["X-Amz-Algorithm", "AWS4-HMAC-SHA256"],
-    ["X-Amz-Credential", `${accessKey}/${scope}`],
-    ["X-Amz-Date", dateStamp],
-    ["X-Amz-Expires", String(expiresInSeconds)],
-    ["X-Amz-SignedHeaders", "host"],
-  ];
-  params.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  const canonicalQs = params.map(([k, v]) => `${awsUriEncode(k)}=${awsUriEncode(v)}`).join("&");
-  const ch = `host:${host}\n`;
-  const cr = ["GET", `/${BUCKET}/${encodeKeyPath(key)}`, canonicalQs, ch, "host", "UNSIGNED-PAYLOAD"].join("\n");
-  const sts = ["AWS4-HMAC-SHA256", dateStamp, scope, sha256(cr)].join("\n");
-  const sig = hmacSha256(kSigning, sts).toString("hex");
-  return `${ENDPOINT.replace(`/${BUCKET}`, "")}/${BUCKET}/${encodeKeyPath(key)}?${canonicalQs}&X-Amz-Signature=${sig}`;
-}
-
-/**
- * Download `url` and return its bytes. Used to fetch sample images so we
- * can re-upload them to R2 (`runflow/reference-inpaint` requires URLs
- * served from a bucket the model worker can reach without auth headers).
- */
-export async function fetchBytes(url: string): Promise<Buffer> {
-  const r = await fetch(url);
-  if (!r.ok) throw new Error(`fetch ${r.status} for ${url}`);
-  return Buffer.from(await r.arrayBuffer());
-}
-
-/**
- * Build a 512×512 PNG mask: a white centered rectangle on black. Marks
- * the central ~45% of the image as the inpaint region, leaving the
- * borders preserved.
- */
-export function buildSampleMask(): Buffer {
-  // Minimal PNG encoder for an 8-bit greyscale 512×512 image. Built
-  // inline to avoid a runtime dep — the proof script needs to stay
-  // self-contained.
-  const W = 512;
-  const H = 512;
-  const data = Buffer.alloc(H * (1 + W)); // each row: filter byte + W bytes
-  for (let y = 0; y < H; y++) {
-    data[y * (1 + W)] = 0; // filter: None
-    const inner = y > H * 0.27 && y < H * 0.72;
-    for (let x = 0; x < W; x++) {
-      const px = inner && x > W * 0.27 && x < W * 0.72 ? 0xff : 0x00;
-      data[y * (1 + W) + 1 + x] = px;
-    }
-  }
-
-  const ihdr = Buffer.alloc(13);
-  ihdr.writeUInt32BE(W, 0);
-  ihdr.writeUInt32BE(H, 4);
-  ihdr[8] = 8; // bit depth
-  ihdr[9] = 0; // grayscale
-  ihdr[10] = 0;
-  ihdr[11] = 0;
-  ihdr[12] = 0;
-
-  const idatRaw = data;
-  const idat = zlibDeflate(idatRaw);
-
-  return Buffer.concat([
-    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
-    chunk("IHDR", ihdr),
-    chunk("IDAT", idat),
-    chunk("IEND", Buffer.alloc(0)),
-  ]);
-}
-
-function chunk(type: string, data: Buffer): Buffer {
-  const len = Buffer.alloc(4);
-  len.writeUInt32BE(data.length, 0);
-  const typeBuf = Buffer.from(type, "ascii");
-  const crc = Buffer.alloc(4);
-  crc.writeUInt32BE(crc32(Buffer.concat([typeBuf, data])), 0);
-  return Buffer.concat([len, typeBuf, data, crc]);
-}
-
-function crc32(buf: Buffer): number {
-  let c = 0xffffffff;
-  for (const b of buf) {
-    c ^= b;
-    for (let k = 0; k < 8; k++) c = (c >>> 1) ^ (0xedb88320 & -(c & 1));
-  }
-  return (c ^ 0xffffffff) >>> 0;
-}
-
-import { deflateSync } from "node:zlib";
-function zlibDeflate(buf: Buffer): Buffer {
-  return deflateSync(buf);
-}
diff --git a/examples/e2e-proof/workflows.ts b/examples/e2e-proof/workflows.ts
index ef92273..6369058 100644
--- a/examples/e2e-proof/workflows.ts
+++ b/examples/e2e-proof/workflows.ts
@@ -16,8 +16,8 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { Runflow, RunFailedError } from "@runflow-io/sdk";
 import { runflowProxy } from "@runflow-io/proxy";
+import { RunFailedError, Runflow } from "@runflow-io/sdk";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROOF_DIR = resolve(__dirname, "../../.proof");
diff --git a/package.json b/package.json
index f1e12e9..0053742 100644
--- a/package.json
+++ b/package.json
@@ -9,10 +9,7 @@
     "type": "git",
     "url": "https://github.com/runflow-io/runflow-js.git"
   },
-  "workspaces": [
-    "packages/*",
-    "examples/*"
-  ],
+  "workspaces": ["packages/*", "examples/*"],
   "scripts": {
     "build": "cd packages/sdk && bun run build && cd ../proxy && bun run build && cd ../studio && bun run build",
     "test": "bun run --filter='./packages/*' test",
diff --git a/packages/proxy/README.md b/packages/proxy/README.md
index 80619ab..23b831c 100644
--- a/packages/proxy/README.md
+++ b/packages/proxy/README.md
@@ -95,16 +95,52 @@ runflowProxy({
 
 ## Path contract
 
-The proxy accepts only these paths (configurable via `allowedModels`):
+The proxy accepts these paths out of the box:
 
-| Method | Path                              | Purpose          |
-|--------|-----------------------------------|------------------|
-| POST   | `/v1/models/{owner}/{slug…}/runs` | Dispatch a run.  |
-| GET    | `/v1/runs/{uuid}`                 | Poll a run.      |
-| GET    | `/v1/health`                      | Public health.   |
+| Method | Path                                    | Purpose                          |
+|--------|-----------------------------------------|----------------------------------|
+| POST   | `/v1/models/{owner}/{slug…}/runs`       | Dispatch a run.                  |
+| GET    | `/v1/runs/{uuid}`                       | Poll a run.                      |
+| GET    | `/v1/health`                            | Public health.                   |
+| POST   | `/v1/asset-uploads`                     | Create a presigned upload.       |
+| POST   | `/v1/asset-uploads/{id}/confirmations`  | Confirm it (`rf.assets.upload`). |
+| GET    | `/v1/assets/{id}`                       | Re-sign an asset URL (`rf.assets.get`). |
 
 Everything else returns `403 Not allowed`. Run IDs are validated as
-UUIDv4-shape to block path traversal.
+UUIDv4-shape to block path traversal. Dispatch is additionally gated by
+`allowedModels`.
+
+### Extending the allow-list: `allowedPaths`
+
+```ts
+import { DEFAULT_ALLOWED_PATHS, runflowProxy } from "@runflow-io/proxy";
+
+runflowProxy({
+  apiKey: process.env.RUNFLOW_API_KEY!,
+  allowedPaths: [
+    ...DEFAULT_ALLOWED_PATHS, // keep the rf.assets.upload/get routes
+    { method: "GET", path: "/v1/runs" }, // run listing
+    { method: "GET", path: "/v1/billing/balance" }, // billing read
+  ],
+});
+```
+
+Like `allowedModels`, a custom list **replaces** the defaults — spread
+`DEFAULT_ALLOWED_PATHS` (exported) to extend them, as above, or pass
+`[]` to turn the asset routes off entirely. Matching is strict — full
+path, segment by segment, no prefixes or wildcards. A `:param` segment
+matches exactly one non-empty segment and rejects traversal (`.`, `..`,
+percent-encoded forms). `method` takes a string or an array
+(`["GET", "DELETE"]`); the handler also exports `PUT`/`PATCH`/`DELETE`
+for framework route files. Non-GET requests must send
+`Content-Type: application/json` (CSRF gate) even when bodyless, and
+upstream responses are fully buffered — avoid allowing large or binary
+endpoints.
+
+> **Security:** every matched request is forwarded with **your** API
+> key, so an allowed `GET /v1/runs` exposes org-wide run data to any
+> same-origin browser session. Opt into reads deliberately and pair
+> them with `authenticate` + `rateLimit` in production.
 
 ## License
 
diff --git a/packages/proxy/package.json b/packages/proxy/package.json
index 42ea8be..5513a02 100644
--- a/packages/proxy/package.json
+++ b/packages/proxy/package.json
@@ -26,11 +26,7 @@
       "require": "./dist/node.cjs"
     }
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
diff --git a/packages/proxy/src/defaults.ts b/packages/proxy/src/defaults.ts
index 0c9cf7c..b3799f9 100644
--- a/packages/proxy/src/defaults.ts
+++ b/packages/proxy/src/defaults.ts
@@ -23,6 +23,26 @@ export const DEFAULT_ALLOWED_MODELS: ReadonlyArray<string> = [
   "topaz/upscale/image",
 ];
 
+import type { AllowedPath } from "./types.js";
+
+/**
+ * Extra upstream routes the proxy forwards out of the box: the
+ * presigned-upload pair `rf.assets.upload(file)` calls, plus the
+ * single-asset read `rf.assets.get(id)` uses to re-sign an expired
+ * asset URL. Like `allowedModels`, a customer-supplied `allowedPaths`
+ * REPLACES this list — spread `DEFAULT_ALLOWED_PATHS` to extend it, or
+ * pass `[]` to turn these routes off entirely.
+ *
+ * Deliberately NOT here: `GET /v1/runs` (org-wide run listing),
+ * billing reads, account info. Those expose org data through the
+ * proxy's API key and must be opted into explicitly.
+ */
+export const DEFAULT_ALLOWED_PATHS: ReadonlyArray<AllowedPath> = [
+  { method: "POST", path: "/v1/asset-uploads" },
+  { method: "POST", path: "/v1/asset-uploads/:id/confirmations" },
+  { method: "GET", path: "/v1/assets/:id" },
+];
+
 export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 export const DEFAULT_RUNFLOW_BASE = "https://api.runflow.io";
diff --git a/packages/proxy/src/handler.ts b/packages/proxy/src/handler.ts
index fd3f992..d5ccd5e 100644
--- a/packages/proxy/src/handler.ts
+++ b/packages/proxy/src/handler.ts
@@ -1,5 +1,6 @@
 import {
   DEFAULT_ALLOWED_MODELS,
+  DEFAULT_ALLOWED_PATHS,
   DEFAULT_BASE_PATH,
   DEFAULT_MAX_BODY_BYTES,
   DEFAULT_RUNFLOW_BASE,
@@ -7,6 +8,7 @@ import {
   UUID_RE,
 } from "./defaults.js";
 import type {
+  AllowedPath,
   AuthResult,
   OnRunArgs,
   ProxyConfig,
@@ -25,6 +27,7 @@ interface NormalizedConfig {
   upstreamTimeoutMs: number;
   fetcher: typeof fetch;
   allowedModelsFor: (auth: AuthResult | null) => ReadonlyArray<string>;
+  allowedPaths: ReadonlyArray<AllowedPath>;
   allowedOrigins: ReadonlyArray<string> | "same-origin" | false;
   requireJsonContentType: boolean;
   authenticate?: ProxyConfig["authenticate"];
@@ -39,7 +42,7 @@ function normalize(cfg: ProxyConfig): NormalizedConfig {
   }
   const allowed = cfg.allowedModels ?? DEFAULT_ALLOWED_MODELS;
   const allowedModelsFor =
-    typeof allowed === "function" ? allowed : (() => allowed as ReadonlyArray<string>);
+    typeof allowed === "function" ? allowed : () => allowed as ReadonlyArray<string>;
   return {
     apiKey: cfg.apiKey,
     basePath: stripTrailing(cfg.basePath ?? DEFAULT_BASE_PATH),
@@ -48,6 +51,7 @@ function normalize(cfg: ProxyConfig): NormalizedConfig {
     upstreamTimeoutMs: cfg.upstreamTimeoutMs ?? DEFAULT_UPSTREAM_TIMEOUT_MS,
     fetcher: cfg.fetch ?? globalThis.fetch,
     allowedModelsFor,
+    allowedPaths: cfg.allowedPaths ?? DEFAULT_ALLOWED_PATHS,
     allowedOrigins: cfg.allowedOrigins ?? "same-origin",
     requireJsonContentType: cfg.requireJsonContentType ?? true,
     authenticate: cfg.authenticate,
@@ -67,10 +71,7 @@ function normalize(cfg: ProxyConfig): NormalizedConfig {
  * header. `false` opts out entirely (not recommended). An explicit
  * array of origins is matched case-insensitively on scheme + host + port.
  */
-function originAllowed(
-  req: Request,
-  policy: NormalizedConfig["allowedOrigins"],
-): boolean {
+function originAllowed(req: Request, policy: NormalizedConfig["allowedOrigins"]): boolean {
   if (policy === false) return true;
   const origin = req.headers.get("origin");
   if (!origin) {
@@ -123,10 +124,19 @@ function jsonContentTypeOK(req: Request): boolean {
 export function runflowProxy(cfg: ProxyConfig): ProxyHandler & {
   GET: ProxyHandler;
   POST: ProxyHandler;
+  PUT: ProxyHandler;
+  PATCH: ProxyHandler;
+  DELETE: ProxyHandler;
 } {
   const c = normalize(cfg);
   const handler: ProxyHandler = async (req) => handle(c, req);
-  return Object.assign(handler, { GET: handler, POST: handler });
+  return Object.assign(handler, {
+    GET: handler,
+    POST: handler,
+    PUT: handler,
+    PATCH: handler,
+    DELETE: handler,
+  });
 }
 
 async function handle(c: NormalizedConfig, req: Request): Promise<Response> {
@@ -135,20 +145,46 @@ async function handle(c: NormalizedConfig, req: Request): Promise<Response> {
   const segments = upstreamPath.split("/").filter(Boolean);
   const { isDispatch, model, runId } = classify(req.method, segments);
   const isHealth =
-    req.method === "GET" && segments.length === 2 && segments[0] === "v1" && segments[1] === "health";
+    req.method === "GET" &&
+    segments.length === 2 &&
+    segments[0] === "v1" &&
+    segments[1] === "health";
 
-  if (!isDispatch && !runId && !isHealth) {
-    return json({ error: "Not allowed" }, 403);
+  // Empty segments (`//`, trailing `/`) would make the matched path
+  // differ from the forwarded one — refuse to match them at all.
+  const hasEmptySegments = /\/\//.test(upstreamPath) || upstreamPath.endsWith("/");
+  const isAllowedPath =
+    !isDispatch &&
+    !runId &&
+    !isHealth &&
+    !hasEmptySegments &&
+    matchAllowedPath(req.method, segments, c.allowedPaths);
+
+  if (!isDispatch && !runId && !isHealth && !isAllowedPath) {
+    return json(
+      {
+        error: `Path not allowed: ${req.method} /${upstreamPath.slice(0, 120)}. The proxy forwards model dispatch, run polling, health, and the asset upload/read routes by default; add other upstream routes via the allowedPaths option.`,
+        code: "path_not_allowed",
+      },
+      403,
+    );
   }
 
   // CSRF gate — must run before any authenticate hook so a malicious
   // page can't drain cookie credentials into the customer's API key.
   if (req.method !== "GET" && req.method !== "HEAD") {
     if (!originAllowed(req, c.allowedOrigins)) {
-      return json({ error: "Origin not allowed" }, 403);
+      return json({ error: "Origin not allowed", code: "origin_not_allowed" }, 403);
     }
     if (c.requireJsonContentType && !jsonContentTypeOK(req)) {
-      return json({ error: "Content-Type must be application/json" }, 415);
+      return json(
+        {
+          error:
+            "Content-Type must be application/json (CSRF defense — required on every non-GET request through the proxy, including bodyless DELETEs)",
+          code: "json_content_type_required",
+        },
+        415,
+      );
     }
   }
 
@@ -168,7 +204,10 @@ async function handle(c: NormalizedConfig, req: Request): Promise<Response> {
   if (isDispatch && model) {
     const allowed = c.allowedModelsFor(auth);
     if (!allowed.includes(model)) {
-      return json({ error: "Model not allowed" }, 403);
+      return json(
+        { error: `Model not allowed: ${model.slice(0, 120)}`, code: "model_not_allowed" },
+        403,
+      );
     }
   }
 
@@ -274,6 +313,53 @@ async function handle(c: NormalizedConfig, req: Request): Promise<Response> {
   });
 }
 
+/**
+ * Strict allow-list matcher for configured extra routes. Full-path,
+ * segment-by-segment comparison — no prefixes, no wildcards. A `:param`
+ * rule segment accepts exactly one non-empty path segment, rejecting
+ * `.`/`..` (and their percent-encoded forms) so a matched path can't
+ * traverse to a different upstream route.
+ */
+function matchAllowedPath(
+  method: string,
+  segments: string[],
+  rules: ReadonlyArray<AllowedPath>,
+): boolean {
+  for (const rule of rules) {
+    const methods = Array.isArray(rule.method) ? rule.method : [rule.method];
+    if (!methods.includes(method)) continue;
+    const ruleSegments = rule.path.split("/").filter(Boolean);
+    if (ruleSegments.length !== segments.length) continue;
+    let matched = true;
+    for (let i = 0; i < ruleSegments.length; i++) {
+      const ruleSegment = ruleSegments[i] ?? "";
+      const pathSegment = segments[i] ?? "";
+      if (ruleSegment.startsWith(":")) {
+        if (!isSafeParamSegment(pathSegment)) {
+          matched = false;
+          break;
+        }
+      } else if (ruleSegment !== pathSegment) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) return true;
+  }
+  return false;
+}
+
+function isSafeParamSegment(segment: string): boolean {
+  if (!segment) return false;
+  let decoded = segment;
+  try {
+    decoded = decodeURIComponent(segment);
+  } catch {
+    return false;
+  }
+  return decoded !== "." && decoded !== ".." && !decoded.includes("/") && !decoded.includes("\\");
+}
+
 function classify(
   method: string,
   segments: string[],
@@ -339,7 +425,11 @@ async function readBoundedBody(req: Request, max: number): Promise<string> {
   return new TextDecoder().decode(merged);
 }
 
-function json(payload: unknown, status: number, extraHeaders: Record<string, string> = {}): Response {
+function json(
+  payload: unknown,
+  status: number,
+  extraHeaders: Record<string, string> = {},
+): Response {
   return new Response(JSON.stringify(payload), {
     status,
     headers: { "Content-Type": "application/json", ...extraHeaders },
diff --git a/packages/proxy/src/index.ts b/packages/proxy/src/index.ts
index e4ceb3a..5746ba6 100644
--- a/packages/proxy/src/index.ts
+++ b/packages/proxy/src/index.ts
@@ -16,6 +16,8 @@
 export { runflowProxy, type ProxyHandler } from "./handler.js";
 export type {
   ProxyConfig,
+  AllowedPath,
+  AllowedPathMethod,
   AuthResult,
   AuthContext,
   ProxyRequestContext,
@@ -26,6 +28,7 @@ export type {
 } from "./types.js";
 export {
   DEFAULT_ALLOWED_MODELS,
+  DEFAULT_ALLOWED_PATHS,
   DEFAULT_BASE_PATH,
   DEFAULT_RUNFLOW_BASE,
   DEFAULT_MAX_BODY_BYTES,
diff --git a/packages/proxy/src/node.ts b/packages/proxy/src/node.ts
index 8238208..62e1e9f 100644
--- a/packages/proxy/src/node.ts
+++ b/packages/proxy/src/node.ts
@@ -65,7 +65,8 @@ function toHeaders(h: IncomingMessage["headers"]): Headers {
 
 async function collectBody(req: IncomingMessage): Promise<Uint8Array> {
   const chunks: Buffer[] = [];
-  for await (const chunk of req) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  for await (const chunk of req)
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
   return Buffer.concat(chunks);
 }
 
diff --git a/packages/proxy/src/types.ts b/packages/proxy/src/types.ts
index e57d487..8256ebe 100644
--- a/packages/proxy/src/types.ts
+++ b/packages/proxy/src/types.ts
@@ -23,7 +23,7 @@ export interface RateLimitDeniedResult {
 export interface RateLimitAllowedResult {
   status: 0;
 }
-export type RateLimitResult = RateLimitDeniedResult | RateLimitAllowedResult | void;
+export type RateLimitResult = RateLimitDeniedResult | RateLimitAllowedResult | undefined;
 
 export interface ProxyRequestContext {
   method: string;
@@ -52,6 +52,25 @@ export interface OnRunArgs extends ProxyRequestContext {
   upstreamStatus: number;
 }
 
+export type AllowedPathMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/**
+ * One extra upstream route the proxy may forward beyond its built-ins
+ * (dispatch, run polling, health).
+ *
+ * `path` is matched against the upstream path (after `basePath` is
+ * stripped) segment by segment — full match only, no prefixes or
+ * wildcards. A `:param` segment matches exactly one non-empty segment;
+ * traversal segments (`.`, `..`, including percent-encoded forms) never
+ * match.
+ */
+export interface AllowedPath {
+  /** HTTP method(s) this rule applies to. */
+  method: AllowedPathMethod | ReadonlyArray<AllowedPathMethod>;
+  /** Upstream path pattern, e.g. `"/v1/asset-uploads/:id/confirmations"`. */
+  path: string;
+}
+
 export interface ProxyConfig {
   /** Runflow API key — required. Sent as `Authorization: Bearer <key>`. */
   apiKey: string;
@@ -63,6 +82,32 @@ export interface ProxyConfig {
    */
   allowedModels?: ReadonlyArray<string> | ((auth: AuthResult | null) => ReadonlyArray<string>);
 
+  /**
+   * Extra upstream routes to forward beyond the always-on built-ins
+   * (dispatch, run polling, health). Like `allowedModels`, passing a
+   * list REPLACES the defaults (`DEFAULT_ALLOWED_PATHS`: the asset
+   * upload pair + `GET /v1/assets/:id`, what `rf.assets.upload`/`get`
+   * need). Spread the exported defaults to extend them:
+   *
+   * ```ts
+   * allowedPaths: [...DEFAULT_ALLOWED_PATHS, { method: "GET", path: "/v1/runs" }]
+   * ```
+   *
+   * Pass `[]` to disable the asset routes entirely.
+   *
+   * SECURITY: every request that matches is forwarded with YOUR API key,
+   * so an allowed GET exposes that data to any same-origin browser
+   * session (the default upload routes included — pair the proxy with
+   * `authenticate` + `rateLimit` in production). Only allow reads like
+   * `GET /v1/runs` or `GET /v1/billing/balance` deliberately.
+   *
+   * Notes: upstream responses are fully buffered (no streaming) — avoid
+   * allowing large/binary endpoints; non-GET requests must send
+   * `Content-Type: application/json` (CSRF gate), including bodyless
+   * DELETE/PATCH/PUT.
+   */
+  allowedPaths?: ReadonlyArray<AllowedPath>;
+
   /**
    * The URL prefix the proxy is mounted at. Stripped from incoming
    * paths before forwarding. Default: `/api/runflow`.
diff --git a/packages/proxy/tests/allowed-paths.test.ts b/packages/proxy/tests/allowed-paths.test.ts
new file mode 100644
index 0000000..21d8eb7
--- /dev/null
+++ b/packages/proxy/tests/allowed-paths.test.ts
@@ -0,0 +1,256 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_ALLOWED_PATHS, runflowProxy } from "../src/index.js";
+import type { ProxyConfig } from "../src/index.js";
+
+function mockUpstream(handler: (req: Request) => Response | Promise<Response>): typeof fetch {
+  return ((input: RequestInfo | URL, init?: RequestInit) => {
+    const req = new Request(input as string, init);
+    return Promise.resolve(handler(req));
+  }) as typeof fetch;
+}
+
+const KEY = "rf_live_test";
+const UUID = "11111111-2222-3333-4444-555555555555";
+
+function spyProxy(extra?: Partial<ProxyConfig>) {
+  const seen: Array<{ method: string; url: string; auth: string | null }> = [];
+  const proxy = runflowProxy({
+    apiKey: KEY,
+    fetch: mockUpstream((req) => {
+      seen.push({
+        method: req.method,
+        url: req.url,
+        auth: req.headers.get("authorization"),
+      });
+      return new Response(JSON.stringify({ ok: true }), {
+        headers: { "Content-Type": "application/json" },
+      });
+    }),
+    ...extra,
+  });
+  return { proxy, seen };
+}
+
+describe("allowedPaths — defaults (asset uploads)", () => {
+  it("forwards POST /v1/asset-uploads with bearer auth", async () => {
+    const { proxy, seen } = spyProxy();
+    const res = await proxy(
+      new Request("http://app/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ filename: "a.png", mime_type: "image/png", size_bytes: 3 }),
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(seen[0]?.auth).toBe(`Bearer ${KEY}`);
+    expect(seen[0]?.url).toBe("https://api.runflow.io/v1/asset-uploads");
+  });
+
+  it("forwards GET /v1/assets/{id} (rf.assets.get re-signing)", async () => {
+    const { proxy, seen } = spyProxy();
+    const res = await proxy(new Request(`http://app/api/runflow/v1/assets/${UUID}`));
+    expect(res.status).toBe(200);
+    expect(seen[0]?.url).toBe(`https://api.runflow.io/v1/assets/${UUID}`);
+  });
+
+  it("rejects a trailing slash on allow-list matches", async () => {
+    const { proxy, seen } = spyProxy();
+    const res = await proxy(new Request(`http://app/api/runflow/v1/assets/${UUID}/`));
+    expect(res.status).toBe(403);
+    expect(seen.length).toBe(0);
+  });
+
+  it("rejects empty path segments so matching always equals forwarding", async () => {
+    const { proxy, seen } = spyProxy();
+    const res = await proxy(
+      new Request("http://app/api/runflow/v1//asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(403);
+    expect(seen.length).toBe(0);
+  });
+
+  it("403 body carries an actionable message + machine code", async () => {
+    const { proxy } = spyProxy();
+    const res = await proxy(new Request("http://app/api/runflow/v1/secrets"));
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: string; code: string };
+    expect(body.code).toBe("path_not_allowed");
+    expect(body.error).toContain("GET /v1/secrets");
+    expect(body.error).toContain("allowedPaths");
+  });
+
+  it("forwards POST /v1/asset-uploads/{id}/confirmations", async () => {
+    const { proxy, seen } = spyProxy();
+    const res = await proxy(
+      new Request(`http://app/api/runflow/v1/asset-uploads/${UUID}/confirmations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ folder_id: null }),
+      }),
+    );
+    expect(res.status).toBe(200);
+    expect(seen[0]?.url).toBe(`https://api.runflow.io/v1/asset-uploads/${UUID}/confirmations`);
+  });
+
+  it("does NOT forward other methods or shapes on the same prefix", async () => {
+    const { proxy, seen } = spyProxy();
+    for (const req of [
+      new Request("http://app/api/runflow/v1/asset-uploads"), // GET
+      new Request("http://app/api/runflow/v1/asset-uploads/x/y/z", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      }),
+      new Request(`http://app/api/runflow/v1/asset-uploads/${UUID}/confirmations/extra`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      }),
+    ]) {
+      const res = await proxy(req);
+      expect(res.status).toBe(403);
+    }
+    expect(seen.length).toBe(0);
+  });
+
+  it("rejects traversal in :param segments, including percent-encoded", async () => {
+    const { proxy, seen } = spyProxy();
+    for (const id of ["..", ".", "%2e%2e", "%2E%2E", "a%2Fb", "a%5Cb"]) {
+      const res = await proxy(
+        new Request(`http://app/api/runflow/v1/asset-uploads/${id}/confirmations`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: "{}",
+        }),
+      );
+      expect(res.status, `id=${id}`).toBe(403);
+    }
+    expect(seen.length).toBe(0);
+  });
+});
+
+describe("allowedPaths — custom rules", () => {
+  it("forwards an opted-in GET /v1/runs listing", async () => {
+    const { proxy, seen } = spyProxy({ allowedPaths: [{ method: "GET", path: "/v1/runs" }] });
+    const res = await proxy(new Request("http://app/api/runflow/v1/runs?limit=5"));
+    expect(res.status).toBe(200);
+    expect(seen[0]?.url).toBe("https://api.runflow.io/v1/runs?limit=5");
+  });
+
+  it("still 403s routes outside the configured set", async () => {
+    const { proxy } = spyProxy({ allowedPaths: [{ method: "GET", path: "/v1/runs" }] });
+    expect((await proxy(new Request("http://app/api/runflow/v1/billing/balance"))).status).toBe(
+      403,
+    );
+    expect((await proxy(new Request("http://app/api/runflow/v1/api-keys"))).status).toBe(403);
+    expect(
+      (await proxy(new Request("http://app/api/runflow/v1/runs", { method: "DELETE" }))).status,
+    ).toBe(403);
+  });
+
+  it("accepts method arrays and :param patterns", async () => {
+    const { proxy, seen } = spyProxy({
+      allowedPaths: [{ method: ["GET", "DELETE"], path: "/v1/assets/:id" }],
+    });
+    expect((await proxy(new Request(`http://app/api/runflow/v1/assets/${UUID}`))).status).toBe(200);
+    const del = await proxy(
+      new Request(`http://app/api/runflow/v1/assets/${UUID}`, {
+        method: "DELETE",
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    expect(del.status).toBe(200);
+    expect(seen.map((s) => s.method)).toEqual(["GET", "DELETE"]);
+  });
+
+  it("custom rules REPLACE the defaults (same semantics as allowedModels)", async () => {
+    const { proxy } = spyProxy({ allowedPaths: [{ method: "GET", path: "/v1/runs" }] });
+    const res = await proxy(
+      new Request("http://app/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(403);
+  });
+
+  it("spreading DEFAULT_ALLOWED_PATHS extends instead of replacing", async () => {
+    const { proxy } = spyProxy({
+      allowedPaths: [...DEFAULT_ALLOWED_PATHS, { method: "GET", path: "/v1/runs" }],
+    });
+    const upload = await proxy(
+      new Request("http://app/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(upload.status).toBe(200);
+    const list = await proxy(new Request("http://app/api/runflow/v1/runs?limit=1"));
+    expect(list.status).toBe(200);
+  });
+
+  it("allowedPaths: [] disables the default asset routes entirely", async () => {
+    const { proxy, seen } = spyProxy({ allowedPaths: [] });
+    const res = await proxy(
+      new Request("http://app/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(403);
+    // Built-ins are unaffected by the path allow-list.
+    const health = await proxy(new Request("http://app/api/runflow/v1/health"));
+    expect(health.status).toBe(200);
+    expect(seen.length).toBe(1);
+  });
+});
+
+describe("allowedPaths — existing gates still apply", () => {
+  it("CSRF origin check still rejects cross-origin POSTs to allowed paths", async () => {
+    const { proxy, seen } = spyProxy();
+    const res = await proxy(
+      new Request("http://app/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Origin: "https://evil.example",
+          Host: "app",
+        },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(403);
+    expect(seen.length).toBe(0);
+  });
+
+  it("authenticate hook still gates allowed paths", async () => {
+    const { proxy } = spyProxy({ authenticate: () => null });
+    const res = await proxy(
+      new Request("http://app/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(401);
+  });
+
+  it("content-type gate still applies to allowed POSTs", async () => {
+    const { proxy } = spyProxy();
+    const res = await proxy(
+      new Request("http://app/api/runflow/v1/asset-uploads", {
+        method: "POST",
+        headers: { "Content-Type": "text/plain" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(415);
+  });
+});
diff --git a/packages/proxy/tests/handler.test.ts b/packages/proxy/tests/handler.test.ts
index 5f47949..e8bb624 100644
--- a/packages/proxy/tests/handler.test.ts
+++ b/packages/proxy/tests/handler.test.ts
@@ -55,11 +55,17 @@ describe("runflowProxy — routing", () => {
       }),
     });
     const res = await proxy(
-      new Request("http://app/api/runflow/v1/models/runfl0w/background-removal/runs".replace("runfl0w", "runflow"), {
-        method: "POST",
-        body: JSON.stringify({ input: { image_url: "https://cdn/x.png" } }),
-        headers: { "Content-Type": "application/json" },
-      }),
+      new Request(
+        "http://app/api/runflow/v1/models/runfl0w/background-removal/runs".replace(
+          "runfl0w",
+          "runflow",
+        ),
+        {
+          method: "POST",
+          body: JSON.stringify({ input: { image_url: "https://cdn/x.png" } }),
+          headers: { "Content-Type": "application/json" },
+        },
+      ),
     );
     expect(res.status).toBe(200);
     expect(seenAuth).toBe(`Bearer ${KEY}`);
@@ -73,9 +79,15 @@ describe("runflowProxy — routing", () => {
       apiKey: KEY,
       fetch: mockUpstream(
         (req) =>
-          new Response(JSON.stringify({ id: new URL(req.url).pathname.split("/").pop(), status_code: "succeeded" }), {
-            headers: { "Content-Type": "application/json" },
-          }),
+          new Response(
+            JSON.stringify({
+              id: new URL(req.url).pathname.split("/").pop(),
+              status_code: "succeeded",
+            }),
+            {
+              headers: { "Content-Type": "application/json" },
+            },
+          ),
       ),
     });
     const goodUuid = "11111111-2222-3333-4444-555555555555";
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index c36912d..e30df6b 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -34,6 +34,44 @@ const rf = new Runflow({ baseUrl: "/api/runflow" });
 The browser SDK never sees your API key — it's injected by
 `@runflow-io/proxy` on your server.
 
+### Uploading files
+
+```ts
+const asset = await rf.assets.upload(fileInput.files[0]);
+await rf.models.run("google/nano-banana-pro/edit", {
+  input: { prompt: "remove the price tag", image_urls: [asset.url] },
+});
+```
+
+`upload()` runs the platform's presigned flow (create session → PUT the
+bytes to storage → confirm), retrying transient failures, and returns
+`{ id, url, ref, ... }`. `url` is a short-TTL **signed HTTPS URL** —
+pass it straight to any model's media inputs, but don't persist it:
+store `id` (or the stable `runflow://assets/{id}` `ref`) and re-mint a
+fresh url with `rf.assets.get(id)` when needed. Works in the browser
+through `@runflow-io/proxy` (the upload + asset-read endpoints are on
+its default allow-list). Raw `Blob`s need `{ filename }`; the cap is
+50 MB.
+
+### Pin-based editing
+
+Edit models like `google/nano-banana-pro/edit` have no `pin_x`/`pin_y`
+inputs — the convention is a region phrase baked into the prompt.
+`composePinPrompt` is that convention, shared with the Studio shell:
+
+```ts
+import { composePinPrompt } from "@runflow-io/sdk";
+
+await rf.models.run("google/nano-banana-pro/edit", {
+  input: {
+    // {x,y} are normalized 0..1; thirds map to upper|middle|lower ×
+    // left|center|right ("upper-left" … "lower-right").
+    prompt: composePinPrompt({ x: 0.25, y: 0.2 }, "remove the price tag"),
+    image_urls: [sourceUrl],
+  },
+});
+```
+
 ## Tools
 
 Declarative model bindings with typed inputs, presets, and outputs:
@@ -109,8 +147,14 @@ information for `buildRequest` and the run helpers.
 - `runflow.models.run(model, body)` — dispatch a run. Model id segments
   are URL-encoded; `..`/empty segments are rejected.
 - `runflow.runs.get(id)` / `runflow.runs.poll(id)` / `runflow.runs.wait(id)`
+- `runflow.assets.upload(file, opts?)` — presigned upload (with retry);
+  returns a signed https `url` + stable `runflow://` `ref`.
+- `runflow.assets.get(id)` — re-fetch an asset with a freshly signed `url`.
 - `runflow.tools.run(tool, args)` / `runflow.tools.dispatch(tool, args)`
 - `runflow.health.check()`
+- `pinRegion(pin)` / `composeRegionPrompt(region, instruction)` /
+  `composePinPrompt(pin, instruction)` — the shared pin→region prompt
+  contract.
 
 All return well-typed promises; errors are `RunflowError`,
 `RunFailedError`, or `RunTimeoutError`.
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 943d8ef..fdf6d27 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -21,11 +21,7 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
diff --git a/packages/sdk/src/assets.ts b/packages/sdk/src/assets.ts
new file mode 100644
index 0000000..91e723e
--- /dev/null
+++ b/packages/sdk/src/assets.ts
@@ -0,0 +1,265 @@
+import type { Runflow } from "./client.js";
+import { RunflowError } from "./errors.js";
+
+/**
+ * Pre-flight mirror of the backend's asset-upload cap (the backend stays
+ * authoritative — it re-validates `size_bytes` at session create).
+ */
+const MAX_UPLOAD_BYTES = 52_428_800; // 50 MB
+
+/**
+ * Floor for the storage PUT timeout. The effective default scales with
+ * file size (assumes a ~2 Mbit/s uplink floor) so a 50 MB file on a slow
+ * connection isn't doomed by a fixed cap.
+ */
+const MIN_UPLOAD_TIMEOUT_MS = 120_000;
+const UPLOAD_BYTES_PER_SECOND_FLOOR = 256 * 1024; // ~2 Mbit/s
+
+/**
+ * Transient-failure retry schedule, mirroring the studio shell's upload
+ * path: a flaky network mid-flow (e.g. after the user painted a mask)
+ * shouldn't lose the work. Applies to network errors, timeouts, and 5xx.
+ */
+const RETRY_DELAYS_MS = [250, 750];
+
+/** A confirmed, ready-to-use uploaded asset. */
+export interface UploadedAsset {
+  /** Asset id (uuid). The durable identifier — store THIS, not `url`. */
+  id: string;
+  /**
+   * Short-TTL signed HTTPS URL for the file. Pass it directly to model
+   * inputs (`image_url`, `image_urls`, `mask_url`, …) right away. Do not
+   * persist it — it expires; re-mint a fresh one with `rf.assets.get(id)`
+   * (allowed through the proxy by default).
+   */
+  url: string;
+  /**
+   * Canonical stable reference (`runflow://assets/{id}`). Accepted today by
+   * ComfyUI workflow file inputs; once the API resolves asset refs at model
+   * dispatch (RUN-418), prefer this over the expiring `url`.
+   */
+  ref: string;
+  /** Original filename. */
+  name: string;
+  mimeType: string;
+  sizeBytes: number;
+  thumbnailUrl: string | null;
+  createdAt: string | null;
+}
+
+export interface UploadOptions {
+  /** Required when uploading a raw `Blob`; defaults to `file.name` for `File`s. */
+  filename?: string;
+  /** Optional asset-library folder to file the upload under. */
+  folderId?: string;
+  /**
+   * Timeout for the storage PUT step only (the JSON steps use the
+   * client's `requestTimeoutMs`). Default: scales with file size,
+   * minimum 120 s.
+   */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+interface UploadSession {
+  asset_id: string;
+  upload_url: string;
+}
+
+/**
+ * Raw asset shape from the API (see
+ * docs/plans/run-384-sdk-gaps/backend-contract.md for the contract this
+ * mirrors — `Asset.FullValidator` with `url` signed on confirm/get).
+ */
+interface RawAsset {
+  id: string;
+  name: string;
+  url: string;
+  thumbnail_url?: string | null;
+  mime_type: string;
+  size_bytes: number;
+  created_at?: string | null;
+}
+
+function isTransient(err: unknown): boolean {
+  if (!(err instanceof RunflowError)) return false;
+  if (err.code === "network_error" || err.code === "request_timeout") return true;
+  return (err.status ?? 0) >= 500;
+}
+
+function abortError(): RunflowError {
+  return new RunflowError("assets: aborted by signal", { code: "aborted" });
+}
+
+/** Sleep that wakes up immediately when the signal aborts. */
+function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    }
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+async function withRetry<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+  let lastErr: unknown;
+  for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
+    if (attempt > 0) {
+      if (signal?.aborted) throw abortError();
+      await abortableSleep(RETRY_DELAYS_MS[attempt - 1] ?? 0, signal);
+      if (signal?.aborted) throw abortError();
+    }
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isTransient(err) || signal?.aborted) throw err;
+    }
+  }
+  throw lastErr;
+}
+
+function mapAsset(asset: RawAsset): UploadedAsset {
+  return {
+    id: asset.id,
+    url: asset.url,
+    ref: `runflow://assets/${asset.id}`,
+    name: asset.name,
+    mimeType: asset.mime_type,
+    sizeBytes: asset.size_bytes,
+    thumbnailUrl: asset.thumbnail_url ?? null,
+    createdAt: asset.created_at ?? null,
+  };
+}
+
+/**
+ * Asset uploads — the browser-safe path for getting a local file in front
+ * of a model.
+ *
+ * Mirrors the Runflow platform's own upload flow:
+ *   1. `POST /v1/asset-uploads` — create a presigned upload session
+ *   2. `PUT <upload_url>` — send the bytes straight to storage (no auth)
+ *   3. `POST /v1/asset-uploads/{id}/confirmations` — verify + create the asset
+ *
+ * Steps 1 and 3 go through the configured base (so they work through
+ * `@runflow-io/proxy`, which allows them by default); step 2 goes directly
+ * to the storage host using the presigned URL. Every step retries
+ * transient failures (network/timeout/5xx) twice with backoff.
+ *
+ * @example Browser, through a proxy
+ * ```ts
+ * const rf = new Runflow({ baseUrl: "/api/runflow" });
+ * const asset = await rf.assets.upload(fileInput.files[0]);
+ * await rf.models.run("google/nano-banana-pro/edit", {
+ *   input: { prompt, image_urls: [asset.url] },
+ * });
+ * // Later, if you stored asset.id and the signed url expired:
+ * const fresh = await rf.assets.get(asset.id);
+ * ```
+ */
+export class AssetsResource {
+  constructor(private readonly client: Runflow) {}
+
+  async upload(file: File | Blob, opts: UploadOptions = {}): Promise<UploadedAsset> {
+    const filename =
+      opts.filename ??
+      (typeof File !== "undefined" && file instanceof File ? file.name : undefined);
+    if (!filename) {
+      throw new RunflowError("assets.upload: pass `filename` when uploading a raw Blob", {
+        code: "missing_filename",
+      });
+    }
+    if (file.size > MAX_UPLOAD_BYTES) {
+      throw new RunflowError(
+        `assets.upload: file is ${file.size} bytes; the limit is ${MAX_UPLOAD_BYTES} (50 MB)`,
+        { code: "file_too_large" },
+      );
+    }
+    const mimeType = file.type || "application/octet-stream";
+
+    // 1. Create the presigned upload session.
+    const session = await withRetry(
+      () =>
+        this.client.request<UploadSession>("POST", "/v1/asset-uploads", {
+          body: { filename, mime_type: mimeType, size_bytes: file.size },
+          signal: opts.signal,
+        }),
+      opts.signal,
+    );
+    if (!session?.asset_id || !session.upload_url) {
+      throw new RunflowError("assets.upload: upload session response missing asset_id/upload_url", {
+        code: "bad_upload_session",
+      });
+    }
+    if (!session.upload_url.startsWith("https://")) {
+      throw new RunflowError("assets.upload: refusing non-https upload_url from the API", {
+        code: "insecure_upload_url",
+      });
+    }
+
+    // 2. PUT the bytes to storage. Presigned URL — no auth header, and it
+    // must NOT go through the API base, so this bypasses request(). The
+    // presigned URL stays valid across retries.
+    const putTimeoutMs =
+      opts.timeoutMs ??
+      Math.max(MIN_UPLOAD_TIMEOUT_MS, Math.ceil(file.size / UPLOAD_BYTES_PER_SECOND_FLOOR) * 1000);
+    await withRetry(async () => {
+      const putRes = await this.client.rawFetch(
+        session.upload_url,
+        { method: "PUT", headers: { "Content-Type": mimeType }, body: file, signal: opts.signal },
+        putTimeoutMs,
+      );
+      if (!putRes.ok) {
+        const text = await putRes.text().catch(() => "");
+        throw new RunflowError(
+          `assets.upload: storage PUT failed (HTTP ${putRes.status})${text ? `: ${text.slice(0, 200)}` : ""}`,
+          { status: putRes.status, code: "storage_put_failed" },
+        );
+      }
+    }, opts.signal);
+
+    // 3. Confirm — the backend HEADs the object, creates the asset record,
+    // and returns it with `url` already signed for GET.
+    const asset = await withRetry(
+      () =>
+        this.client.request<RawAsset>(
+          "POST",
+          `/v1/asset-uploads/${encodeURIComponent(session.asset_id)}/confirmations`,
+          { body: { folder_id: opts.folderId ?? null }, signal: opts.signal },
+        ),
+      opts.signal,
+    );
+    if (!asset?.id || !asset.url) {
+      throw new RunflowError("assets.upload: confirmation response missing id/url", {
+        code: "bad_upload_confirmation",
+      });
+    }
+
+    return mapAsset(asset);
+  }
+
+  /**
+   * Fetch an asset by id with a freshly signed `url`. Use this instead of
+   * persisting `UploadedAsset.url`, which expires. Allowed through
+   * `@runflow-io/proxy` by default (`GET /v1/assets/:id`).
+   */
+  async get(id: string, opts: { signal?: AbortSignal } = {}): Promise<UploadedAsset> {
+    if (!id || id.includes("/") || id === "." || id === "..") {
+      throw new RunflowError(`assets.get: invalid asset id ${JSON.stringify(id)}`, {
+        code: "invalid_asset_id",
+      });
+    }
+    const asset = await this.client.request<RawAsset>(
+      "GET",
+      `/v1/assets/${encodeURIComponent(id)}`,
+      { signal: opts.signal },
+    );
+    if (!asset?.id || !asset.url) {
+      throw new RunflowError("assets.get: response missing id/url", { code: "bad_asset_response" });
+    }
+    return mapAsset(asset);
+  }
+}
diff --git a/packages/sdk/src/client.ts b/packages/sdk/src/client.ts
index 106e405..a31f501 100644
--- a/packages/sdk/src/client.ts
+++ b/packages/sdk/src/client.ts
@@ -1,7 +1,8 @@
+import { AssetsResource } from "./assets.js";
 import { RunflowError } from "./errors.js";
-import type { Run, RunDispatched, RunflowConfig, WaitOptions } from "./types.js";
 import { RunFailedError, RunTimeoutError } from "./errors.js";
 import { ToolsResource } from "./tools/run.js";
+import type { Run, RunDispatched, RunflowConfig, WaitOptions } from "./types.js";
 
 const DEFAULT_API_BASE = "https://api.runflow.io";
 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
@@ -19,6 +20,7 @@ export class Runflow {
   readonly runs: RunsResource;
   readonly health: HealthResource;
   readonly tools: ToolsResource;
+  readonly assets: AssetsResource;
 
   constructor(config: RunflowConfig) {
     if (!config.apiKey && !config.baseUrl) {
@@ -32,7 +34,10 @@ export class Runflow {
     }
     this.fetcher = config.fetch ?? globalThis.fetch;
     this.base = stripTrailing(config.baseUrl ?? config.apiBase ?? DEFAULT_API_BASE);
-    this.authHeader = config.apiKey ? `Bearer ${config.apiKey}` : undefined;
+    // In proxy mode (baseUrl) the proxy injects the key server-side — the
+    // browser-side client must never send one, even if a caller passes
+    // both. Matches the documented "baseUrl wins, bearer omitted" contract.
+    this.authHeader = config.apiKey && !config.baseUrl ? `Bearer ${config.apiKey}` : undefined;
     this.extraHeaders = { ...config.headers };
     this.requestTimeoutMs = config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
 
@@ -40,6 +45,53 @@ export class Runflow {
     this.runs = new RunsResource(this);
     this.health = new HealthResource(this);
     this.tools = new ToolsResource(this);
+    this.assets = new AssetsResource(this);
+  }
+
+  /**
+   * Fetch an absolute URL through the configured fetcher — no base-URL
+   * joining, no auth header. Used for presigned storage PUTs, which are
+   * authorized by the URL itself and must not leak the API key.
+   * @internal
+   */
+  async rawFetch(
+    url: string,
+    init: {
+      method?: string;
+      headers?: Record<string, string>;
+      body?: BodyInit;
+      signal?: AbortSignal;
+    },
+    timeoutMs: number = this.requestTimeoutMs,
+  ): Promise<Response> {
+    const controller = mergeAbort(init.signal, timeoutMs);
+    try {
+      return await this.fetcher(url, {
+        method: init.method ?? "GET",
+        headers: init.headers,
+        body: init.body,
+        signal: controller.signal,
+      });
+    } catch (err) {
+      // Presigned URLs carry bearer-like signatures in the query string —
+      // never echo them into error messages.
+      const redacted = redactUrl(url);
+      if (controller.timedOut()) {
+        throw new RunflowError(
+          `Request timed out (${timeoutMs}ms): ${init.method ?? "GET"} ${redacted}`,
+          {
+            code: "request_timeout",
+            cause: err,
+          },
+        );
+      }
+      throw new RunflowError(`Request failed: ${init.method ?? "GET"} ${redacted}`, {
+        code: "network_error",
+        cause: err,
+      });
+    } finally {
+      controller.clear();
+    }
   }
 
   /** @internal */
@@ -72,10 +124,13 @@ export class Runflow {
       res = await this.fetcher(url, { method, headers, body, signal: controller.signal });
     } catch (err) {
       if (controller.timedOut()) {
-        throw new RunflowError(`Request timed out (${this.requestTimeoutMs}ms): ${method} ${path}`, {
-          code: "request_timeout",
-          cause: err,
-        });
+        throw new RunflowError(
+          `Request timed out (${this.requestTimeoutMs}ms): ${method} ${path}`,
+          {
+            code: "request_timeout",
+            cause: err,
+          },
+        );
       }
       throw new RunflowError(`Request failed: ${method} ${path}`, {
         code: "network_error",
@@ -87,16 +142,29 @@ export class Runflow {
 
     if (!res.ok) {
       const text = await res.text().catch(() => "");
-      let parsed: { error?: { message?: string; code?: string }; message?: string } | null = null;
+      // Two error body shapes flow through here: the API's nested
+      // { error: { message, code } } and the proxy's flat
+      // { error: string, code: string }.
+      let parsed: {
+        error?: { message?: string; code?: string } | string;
+        message?: string;
+        code?: string;
+      } | null = null;
       try {
         parsed = text ? JSON.parse(text) : null;
       } catch {
         // body wasn't JSON
       }
-      const msg = parsed?.error?.message ?? parsed?.message ?? text.slice(0, 300) ?? res.statusText;
+      const errField = parsed?.error;
+      const msg =
+        (typeof errField === "string" ? errField : errField?.message) ??
+        parsed?.message ??
+        text.slice(0, 300) ??
+        res.statusText;
+      const code = (typeof errField === "object" ? errField?.code : undefined) ?? parsed?.code;
       throw new RunflowError(`HTTP ${res.status}: ${msg || "request failed"}`, {
         status: res.status,
-        code: parsed?.error?.code,
+        code,
       });
     }
 
@@ -166,7 +234,11 @@ export class RunsResource {
       }
       opts.onPoll?.(run);
       yield run;
-      if (run.status_code === "succeeded" || run.status_code === "failed" || run.status_code === "canceled") {
+      if (
+        run.status_code === "succeeded" ||
+        run.status_code === "failed" ||
+        run.status_code === "canceled"
+      ) {
         return;
       }
       await sleep(interval);
@@ -189,10 +261,11 @@ export class RunsResource {
       throw new RunflowError(`Run ${id} produced no status updates`, { code: "no_status" });
     }
     if (last.status_code === "failed" || last.status_code === "canceled") {
-      throw new RunFailedError(
-        last.error?.message ?? `Run ${id} ${last.status_code}`,
-        { id: last.id, status: last.status_code, error: last.error },
-      );
+      throw new RunFailedError(last.error?.message ?? `Run ${id} ${last.status_code}`, {
+        id: last.id,
+        status: last.status_code,
+        error: last.error,
+      });
     }
     return last;
   }
@@ -210,6 +283,12 @@ function stripTrailing(url: string): string {
   return url.endsWith("/") ? url.slice(0, -1) : url;
 }
 
+/** Drop the query string (where presigned-URL signatures live). */
+function redactUrl(url: string): string {
+  const q = url.indexOf("?");
+  return q === -1 ? url : `${url.slice(0, q)}?…`;
+}
+
 /**
  * Validate + percent-encode a multi-segment model id (`owner/slug`,
  * `owner/slug/subroute`). Each segment must be non-empty and not `.`
@@ -223,9 +302,12 @@ function encodeModelId(model: string): string {
   const parts = model.split("/");
   for (const p of parts) {
     if (p === "" || p === "." || p === "..") {
-      throw new RunflowError(`models.run: invalid model id segment ${JSON.stringify(p)} in ${JSON.stringify(model)}`, {
-        code: "invalid_model_id",
-      });
+      throw new RunflowError(
+        `models.run: invalid model id segment ${JSON.stringify(p)} in ${JSON.stringify(model)}`,
+        {
+          code: "invalid_model_id",
+        },
+      );
     }
   }
   return parts.map(encodeURIComponent).join("/");
diff --git a/packages/sdk/src/errors.ts b/packages/sdk/src/errors.ts
index 3d6b619..fb2aa65 100644
--- a/packages/sdk/src/errors.ts
+++ b/packages/sdk/src/errors.ts
@@ -1,7 +1,32 @@
+/**
+ * Known SDK error codes (open union — backend/proxy codes pass through
+ * verbatim, so any string remains assignable).
+ */
+export type RunflowErrorCode =
+  | "missing_config"
+  | "invalid_api_key"
+  | "request_timeout"
+  | "network_error"
+  | "missing_filename"
+  | "file_too_large"
+  | "bad_upload_session"
+  | "insecure_upload_url"
+  | "storage_put_failed"
+  | "bad_upload_confirmation"
+  | "invalid_asset_id"
+  | "bad_asset_response"
+  | "invalid_model_id"
+  | "invalid_run_id"
+  | "aborted"
+  | "no_status"
+  | "run_failed"
+  | "run_timeout"
+  | (string & {});
+
 export class RunflowError extends Error {
   constructor(
     message: string,
-    readonly opts: { status?: number; code?: string; cause?: unknown } = {},
+    readonly opts: { status?: number; code?: RunflowErrorCode; cause?: unknown } = {},
   ) {
     super(message);
     this.name = "RunflowError";
@@ -12,7 +37,7 @@ export class RunflowError extends Error {
   get status(): number | undefined {
     return this.opts.status;
   }
-  get code(): string | undefined {
+  get code(): RunflowErrorCode | undefined {
     return this.opts.code;
   }
 }
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index c3d9000..81879d1 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -19,11 +19,14 @@
  */
 
 export { Runflow, ModelsResource, RunsResource, HealthResource } from "./client.js";
+export { AssetsResource } from "./assets.js";
+export type { UploadedAsset, UploadOptions } from "./assets.js";
 export {
   RunflowError,
   RunFailedError,
   RunTimeoutError,
 } from "./errors.js";
+export type { RunflowErrorCode } from "./errors.js";
 export type {
   Run,
   RunDispatched,
diff --git a/packages/sdk/src/tools/define.ts b/packages/sdk/src/tools/define.ts
index 51e5e3b..524844b 100644
--- a/packages/sdk/src/tools/define.ts
+++ b/packages/sdk/src/tools/define.ts
@@ -78,10 +78,9 @@ export interface ToolDef<
  *   }),
  * });
  */
-export function defineTool<
-  I extends Record<string, AnyInput>,
-  O extends Record<string, AnyOutput>,
->(def: ToolDef<I, O>): ToolDef<I, O> {
+export function defineTool<I extends Record<string, AnyInput>, O extends Record<string, AnyOutput>>(
+  def: ToolDef<I, O>,
+): ToolDef<I, O> {
   return def;
 }
 
diff --git a/packages/sdk/src/tools/index.ts b/packages/sdk/src/tools/index.ts
index 5d56433..edd8b15 100644
--- a/packages/sdk/src/tools/index.ts
+++ b/packages/sdk/src/tools/index.ts
@@ -1,4 +1,5 @@
 export * from "./inputs.js";
 export * from "./outputs.js";
 export * from "./define.js";
+export * from "./pin.js";
 export * from "./run.js";
diff --git a/packages/sdk/src/tools/inputs.ts b/packages/sdk/src/tools/inputs.ts
index f8470f2..cab20fa 100644
--- a/packages/sdk/src/tools/inputs.ts
+++ b/packages/sdk/src/tools/inputs.ts
@@ -110,8 +110,8 @@ export type RuntimeInputValues<T extends Record<string, AnyInput>> =
       : T[K]["optional"] extends true
         ? never
         : K]: InputValue<T[K]>;
-  } & // optional: source !== "preset" AND optional === true
-  {
+  } & {
+    // optional: source !== "preset" AND optional === true
     [K in keyof T as T[K]["source"] extends "preset"
       ? never
       : T[K]["optional"] extends true
diff --git a/packages/sdk/src/tools/pin.ts b/packages/sdk/src/tools/pin.ts
new file mode 100644
index 0000000..b895e21
--- /dev/null
+++ b/packages/sdk/src/tools/pin.ts
@@ -0,0 +1,63 @@
+/**
+ * Pin → prompt helpers.
+ *
+ * `google/nano-banana-pro/edit` (and the other prompt-driven edit models)
+ * have no `pin_x` / `pin_y` input fields. The convention — used by the
+ * Studio shell's ai-edit tool and expected by the model — is to name the
+ * region in the prompt text: a 3×3 grid of `upper|middle|lower` ×
+ * `left|center|right` phrases derived from normalized pin coordinates.
+ *
+ * These helpers are the single public implementation of that convention,
+ * shared by `@runflow-io/studio` and external forks, so pin-based editing
+ * produces the exact same dispatch body everywhere.
+ */
+
+/** A pin location in normalized image coordinates (0..1 on each axis). */
+export interface PinPoint {
+  /** Horizontal position: 0 = left edge, 1 = right edge. */
+  x: number;
+  /** Vertical position: 0 = top edge, 1 = bottom edge. */
+  y: number;
+}
+
+/**
+ * Map a normalized pin to its region phrase on the 3×3 grid.
+ *
+ * Thirds are split at 0.33 and 0.66 — an exact 0.33 falls into the
+ * middle/center band, an exact 0.66 into the lower/right band:
+ * `{x: 0.1, y: 0.1}` → `"upper-left"`,
+ * `{x: 0.5, y: 0.5}` → `"middle-center"`, `{x: 0.9, y: 0.9}` →
+ * `"lower-right"`.
+ */
+export function pinRegion(pin: PinPoint): string {
+  const yLabel = pin.y < 0.33 ? "upper" : pin.y < 0.66 ? "middle" : "lower";
+  const xLabel = pin.x < 0.33 ? "left" : pin.x < 0.66 ? "center" : "right";
+  return `${yLabel}-${xLabel}`;
+}
+
+/**
+ * Compose the full edit prompt for a named region. This is the exact
+ * template the Studio shell dispatches — kept verbatim so shells, forks,
+ * and the e2e proof share one contract.
+ */
+export function composeRegionPrompt(region: string, instruction: string): string {
+  return `Edit the ${region} area of this image: ${instruction}. Photoreal product photography, preserve the rest of the image, true colors and lighting.`;
+}
+
+/**
+ * Compose the full edit prompt for a pin location.
+ *
+ * @example
+ * ```ts
+ * const body = {
+ *   input: {
+ *     prompt: composePinPrompt({ x: 0.25, y: 0.25 }, "remove the price tag"),
+ *     image_urls: [sourceUrl],
+ *   },
+ * };
+ * await rf.models.run("google/nano-banana-pro/edit", body);
+ * ```
+ */
+export function composePinPrompt(pin: PinPoint, instruction: string): string {
+  return composeRegionPrompt(pinRegion(pin), instruction);
+}
diff --git a/packages/sdk/src/tools/run.ts b/packages/sdk/src/tools/run.ts
index b0f55b9..d0629ea 100644
--- a/packages/sdk/src/tools/run.ts
+++ b/packages/sdk/src/tools/run.ts
@@ -56,12 +56,14 @@ export class ToolsResource {
     const dispatched = await this.client.models.run(tool.model, enriched, { signal: opts.signal });
     const final = await this.client.runs.wait(dispatched.id, opts);
     if (final.status_code !== "succeeded") {
-      throw new RunFailedError(
-        final.error?.message ?? `Run ${final.id} ${final.status_code}`,
-        { id: final.id, status: final.status_code, error: final.error },
-      );
+      throw new RunFailedError(final.error?.message ?? `Run ${final.id} ${final.status_code}`, {
+        id: final.id,
+        status: final.status_code,
+        error: final.error,
+      });
     }
-    const extractor = tool.extractOutput ?? (defaultExtract as unknown as (raw: unknown) => OutputValues<O>);
+    const extractor =
+      tool.extractOutput ?? (defaultExtract as unknown as (raw: unknown) => OutputValues<O>);
     const extracted = extractor(final.output);
     return { runId: final.id, status: "succeeded", output: extracted, raw: final };
   }
diff --git a/packages/sdk/tests/assets.test.ts b/packages/sdk/tests/assets.test.ts
new file mode 100644
index 0000000..136f715
--- /dev/null
+++ b/packages/sdk/tests/assets.test.ts
@@ -0,0 +1,324 @@
+import { describe, expect, it } from "vitest";
+import { Runflow, RunflowError } from "../src/index.js";
+
+function mockFetch(handler: (req: Request) => Response | Promise<Response>): typeof fetch {
+  return ((input: RequestInfo | URL, init?: RequestInit) => {
+    const req = new Request(input as string, init);
+    return Promise.resolve(handler(req));
+  }) as typeof fetch;
+}
+
+const ASSET_ID = "11111111-2222-3333-4444-555555555555";
+const SIGNED_URL = `https://storage.example/org/assets/${ASSET_ID}/photo.png?X-Amz-Signature=abc`;
+
+function uploadBackend(
+  opts: { onPut?: (req: Request) => void; onConfirm?: (body: unknown) => void } = {},
+) {
+  const calls: string[] = [];
+  const fetch = mockFetch(async (req) => {
+    const url = new URL(req.url);
+    calls.push(`${req.method} ${url.host}${url.pathname}`);
+    if (req.method === "POST" && url.pathname.endsWith("/v1/asset-uploads")) {
+      return Response.json(
+        { asset_id: ASSET_ID, upload_url: "https://storage.example/presigned-put?sig=xyz" },
+        { status: 201 },
+      );
+    }
+    if (
+      req.method === "PUT" &&
+      url.host === "storage.example" &&
+      url.pathname === "/presigned-put"
+    ) {
+      opts.onPut?.(req);
+      return new Response(null, { status: 200 });
+    }
+    if (
+      req.method === "POST" &&
+      url.pathname.endsWith(`/v1/asset-uploads/${ASSET_ID}/confirmations`)
+    ) {
+      opts.onConfirm?.(await req.json());
+      return Response.json(
+        {
+          id: ASSET_ID,
+          name: "photo.png",
+          url: SIGNED_URL,
+          thumbnail_url: null,
+          asset_type: "image",
+          mime_type: "image/png",
+          size_bytes: 3,
+          created_at: "2026-06-10T00:00:00Z",
+        },
+        { status: 201 },
+      );
+    }
+    return new Response("not found", { status: 404 });
+  });
+  return { fetch, calls };
+}
+
+describe("rf.assets.upload", () => {
+  it("runs the 3-step presigned flow and returns a signed https url + stable ref", async () => {
+    let putAuth: string | null = "sentinel";
+    let putContentType: string | null = null;
+    let confirmBody: unknown;
+    const backend = uploadBackend({
+      onPut: (req) => {
+        putAuth = req.headers.get("authorization");
+        putContentType = req.headers.get("content-type");
+      },
+      onConfirm: (body) => {
+        confirmBody = body;
+      },
+    });
+    const rf = new Runflow({ apiKey: "rf_live_x", fetch: backend.fetch });
+
+    const asset = await rf.assets.upload(
+      new File([new Uint8Array(3)], "photo.png", { type: "image/png" }),
+    );
+
+    expect(asset.id).toBe(ASSET_ID);
+    expect(asset.url).toBe(SIGNED_URL);
+    expect(asset.url.startsWith("https://")).toBe(true);
+    expect(asset.ref).toBe(`runflow://assets/${ASSET_ID}`);
+    expect(asset.mimeType).toBe("image/png");
+    expect(asset.sizeBytes).toBe(3);
+    // The presigned PUT must not leak the API key — the URL is the auth.
+    expect(putAuth).toBeNull();
+    expect(putContentType).toBe("image/png");
+    expect(confirmBody).toEqual({ folder_id: null });
+    expect(backend.calls).toEqual([
+      "POST api.runflow.io/v1/asset-uploads",
+      "PUT storage.example/presigned-put",
+      `POST api.runflow.io/v1/asset-uploads/${ASSET_ID}/confirmations`,
+    ]);
+  });
+
+  it("works through a proxy base for the API steps while the PUT stays absolute", async () => {
+    const backend = uploadBackend();
+    const rf = new Runflow({
+      baseUrl: "http://app.local/api/runflow",
+      fetch: backend.fetch,
+    });
+    const asset = await rf.assets.upload(new File(["x"], "a.png", { type: "image/png" }));
+    expect(asset.id).toBe(ASSET_ID);
+    expect(backend.calls[0]).toBe("POST app.local/api/runflow/v1/asset-uploads");
+    expect(backend.calls[1]).toBe("PUT storage.example/presigned-put");
+    expect(backend.calls[2]).toBe(
+      `POST app.local/api/runflow/v1/asset-uploads/${ASSET_ID}/confirmations`,
+    );
+  });
+
+  it("uploads a raw Blob when filename is provided, and rejects one without", async () => {
+    const backend = uploadBackend();
+    const rf = new Runflow({ apiKey: "rf_live_x", fetch: backend.fetch });
+    const blob = new Blob([new Uint8Array(2)], { type: "image/png" });
+    await expect(rf.assets.upload(blob)).rejects.toThrow(/filename/);
+    const asset = await rf.assets.upload(blob, { filename: "mask.png" });
+    expect(asset.id).toBe(ASSET_ID);
+  });
+
+  it("passes folderId through to the confirmation", async () => {
+    let confirmBody: unknown;
+    const backend = uploadBackend({
+      onConfirm: (b) => {
+        confirmBody = b;
+      },
+    });
+    const rf = new Runflow({ apiKey: "rf_live_x", fetch: backend.fetch });
+    await rf.assets.upload(new File(["x"], "a.png", { type: "image/png" }), { folderId: "fold_1" });
+    expect(confirmBody).toEqual({ folder_id: "fold_1" });
+  });
+
+  it("rejects files over the 50 MB cap without any network call", async () => {
+    let called = false;
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch(() => {
+        called = true;
+        return new Response("nope");
+      }),
+    });
+    const big = { size: 52_428_801, type: "image/png", name: "big.png" } as File;
+    await expect(rf.assets.upload(big, { filename: "big.png" })).rejects.toThrow(/50 MB/);
+    expect(called).toBe(false);
+  });
+
+  it("surfaces a failed storage PUT with status and code", async () => {
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch((req) => {
+        const url = new URL(req.url);
+        if (req.method === "POST" && url.pathname === "/v1/asset-uploads") {
+          return Response.json({ asset_id: ASSET_ID, upload_url: "https://storage.example/p" });
+        }
+        if (req.method === "PUT") return new Response("denied", { status: 403 });
+        return new Response("not found", { status: 404 });
+      }),
+    });
+    const err = await rf.assets
+      .upload(new File(["x"], "a.png", { type: "image/png" }))
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(RunflowError);
+    expect((err as RunflowError).status).toBe(403);
+    expect((err as RunflowError).message).toMatch(/storage PUT failed/);
+  });
+
+  it("retries transient failures (5xx / network) and then succeeds", async () => {
+    let sessionAttempts = 0;
+    let putAttempts = 0;
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch((req) => {
+        const url = new URL(req.url);
+        if (req.method === "POST" && url.pathname === "/v1/asset-uploads") {
+          sessionAttempts++;
+          if (sessionAttempts === 1) return new Response("oops", { status: 503 });
+          return Response.json({ asset_id: ASSET_ID, upload_url: "https://storage.example/p" });
+        }
+        if (req.method === "PUT") {
+          putAttempts++;
+          if (putAttempts === 1) throw new Error("socket reset");
+          return new Response(null, { status: 200 });
+        }
+        if (url.pathname.endsWith("/confirmations")) {
+          return Response.json({
+            id: ASSET_ID,
+            name: "a.png",
+            url: SIGNED_URL,
+            mime_type: "image/png",
+            size_bytes: 1,
+          });
+        }
+        return new Response("not found", { status: 404 });
+      }),
+    });
+    const asset = await rf.assets.upload(new File(["x"], "a.png", { type: "image/png" }));
+    expect(asset.id).toBe(ASSET_ID);
+    expect(sessionAttempts).toBe(2);
+    expect(putAttempts).toBe(2);
+  });
+
+  it("does not retry deterministic 4xx failures", async () => {
+    let attempts = 0;
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch(() => {
+        attempts++;
+        return new Response(JSON.stringify({ error: { message: "nope" } }), { status: 422 });
+      }),
+    });
+    await expect(rf.assets.upload(new File(["x"], "a.png", { type: "image/png" }))).rejects.toThrow(
+      /422/,
+    );
+    expect(attempts).toBe(1);
+  });
+
+  it("refuses a non-https upload_url", async () => {
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch(() =>
+        Response.json({ asset_id: ASSET_ID, upload_url: "http://storage.example/p" }),
+      ),
+    });
+    await expect(rf.assets.upload(new File(["x"], "a.png", { type: "image/png" }))).rejects.toThrow(
+      /non-https/,
+    );
+  });
+
+  it("never leaks presigned query strings into error messages", async () => {
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch((req) => {
+        const url = new URL(req.url);
+        if (req.method === "POST" && url.pathname === "/v1/asset-uploads") {
+          return Response.json({
+            asset_id: ASSET_ID,
+            upload_url: "https://storage.example/p?X-Amz-Signature=SECRETSIG",
+          });
+        }
+        throw new Error("network down");
+      }),
+    });
+    const err = await rf.assets
+      .upload(new File(["x"], "a.png", { type: "image/png" }))
+      .catch((e: unknown) => e as Error);
+    expect((err as Error).message).not.toContain("SECRETSIG");
+    expect((err as Error).message).not.toContain("X-Amz-Signature");
+  });
+
+  it("assets.get(id) returns a freshly signed asset and validates the id", async () => {
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch((req) => {
+        const url = new URL(req.url);
+        if (req.method === "GET" && url.pathname === `/v1/assets/${ASSET_ID}`) {
+          return Response.json({
+            id: ASSET_ID,
+            name: "photo.png",
+            url: SIGNED_URL,
+            mime_type: "image/png",
+            size_bytes: 3,
+          });
+        }
+        return new Response("not found", { status: 404 });
+      }),
+    });
+    const asset = await rf.assets.get(ASSET_ID);
+    expect(asset.url).toBe(SIGNED_URL);
+    expect(asset.ref).toBe(`runflow://assets/${ASSET_ID}`);
+    await expect(rf.assets.get("../sneaky")).rejects.toThrow(/invalid asset id/);
+  });
+
+  it("abort during retry backoff surfaces an aborted error immediately", async () => {
+    const ac = new AbortController();
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch(() => {
+        // First (and only) attempt fails transiently; abort fires during
+        // the backoff sleep.
+        setTimeout(() => ac.abort(), 5);
+        return new Response("oops", { status: 503 });
+      }),
+    });
+    const started = Date.now();
+    const err = await rf.assets
+      .upload(new File(["x"], "a.png", { type: "image/png" }), { signal: ac.signal })
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(RunflowError);
+    expect((err as RunflowError).code).toBe("aborted");
+    // Must not sit through the full 250ms backoff after the abort.
+    expect(Date.now() - started).toBeLessThan(200);
+  });
+
+  it("surfaces the proxy's flat { error, code } body shape", async () => {
+    const rf = new Runflow({
+      baseUrl: "http://app.local/api/runflow",
+      fetch: mockFetch(
+        () =>
+          new Response(
+            JSON.stringify({ error: "Path not allowed: GET /v1/foo", code: "path_not_allowed" }),
+            {
+              status: 403,
+              headers: { "Content-Type": "application/json" },
+            },
+          ),
+      ),
+    });
+    const err = await rf.assets
+      .get("11111111-2222-3333-4444-555555555555")
+      .catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(RunflowError);
+    expect((err as RunflowError).code).toBe("path_not_allowed");
+    expect((err as RunflowError).message).toContain("Path not allowed");
+  });
+
+  it("rejects a malformed upload-session response", async () => {
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch(() => Response.json({ nope: true })),
+    });
+    await expect(rf.assets.upload(new File(["x"], "a.png", { type: "image/png" }))).rejects.toThrow(
+      /upload session/,
+    );
+  });
+});
diff --git a/packages/sdk/tests/auth-mode.test.ts b/packages/sdk/tests/auth-mode.test.ts
new file mode 100644
index 0000000..5a7a820
--- /dev/null
+++ b/packages/sdk/tests/auth-mode.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { Runflow } from "../src/index.js";
+
+function mockFetch(handler: (req: Request) => Response | Promise<Response>): typeof fetch {
+  return ((input: RequestInfo | URL, init?: RequestInit) => {
+    const req = new Request(input as string, init);
+    return Promise.resolve(handler(req));
+  }) as typeof fetch;
+}
+
+describe("auth mode — apiKey vs baseUrl", () => {
+  it("server mode (apiKey only) sends the bearer header", async () => {
+    let auth: string | null = null;
+    const rf = new Runflow({
+      apiKey: "rf_live_x",
+      fetch: mockFetch((req) => {
+        auth = req.headers.get("authorization");
+        return Response.json({ ok: true });
+      }),
+    });
+    await rf.health.check();
+    expect(auth).toBe("Bearer rf_live_x");
+  });
+
+  it("proxy mode (baseUrl) never sends Authorization — even when apiKey is also passed", async () => {
+    // The documented contract: "If both are set, baseUrl wins — the bearer
+    // header is omitted." The key must not reach the proxy origin.
+    let auth: string | null = "sentinel";
+    const rf = new Runflow({
+      apiKey: "rf_live_should_not_leak",
+      baseUrl: "http://app.local/api/runflow",
+      fetch: mockFetch((req) => {
+        auth = req.headers.get("authorization");
+        return Response.json({ ok: true });
+      }),
+    });
+    await rf.health.check();
+    expect(auth).toBeNull();
+  });
+});
diff --git a/packages/sdk/tests/client.test.ts b/packages/sdk/tests/client.test.ts
index 9d463a9..7d4cf2d 100644
--- a/packages/sdk/tests/client.test.ts
+++ b/packages/sdk/tests/client.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { Runflow, RunflowError, RunFailedError } from "../src/index.js";
+import { RunFailedError, Runflow, RunflowError } from "../src/index.js";
 
 function mockFetch(handler: (req: Request) => Response | Promise<Response>): typeof fetch {
   return ((input: RequestInfo | URL, init?: RequestInit) => {
@@ -95,17 +95,20 @@ describe("models.run + runs.wait", () => {
         );
       }),
     });
-    await expect(rf.runs.wait("run_2", { pollIntervalMs: 1 })).rejects.toBeInstanceOf(RunFailedError);
+    await expect(rf.runs.wait("run_2", { pollIntervalMs: 1 })).rejects.toBeInstanceOf(
+      RunFailedError,
+    );
   });
 
   it("surfaces HTTP errors as RunflowError with status", async () => {
     const rf = new Runflow({
       apiKey: "rf_live_x",
-      fetch: mockFetch(() =>
-        new Response(JSON.stringify({ error: { message: "rate limited" } }), {
-          status: 429,
-          headers: { "Content-Type": "application/json" },
-        }),
+      fetch: mockFetch(
+        () =>
+          new Response(JSON.stringify({ error: { message: "rate limited" } }), {
+            status: 429,
+            headers: { "Content-Type": "application/json" },
+          }),
       ),
     });
     try {
@@ -131,14 +134,14 @@ describe("models.run + runs.get — path encoding", () => {
       }),
     });
     await rf.models.run("space owner/has spaces/runs slug", {});
-    expect(seenUrl).toMatch(
-      /\/v1\/models\/space%20owner\/has%20spaces\/runs%20slug\/runs/,
-    );
+    expect(seenUrl).toMatch(/\/v1\/models\/space%20owner\/has%20spaces\/runs%20slug\/runs/);
   });
 
   it("rejects model id with empty / dot / dot-dot segments", async () => {
     const rf = new Runflow({ apiKey: "rf_live_x", fetch: mockFetch(() => new Response("")) });
-    await expect(rf.models.run("runflow//background-removal", {})).rejects.toThrow(/invalid model id/);
+    await expect(rf.models.run("runflow//background-removal", {})).rejects.toThrow(
+      /invalid model id/,
+    );
     await expect(rf.models.run("runflow/../secret", {})).rejects.toThrow(/invalid model id/);
     await expect(rf.models.run("./foo", {})).rejects.toThrow(/invalid model id/);
   });
@@ -207,8 +210,9 @@ describe("tools.run — type-contract enforcement", () => {
 
 describe("tools.run", () => {
   it("merges presets and runtime args, then extracts output", async () => {
-    const { defineTool, imageInput, textInput, imageOutput, extractFirstImageUrl } =
-      await import("../src/tools/index.js");
+    const { defineTool, imageInput, textInput, imageOutput, extractFirstImageUrl } = await import(
+      "../src/tools/index.js"
+    );
 
     const tool = defineTool({
       id: "scene-test",
diff --git a/packages/sdk/tests/pin.test.ts b/packages/sdk/tests/pin.test.ts
new file mode 100644
index 0000000..665f2e4
--- /dev/null
+++ b/packages/sdk/tests/pin.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { composePinPrompt, composeRegionPrompt, pinRegion } from "../src/tools/pin.js";
+
+describe("pinRegion", () => {
+  it("maps all nine grid regions", () => {
+    expect(pinRegion({ x: 0.1, y: 0.1 })).toBe("upper-left");
+    expect(pinRegion({ x: 0.5, y: 0.1 })).toBe("upper-center");
+    expect(pinRegion({ x: 0.9, y: 0.1 })).toBe("upper-right");
+    expect(pinRegion({ x: 0.1, y: 0.5 })).toBe("middle-left");
+    expect(pinRegion({ x: 0.5, y: 0.5 })).toBe("middle-center");
+    expect(pinRegion({ x: 0.9, y: 0.5 })).toBe("middle-right");
+    expect(pinRegion({ x: 0.1, y: 0.9 })).toBe("lower-left");
+    expect(pinRegion({ x: 0.5, y: 0.9 })).toBe("lower-center");
+    expect(pinRegion({ x: 0.9, y: 0.9 })).toBe("lower-right");
+  });
+
+  it("puts exact band boundaries into the next band (matches the shell's historical behavior)", () => {
+    expect(pinRegion({ x: 0.33, y: 0.33 })).toBe("middle-center");
+    expect(pinRegion({ x: 0.66, y: 0.66 })).toBe("lower-right");
+    expect(pinRegion({ x: 0, y: 0 })).toBe("upper-left");
+    expect(pinRegion({ x: 1, y: 1 })).toBe("lower-right");
+  });
+});
+
+describe("composeRegionPrompt / composePinPrompt", () => {
+  it("produces the verbatim template the studio shell has always dispatched", () => {
+    // This exact string is the contract with google/nano-banana-pro/edit.
+    // If it changes, pin edits behave differently for every consumer.
+    expect(composeRegionPrompt("upper-center", "remove the price tag")).toBe(
+      "Edit the upper-center area of this image: remove the price tag. Photoreal product photography, preserve the rest of the image, true colors and lighting.",
+    );
+  });
+
+  it("composePinPrompt is composeRegionPrompt over pinRegion", () => {
+    const pin = { x: 0.25, y: 0.25 };
+    expect(composePinPrompt(pin, "remove the price tag")).toBe(
+      composeRegionPrompt(pinRegion(pin), "remove the price tag"),
+    );
+    expect(composePinPrompt(pin, "remove the price tag")).toContain("Edit the upper-left area");
+  });
+});
diff --git a/packages/studio/README.md b/packages/studio/README.md
index 935373c..71cd321 100644
--- a/packages/studio/README.md
+++ b/packages/studio/README.md
@@ -23,9 +23,11 @@ export const { GET, POST } = runflowProxy({
 });
 ```
 
-This handler covers the `/v1/models/*/runs` dispatch path and the
-`/v1/runs/{id}` poll path the Studio uses for every workflow run. It
-does NOT cover uploads, chat, image-proxy, or sentinel — see [Companion
+This handler covers the `/v1/models/*/runs` dispatch path, the
+`/v1/runs/{id}` poll path, and the asset-upload/read routes the Studio
+uses for workflow runs and file uploads (`rf.assets.upload` through the
+proxy's default allow-list — no extra upload endpoint needed). It does
+NOT cover chat, image-proxy, or sentinel — see [Companion
 endpoints](#companion-endpoints) below.
 
 ## Browser: mount the Studio
@@ -58,7 +60,9 @@ mount(target: string | HTMLElement, options?: {
     runflowProxy?: string;     // /api/runflow         — dispatch + poll
     runflowDevProxy?: string;  // (off by default)      — unreleased models
     imageProxy?: string;       // /api/runflow/image    — same-origin image fetch
-    upload?: string;           // /api/runflow/upload   — multipart → public URL
+    upload?: string;           // optional legacy multipart endpoint — by default
+                               // uploads use the SDK presigned flow through
+                               // runflowProxy (no extra endpoint needed)
     chat?: string;             // /api/runflow/chat     — chat agent (SSE)
     sentinel?: string;         // /api/runflow/sentinel — sentinel evaluation
   };
@@ -66,12 +70,35 @@ mount(target: string | HTMLElement, options?: {
   theme?: ThemeMode | ThemeOverrides;
   /** Inject the default <style> into <head>. Default: true. */
   injectStyles?: boolean;
+  /** Shell customization — see "Customizing the shell" below. */
+  props?: StudioShellProps;
 }): { unmount(): void };
 ```
 
-That is the entire option surface today. If you need event callbacks,
-custom tool catalogues, the source picker hidden, or `update()` to
-reconfigure at runtime, those are tracked as follow-ups.
+## Customizing the shell
+
+`<StudioShell>` (and `mount()`'s `props` option) takes four optional
+props; zero props renders the stock studio.
+
+```tsx
+import { StudioShell } from "@runflow-io/studio";
+import { WORKFLOWS } from "@runflow-io/studio/headless";
+
+<StudioShell
+  // The workflow catalogue (Workflow[], not the SDK's ToolDefs):
+  // cards, chat-agent tools, package steps.
+  tools={WORKFLOWS.filter((w) => w.group === "cleanup")}
+  // A starting image URL, or SampleAsset[] to replace the samples.
+  source="https://cdn.example/listing.jpg"
+  // Disable quality evals, or re-template their task description.
+  sentinel={{ enabled: false }}
+  // Brand + labels, shallow-merged over the defaults.
+  copy={{ brandName: "Estates Studio", brandTag: "", assetsTitle: "Listings" }}
+/>
+```
+
+If you need event callbacks or `update()` to reconfigure at runtime,
+those are tracked as follow-ups.
 
 ## Companion endpoints
 
@@ -84,13 +111,13 @@ service:
 |---|---|---|
 | `runflowProxy` | `POST /v1/models/{model}/runs` + `GET /v1/runs/{id}` | `@runflow-io/proxy` |
 | `imageProxy` | `GET /?url=<external>` → echo bytes, same-origin (for cross-origin source images) | You |
-| `upload` | `POST` multipart → `{ url }` (writes to your storage) | You |
+| `upload` | *(optional legacy)* `POST` multipart → `{ url }` — by default uploads use the SDK presigned flow through `runflowProxy`; only set this to keep a custom storage path | You |
 | `chat` | SSE chat agent (wraps Anthropic + the tool catalogue) | You |
 | `sentinel` | `POST /evaluate?sync=false` + `GET /evaluate/{eval_id}` | You |
 
 The runflow-prototypes repo has working reference implementations under
 `projects/demos/api/{upload,chat,sentinel,image}.mjs`. If you only need
-single-step dispatch (no uploads, no chat, no sentinel), the proxy alone
+dispatch + uploads (no chat, no sentinel), the proxy alone
 is enough — the upload/chat/sentinel-dependent UI paths gracefully
 degrade when the routes return 404/403.
 
@@ -150,9 +177,24 @@ const { output } = await rf.tools.run(tool, { image: "https://cdn/x.png" });
 ```
 
 The headless entry also exports `WORKFLOWS`, `SAMPLES`, the prototype's
-`runWorkflow` dispatcher, the `sentinelEvaluate` client, and
-`setStudioUrls`. A React state reducer for building a custom shell is
-tracked as a follow-up.
+`runWorkflow` dispatcher, the `sentinelEvaluate` client, `setStudioUrls`,
+and `createMaskController` — the framework-free dual-canvas brush engine
+the shell uses for its mask workflows:
+
+```ts
+import { createMaskController } from "@runflow-io/studio/headless";
+
+const mask = createMaskController({ brushSize: 45 });
+mask.attach(overlayCanvas); // rendered over your image
+mask.syncToDisplay(rect.width, rect.height, devicePixelRatio);
+// pointer events → beginStroke / strokeTo / endStroke; then:
+const blob = await mask.toMaskBlob(img.naturalWidth, img.naturalHeight);
+const asset = await rf.assets.upload(blob, { filename: "mask.png" });
+// → feed asset.url as mask_url to runflow/reference-inpaint etc.
+```
+
+A React state reducer for building a custom shell is tracked as a
+follow-up.
 
 ## License
 
diff --git a/packages/studio/package.json b/packages/studio/package.json
index 482809c..0d23241 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -13,9 +13,7 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "sideEffects": [
-    "./dist/styles.css"
-  ],
+  "sideEffects": ["./dist/styles.css"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -34,11 +32,7 @@
     },
     "./styles.css": "./dist/styles.css"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
   "scripts": {
     "build": "tsup && cp src/styles.css dist/styles.css",
     "dev": "tsup --watch",
diff --git a/packages/studio/src/components/Canvas.tsx b/packages/studio/src/components/Canvas.tsx
index 1332702..7a2b02d 100644
--- a/packages/studio/src/components/Canvas.tsx
+++ b/packages/studio/src/components/Canvas.tsx
@@ -6,13 +6,15 @@
 // bounding box (no off-by-letterbox drift on pin clicks).
 
 import { type ReactNode, type Ref, useState } from "react";
-import { Icon } from "./icons";
-import { displayBucket, aspectRatioLabel } from "../lib/resolution";
+import { aspectRatioLabel, displayBucket } from "../lib/resolution";
 import { usePendingPhrase } from "../lib/workflow-progress";
+import { Icon } from "./icons";
 
 export type Pin = { x: number; y: number };
 
 export function StudioCanvas({
+  emptyTitle = "No image selected",
+  emptySubtitle = "Pick a sample from the left, or drop your own to get started.",
   imageUrl,
   imageTitle,
   imageWidth,
@@ -49,6 +51,10 @@ export function StudioCanvas({
   onDownloadAll,
   canDownloadAll,
 }: {
+  /** Empty-state heading shown when no image is selected. */
+  emptyTitle?: string;
+  /** Empty-state subline shown when no image is selected. */
+  emptySubtitle?: string;
   imageUrl: string | null;
   imageTitle: string;
   imageWidth?: number;
@@ -147,7 +153,9 @@ export function StudioCanvas({
                 <span className="rfs-canvas-pending-phrase">
                   {pendingPhrase}
                   <span className="rfs-canvas-pending-dots" aria-hidden>
-                    <span /><span /><span />
+                    <span />
+                    <span />
+                    <span />
                   </span>
                 </span>
               </div>
@@ -180,17 +188,26 @@ export function StudioCanvas({
     return (
       <div className="rfs-canvas">
         <div className="rfs-canvas-empty">
-          <h2>No image selected</h2>
-          <p>Pick a sample from the left, or drop your own to get started.</p>
+          <h2>{emptyTitle}</h2>
+          <p>{emptySubtitle}</p>
         </div>
       </div>
     );
   }
 
   return (
-    <div className={`rfs-canvas${isPinning ? " is-pinning" : ""}${isPainting ? " is-painting" : ""}`}>
+    <div
+      className={`rfs-canvas${isPinning ? " is-pinning" : ""}${isPainting ? " is-painting" : ""}`}
+    >
       <div className="rfs-image-frame">
-        <img ref={imgRef} src={imageUrl} alt={imageTitle} draggable={false} onClick={onImageClick} />
+        {/* biome-ignore lint/a11y/useKeyWithClickEvents: pin placement is pointer-coordinate-driven; the keyboard path is the chat agent's pin flow */}
+        <img
+          ref={imgRef}
+          src={imageUrl}
+          alt={imageTitle}
+          draggable={false}
+          onClick={onImageClick}
+        />
         {pin && isPinning ? (
           <div
             className="rfs-pin"
@@ -218,6 +235,7 @@ export function StudioCanvas({
             studio's headline moments. Persistent top-right floating
             button on the canvas, subtle when idle, clear on hover. */}
         <button
+          type="button"
           className="rfs-canvas-compare-btn"
           title={compareEnabled ? "Compare versions" : "Need at least 2 versions to compare"}
           onClick={onOpenCompare}
@@ -236,6 +254,7 @@ export function StudioCanvas({
             <summary className="rfs-canvas-info-btn" aria-label="Show image details">
               ?
             </summary>
+            {/* biome-ignore lint/a11y/useSemanticElements: role="status" on a styled div; <output> carries form semantics and inline display */}
             <div className="rfs-canvas-info-popover" role="status">
               {(() => {
                 const bucket = displayBucket(imageWidth, imageHeight, requestedResolution);
@@ -245,7 +264,9 @@ export function StudioCanvas({
                   </span>
                 );
               })()}
-              <span className="rfs-canvas-info-pill">{aspectRatioLabel(imageWidth, imageHeight)}</span>
+              <span className="rfs-canvas-info-pill">
+                {aspectRatioLabel(imageWidth, imageHeight)}
+              </span>
               <span className="rfs-canvas-info-dim">
                 {imageWidth}×{imageHeight}
               </span>
@@ -275,6 +296,7 @@ export function StudioCanvas({
             </>
           ) : null}
           <button
+            type="button"
             className="rfs-iconbtn"
             title={copied ? "Copied!" : "Copy image link"}
             onClick={handleCopyLink}
@@ -282,15 +304,26 @@ export function StudioCanvas({
           >
             {copied ? Icon.check : Icon.link}
           </button>
-          <a className="rfs-iconbtn" href={imageUrl} target="_blank" rel="noreferrer" title="Download this version">
+          <a
+            className="rfs-iconbtn"
+            href={imageUrl}
+            target="_blank"
+            rel="noreferrer"
+            title="Download this version"
+          >
             {Icon.download}
           </a>
           {onDownloadAll ? (
             <button
+              type="button"
               className="rfs-iconbtn"
               onClick={onDownloadAll}
               disabled={!canDownloadAll}
-              title={canDownloadAll ? "Download all versions as .zip" : "Need at least 2 versions to bundle"}
+              title={
+                canDownloadAll
+                  ? "Download all versions as .zip"
+                  : "Need at least 2 versions to bundle"
+              }
               aria-label="Download all versions as .zip"
             >
               {Icon.downloadAll}
@@ -307,11 +340,12 @@ export function StudioCanvas({
             min={10}
             max={120}
             value={brushSize}
-            onChange={(e) => onBrushSize(parseInt(e.target.value, 10))}
+            onChange={(e) => onBrushSize(Number.parseInt(e.target.value, 10))}
             className="rfs-brush-range"
           />
           <span className="rfs-brush-size">{brushSize}px</span>
           <button
+            type="button"
             className="rfs-brush-clear"
             onClick={onClearMask}
             disabled={maskCoverage === 0}
@@ -322,13 +356,14 @@ export function StudioCanvas({
             <>
               <span className="rfs-brush-divider" />
               <button
+                type="button"
                 className="rfs-brush-confirm"
                 onClick={onConfirmChatMask}
                 disabled={maskCoverage < 0.08}
               >
                 Confirm mask
               </button>
-              <button className="rfs-brush-clear" onClick={onCancelChatMask}>
+              <button type="button" className="rfs-brush-clear" onClick={onCancelChatMask}>
                 Cancel
               </button>
             </>
@@ -337,6 +372,7 @@ export function StudioCanvas({
       ) : null}
       {chatPinMode ? (
         <button
+          type="button"
           className="rfs-brush-clear"
           onClick={onCancelChatPin}
           style={{
@@ -363,6 +399,7 @@ export function StudioCanvas({
       ) : null}
 
       {pending ? (
+        // biome-ignore lint/a11y/useSemanticElements: role="status" on a styled div; <output> carries form semantics and inline display
         <div className="rfs-canvas-pending" role="status">
           <span className="rfs-canvas-pending-spinner" aria-hidden />
           <span className="rfs-canvas-pending-phrase">
diff --git a/packages/studio/src/components/ChatPanel.tsx b/packages/studio/src/components/ChatPanel.tsx
index a5b1291..bba7cf7 100644
--- a/packages/studio/src/components/ChatPanel.tsx
+++ b/packages/studio/src/components/ChatPanel.tsx
@@ -19,12 +19,8 @@
 //   5. when assistant returns no tool_use → stop
 
 import { useEffect, useMemo, useRef, useState } from "react";
+import type { Workflow } from "../data/workflows";
 import {
-  emptyCaptured,
-  extractToolUses,
-  getSessionId,
-  runTool,
-  streamChatTurn,
   type CapturedInputs,
   type ChatMessage,
   type ChoiceOption,
@@ -32,84 +28,75 @@ import {
   type StudioHandle,
   type ToolResultBlock,
   type ToolUseBlock,
+  emptyCaptured,
+  extractToolUses,
+  getSessionId,
+  runTool,
+  streamChatTurn,
 } from "../lib/chat";
+import { type ResBucket, isUpscale, resBucket } from "../lib/resolution";
+import { useShellConfig } from "../lib/shell-config";
 import type { PartialStudioHandle } from "../lib/studio-handle";
-import { WORKFLOWS } from "../data/workflows";
-import { isUpscale, resBucket, type ResBucket } from "../lib/resolution";
 import { Icon } from "./icons";
 
-function workflowDisplayName(workflowId: string): string {
-  return WORKFLOWS.find((w) => w.id === workflowId)?.name ?? workflowId;
+function workflowDisplayName(workflowId: string, workflows: ReadonlyArray<Workflow>): string {
+  return workflows.find((w) => w.id === workflowId)?.name ?? workflowId;
 }
 
 type PlanStep = { workflow_id: string; description: string };
 
-type PlanState =
-  | null
-  | {
-      steps: PlanStep[];
-      rationale: string;
-      resolved: boolean;
-      confirmed: boolean;
-    };
+type PlanState = null | {
+  steps: PlanStep[];
+  rationale: string;
+  resolved: boolean;
+  confirmed: boolean;
+};
 
-type RefRequestState =
-  | null
-  | {
-      hint: string;
-      resolved: boolean;
-      file: File | null;
-    };
+type RefRequestState = null | {
+  hint: string;
+  resolved: boolean;
+  file: File | null;
+};
 
-type TextRequestState =
-  | null
-  | {
-      label: string;
-      placeholder?: string;
-      optional: boolean;
-      resolved: boolean;
-      value: string | null;
-    };
+type TextRequestState = null | {
+  label: string;
+  placeholder?: string;
+  optional: boolean;
+  resolved: boolean;
+  value: string | null;
+};
 
-type ColorRequestState =
-  | null
-  | {
-      hint: string;
-      defaultHex: string;
-      resolved: boolean;
-      value: string | null;
-    };
+type ColorRequestState = null | {
+  hint: string;
+  defaultHex: string;
+  resolved: boolean;
+  value: string | null;
+};
 
-type AspectRequestState =
-  | null
-  | {
-      hint: string;
-      options: string[];
-      allowCustom: boolean;
-      defaultValue?: string;
-      resolved: boolean;
-      value: string | null;
-    };
+type AspectRequestState = null | {
+  hint: string;
+  options: string[];
+  allowCustom: boolean;
+  defaultValue?: string;
+  resolved: boolean;
+  value: string | null;
+};
 
-type ResolutionRequestState =
-  | null
-  | {
-      hint: string;
-      defaultValue?: string;
-      sourceDims: { width: number; height: number } | null;
-      resolved: boolean;
-      value: string | null;
-    };
+type ResolutionRequestState = null | {
+  hint: string;
+  defaultValue?: string;
+  sourceDims: { width: number; height: number } | null;
+  resolved: boolean;
+  value: string | null;
+};
 
-type ChoiceRequestState =
-  | null
-  | {
-      hint: string;
-      options: ChoiceOption[];
-      defaultValue?: string;
-      resolved: boolean;
-      value: string | null;
-    };
+type ChoiceRequestState = null | {
+  hint: string;
+  options: ChoiceOption[];
+  defaultValue?: string;
+  resolved: boolean;
+  value: string | null;
+};
 
 // Inline retry-or-skip state shown when run_workflow returns an error
 // inside an agent plan. Survives across attempts so the user can keep
@@ -117,14 +104,12 @@ type ChoiceRequestState =
 // model adapt around the failure. `attempt` increments on every retry
 // so the bubble can show "Attempt 3 of 4 failed" instead of swallowing
 // repeated failures.
-type RetryState =
-  | null
-  | {
-      workflowId: string;
-      error: string;
-      attempt: number;
-      resolved: boolean;
-    };
+type RetryState = null | {
+  workflowId: string;
+  error: string;
+  attempt: number;
+  resolved: boolean;
+};
 
 type RetryDecision = "retry" | "skip";
 
@@ -146,7 +131,7 @@ function isValidHex(s: string): boolean {
 }
 function normaliseHex(s: string): string {
   let v = s.trim();
-  if (!v.startsWith("#")) v = "#" + v;
+  if (!v.startsWith("#")) v = `#${v}`;
   if (v.length === 4) {
     // #RGB → #RRGGBB
     v = `#${v[1]}${v[1]}${v[2]}${v[2]}${v[3]}${v[3]}`;
@@ -188,10 +173,7 @@ function healStuckTranscript(messages: ChatMessage[]): ChatMessage[] {
   if (last.role !== "assistant" || !Array.isArray(last.content)) return messages;
   const hasOrphanToolUse = last.content.some((b) => b.type === "tool_use");
   if (!hasOrphanToolUse) return messages;
-  console.warn(
-    "[chat] dropping trailing assistant message with unresolved tool_use blocks",
-    last,
-  );
+  console.warn("[chat] dropping trailing assistant message with unresolved tool_use blocks", last);
   // Walk back past the orphan AND the user message that triggered it.
   let i = messages.length - 2;
   while (i >= 0 && messages[i].role !== "user") i -= 1;
@@ -216,6 +198,7 @@ export function ChatPanel({
   studioHandle: PartialStudioHandle;
   activeAssetId: string | null;
 }) {
+  const { workflows: catalogWorkflows } = useShellConfig();
   const [messages, setMessages] = useState<ChatMessage[]>(() => loadMessages(activeAssetId));
   const [input, setInput] = useState("");
   const [isStreaming, setIsStreaming] = useState(false);
@@ -272,7 +255,17 @@ export function ChatPanel({
     if (scrollRef.current) {
       scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
     }
-  }, [messages, planState, refState, textState, colorState, aspectState, resolutionState, choiceState, retryState]);
+  }, [
+    messages,
+    planState,
+    refState,
+    textState,
+    colorState,
+    aspectState,
+    resolutionState,
+    choiceState,
+    retryState,
+  ]);
 
   const sessionId = useMemo(() => getSessionId(), []);
 
@@ -411,10 +404,7 @@ export function ChatPanel({
             // tool_result. Loops until the user picks Skip or the run
             // finally succeeds.
             let attempt = 1;
-            while (
-              dispatch.uiEffect?.kind === "workflow_failed" &&
-              tu.name === "run_workflow"
-            ) {
+            while (dispatch.uiEffect?.kind === "workflow_failed" && tu.name === "run_workflow") {
               const failed = dispatch.uiEffect;
               const decision = await new Promise<RetryDecision>((resolve) => {
                 retryResolverRef.current = resolve;
@@ -582,10 +572,9 @@ export function ChatPanel({
   return (
     <div className="rfs-chat">
       <header className="rfs-chat-header">
-        <span className="rfs-chat-header-title">
-          {hasTranscript ? "Conversation" : "New chat"}
-        </span>
+        <span className="rfs-chat-header-title">{hasTranscript ? "Conversation" : "New chat"}</span>
         <button
+          type="button"
           className="rfs-chat-reset"
           onClick={clearChat}
           disabled={isStreaming || !hasTranscript}
@@ -595,7 +584,17 @@ export function ChatPanel({
               : "Reset the conversation and start fresh"
           }
         >
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden>
+          <svg
+            width="14"
+            height="14"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
             <path d="M3 12a9 9 0 1 0 3.5-7.1" />
             <path d="M3 4v6h6" />
           </svg>
@@ -608,7 +607,9 @@ export function ChatPanel({
             <div className="rfs-empty-icon">{Icon.chat}</div>
             <h3>Chat with the studio</h3>
             <p>
-              Describe what you want done — &ldquo;remove the price tag&rdquo;, &ldquo;put this on a Mediterranean rooftop&rdquo;, &ldquo;swap the print on the sleeve&rdquo;. The agent picks the workflow, asks for what it needs, and runs it.
+              Describe what you want done — &ldquo;remove the price tag&rdquo;, &ldquo;put this on a
+              Mediterranean rooftop&rdquo;, &ldquo;swap the print on the sleeve&rdquo;. The agent
+              picks the workflow, asks for what it needs, and runs it.
             </p>
           </div>
         ) : (
@@ -623,7 +624,11 @@ export function ChatPanel({
           />
         ) : null}
         {refState && !refState.resolved ? (
-          <ReferenceBubble hint={refState.hint} onSubmit={submitReference} onCancel={cancelReference} />
+          <ReferenceBubble
+            hint={refState.hint}
+            onSubmit={submitReference}
+            onCancel={cancelReference}
+          />
         ) : null}
         {textState && !textState.resolved ? (
           <TextBubble
@@ -672,7 +677,7 @@ export function ChatPanel({
         ) : null}
         {retryState && !retryState.resolved ? (
           <RetryBubble
-            workflowName={workflowDisplayName(retryState.workflowId)}
+            workflowName={workflowDisplayName(retryState.workflowId, catalogWorkflows)}
             error={retryState.error}
             attempt={retryState.attempt}
             onRetry={() => decideRetry("retry")}
@@ -713,6 +718,7 @@ export function ChatPanel({
         />
         <div className="rfs-chat-footer-actions">
           <button
+            type="button"
             className="rfs-btn rfs-btn-primary rfs-chat-send"
             onClick={send}
             disabled={!input.trim() || isStreaming || !activeAssetId}
@@ -730,6 +736,7 @@ export function ChatPanel({
 // ============================================================
 
 function MessageBubble({ message }: { message: ChatMessage }) {
+  const { workflows } = useShellConfig();
   // User message — text only (we don't render the image attachment back
   // to the user; the canvas is right there).
   if (message.role === "user") {
@@ -771,7 +778,7 @@ function MessageBubble({ message }: { message: ChatMessage }) {
           return (
             <div key={i} className="rfs-chat-tool-call" title={JSON.stringify(block.input)}>
               <span className="rfs-chat-tool-icon">⚙</span>
-              {labelForTool(block)}
+              {labelForTool(block, workflows)}
             </div>
           );
         }
@@ -781,7 +788,7 @@ function MessageBubble({ message }: { message: ChatMessage }) {
   );
 }
 
-function labelForTool(block: ToolUseBlock): string {
+function labelForTool(block: ToolUseBlock, workflows: ReadonlyArray<Workflow>): string {
   switch (block.name) {
     case "propose_plan":
       return "Proposing plan…";
@@ -802,7 +809,7 @@ function labelForTool(block: ToolUseBlock): string {
     case "request_choice":
       return "Asking you to pick an option";
     case "run_workflow":
-      return `Running ${workflowDisplayName(String(block.input.workflow_id ?? "workflow"))}…`;
+      return `Running ${workflowDisplayName(String(block.input.workflow_id ?? "workflow"), workflows)}…`;
     case "finish":
       return "Done";
     default:
@@ -821,6 +828,7 @@ function PlanBubble({
   onConfirm: () => void;
   onReject: () => void;
 }) {
+  const { workflows } = useShellConfig();
   return (
     <div className="rfs-chat-msg rfs-chat-msg-assistant">
       <div className="rfs-chat-plan">
@@ -834,14 +842,20 @@ function PlanBubble({
               <span className="rfs-chat-plan-num">{i + 1}</span>
               <div className="rfs-chat-plan-step-text">
                 <div className="rfs-chat-plan-step-desc">{s.description}</div>
-                <div className="rfs-chat-plan-step-id">{workflowDisplayName(s.workflow_id)}</div>
+                <div className="rfs-chat-plan-step-id">
+                  {workflowDisplayName(s.workflow_id, workflows)}
+                </div>
               </div>
             </li>
           ))}
         </ol>
         <div className="rfs-chat-plan-actions">
-          <button className="rfs-btn" onClick={onReject}>Push back</button>
-          <button className="rfs-btn rfs-btn-primary" onClick={onConfirm}>Run plan</button>
+          <button type="button" className="rfs-btn" onClick={onReject}>
+            Push back
+          </button>
+          <button type="button" className="rfs-btn rfs-btn-primary" onClick={onConfirm}>
+            Run plan
+          </button>
         </div>
       </div>
     </div>
@@ -872,7 +886,12 @@ function ReferenceBubble({
         />
         <span>Click to upload a reference image</span>
       </label>
-      <button className="rfs-link" onClick={onCancel} style={{ marginTop: 4, fontSize: 12 }}>
+      <button
+        type="button"
+        className="rfs-link"
+        onClick={onCancel}
+        style={{ marginTop: 4, fontSize: 12 }}
+      >
         Skip
       </button>
     </div>
@@ -907,6 +926,7 @@ function ColorBubble({
         <div className="rfs-chat-color-presets">
           {COLOR_PRESETS.map((p) => (
             <button
+              type="button"
               key={p.hex}
               className={`rfs-chat-color-swatch${picked === p.hex ? " is-picked" : ""}`}
               style={{ background: p.hex }}
@@ -937,6 +957,7 @@ function ColorBubble({
             spellCheck={false}
           />
           <button
+            type="button"
             className="rfs-btn rfs-btn-primary"
             onClick={submit}
             disabled={!isValidHex(hexInput)}
@@ -944,7 +965,12 @@ function ColorBubble({
             Use color
           </button>
         </div>
-        <button className="rfs-link" onClick={onCancel} style={{ fontSize: 12, alignSelf: "flex-start" }}>
+        <button
+          type="button"
+          className="rfs-link"
+          onClick={onCancel}
+          style={{ fontSize: 12, alignSelf: "flex-start" }}
+        >
           Skip
         </button>
       </div>
@@ -969,7 +995,8 @@ function TextBubble({
   return (
     <div className="rfs-chat-msg rfs-chat-msg-assistant">
       <div className="rfs-chat-bubble">
-        {label}{optional ? " (optional)" : ""}
+        {label}
+        {optional ? " (optional)" : ""}
       </div>
       <textarea
         className="rfs-textarea"
@@ -981,11 +1008,16 @@ function TextBubble({
       />
       <div style={{ display: "flex", gap: 6, marginTop: 6, justifyContent: "flex-end" }}>
         {optional ? (
-          <button className="rfs-btn" onClick={() => onSubmit("")}>Skip</button>
+          <button type="button" className="rfs-btn" onClick={() => onSubmit("")}>
+            Skip
+          </button>
         ) : (
-          <button className="rfs-btn" onClick={onCancel}>Cancel</button>
+          <button type="button" className="rfs-btn" onClick={onCancel}>
+            Cancel
+          </button>
         )}
         <button
+          type="button"
           className="rfs-btn rfs-btn-primary"
           onClick={() => onSubmit(value)}
           disabled={!optional && !value.trim()}
@@ -1021,8 +1053,8 @@ function AspectBubble({
   const [customW, setCustomW] = useState("");
   const [customH, setCustomH] = useState("");
   const submitCustom = () => {
-    const w = parseInt(customW, 10);
-    const h = parseInt(customH, 10);
+    const w = Number.parseInt(customW, 10);
+    const h = Number.parseInt(customH, 10);
     if (!w || !h || w < 1 || h < 1) return;
     onSubmit(`${w}:${h}`);
   };
@@ -1033,13 +1065,14 @@ function AspectBubble({
         <div className="rfs-chat-aspect-grid">
           {options.map((opt) => {
             const [wStr, hStr] = opt.split(":");
-            const w = parseInt(wStr, 10) || 1;
-            const h = parseInt(hStr, 10) || 1;
+            const w = Number.parseInt(wStr, 10) || 1;
+            const h = Number.parseInt(hStr, 10) || 1;
             const max = 14;
             const tileW = w >= h ? max : Math.round((w / h) * max);
             const tileH = h >= w ? max : Math.round((h / w) * max);
             return (
               <button
+                type="button"
                 key={opt}
                 className={`rfs-chat-aspect-tile${picked === opt ? " is-picked" : ""}`}
                 onClick={() => {
@@ -1049,10 +1082,7 @@ function AspectBubble({
                 title={opt}
               >
                 <span className="rfs-chat-aspect-shape-wrap" aria-hidden>
-                  <span
-                    className="rfs-chat-aspect-shape"
-                    style={{ width: tileW, height: tileH }}
-                  />
+                  <span className="rfs-chat-aspect-shape" style={{ width: tileW, height: tileH }} />
                 </span>
                 <span className="rfs-chat-aspect-label">{opt}</span>
               </button>
@@ -1084,15 +1114,17 @@ function AspectBubble({
               aria-label="Custom height"
             />
             <button
+              type="button"
               className="rfs-btn rfs-btn-primary"
               onClick={submitCustom}
-              disabled={!parseInt(customW, 10) || !parseInt(customH, 10)}
+              disabled={!Number.parseInt(customW, 10) || !Number.parseInt(customH, 10)}
             >
               Use
             </button>
           </div>
         ) : null}
         <button
+          type="button"
           className="rfs-link"
           onClick={onCancel}
           style={{ fontSize: 12, alignSelf: "flex-start" }}
@@ -1124,8 +1156,7 @@ function ResolutionBubble({
   const sourceBucket: ResBucket | null = sourceDims
     ? resBucket(sourceDims.width, sourceDims.height)
     : null;
-  const initial: ResBucket =
-    (defaultValue as ResBucket) ?? sourceBucket ?? "2K";
+  const initial: ResBucket = (defaultValue as ResBucket) ?? sourceBucket ?? "2K";
   const [picked, setPicked] = useState<ResBucket>(initial);
   const upscaling = sourceBucket && isUpscale(sourceBucket, picked);
   const buckets: ResBucket[] = ["1K", "2K", "4K"];
@@ -1136,6 +1167,7 @@ function ResolutionBubble({
         <div className="rfs-chat-resolution-segmented" role="radiogroup">
           {buckets.map((b) => (
             <button
+              type="button"
               key={b}
               role="radio"
               aria-checked={picked === b}
@@ -1154,15 +1186,19 @@ function ResolutionBubble({
         ) : null}
         {upscaling ? (
           <div className="rfs-help rfs-help-warn">
-            Heads up — picking {picked} from a {sourceBucket} source means
-            upscaling; the model can't add detail that isn't there.
+            Heads up — picking {picked} from a {sourceBucket} source means upscaling; the model
+            can't add detail that isn't there.
           </div>
         ) : null}
         <div className="rfs-chat-resolution-actions">
-          <button className="rfs-link" onClick={onCancel} style={{ fontSize: 12 }}>
+          <button type="button" className="rfs-link" onClick={onCancel} style={{ fontSize: 12 }}>
             Skip
           </button>
-          <button className="rfs-btn rfs-btn-primary" onClick={() => onSubmit(picked)}>
+          <button
+            type="button"
+            className="rfs-btn rfs-btn-primary"
+            onClick={() => onSubmit(picked)}
+          >
             Use {picked}
           </button>
         </div>
@@ -1201,10 +1237,10 @@ function RetryBubble({
         </div>
         <div className="rfs-chat-retry-error">{error}</div>
         <div className="rfs-chat-retry-actions">
-          <button className="rfs-btn" onClick={onSkip}>
+          <button type="button" className="rfs-btn" onClick={onSkip}>
             Skip step and continue
           </button>
-          <button className="rfs-btn rfs-btn-primary" onClick={onRetry}>
+          <button type="button" className="rfs-btn rfs-btn-primary" onClick={onRetry}>
             Retry
           </button>
         </div>
@@ -1234,6 +1270,7 @@ function ChoiceBubble({
       <div className="rfs-chat-choice">
         {options.map((o) => (
           <button
+            type="button"
             key={o.value}
             className={`rfs-chat-choice-btn${defaultValue === o.value ? " is-default" : ""}`}
             onClick={() => onSubmit(o.value)}
@@ -1242,6 +1279,7 @@ function ChoiceBubble({
           </button>
         ))}
         <button
+          type="button"
           className="rfs-link"
           onClick={onCancel}
           style={{ fontSize: 12, alignSelf: "flex-start" }}
diff --git a/packages/studio/src/components/ComparePanel.tsx b/packages/studio/src/components/ComparePanel.tsx
index 9b7dc23..11ff03a 100644
--- a/packages/studio/src/components/ComparePanel.tsx
+++ b/packages/studio/src/components/ComparePanel.tsx
@@ -53,8 +53,7 @@ export function ComparePanel({
     [versions, leftId],
   );
   const right = useMemo(
-    () =>
-      versions.find((v) => v.id === rightId) ?? versions[versions.length - 1],
+    () => versions.find((v) => v.id === rightId) ?? versions[versions.length - 1],
     [versions, rightId],
   );
 
@@ -94,15 +93,19 @@ export function ComparePanel({
     <div className="rfs-compare-shell" role="dialog" aria-label="Compare versions">
       <header className="rfs-compare-header">
         <div className="rfs-compare-title">
-          <span className="rfs-compare-title-mark" aria-hidden>{Icon.compare}</span>
+          <span className="rfs-compare-title-mark" aria-hidden>
+            {Icon.compare}
+          </span>
           <span>Compare versions</span>
           <span className="rfs-compare-title-meta">
             {versions.length} version{versions.length === 1 ? "" : "s"}
           </span>
         </div>
         <div className="rfs-compare-header-actions">
-          <button className="rfs-btn" onClick={reset}>Reset</button>
-          <button className="rfs-iconbtn" onClick={onClose} aria-label="Close">
+          <button type="button" className="rfs-btn" onClick={reset}>
+            Reset
+          </button>
+          <button type="button" className="rfs-iconbtn" onClick={onClose} aria-label="Close">
             {Icon.close}
           </button>
         </div>
@@ -194,13 +197,14 @@ function ComparePane({
     };
   };
   const onMouseMove = (e: React.MouseEvent) => {
-    if (!dragRef.current) return;
-    const dx = e.clientX - dragRef.current.x;
-    const dy = e.clientY - dragRef.current.y;
+    const drag = dragRef.current;
+    if (!drag) return;
+    const dx = e.clientX - drag.x;
+    const dy = e.clientY - drag.y;
     onTransform((prev) => ({
       ...prev,
-      panX: dragRef.current!.px + dx,
-      panY: dragRef.current!.py + dy,
+      panX: drag.px + dx,
+      panY: drag.py + dy,
     }));
   };
   const onMouseUp = () => {
@@ -229,9 +233,7 @@ function ComparePane({
         ) : (
           <span className="rfs-compare-pane-label">{version.label}</span>
         )}
-        <span className="rfs-compare-pane-zoom">
-          {Math.round(transform.zoom * 100)}%
-        </span>
+        <span className="rfs-compare-pane-zoom">{Math.round(transform.zoom * 100)}%</span>
       </div>
       <div
         ref={stageRef}
diff --git a/packages/studio/src/components/GeneratePanel.tsx b/packages/studio/src/components/GeneratePanel.tsx
index 7299f45..e1bbd7a 100644
--- a/packages/studio/src/components/GeneratePanel.tsx
+++ b/packages/studio/src/components/GeneratePanel.tsx
@@ -22,14 +22,14 @@
 // and a "+ New generation" button that resets the form so they can
 // fire off another batch without leaving the panel.
 
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import {
+  type GenerationResolution,
   estimateGenerationCost,
   formatCostUsd,
-  type GenerationResolution,
 } from "../lib/generation";
-import { Icon } from "./icons";
 import { ReferenceGallery } from "./ReferenceGallery";
+import { Icon } from "./icons";
 
 const ASPECT_OPTIONS: { value: string; label: string }[] = [
   { value: "1:1", label: "1:1 — square" },
@@ -99,6 +99,22 @@ export function GeneratePanel({
   const [extraReferences, setExtraReferences] = useState<File[]>([]);
   const [extraReferencePreviews, setExtraReferencePreviews] = useState<string[]>([]);
 
+  // Unmount-only cleanup for blob previews. A ref mirror (not effect
+  // deps) so URLs are never revoked while still rendered.
+  const previewUrlsRef = useRef<{ primary: string | null; extras: string[] }>({
+    primary: null,
+    extras: [],
+  });
+  previewUrlsRef.current = { primary: referencePreview, extras: extraReferencePreviews };
+  useEffect(
+    () => () => {
+      const p = previewUrlsRef.current;
+      if (p.primary) URL.revokeObjectURL(p.primary);
+      for (const u of p.extras) URL.revokeObjectURL(u);
+    },
+    [],
+  );
+
   const cost = estimateGenerationCost(resolution, count);
   const canGenerate = prompt.trim().length > 0;
 
@@ -115,10 +131,12 @@ export function GeneratePanel({
   const onAddReferenceFiles = (files: File[]) => {
     if (files.length === 0) return;
     const remaining = files.slice();
-    if (!reference && remaining.length > 0) {
-      const head = remaining.shift()!;
-      setReference(head);
-      setReferencePreview(URL.createObjectURL(head));
+    if (!reference) {
+      const head = remaining.shift();
+      if (head) {
+        setReference(head);
+        setReferencePreview(URL.createObjectURL(head));
+      }
     }
     if (remaining.length === 0) return;
     const room = MAX_GENERATE_REFERENCES - 1 - extraReferences.length;
@@ -181,9 +199,7 @@ export function GeneratePanel({
             </span>
           </div>
           {inFlightPrompt ? (
-            <div className="rfs-generate-inflight-prompt">
-              {inFlightPrompt}
-            </div>
+            <div className="rfs-generate-inflight-prompt">{inFlightPrompt}</div>
           ) : null}
           <div className="rfs-generate-inflight-hint">
             Watch the canvas — each variation will fill in as the model finishes.
@@ -202,8 +218,11 @@ export function GeneratePanel({
 
       <div className="rfs-generate-panel-body">
         <div className="rfs-input-group">
-          <label className="rfs-label">Prompt</label>
+          <label className="rfs-label" htmlFor="rfs-generate-prompt">
+            Prompt
+          </label>
           <textarea
+            id="rfs-generate-prompt"
             className="rfs-textarea"
             placeholder="e.g. premium minimalist white sneaker on a clean off-white backdrop, studio lighting"
             maxLength={400}
@@ -214,14 +233,19 @@ export function GeneratePanel({
         </div>
 
         <div className="rfs-input-group">
-          <label className="rfs-label">Aspect ratio</label>
+          <label className="rfs-label" htmlFor="rfs-generate-aspect">
+            Aspect ratio
+          </label>
           <select
+            id="rfs-generate-aspect"
             className="rfs-select"
             value={aspectRatio}
             onChange={(e) => setAspectRatio(e.target.value)}
           >
             {ASPECT_OPTIONS.map((o) => (
-              <option key={o.value} value={o.value}>{o.label}</option>
+              <option key={o.value} value={o.value}>
+                {o.label}
+              </option>
             ))}
           </select>
         </div>
@@ -263,22 +287,24 @@ export function GeneratePanel({
             maxReferences={MAX_GENERATE_REFERENCES}
           />
           <div className="rfs-help">
-            Drop in up to {MAX_GENERATE_REFERENCES} shots the model should
-            take cues from — style, subject, framing.
+            Drop in up to {MAX_GENERATE_REFERENCES} shots the model should take cues from — style,
+            subject, framing.
           </div>
         </div>
 
         <div className="rfs-input-group">
           <label className="rfs-label">
             Variations
-            <span className="rfs-label-meta">{count} image{count === 1 ? "" : "s"}</span>
+            <span className="rfs-label-meta">
+              {count} image{count === 1 ? "" : "s"}
+            </span>
           </label>
           <input
             type="range"
             min={1}
             max={MAX_VARIATIONS}
             value={count}
-            onChange={(e) => setCount(parseInt(e.target.value, 10))}
+            onChange={(e) => setCount(Number.parseInt(e.target.value, 10))}
             className="rfs-generate-count"
           />
         </div>
@@ -291,9 +317,7 @@ export function GeneratePanel({
           onClick={onSubmit}
           disabled={!canGenerate}
           title={
-            !canGenerate
-              ? "Enter a prompt"
-              : `Generate ${count} image${count === 1 ? "" : "s"}`
+            !canGenerate ? "Enter a prompt" : `Generate ${count} image${count === 1 ? "" : "s"}`
           }
         >
           {Icon.generate}
diff --git a/packages/studio/src/components/ReferenceGallery.tsx b/packages/studio/src/components/ReferenceGallery.tsx
index 4eb87a9..3d0c2e2 100644
--- a/packages/studio/src/components/ReferenceGallery.tsx
+++ b/packages/studio/src/components/ReferenceGallery.tsx
@@ -47,7 +47,7 @@ export function ReferenceGallery({
         </div>
       ) : null}
       {extraReferencePreviews.map((url, i) => (
-        <div className="rfs-ref-tile" key={i}>
+        <div className="rfs-ref-tile" key={`${url}-${i}`}>
           <img src={url} alt={`Reference ${i + 2}`} />
           <button
             type="button"
diff --git a/packages/studio/src/components/SentinelBadge.tsx b/packages/studio/src/components/SentinelBadge.tsx
index 6c4f28d..444d94f 100644
--- a/packages/studio/src/components/SentinelBadge.tsx
+++ b/packages/studio/src/components/SentinelBadge.tsx
@@ -155,7 +155,12 @@ export function SentinelChip({
   if (result.state === "pending") body = <span>checking</span>;
   else if (result.state === "failed") body = <span aria-label="Quality check error">?</span>;
   else if (score !== null) body = <span>{score}%</span>;
-  else if (total > 0) body = <span>{passes}/{total}</span>;
+  else if (total > 0)
+    body = (
+      <span>
+        {passes}/{total}
+      </span>
+    );
   else body = <span>{result.state}</span>;
 
   return (
@@ -236,6 +241,7 @@ export function SentinelBadge({
   return (
     <>
       <button
+        type="button"
         className={`rfs-sentinel-badge is-${result.state}`}
         onClick={onToggle}
         aria-expanded={open}
@@ -253,7 +259,10 @@ export function SentinelBadge({
         )}
         <span>{LABEL[result.state]}</span>
         {result.state === "pending" ? (
-          <span className="rfs-sentinel-badge-elapsed" aria-label={`Elapsed ${formatElapsed(elapsedSec)}`}>
+          <span
+            className="rfs-sentinel-badge-elapsed"
+            aria-label={`Elapsed ${formatElapsed(elapsedSec)}`}
+          >
             {formatElapsed(elapsedSec)}
           </span>
         ) : null}
@@ -281,17 +290,14 @@ export function SentinelBadge({
                   : "Sentinel checks"}
             </span>
             {typeof result.score === "number" ? (
-              <span className="rfs-sentinel-panel-score">
-                {Math.round(result.score * 100)}%
-              </span>
+              <span className="rfs-sentinel-panel-score">{Math.round(result.score * 100)}%</span>
             ) : null}
           </header>
 
           {/* Hard-gate banner — appears only if a critical check failed. */}
           {result.hardGateFailures && result.hardGateFailures.length > 0 ? (
             <div className="rfs-sentinel-hardgate">
-              <strong>Critical:</strong>{" "}
-              {result.hardGateFailures.length} hard-gate{" "}
+              <strong>Critical:</strong> {result.hardGateFailures.length} hard-gate{" "}
               {result.hardGateFailures.length === 1 ? "failure" : "failures"}
             </div>
           ) : null}
@@ -313,9 +319,9 @@ export function SentinelBadge({
             <div className="rfs-sentinel-panel-empty">
               {result.error ? (
                 <>
-                  Couldn&apos;t reach Sentinel: <code>{result.error}</code>. The image still works
-                  — only the quality score is missing. If this keeps happening, ping Ziad
-                  (ML) with the error above.
+                  Couldn&apos;t reach Sentinel: <code>{result.error}</code>. The image still works —
+                  only the quality score is missing. If this keeps happening, ping Ziad (ML) with
+                  the error above.
                 </>
               ) : (
                 "Sentinel returned no judges for this run."
@@ -370,14 +376,13 @@ export function SentinelBadge({
 // shows detected_issues (specific findings) + reasoning text.
 function JudgeRow({ judge }: { judge: Judge }) {
   const [expanded, setExpanded] = useState(false);
-  const hasDetail =
-    !!judge.reasoning || (judge.detectedIssues && judge.detectedIssues.length > 0);
-  const conf =
-    typeof judge.confidence === "number" ? Math.round(judge.confidence * 100) : null;
+  const hasDetail = !!judge.reasoning || (judge.detectedIssues && judge.detectedIssues.length > 0);
+  const conf = typeof judge.confidence === "number" ? Math.round(judge.confidence * 100) : null;
 
   return (
     <div className={`rfs-sentinel-judge${judge.pass ? " is-pass" : " is-fail"}`}>
       <button
+        type="button"
         className="rfs-sentinel-judge-header"
         onClick={() => hasDetail && setExpanded((v) => !v)}
         disabled={!hasDetail}
@@ -407,7 +412,9 @@ function JudgeRow({ judge }: { judge: Judge }) {
                 {judge.detectedIssues.map((iss, i) => (
                   <li key={i}>
                     <span className="rfs-sentinel-judge-tag">{iss.subcategory}</span>
-                    {iss.detail ? <span className="rfs-sentinel-judge-detail"> — {iss.detail}</span> : null}
+                    {iss.detail ? (
+                      <span className="rfs-sentinel-judge-detail"> — {iss.detail}</span>
+                    ) : null}
                   </li>
                 ))}
               </ul>
@@ -440,7 +447,11 @@ function CollapsibleSummary({
   const [open, setOpen] = useState(false);
   return (
     <div className={`rfs-sentinel-summary rfs-sentinel-summary-${kind}`}>
-      <button className="rfs-sentinel-summary-header" onClick={() => setOpen((v) => !v)}>
+      <button
+        type="button"
+        className="rfs-sentinel-summary-header"
+        onClick={() => setOpen((v) => !v)}
+      >
         <span className="rfs-sentinel-summary-icon" aria-hidden>
           {kind === "strength" ? "✓" : "!"}
         </span>
diff --git a/packages/studio/src/components/SettingsMenu.tsx b/packages/studio/src/components/SettingsMenu.tsx
index 29e7e9c..65fa3dd 100644
--- a/packages/studio/src/components/SettingsMenu.tsx
+++ b/packages/studio/src/components/SettingsMenu.tsx
@@ -13,10 +13,7 @@
 // per step, which is too slow for casual demos but useful when the
 // operator wants to catch a regression early.
 
-import {
-  setStudioSetting,
-  useStudioSettings,
-} from "../lib/studio-settings";
+import { setStudioSetting, useStudioSettings } from "../lib/studio-settings";
 
 const TOOLTIP =
   "Pause the chain if any intermediate step fails the quality check. Adds ~2 minutes per step.";
diff --git a/packages/studio/src/components/StepEditor.tsx b/packages/studio/src/components/StepEditor.tsx
index 0ad6be7..b03fb35 100644
--- a/packages/studio/src/components/StepEditor.tsx
+++ b/packages/studio/src/components/StepEditor.tsx
@@ -18,11 +18,12 @@
 // runtime), packages (no nested chains for now), and `soon` are
 // excluded.
 
-import { WORKFLOWS, type Workflow } from "../data/workflows";
+import type { Workflow } from "../data/workflows";
+import { useShellConfig } from "../lib/shell-config";
 import { Icon } from "./icons";
 
-export function buildableWorkflowsForChain(): Workflow[] {
-  return WORKFLOWS.filter(
+export function buildableWorkflowsForChain(workflows: ReadonlyArray<Workflow>): Workflow[] {
+  return workflows.filter(
     (w) =>
       (w.kind === "simple" || w.kind === "prompt" || w.kind === "prompt-zip") &&
       w.id !== "reference-inpaint",
@@ -109,7 +110,9 @@ export function StepParamsForm({
                 onChange={(e) => setValue(e.target.value)}
               >
                 {inp.options.map((o) => (
-                  <option key={o.value} value={o.value}>{o.label}</option>
+                  <option key={o.value} value={o.value}>
+                    {o.label}
+                  </option>
                 ))}
               </select>
               {inp.help ? <div className="rfs-help">{inp.help}</div> : null}
@@ -136,6 +139,7 @@ export function StepPicker({
   onCancel: () => void;
   onPick: (wf: Workflow) => void;
 }) {
+  const { workflows } = useShellConfig();
   if (!open) {
     return (
       <button type="button" className="rfs-custom-editor-add" onClick={onOpen}>
@@ -143,7 +147,7 @@ export function StepPicker({
       </button>
     );
   }
-  const choices = buildableWorkflowsForChain();
+  const choices = buildableWorkflowsForChain(workflows);
   return (
     <div className="rfs-custom-editor-picker">
       <div className="rfs-custom-editor-picker-header">
diff --git a/packages/studio/src/components/StudioShell.tsx b/packages/studio/src/components/StudioShell.tsx
index c1a48f7..d6dd519 100644
--- a/packages/studio/src/components/StudioShell.tsx
+++ b/packages/studio/src/components/StudioShell.tsx
@@ -18,45 +18,47 @@
 // selected. Two canvases sync (visible coral + hidden B&W) just like
 // the retaillabs version, but scoped to this shell.
 
-import { useEffect, useMemo, useRef, useState } from "react";
 import JSZip from "jszip";
-import {
-  WORKFLOWS,
-  type Workflow,
-  type PackageRecipeStep,
-  type PackageVariant,
-  type PackageCreativeDirection,
+import { useEffect, useMemo, useRef, useState } from "react";
+import type {
+  PackageCreativeDirection,
+  PackageRecipeStep,
+  PackageVariant,
+  Workflow,
 } from "../data/workflows";
-import { SAMPLES } from "../data/samples";
-import { runWorkflow, uploadFile, type RunProgress } from "../lib/runflow";
-import { Toasts, type StudioToast } from "./Toasts";
-import { ComparePanel } from "./ComparePanel";
-import { evaluate as sentinelEvaluate, taskDescription as sentinelTaskDescription, type SentinelResult } from "../lib/sentinel";
+import type { CustomWorkflow } from "../lib/custom-workflows";
+import { type GenerationResolution, dispatchGeneration } from "../lib/generation";
+import { createMaskController } from "../lib/mask";
 import {
-  probeImageDims,
+  type ResBucket,
+  TOPAZ_MAX_OUTPUT_MP,
   displayBucket,
-  resBucket,
   isUpscale,
+  probeImageDims,
+  resBucket,
   topazExceedsCap,
   topazOutputMP,
-  TOPAZ_MAX_OUTPUT_MP,
-  type ResBucket,
 } from "../lib/resolution";
-import { compactSummary } from "../lib/version-summary";
-import { getStudioSettings } from "../lib/studio-settings";
-import type { CustomWorkflow } from "../lib/custom-workflows";
+import { type RunProgress, runWorkflow, uploadFile } from "../lib/runflow";
+import { type SentinelResult, evaluate as sentinelEvaluate } from "../lib/sentinel";
+import {
+  ShellConfigProvider,
+  type StudioShellProps,
+  resolveShellConfig,
+  useShellConfig,
+} from "../lib/shell-config";
 import type { PartialStudioHandle } from "../lib/studio-handle";
-import { StudioCanvas, type Pin } from "./Canvas";
-import { StepParamsForm, StepPicker, defaultStepValues } from "./StepEditor";
+import { getStudioSettings } from "../lib/studio-settings";
+import { compactSummary } from "../lib/version-summary";
+import { type Pin, StudioCanvas } from "./Canvas";
+import { ComparePanel } from "./ComparePanel";
 import { GeneratePanel } from "./GeneratePanel";
-import {
-  dispatchGeneration,
-  type GenerationResolution,
-} from "../lib/generation";
-import { WorkflowsPanel, type Version, type VersionRequest } from "./WorkflowsPanel";
+import { ReferenceGallery } from "./ReferenceGallery";
 import { SentinelBadge, SentinelChip } from "./SentinelBadge";
 import { SettingsMenu } from "./SettingsMenu";
-import { ReferenceGallery } from "./ReferenceGallery";
+import { StepParamsForm, StepPicker, defaultStepValues } from "./StepEditor";
+import { type StudioToast, Toasts } from "./Toasts";
+import { type Version, type VersionRequest, WorkflowsPanel } from "./WorkflowsPanel";
 import { Icon } from "./icons";
 
 type AssetState = {
@@ -101,14 +103,36 @@ function assetFromSample(s: {
   };
 }
 
-export function StudioShell() {
+export function StudioShell(props: StudioShellProps) {
+  // Resolve the customization props once per change; zero props ⇒ the
+  // built-in catalogue/samples/sentinel/copy (original behavior).
+  // Deps are field-level (not object identity) so idiomatic inline
+  // objects — copy={{...}} / sentinel={{...}} — don't re-mint the
+  // context value every parent render. `tools`/`source` arrays and the
+  // taskDescription function still compare by reference: pass stable
+  // values for those.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: field-level deps are deliberate (see above)
+  const config = useMemo(
+    () => resolveShellConfig(props),
+    [
+      props.tools,
+      props.source,
+      props.sentinel?.enabled,
+      props.sentinel?.taskDescription,
+      JSON.stringify(props.copy ?? null),
+    ],
+  );
+  // Ref mirror for the stable-memo studioHandle closures below.
+  const configRef = useRef(config);
+  configRef.current = config;
+
   const [assets, setAssets] = useState<Record<string, AssetState>>(() => {
     const m: Record<string, AssetState> = {};
-    for (const s of SAMPLES) m[s.id] = assetFromSample(s);
+    for (const s of config.samples) m[s.id] = assetFromSample(s);
     return m;
   });
-  const [order, setOrder] = useState<string[]>(() => SAMPLES.map((s) => s.id));
-  const [activeId, setActiveId] = useState<string | null>(SAMPLES[0]?.id ?? null);
+  const [order, setOrder] = useState<string[]>(() => config.samples.map((s) => s.id));
+  const [activeId, setActiveId] = useState<string | null>(config.samples[0]?.id ?? null);
   const [selected, setSelected] = useState<string | null>(null);
   // Per-run edits to a package workflow. Initialised from the workflow's
   // preset on selection; user reordering/deleting/toggling in the action
@@ -129,10 +153,10 @@ export function StudioShell() {
   // ("custom" when the user typed their own); `value` is the actual
   // prompt that gets injected into the matching prep step at apply
   // time. Both reset when the user switches workflows.
-  const [editedPackageCreativePickId, setEditedPackageCreativePickId] =
-    useState<string | null>(null);
-  const [editedPackageCreativeValue, setEditedPackageCreativeValue] =
-    useState<string>("");
+  const [editedPackageCreativePickId, setEditedPackageCreativePickId] = useState<string | null>(
+    null,
+  );
+  const [editedPackageCreativeValue, setEditedPackageCreativeValue] = useState<string>("");
   const [inputs, setInputs] = useState<Record<string, string>>({});
   const [pin, setPin] = useState<Pin | null>(null);
   const [editText, setEditText] = useState("");
@@ -145,8 +169,25 @@ export function StudioShell() {
   const [extraReferences, setExtraReferences] = useState<File[]>([]);
   const [extraReferencePreviews, setExtraReferencePreviews] = useState<string[]>([]);
   const [referencePrompt, setReferencePrompt] = useState("");
+  // Unmount-only blob-URL cleanup (ref mirror — never revoke while rendered).
+  const previewUrlsRef = useRef<{ primary: string | null; extras: string[] }>({
+    primary: null,
+    extras: [],
+  });
+  previewUrlsRef.current = { primary: referencePreview, extras: extraReferencePreviews };
+  useEffect(
+    () => () => {
+      const p = previewUrlsRef.current;
+      if (p.primary) URL.revokeObjectURL(p.primary);
+      for (const u of p.extras) URL.revokeObjectURL(u);
+    },
+    [],
+  );
   const [brushSize, setBrushSize] = useState(45);
   const [maskCoverage, setMaskCoverage] = useState(0);
+  useEffect(() => {
+    maskCtl.setBrushSize(brushSize);
+  }, [brushSize]);
   const [error, setError] = useState<string | null>(null);
   // Non-blocking edit UX:
   //   - Each Apply synchronously adds a *pending* Version to the asset's
@@ -203,9 +244,14 @@ export function StudioShell() {
 
   const imgRef = useRef<HTMLImageElement>(null);
   const visibleMaskRef = useRef<HTMLCanvasElement>(null);
-  const hiddenMaskRef = useRef<HTMLCanvasElement | null>(null);
-  const drawingRef = useRef(false);
-  const lastPosRef = useRef<{ x: number; y: number } | null>(null);
+  // Brush engine — the same controller exported from ./headless, so the
+  // shell is itself a consumer of the public mask primitive. Lazy init:
+  // the factory allocates closures, no need to redo that per render.
+  const maskCtlRef = useRef<ReturnType<typeof createMaskController> | null>(null);
+  if (maskCtlRef.current === null) {
+    maskCtlRef.current = createMaskController({ brushSize: 45 });
+  }
+  const maskCtl = maskCtlRef.current;
 
   // Always-fresh refs for the studioHandle. The chat agent can dispatch
   // multiple run_workflow calls in sequence, and each subsequent call
@@ -222,7 +268,10 @@ export function StudioShell() {
   const currentVersion = active
     ? active.versions.find((v) => v.id === active.currentVersionId) || active.versions[0]
     : null;
-  const selectedWf = useMemo(() => WORKFLOWS.find((w) => w.id === selected) ?? null, [selected]);
+  const selectedWf = useMemo(
+    () => config.workflows.find((w) => w.id === selected) ?? null,
+    [selected, config.workflows],
+  );
   const isPinning = selectedWf?.kind === "pin" || chatPinMode;
   const isPainting =
     selectedWf?.kind === "mask-only" || selectedWf?.kind === "mask-ref" || chatMaskMode;
@@ -264,10 +313,10 @@ export function StudioShell() {
       return s;
     });
     if (assets[wantAsset]) setActiveId(wantAsset);
-  // We only run this once on mount — `assets` is captured for the
-  // membership check; running it again on `assets` change would clobber
-  // user navigation back into the URL on every state update.
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+    // We only run this once on mount — `assets` is captured for the
+    // membership check; running it again on `assets` change would clobber
+    // user navigation back into the URL on every state update.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   // On change: write asset + version into the URL via replaceState so
@@ -298,24 +347,8 @@ export function StudioShell() {
       const w = Math.round(rect.width);
       const h = Math.round(rect.height);
       if (w === 0 || h === 0) return;
-      const dpr = Math.min(2, window.devicePixelRatio || 1);
-      visible.width = w * dpr;
-      visible.height = h * dpr;
-      visible.style.width = `${w}px`;
-      visible.style.height = `${h}px`;
-      const vctx = visible.getContext("2d");
-      if (!vctx) return;
-      vctx.setTransform(dpr, 0, 0, dpr, 0, 0);
-      vctx.clearRect(0, 0, w, h);
-      const hidden = document.createElement("canvas");
-      hidden.width = w;
-      hidden.height = h;
-      const hctx = hidden.getContext("2d");
-      if (hctx) {
-        hctx.fillStyle = "black";
-        hctx.fillRect(0, 0, w, h);
-      }
-      hiddenMaskRef.current = hidden;
+      maskCtl.attach(visible);
+      maskCtl.syncToDisplay(w, h, window.devicePixelRatio || 1);
       setMaskCoverage(0);
     };
     if (img.complete) sync();
@@ -325,119 +358,33 @@ export function StudioShell() {
     return () => ro.disconnect();
   }, [isPainting, currentVersion?.url]);
 
-  const paintAt = (x: number, y: number) => {
-    const visible = visibleMaskRef.current;
-    const hidden = hiddenMaskRef.current;
-    if (!visible || !hidden) return;
-    const r = brushSize;
-    const vctx = visible.getContext("2d");
-    if (vctx) {
-      vctx.fillStyle = "rgba(251,191,36,0.55)";
-      vctx.beginPath();
-      vctx.arc(x, y, r, 0, Math.PI * 2);
-      vctx.fill();
-    }
-    const hctx = hidden.getContext("2d");
-    if (hctx) {
-      hctx.fillStyle = "white";
-      hctx.beginPath();
-      hctx.arc(x, y, r, 0, Math.PI * 2);
-      hctx.fill();
-    }
-  };
-
-  const updateCoverage = () => {
-    const hidden = hiddenMaskRef.current;
-    if (!hidden) return;
-    const ctx = hidden.getContext("2d");
-    if (!ctx) return;
-    const data = ctx.getImageData(0, 0, hidden.width, hidden.height).data;
-    let white = 0;
-    let total = 0;
-    const step = 8;
-    for (let yy = 0; yy < hidden.height; yy += step) {
-      for (let xx = 0; xx < hidden.width; xx += step) {
-        const i = (yy * hidden.width + xx) * 4;
-        if (data[i] > 200) white += 1;
-        total += 1;
-      }
-    }
-    setMaskCoverage((white / total) * 100);
-  };
-
   const onMaskDown = (e: React.MouseEvent<HTMLCanvasElement>) => {
     if (!isPainting) return;
     e.preventDefault();
     const rect = e.currentTarget.getBoundingClientRect();
-    const p = { x: e.clientX - rect.left, y: e.clientY - rect.top };
-    drawingRef.current = true;
-    lastPosRef.current = p;
-    paintAt(p.x, p.y);
+    maskCtl.beginStroke(e.clientX - rect.left, e.clientY - rect.top);
   };
   const onMaskMove = (e: React.MouseEvent<HTMLCanvasElement>) => {
-    if (!drawingRef.current) return;
+    if (!maskCtl.isStroking()) return;
     const rect = e.currentTarget.getBoundingClientRect();
-    const p = { x: e.clientX - rect.left, y: e.clientY - rect.top };
-    const last = lastPosRef.current;
-    if (last) {
-      const dist = Math.hypot(p.x - last.x, p.y - last.y);
-      const steps = Math.max(1, Math.ceil(dist / (brushSize * 0.4)));
-      for (let i = 1; i <= steps; i++) {
-        const t = i / steps;
-        paintAt(last.x + (p.x - last.x) * t, last.y + (p.y - last.y) * t);
-      }
-    } else {
-      paintAt(p.x, p.y);
-    }
-    lastPosRef.current = p;
+    maskCtl.strokeTo(e.clientX - rect.left, e.clientY - rect.top);
   };
   const onMaskUp = () => {
-    if (drawingRef.current) {
-      drawingRef.current = false;
-      lastPosRef.current = null;
-      updateCoverage();
+    if (maskCtl.isStroking()) {
+      maskCtl.endStroke();
+      setMaskCoverage(maskCtl.coverage());
     }
   };
 
   const clearMask = () => {
-    const visible = visibleMaskRef.current;
-    const hidden = hiddenMaskRef.current;
-    if (visible) {
-      const vctx = visible.getContext("2d");
-      vctx?.clearRect(0, 0, visible.width, visible.height);
-    }
-    if (hidden) {
-      const hctx = hidden.getContext("2d");
-      if (hctx) {
-        hctx.fillStyle = "black";
-        hctx.fillRect(0, 0, hidden.width, hidden.height);
-      }
-    }
+    maskCtl.clear();
     setMaskCoverage(0);
   };
 
   const generateMaskBlob = async (): Promise<Blob | null> => {
     const img = imgRef.current;
-    const hidden = hiddenMaskRef.current;
-    if (!img || !hidden || !img.naturalWidth) return null;
-    const out = document.createElement("canvas");
-    out.width = img.naturalWidth;
-    out.height = img.naturalHeight;
-    const ctx = out.getContext("2d");
-    if (!ctx) return null;
-    ctx.fillStyle = "black";
-    ctx.fillRect(0, 0, out.width, out.height);
-    ctx.drawImage(hidden, 0, 0, out.width, out.height);
-    const id = ctx.getImageData(0, 0, out.width, out.height);
-    for (let i = 0; i < id.data.length; i += 4) {
-      const v = id.data[i] > 127 ? 255 : 0;
-      id.data[i] = v;
-      id.data[i + 1] = v;
-      id.data[i + 2] = v;
-      id.data[i + 3] = 255;
-    }
-    ctx.putImageData(id, 0, 0);
-    return new Promise((resolve) => out.toBlob((b) => resolve(b), "image/png"));
+    if (!img || !img.naturalWidth) return null;
+    return maskCtl.toMaskBlob(img.naturalWidth, img.naturalHeight);
   };
 
   // ---------- Image click for AI-Edit pin (and chat-driven pin) ----------
@@ -483,10 +430,12 @@ export function StudioShell() {
   const onAddReferenceFiles = (files: File[]) => {
     if (files.length === 0) return;
     const remaining = files.slice();
-    if (!reference && remaining.length > 0) {
-      const head = remaining.shift()!;
-      setReference(head);
-      setReferencePreview(URL.createObjectURL(head));
+    if (!reference) {
+      const head = remaining.shift();
+      if (head) {
+        setReference(head);
+        setReferencePreview(URL.createObjectURL(head));
+      }
     }
     if (remaining.length === 0) return;
     const room = MAX_REFERENCES - 1 - extraReferences.length;
@@ -506,7 +455,7 @@ export function StudioShell() {
   };
   const clearAllReferences = () => {
     onReferenceFile(null);
-    extraReferencePreviews.forEach((u) => URL.revokeObjectURL(u));
+    for (const u of extraReferencePreviews) URL.revokeObjectURL(u);
     setExtraReferences([]);
     setExtraReferencePreviews([]);
   };
@@ -550,9 +499,7 @@ export function StudioShell() {
     if (!trimmedPrompt) return;
     const assetId = `gen-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const title =
-      trimmedPrompt.length > 50
-        ? `${trimmedPrompt.slice(0, 50).trim()}…`
-        : trimmedPrompt;
+      trimmedPrompt.length > 50 ? `${trimmedPrompt.slice(0, 50).trim()}…` : trimmedPrompt;
 
     // Build N pending versions up front — the version stripe + canvas
     // skeleton render off these immediately so the user sees "we're
@@ -566,19 +513,16 @@ export function StudioShell() {
       },
     };
     const baseTs = Date.now();
-    const initialVersions: Version[] = Array.from(
-      { length: params.count },
-      (_, i) => ({
-        id: `v${i}`,
-        url: "",
-        label: `Variation ${i + 1}`,
-        ts: baseTs + i,
-        pending: true,
-        pendingKind: "generation",
-        progressMessage: "Drafting…",
-        request: versionRequest,
-      }),
-    );
+    const initialVersions: Version[] = Array.from({ length: params.count }, (_, i) => ({
+      id: `v${i}`,
+      url: "",
+      label: `Variation ${i + 1}`,
+      ts: baseTs + i,
+      pending: true,
+      pendingKind: "generation",
+      progressMessage: "Drafting…",
+      request: versionRequest,
+    }));
 
     const asset: AssetState = {
       id: assetId,
@@ -634,9 +578,7 @@ export function StudioShell() {
               [assetId]: {
                 ...a,
                 versions: a.versions.map((v, i) =>
-                  i === idx
-                    ? { ...v, pending: false, error: result.error }
-                    : v,
+                  i === idx ? { ...v, pending: false, error: result.error } : v,
                 ),
               },
             };
@@ -681,10 +623,8 @@ export function StudioShell() {
         // Sentinel evaluation — same per-version pattern the workflow
         // runs use. Task description is the user's prompt verbatim,
         // exactly what the judges should be scoring against.
-        const sentinelResult = await sentinelEvaluate(
-          result.outputUrl,
-          trimmedPrompt,
-        );
+        if (!configRef.current.sentinel.enabled) return;
+        const sentinelResult = await sentinelEvaluate(result.outputUrl, trimmedPrompt);
         setAssets((s) => {
           const a = s[assetId];
           if (!a) return s;
@@ -777,9 +717,7 @@ export function StudioShell() {
     // so up/down/delete/toggle in the action panel doesn't mutate the
     // workflow definition.
     if (wf.kind === "package" && wf.package) {
-      setEditedPackagePrep(
-        wf.package.prep.map((s) => ({ ...s, params: { ...s.params } })),
-      );
+      setEditedPackagePrep(wf.package.prep.map((s) => ({ ...s, params: { ...s.params } })));
       setEditedPackageVariants(
         (wf.package.variants ?? []).map((v) => ({
           variant: {
@@ -854,8 +792,7 @@ export function StudioShell() {
       suppressErrorToast?: boolean;
     },
   ): Promise<
-    | { ok: true; versionId: string; outputUrl: string; label: string }
-    | { ok: false; error: string }
+    { ok: true; versionId: string; outputUrl: string; label: string } | { ok: false; error: string }
   > => {
     // Unique version id generated up front so concurrent runs can't
     // collide on `v${versions.length}`.
@@ -867,14 +804,12 @@ export function StudioShell() {
     // without having to remember.
     const request: VersionRequest = {
       workflowId: wf.id,
-      ...(dispatch.prompt && dispatch.prompt.trim() ? { prompt: dispatch.prompt.trim() } : {}),
+      ...(dispatch.prompt?.trim() ? { prompt: dispatch.prompt.trim() } : {}),
       ...(dispatch.values && Object.keys(dispatch.values).length
         ? { values: { ...dispatch.values } }
         : {}),
       ...(dispatch.pin ? { pin: dispatch.pin } : {}),
-      ...(typeof dispatch.maskCoverage === "number"
-        ? { maskCoverage: dispatch.maskCoverage }
-        : {}),
+      ...(typeof dispatch.maskCoverage === "number" ? { maskCoverage: dispatch.maskCoverage } : {}),
       ...(dispatch.referenceFile ? { referenceFileName: dispatch.referenceFile.name } : {}),
       sourceUrl,
     };
@@ -885,7 +820,7 @@ export function StudioShell() {
       if (!a) return s;
       const v: Version = {
         id: newVid,
-        url: sourceUrl,            // show source while waiting
+        url: sourceUrl, // show source while waiting
         label: wf.name,
         ts: startedAt,
         pending: true,
@@ -988,9 +923,7 @@ export function StudioShell() {
             [targetAssetId]: {
               ...a,
               versions: a.versions.map((ver) =>
-                ver.id === newVid
-                  ? { ...ver, width: dims.width, height: dims.height }
-                  : ver,
+                ver.id === newVid ? { ...ver, width: dims.width, height: dims.height } : ver,
               ),
             },
           };
@@ -1043,6 +976,25 @@ export function StudioShell() {
       //     the chat agent's tool_result becomes is_error=true and the
       //     model stops kicking off subsequent steps. Amber and green
       //     both pass through; toast still surfaces verdict either way.
+      // Host disabled Sentinel entirely — clear the pending placeholder
+      // so no quality badge renders, and resolve.
+      if (!config.sentinel.enabled) {
+        setAssets((s) => {
+          const a = s[targetAssetId];
+          if (!a) return s;
+          return {
+            ...s,
+            [targetAssetId]: {
+              ...a,
+              versions: a.versions.map((ver) =>
+                ver.id === newVid ? { ...ver, sentinel: undefined } : ver,
+              ),
+            },
+          };
+        });
+        return { ok: true, versionId: newVid, outputUrl, label: wf.name };
+      }
+
       const settings = getStudioSettings();
       const isIntermediate = !!dispatch.intermediate;
       const gateThis = isIntermediate && settings.gateBetweenSteps;
@@ -1067,7 +1019,7 @@ export function StudioShell() {
         return { ok: true, versionId: newVid, outputUrl, label: wf.name };
       }
 
-      const taskDesc = sentinelTaskDescription(wf.id, dispatch.values, dispatch.prompt);
+      const taskDesc = config.sentinel.taskDescription(wf.id, dispatch.values, dispatch.prompt);
       const sentinelPromise = sentinelEvaluate(outputUrl, taskDesc, sourceUrl);
 
       // Gating mode: await the verdict so we can halt the chain on red.
@@ -1082,9 +1034,7 @@ export function StudioShell() {
             ...s,
             [targetAssetId]: {
               ...a,
-              versions: a.versions.map((ver) =>
-                ver.id === newVid ? { ...ver, sentinel } : ver,
-              ),
+              versions: a.versions.map((ver) => (ver.id === newVid ? { ...ver, sentinel } : ver)),
             },
           };
         });
@@ -1142,9 +1092,7 @@ export function StudioShell() {
             ...s,
             [targetAssetId]: {
               ...a,
-              versions: a.versions.map((ver) =>
-                ver.id === newVid ? { ...ver, sentinel } : ver,
-              ),
+              versions: a.versions.map((ver) => (ver.id === newVid ? { ...ver, sentinel } : ver)),
             },
           };
         });
@@ -1235,6 +1183,7 @@ export function StudioShell() {
   // between assets and versions. Idempotency guard: if a retry is
   // already in flight for this version, the second click no-ops.
   const onRetrySentinel = (versionId: string) => {
+    if (!config.sentinel.enabled) return;
     if (sentinelRetrying[versionId]) return;
     // Locate the version + asset once up front; if either's gone we
     // can't retry. (Covers the edge case of a deleted asset between
@@ -1281,7 +1230,7 @@ export function StudioShell() {
       };
     });
 
-    const taskDesc = sentinelTaskDescription(req.workflowId, req.values ?? {}, req.prompt);
+    const taskDesc = config.sentinel.taskDescription(req.workflowId, req.values ?? {}, req.prompt);
     void sentinelEvaluate(ver.url, taskDesc, req.sourceUrl).then((sentinel) => {
       setAssets((s) => {
         const a = s[targetAssetId];
@@ -1290,9 +1239,7 @@ export function StudioShell() {
           ...s,
           [targetAssetId]: {
             ...a,
-            versions: a.versions.map((v) =>
-              v.id === versionId ? { ...v, sentinel } : v,
-            ),
+            versions: a.versions.map((v) => (v.id === versionId ? { ...v, sentinel } : v)),
           },
         };
       });
@@ -1348,7 +1295,11 @@ export function StudioShell() {
   ) => {
     const targetAssetId = activeIdRef.current;
     if (!targetAssetId) {
-      addToast({ kind: "error", title: "Pick a photo first", body: "No active asset to replay onto." });
+      addToast({
+        kind: "error",
+        title: "Pick a photo first",
+        body: "No active asset to replay onto.",
+      });
       return;
     }
     if (isMobileRef.current) setRightOpenMobile(false);
@@ -1364,7 +1315,7 @@ export function StudioShell() {
     for (let i = 0; i < custom.steps.length; i += 1) {
       const step = custom.steps[i];
       const isLast = i === custom.steps.length - 1;
-      const wf = WORKFLOWS.find((w) => w.id === step.workflowId);
+      const wf = config.workflows.find((w) => w.id === step.workflowId);
       if (!wf || wf.kind === "soon") {
         addToast({
           kind: "error",
@@ -1376,7 +1327,11 @@ export function StudioShell() {
       const asset = assetsRef.current[targetAssetId];
       const sourceUrl = asset?.versions.find((v) => v.id === asset.currentVersionId)?.url;
       if (!sourceUrl) {
-        addToast({ kind: "error", title: `${custom.name} halted`, body: "Lost the current version URL between steps." });
+        addToast({
+          kind: "error",
+          title: `${custom.name} halted`,
+          body: "Lost the current version URL between steps.",
+        });
         return;
       }
       // Apply overrides only to the final step (per UX spec). Other
@@ -1454,12 +1409,10 @@ export function StudioShell() {
     // enabled, all prep steps run intermediate=true since the actual
     // Sentinel-scored outputs are the variants downstream.
     let prepUrl = sourceUrl;
-    let prepFinal:
-      | { versionId: string; outputUrl: string; label: string }
-      | null = null;
+    let prepFinal: { versionId: string; outputUrl: string; label: string } | null = null;
     for (let i = 0; i < prep.length; i++) {
       const step = prep[i];
-      const stepWf = WORKFLOWS.find((w) => w.id === step.workflowId);
+      const stepWf = config.workflows.find((w) => w.id === step.workflowId);
       if (!stepWf) {
         const err = `Prep step ${i + 1}: unknown workflow ${step.workflowId}`;
         addToast({
@@ -1508,7 +1461,7 @@ export function StudioShell() {
         let vUrl = prepUrl;
         for (let i = 0; i < variant.steps.length; i++) {
           const step = variant.steps[i];
-          const stepWf = WORKFLOWS.find((w) => w.id === step.workflowId);
+          const stepWf = config.workflows.find((w) => w.id === step.workflowId);
           if (!stepWf) {
             addToast({
               kind: "error",
@@ -1624,9 +1577,8 @@ export function StudioShell() {
   // Pending versions are skipped: landing on one shows the source image
   // until the run completes, which is confusing.
   const versionList = active?.versions ?? [];
-  const versionIndex = active && currentVersion
-    ? versionList.findIndex((v) => v.id === currentVersion.id)
-    : -1;
+  const versionIndex =
+    active && currentVersion ? versionList.findIndex((v) => v.id === currentVersion.id) : -1;
   const stepVersion = (dir: -1 | 1): Version | null => {
     if (versionIndex < 0) return null;
     let i = versionIndex + dir;
@@ -1651,7 +1603,7 @@ export function StudioShell() {
   const onShare = async () => {
     const url = typeof window !== "undefined" ? window.location.href : "";
     if (!url) return;
-    const isSample = activeId ? SAMPLES.some((s) => s.id === activeId) : false;
+    const isSample = activeId ? config.samples.some((s) => s.id === activeId) : false;
     try {
       await navigator.clipboard.writeText(url);
       addToast({
@@ -1802,8 +1754,7 @@ export function StudioShell() {
     // creative-direction picker require the user to have picked or
     // typed a value (campaign-pack today).
     if (selectedWf.kind === "package") {
-      const hasSteps =
-        editedPackagePrep.length > 0 || editedPackageVariants.some((v) => v.enabled);
+      const hasSteps = editedPackagePrep.length > 0 || editedPackageVariants.some((v) => v.enabled);
       if (!hasSteps) return false;
       if (selectedWf.package?.creativeDirection) {
         return editedPackageCreativeValue.trim().length > 0;
@@ -1816,7 +1767,7 @@ export function StudioShell() {
     if (selectedWf.id === "topaz-upscale") {
       const w = currentVersion?.width;
       const h = currentVersion?.height;
-      const factor = parseFloat(inputs.upscale_factor || "2");
+      const factor = Number.parseFloat(inputs.upscale_factor || "2");
       if (w && h && topazExceedsCap(w, h, factor)) return false;
     }
     return true;
@@ -1937,7 +1888,7 @@ export function StudioShell() {
           setChatStageHint(hint || "Brush over the area, then click Confirm mask.");
         }),
       runWorkflow: async (workflowId, params, captured, opts) => {
-        const wf = WORKFLOWS.find((w) => w.id === workflowId);
+        const wf = configRef.current.workflows.find((w) => w.id === workflowId);
         if (!wf) return { ok: false, error: `Unknown workflow: ${workflowId}` };
         if (wf.kind === "soon") return { ok: false, error: `${wf.name} isn't shipped yet.` };
         const targetAssetId = activeIdRef.current;
@@ -1964,9 +1915,7 @@ export function StudioShell() {
           // prep step. If neither is present, return a structured
           // error the agent can recover from by calling request_text.
           const direction = wf.package?.creativeDirection;
-          const directionPrompt = direction
-            ? (params.prompt || captured.text || "").trim()
-            : "";
+          const directionPrompt = direction ? (params.prompt || captured.text || "").trim() : "";
           if (direction && !directionPrompt) {
             return {
               ok: false,
@@ -1974,10 +1923,7 @@ export function StudioShell() {
             };
           }
           const presetPrep = (wf.package?.prep ?? []).map((step) => {
-            if (
-              direction &&
-              step.workflowId === direction.injectAt.workflowIdMatch
-            ) {
+            if (direction && step.workflowId === direction.injectAt.workflowIdMatch) {
               return {
                 ...step,
                 params: {
@@ -2069,443 +2015,486 @@ export function StudioShell() {
 
   const selectedActionFooter = selectedWf ? (
     <>
-      <button className="rfs-btn" onClick={resetSelection}>
+      <button type="button" className="rfs-btn" onClick={resetSelection}>
         Cancel
       </button>
-      <button className="rfs-btn rfs-btn-primary" onClick={onApply} disabled={!canApply}>
+      <button
+        type="button"
+        className="rfs-btn rfs-btn-primary"
+        onClick={onApply}
+        disabled={!canApply}
+      >
         Apply
       </button>
     </>
   ) : null;
 
   return (
-    <div
-      className={`rfs-root${leftCollapsed ? " is-rail-collapsed" : ""}${rightOpenMobile ? " is-right-open" : ""}`}
-    >
-      <header className="rfs-header">
-        <div style={{ display: "flex", alignItems: "center", gap: "0.5rem" }}>
-          <button
-            className="rfs-iconbtn"
-            onClick={() => setLeftCollapsed((v) => !v)}
-            title={leftCollapsed ? "Show assets" : "Hide assets"}
-            aria-label={leftCollapsed ? "Show assets" : "Hide assets"}
-          >
-            {leftCollapsed ? Icon.sidebarShow : Icon.sidebarHide}
-          </button>
-          <div className="rfs-brand">
-            <span className="rfs-brand-mark" aria-hidden />
-            <span className="rfs-brand-name">
-              Run<span>flow</span>
-            </span>
-            <span className="rfs-brand-tag">BETA</span>
-          </div>
-          <div className="rfs-project">
-            <span style={{ color: "var(--rfs-bg-3)" }}>/</span>
-            {editingName && active ? (
-              <input
-                className="rfs-project-name-input"
-                autoFocus
-                value={nameDraft}
-                onChange={(e) => setNameDraft(e.target.value)}
-                onBlur={() => {
-                  const next = nameDraft.trim();
-                  if (active && next && next !== active.title) {
-                    setAssets((s) => ({
-                      ...s,
-                      [active.id]: { ...s[active.id], title: next },
-                    }));
-                  }
-                  setEditingName(false);
-                }}
-                onKeyDown={(e) => {
-                  if (e.key === "Enter") (e.currentTarget as HTMLInputElement).blur();
-                  if (e.key === "Escape") {
-                    setEditingName(false);
-                    setNameDraft(active?.title ?? "");
-                  }
-                }}
-                maxLength={80}
-              />
-            ) : (
-              <button
-                className="rfs-project-name"
-                onClick={() => {
-                  if (!active) return;
-                  setNameDraft(active.title);
-                  setEditingName(true);
-                }}
-                disabled={!active}
-                title="Click to rename"
-              >
-                {active?.title ?? "Untitled"}
-              </button>
-            )}
-          </div>
-        </div>
-        <div className="rfs-header-right">
-          <button
-            className="rfs-iconbtn"
-            onClick={onUndo}
-            disabled={!undoTarget}
-            title={undoTarget ? `Undo to ${undoTarget.label}` : "Nothing to undo"}
-            aria-label="Step to previous version"
-          >
-            {Icon.undo}
-          </button>
-          <button
-            className="rfs-iconbtn"
-            onClick={onRedo}
-            disabled={!redoTarget}
-            title={redoTarget ? `Redo to ${redoTarget.label}` : "Nothing to redo"}
-            aria-label="Step to next version"
-          >
-            {Icon.redo}
-          </button>
-          <SettingsMenu />
-          <button className="rfs-btn" onClick={onShare} disabled={!active} title="Copy link to this view">
-            {Icon.share}
-            Share
-          </button>
-          <button
-            className="rfs-btn rfs-btn-primary"
-            disabled={!currentVersion}
-            onClick={onExport}
-          >
-            {Icon.download}
-            Export
-          </button>
-          <span className="rfs-avatar">RG</span>
-        </div>
-      </header>
-
-      <aside className="rfs-left">
-        {generateOpen ? (
-          (() => {
-            // Derive the "in-flight" summary from the active asset
-            // when it's a generation session — we just look at the
-            // current asset's pending versions. If the user navigated
-            // away (e.g. picked a sample) we treat the panel as idle
-            // again. Surface count + prompt so the GeneratePanel's
-            // summary can show "Generating 4 variations: <prompt>".
-            const generatingActive = !!(
-              active &&
-              active.tags?.includes("generated") &&
-              active.versions.some((v) => v.pending)
-            );
-            const inFlightCount =
-              generatingActive && active
-                ? active.versions.filter((v) => v.pending).length
-                : 0;
-            const inFlightPrompt =
-              generatingActive && active
-                ? active.versions[0]?.request?.prompt ?? ""
-                : "";
-            return (
-              <GeneratePanel
-                onClose={() => setGenerateOpen(false)}
-                onGenerate={dispatchGenerationSession}
-                inFlight={generatingActive}
-                inFlightCount={inFlightCount}
-                inFlightPrompt={inFlightPrompt}
-              />
-            );
-          })()
-        ) : (
-          <>
-            <div className="rfs-left-header">
-              <span className="rfs-left-title">Assets</span>
-              <span className="rfs-left-title" style={{ letterSpacing: 0, textTransform: "none", fontWeight: 500 }}>
-                {order.length}
+    <ShellConfigProvider value={config}>
+      <div
+        className={`rfs-root${leftCollapsed ? " is-rail-collapsed" : ""}${rightOpenMobile ? " is-right-open" : ""}`}
+      >
+        <header className="rfs-header">
+          <div style={{ display: "flex", alignItems: "center", gap: "0.5rem" }}>
+            <button
+              type="button"
+              className="rfs-iconbtn"
+              onClick={() => setLeftCollapsed((v) => !v)}
+              title={leftCollapsed ? "Show assets" : "Hide assets"}
+              aria-label={leftCollapsed ? "Show assets" : "Hide assets"}
+            >
+              {leftCollapsed ? Icon.sidebarShow : Icon.sidebarHide}
+            </button>
+            <div className="rfs-brand">
+              <span className="rfs-brand-mark" aria-hidden />
+              <span className="rfs-brand-name">
+                {config.copy.brandName === "Runflow" ? (
+                  <>
+                    Run<span>flow</span>
+                  </>
+                ) : (
+                  config.copy.brandName
+                )}
               </span>
+              {config.copy.brandTag ? (
+                <span className="rfs-brand-tag">{config.copy.brandTag}</span>
+              ) : null}
             </div>
-            {/* "+ New asset" splits two ways. Upload accepts a local
-                file (the existing path); Generate flips the rail into
-                the GeneratePanel for text-to-image. The user never
-                picks a model — the gateway maps resolution → tier. */}
-            <div className="rfs-left-newasset">
-              <label className="rfs-left-newasset-btn">
-                {Icon.upload}
-                Upload
+            <div className="rfs-project">
+              <span style={{ color: "var(--rfs-bg-3)" }}>/</span>
+              {editingName && active ? (
                 <input
-                  type="file"
-                  accept="image/png,image/jpeg,image/webp"
-                  onChange={(e) => {
-                    const f = e.target.files?.[0];
-                    if (f) onUploadAsset(f);
-                    e.currentTarget.value = "";
+                  className="rfs-project-name-input"
+                  autoFocus
+                  value={nameDraft}
+                  onChange={(e) => setNameDraft(e.target.value)}
+                  onBlur={() => {
+                    const next = nameDraft.trim();
+                    if (active && next && next !== active.title) {
+                      setAssets((s) => ({
+                        ...s,
+                        [active.id]: { ...s[active.id], title: next },
+                      }));
+                    }
+                    setEditingName(false);
+                  }}
+                  onKeyDown={(e) => {
+                    if (e.key === "Enter") (e.currentTarget as HTMLInputElement).blur();
+                    if (e.key === "Escape") {
+                      setEditingName(false);
+                      setNameDraft(active?.title ?? "");
+                    }
                   }}
+                  maxLength={80}
                 />
-              </label>
-              <button
-                type="button"
-                className="rfs-left-newasset-btn rfs-left-newasset-generate"
-                onClick={() => setGenerateOpen(true)}
-                title="Generate new images from a prompt"
-              >
-                {Icon.generate}
-                Generate
-              </button>
+              ) : (
+                <button
+                  type="button"
+                  className="rfs-project-name"
+                  onClick={() => {
+                    if (!active) return;
+                    setNameDraft(active.title);
+                    setEditingName(true);
+                  }}
+                  disabled={!active}
+                  title="Click to rename"
+                >
+                  {active?.title ?? "Untitled"}
+                </button>
+              )}
             </div>
-            <div className="rfs-asset-list">
-              {order.map((id) => {
-                const a = assets[id];
-                if (!a) return null;
-                // Pick the freshest URL we have. For a generation
-                // session where v0 is still pending, the FIRST resolved
-                // version (anywhere in the array) is what we want — so
-                // walk back-to-front and grab the first non-empty url.
-                // Falls back to baseUrl, then empty.
-                const thumbUrl =
-                  [...a.versions].reverse().find((v) => v.url)?.url ??
-                  a.baseUrl ??
-                  "";
-                const allPending = a.versions.every((v) => v.pending);
+          </div>
+          <div className="rfs-header-right">
+            <button
+              type="button"
+              className="rfs-iconbtn"
+              onClick={onUndo}
+              disabled={!undoTarget}
+              title={undoTarget ? `Undo to ${undoTarget.label}` : "Nothing to undo"}
+              aria-label="Step to previous version"
+            >
+              {Icon.undo}
+            </button>
+            <button
+              type="button"
+              className="rfs-iconbtn"
+              onClick={onRedo}
+              disabled={!redoTarget}
+              title={redoTarget ? `Redo to ${redoTarget.label}` : "Nothing to redo"}
+              aria-label="Step to next version"
+            >
+              {Icon.redo}
+            </button>
+            <SettingsMenu />
+            <button
+              type="button"
+              className="rfs-btn"
+              onClick={onShare}
+              disabled={!active}
+              title="Copy link to this view"
+            >
+              {Icon.share}
+              Share
+            </button>
+            <button
+              type="button"
+              className="rfs-btn rfs-btn-primary"
+              disabled={!currentVersion}
+              onClick={onExport}
+            >
+              {Icon.download}
+              Export
+            </button>
+            {config.copy.avatarInitials ? (
+              <span className="rfs-avatar">{config.copy.avatarInitials}</span>
+            ) : null}
+          </div>
+        </header>
+
+        <aside className="rfs-left">
+          {generateOpen ? (
+            (() => {
+              // Derive the "in-flight" summary from the active asset
+              // when it's a generation session — we just look at the
+              // current asset's pending versions. If the user navigated
+              // away (e.g. picked a sample) we treat the panel as idle
+              // again. Surface count + prompt so the GeneratePanel's
+              // summary can show "Generating 4 variations: <prompt>".
+              const generatingActive = !!(
+                active?.tags?.includes("generated") && active.versions.some((v) => v.pending)
+              );
+              const inFlightCount =
+                generatingActive && active ? active.versions.filter((v) => v.pending).length : 0;
+              const inFlightPrompt =
+                generatingActive && active ? (active.versions[0]?.request?.prompt ?? "") : "";
+              return (
+                <GeneratePanel
+                  onClose={() => setGenerateOpen(false)}
+                  onGenerate={dispatchGenerationSession}
+                  inFlight={generatingActive}
+                  inFlightCount={inFlightCount}
+                  inFlightPrompt={inFlightPrompt}
+                />
+              );
+            })()
+          ) : (
+            <>
+              <div className="rfs-left-header">
+                <span className="rfs-left-title">{config.copy.assetsTitle}</span>
+                <span
+                  className="rfs-left-title"
+                  style={{ letterSpacing: 0, textTransform: "none", fontWeight: 500 }}
+                >
+                  {order.length}
+                </span>
+              </div>
+              {/* "+ New asset" splits two ways. Upload accepts a local
+                file (the existing path); Generate flips the rail into
+                the GeneratePanel for text-to-image. The user never
+                picks a model — the gateway maps resolution → tier. */}
+              <div className="rfs-left-newasset">
+                <label className="rfs-left-newasset-btn">
+                  {Icon.upload}
+                  Upload
+                  <input
+                    type="file"
+                    accept="image/png,image/jpeg,image/webp"
+                    onChange={(e) => {
+                      const f = e.target.files?.[0];
+                      if (f) onUploadAsset(f);
+                      e.currentTarget.value = "";
+                    }}
+                  />
+                </label>
+                <button
+                  type="button"
+                  className="rfs-left-newasset-btn rfs-left-newasset-generate"
+                  onClick={() => setGenerateOpen(true)}
+                  title="Generate new images from a prompt"
+                >
+                  {Icon.generate}
+                  Generate
+                </button>
+              </div>
+              <div className="rfs-asset-list">
+                {order.map((id) => {
+                  const a = assets[id];
+                  if (!a) return null;
+                  // Pick the freshest URL we have. For a generation
+                  // session where v0 is still pending, the FIRST resolved
+                  // version (anywhere in the array) is what we want — so
+                  // walk back-to-front and grab the first non-empty url.
+                  // Falls back to baseUrl, then empty.
+                  const thumbUrl =
+                    [...a.versions].reverse().find((v) => v.url)?.url ?? a.baseUrl ?? "";
+                  const allPending = a.versions.every((v) => v.pending);
+                  return (
+                    <button
+                      type="button"
+                      key={id}
+                      className={`rfs-asset${id === activeId ? " is-current" : ""}${allPending ? " is-pending" : ""}`}
+                      onClick={() => onSelectAsset(id)}
+                      title={a.title}
+                    >
+                      {thumbUrl ? (
+                        <img src={thumbUrl} alt={a.title} />
+                      ) : (
+                        <span className="rfs-asset-skeleton" aria-hidden />
+                      )}
+                      {a.versions.length > 1 ? (
+                        <span
+                          className="rfs-asset-count"
+                          aria-label={`${a.versions.length} versions`}
+                        >
+                          {a.versions.length}
+                        </span>
+                      ) : null}
+                    </button>
+                  );
+                })}
+              </div>
+            </>
+          )}
+        </aside>
+
+        <main className="rfs-center">
+          <StudioCanvas
+            emptyTitle={config.copy.emptyTitle}
+            emptySubtitle={config.copy.emptySubtitle}
+            imageUrl={currentVersion?.url ?? null}
+            imageTitle={active?.title ?? "Untitled"}
+            imageWidth={currentVersion?.width}
+            imageHeight={currentVersion?.height}
+            requestedResolution={currentVersion?.request?.values?.resolution}
+            imgRef={imgRef}
+            isPinning={isPinning}
+            isPainting={isPainting}
+            pin={pin}
+            onImageClick={onImageClick}
+            brushCanvasRef={visibleMaskRef}
+            onMaskDown={onMaskDown}
+            onMaskMove={onMaskMove}
+            onMaskUp={onMaskUp}
+            brushSize={brushSize}
+            onBrushSize={setBrushSize}
+            maskCoverage={maskCoverage}
+            onClearMask={clearMask}
+            hint={stageHint}
+            pending={currentPending}
+            pendingLabel={currentVersion?.label ?? null}
+            pendingWorkflowId={currentVersion?.request?.workflowId ?? null}
+            pendingKind={currentVersion?.pendingKind}
+            pendingPrompt={currentVersion?.request?.prompt ?? null}
+            error={
+              // Two error sources land in the canvas:
+              //   1. A workflow run error (`error` state, set by the
+              //      action panel's apply path)
+              //   2. A version-level error (e.g. a failed generation
+              //      variation — the version has `error` set and an
+              //      empty url, so the canvas needs to show "couldn't
+              //      generate" instead of falling through to the cold
+              //      empty state)
+              error ?? currentVersion?.error ?? null
+            }
+            sentinelBadge={
+              currentVersion?.sentinel ? (
+                <SentinelBadge
+                  result={currentVersion.sentinel}
+                  open={sentinelOpen}
+                  onToggle={() => setSentinelOpen((v) => !v)}
+                  versionId={currentVersion.id}
+                  onRetry={
+                    currentVersion.request ? () => onRetrySentinel(currentVersion.id) : undefined
+                  }
+                  retryInFlight={!!sentinelRetrying[currentVersion.id]}
+                />
+              ) : config.sentinel.enabled &&
+                currentVersion?.request &&
+                !currentVersion.error &&
+                !currentVersion.pending ? (
+                // Intermediate step that bypassed Sentinel — surface a
+                // muted badge so the user knows quality wasn't checked
+                // (rather than the badge silently disappearing).
+                <div
+                  className="rfs-sentinel-badge is-skipped"
+                  title="Sentinel skipped on this intermediate step. Toggle “Run Sentinel between steps” in Settings to gate every step."
+                >
+                  <span className="rfs-sentinel-dot is-failed" />
+                  <span>Sentinel skipped</span>
+                </div>
+              ) : null
+            }
+            chatMaskMode={chatMaskMode}
+            chatPinMode={chatPinMode}
+            onConfirmChatMask={onConfirmChatMask}
+            onCancelChatMask={onCancelChatMask}
+            onCancelChatPin={onCancelChatPin}
+            onOpenCompare={() => setCompareOpen(true)}
+            compareEnabled={(active?.versions.length ?? 0) >= 2}
+            onDownloadAll={onDownloadAll}
+            canDownloadAll={canDownloadAll}
+          />
+          {active ? (
+            <div className="rfs-version-stripe">
+              <span className="rfs-version-stripe-label">Versions</span>
+              {active.versions.map((v) => {
+                const bucket =
+                  !v.pending && v.width && v.height
+                    ? displayBucket(v.width, v.height, v.request?.values?.resolution)
+                    : null;
+                const dimSuffix =
+                  !v.pending && v.width && v.height ? ` · ${v.width}×${v.height}` : "";
+                // Intermediate steps that bypassed Sentinel (gating off,
+                // not the final step) end up with no sentinel + no error.
+                // Original v0 has no `request` and shouldn't get a chip.
+                const isIntermediateSkipped = !v.pending && !v.error && !v.sentinel && !!v.request;
                 return (
                   <button
-                    key={id}
-                    className={`rfs-asset${id === activeId ? " is-current" : ""}${allPending ? " is-pending" : ""}`}
-                    onClick={() => onSelectAsset(id)}
-                    title={a.title}
+                    type="button"
+                    key={v.id}
+                    className={`rfs-version-thumb${v.id === active.currentVersionId ? " is-current" : ""}${v.pending ? " is-pending" : ""}${v.error ? " is-error" : ""}${v.sentinel && !v.pending ? ` sentinel-${v.sentinel.state}` : ""}`}
+                    onClick={() => onPickVersion(v.id)}
+                    title={
+                      v.error
+                        ? `${v.label} — ${v.error}`
+                        : `${compactSummary(v.label, v.request)}${dimSuffix}`
+                    }
                   >
-                    {thumbUrl ? (
-                      <img src={thumbUrl} alt={a.title} />
+                    {v.url ? (
+                      <img src={v.url} alt={v.label} />
                     ) : (
-                      <span className="rfs-asset-skeleton" aria-hidden />
+                      // Generation pending versions have no URL until the
+                      // model returns. Skeleton block instead of a broken
+                      // <img> while the spinner overlay (below) carries
+                      // the "still working" signal.
+                      <span className="rfs-version-thumb-skeleton" aria-hidden />
                     )}
-                    {a.versions.length > 1 ? (
-                      <span className="rfs-asset-count" aria-label={`${a.versions.length} versions`}>
-                        {a.versions.length}
+                    <span className="rfs-version-thumb-label">{v.label}</span>
+                    {bucket ? (
+                      <span
+                        className={`rfs-version-thumb-res rfs-version-thumb-res-${bucket.toLowerCase()}`}
+                        aria-label={`${v.width}×${v.height} pixels`}
+                      >
+                        {bucket}
+                      </span>
+                    ) : null}
+                    {v.sentinel || isIntermediateSkipped ? (
+                      <span className="rfs-version-thumb-sentinel">
+                        <SentinelChip
+                          result={v.sentinel}
+                          skipped={isIntermediateSkipped}
+                          size="xs"
+                        />
+                      </span>
+                    ) : null}
+                    {v.pending ? (
+                      <span className="rfs-version-thumb-spinner" aria-hidden>
+                        <span className="rfs-version-thumb-spinner-ring" />
                       </span>
                     ) : null}
                   </button>
                 );
               })}
             </div>
-          </>
-        )}
-      </aside>
-
-      <main className="rfs-center">
-        <StudioCanvas
-          imageUrl={currentVersion?.url ?? null}
-          imageTitle={active?.title ?? "Untitled"}
-          imageWidth={currentVersion?.width}
-          imageHeight={currentVersion?.height}
-          requestedResolution={currentVersion?.request?.values?.resolution}
-          imgRef={imgRef}
-          isPinning={isPinning}
-          isPainting={isPainting}
-          pin={pin}
-          onImageClick={onImageClick}
-          brushCanvasRef={visibleMaskRef}
-          onMaskDown={onMaskDown}
-          onMaskMove={onMaskMove}
-          onMaskUp={onMaskUp}
-          brushSize={brushSize}
-          onBrushSize={setBrushSize}
-          maskCoverage={maskCoverage}
-          onClearMask={clearMask}
-          hint={stageHint}
-          pending={currentPending}
-          pendingLabel={currentVersion?.label ?? null}
-          pendingWorkflowId={currentVersion?.request?.workflowId ?? null}
-          pendingKind={currentVersion?.pendingKind}
-          pendingPrompt={currentVersion?.request?.prompt ?? null}
-          error={
-            // Two error sources land in the canvas:
-            //   1. A workflow run error (`error` state, set by the
-            //      action panel's apply path)
-            //   2. A version-level error (e.g. a failed generation
-            //      variation — the version has `error` set and an
-            //      empty url, so the canvas needs to show "couldn't
-            //      generate" instead of falling through to the cold
-            //      empty state)
-            error ?? currentVersion?.error ?? null
-          }
-          sentinelBadge={
-            currentVersion?.sentinel ? (
-              <SentinelBadge
-                result={currentVersion.sentinel}
-                open={sentinelOpen}
-                onToggle={() => setSentinelOpen((v) => !v)}
-                versionId={currentVersion.id}
-                onRetry={
-                  currentVersion.request
-                    ? () => onRetrySentinel(currentVersion.id)
-                    : undefined
-                }
-                retryInFlight={!!sentinelRetrying[currentVersion.id]}
-              />
-            ) : currentVersion?.request && !currentVersion.error && !currentVersion.pending ? (
-              // Intermediate step that bypassed Sentinel — surface a
-              // muted badge so the user knows quality wasn't checked
-              // (rather than the badge silently disappearing).
-              <div className="rfs-sentinel-badge is-skipped" title="Sentinel skipped on this intermediate step. Toggle “Run Sentinel between steps” in Settings to gate every step.">
-                <span className="rfs-sentinel-dot is-failed" />
-                <span>Sentinel skipped</span>
-              </div>
-            ) : null
+          ) : null}
+        </main>
+
+        <WorkflowsPanel
+          selectedWorkflowId={selected}
+          onSelectWorkflow={onSelectWorkflow}
+          onClearWorkflowSelection={resetSelection}
+          photoTags={active?.tags ?? []}
+          recommendedWorkflowIds={active?.recommendedWorkflows ?? []}
+          versions={active?.versions ?? []}
+          currentVersionId={active?.currentVersionId ?? "v0"}
+          onPickVersion={onPickVersion}
+          selectedActionContent={selectedActionContent}
+          selectedActionFooter={selectedActionFooter}
+          selectedActionMeta={
+            selectedWf
+              ? { name: selectedWf.name, desc: selectedWf.desc, iconKey: selectedWf.id }
+              : null
           }
-          chatMaskMode={chatMaskMode}
-          chatPinMode={chatPinMode}
-          onConfirmChatMask={onConfirmChatMask}
-          onCancelChatMask={onCancelChatMask}
-          onCancelChatPin={onCancelChatPin}
-          onOpenCompare={() => setCompareOpen(true)}
-          compareEnabled={(active?.versions.length ?? 0) >= 2}
-          onDownloadAll={onDownloadAll}
-          canDownloadAll={canDownloadAll}
+          studioHandle={studioHandle}
+          activeAssetId={activeId}
+          onRunCustom={runCustomWorkflow}
+          onSelectAsset={onSelectAsset}
         />
-        {active ? (
-          <div className="rfs-version-stripe">
-            <span className="rfs-version-stripe-label">Versions</span>
-            {active.versions.map((v) => {
-              const bucket =
-                !v.pending && v.width && v.height
-                  ? displayBucket(v.width, v.height, v.request?.values?.resolution)
-                  : null;
-              const dimSuffix =
-                !v.pending && v.width && v.height ? ` · ${v.width}×${v.height}` : "";
-              // Intermediate steps that bypassed Sentinel (gating off,
-              // not the final step) end up with no sentinel + no error.
-              // Original v0 has no `request` and shouldn't get a chip.
-              const isIntermediateSkipped =
-                !v.pending && !v.error && !v.sentinel && !!v.request;
-              return (
-                <button
-                  key={v.id}
-                  className={`rfs-version-thumb${v.id === active.currentVersionId ? " is-current" : ""}${v.pending ? " is-pending" : ""}${v.error ? " is-error" : ""}${v.sentinel && !v.pending ? ` sentinel-${v.sentinel.state}` : ""}`}
-                  onClick={() => onPickVersion(v.id)}
-                  title={
-                    v.error
-                      ? `${v.label} — ${v.error}`
-                      : `${compactSummary(v.label, v.request)}${dimSuffix}`
-                  }
-                >
-                  {v.url ? (
-                    <img src={v.url} alt={v.label} />
-                  ) : (
-                    // Generation pending versions have no URL until the
-                    // model returns. Skeleton block instead of a broken
-                    // <img> while the spinner overlay (below) carries
-                    // the "still working" signal.
-                    <span className="rfs-version-thumb-skeleton" aria-hidden />
-                  )}
-                  <span className="rfs-version-thumb-label">{v.label}</span>
-                  {bucket ? (
-                    <span
-                      className={`rfs-version-thumb-res rfs-version-thumb-res-${bucket.toLowerCase()}`}
-                      aria-label={`${v.width}×${v.height} pixels`}
-                    >
-                      {bucket}
-                    </span>
-                  ) : null}
-                  {v.sentinel || isIntermediateSkipped ? (
-                    <span className="rfs-version-thumb-sentinel">
-                      <SentinelChip
-                        result={v.sentinel}
-                        skipped={isIntermediateSkipped}
-                        size="xs"
-                      />
-                    </span>
-                  ) : null}
-                  {v.pending ? (
-                    <span className="rfs-version-thumb-spinner" aria-hidden>
-                      <span className="rfs-version-thumb-spinner-ring" />
-                    </span>
-                  ) : null}
-                </button>
-              );
-            })}
-          </div>
-        ) : null}
-      </main>
-
-      <WorkflowsPanel
-        selectedWorkflowId={selected}
-        onSelectWorkflow={onSelectWorkflow}
-        onClearWorkflowSelection={resetSelection}
-        photoTags={active?.tags ?? []}
-        recommendedWorkflowIds={active?.recommendedWorkflows ?? []}
-        versions={active?.versions ?? []}
-        currentVersionId={active?.currentVersionId ?? "v0"}
-        onPickVersion={onPickVersion}
-        selectedActionContent={selectedActionContent}
-        selectedActionFooter={selectedActionFooter}
-        selectedActionMeta={
-          selectedWf
-            ? { name: selectedWf.name, desc: selectedWf.desc, iconKey: selectedWf.id }
-            : null
-        }
-        studioHandle={studioHandle}
-        activeAssetId={activeId}
-        onRunCustom={runCustomWorkflow}
-        onSelectAsset={onSelectAsset}
-      />
 
-      {/* Mobile-only floating CTA: opens the workflows/chat bottom sheet.
+        {/* Mobile-only floating CTA: opens the workflows/chat bottom sheet.
           Sits on the canvas so the user can reach Edits with one thumb.
           Hidden by CSS on desktop and while the sheet itself is open. */}
-      <button
-        type="button"
-        className="rfs-mobile-fab rfs-mobile-fab-tools"
-        onClick={() => setRightOpenMobile(true)}
-        aria-label="Open edits panel"
-      >
-        {Icon.workflows}
-        <span>{selected ? "Configure" : "Edits"}</span>
-      </button>
-
-      {/* Backdrops + close affordances for the mobile overlays. The
-          left drawer and bottom sheet share the same dismiss pattern:
-          tap outside to close. */}
-      {!leftCollapsed ? (
         <button
           type="button"
-          className="rfs-mobile-backdrop rfs-mobile-backdrop-left"
-          aria-label="Close assets"
-          onClick={() => setLeftCollapsed(true)}
-        />
-      ) : null}
-      {rightOpenMobile ? (
-        <>
+          className="rfs-mobile-fab rfs-mobile-fab-tools"
+          onClick={() => setRightOpenMobile(true)}
+          aria-label="Open edits panel"
+        >
+          {Icon.workflows}
+          <span>{selected ? "Configure" : "Edits"}</span>
+        </button>
+
+        {/* Backdrops + close affordances for the mobile overlays. The
+          left drawer and bottom sheet share the same dismiss pattern:
+          tap outside to close. */}
+        {!leftCollapsed ? (
           <button
             type="button"
-            className="rfs-mobile-backdrop rfs-mobile-backdrop-right"
-            aria-label="Close edits panel"
-            onClick={() => setRightOpenMobile(false)}
+            className="rfs-mobile-backdrop rfs-mobile-backdrop-left"
+            aria-label="Close assets"
+            onClick={() => setLeftCollapsed(true)}
           />
-          <button
-            type="button"
-            className="rfs-sheet-close"
-            aria-label="Close edits panel"
-            onClick={() => setRightOpenMobile(false)}
-          >
-            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-              <path d="M18 6L6 18M6 6l12 12" />
-            </svg>
-          </button>
-        </>
-      ) : null}
+        ) : null}
+        {rightOpenMobile ? (
+          <>
+            <button
+              type="button"
+              className="rfs-mobile-backdrop rfs-mobile-backdrop-right"
+              aria-label="Close edits panel"
+              onClick={() => setRightOpenMobile(false)}
+            />
+            <button
+              type="button"
+              className="rfs-sheet-close"
+              aria-label="Close edits panel"
+              onClick={() => setRightOpenMobile(false)}
+            >
+              <svg
+                aria-hidden="true"
+                width="20"
+                height="20"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
+                <path d="M18 6L6 18M6 6l12 12" />
+              </svg>
+            </button>
+          </>
+        ) : null}
 
-      <Toasts toasts={toasts} onDismiss={dismissToast} />
-
-      {compareOpen && active && active.versions.length >= 2 ? (
-        <ComparePanel
-          versions={active.versions}
-          // 2 versions: left = first (original), right = latest.
-          // 3+ versions: same defaults; user can switch via per-pane
-          // dropdowns inside the modal.
-          initialLeftId={active.versions[0].id}
-          initialRightId={
-            active.currentVersionId !== active.versions[0].id
-              ? active.currentVersionId
-              : active.versions[active.versions.length - 1].id
-          }
-          onClose={() => setCompareOpen(false)}
-        />
-      ) : null}
-    </div>
+        <Toasts toasts={toasts} onDismiss={dismissToast} />
+
+        {compareOpen && active && active.versions.length >= 2 ? (
+          <ComparePanel
+            versions={active.versions}
+            // 2 versions: left = first (original), right = latest.
+            // 3+ versions: same defaults; user can switch via per-pane
+            // dropdowns inside the modal.
+            initialLeftId={active.versions[0].id}
+            initialRightId={
+              active.currentVersionId !== active.versions[0].id
+                ? active.currentVersionId
+                : active.versions[active.versions.length - 1].id
+            }
+            onClose={() => setCompareOpen(false)}
+          />
+        ) : null}
+      </div>
+    </ShellConfigProvider>
   );
 }
 
@@ -2595,7 +2584,7 @@ function renderSelectedActionContent({
           title={pin ? "Spot pinned" : "Click the spot you want to edit"}
           sub={
             pin ? (
-              <button className="rfs-link" onClick={onClearPin}>
+              <button type="button" className="rfs-link" onClick={onClearPin}>
                 Click again on the image to move the pin
               </button>
             ) : (
@@ -2631,7 +2620,7 @@ function renderSelectedActionContent({
           }
           sub={
             maskCoverage >= 0.08 ? (
-              <button className="rfs-link" onClick={onClearMask}>
+              <button type="button" className="rfs-link" onClick={onClearMask}>
                 Clear and start over
               </button>
             ) : (
@@ -2651,10 +2640,14 @@ function renderSelectedActionContent({
           n="1"
           done={hasMask}
           active={!hasMask}
-          title={hasMask ? `Mask painted — ${maskCoverage.toFixed(1)}% covered` : "Brush the area to inpaint"}
+          title={
+            hasMask
+              ? `Mask painted — ${maskCoverage.toFixed(1)}% covered`
+              : "Brush the area to inpaint"
+          }
           sub={
             hasMask ? (
-              <button className="rfs-link" onClick={onClearMask}>
+              <button type="button" className="rfs-link" onClick={onClearMask}>
                 Clear and start over
               </button>
             ) : (
@@ -2689,7 +2682,8 @@ function renderSelectedActionContent({
           active={hasMask && hasReference}
           title={
             <>
-              Direction <span style={{ color: "var(--rfs-ink-3)", fontWeight: 500 }}>(optional)</span>
+              Direction{" "}
+              <span style={{ color: "var(--rfs-ink-3)", fontWeight: 500 }}>(optional)</span>
             </>
           }
           sub="Tell the model what to emphasize or how to apply the reference."
@@ -2728,7 +2722,7 @@ function renderSelectedActionContent({
         {referencePreview ? (
           <div className="rfs-ref-preview">
             <img src={referencePreview} alt="Logo" />
-            <button className="rfs-link" onClick={() => onReferenceFile(null)}>
+            <button type="button" className="rfs-link" onClick={() => onReferenceFile(null)}>
               Remove
             </button>
           </div>
@@ -2767,11 +2761,15 @@ function renderSelectedActionContent({
             <label className="rfs-label">{resolutionInput.label}</label>
             <select
               className="rfs-select"
-              value={inputs.resolution ?? resolutionInput.default ?? resolutionInput.options[0].value}
+              value={
+                inputs.resolution ?? resolutionInput.default ?? resolutionInput.options[0].value
+              }
               onChange={(e) => onInputChange("resolution", e.target.value)}
             >
               {resolutionInput.options.map((o) => (
-                <option key={o.value} value={o.value}>{o.label}</option>
+                <option key={o.value} value={o.value}>
+                  {o.label}
+                </option>
               ))}
             </select>
             {resolutionInput.help ? <div className="rfs-help">{resolutionInput.help}</div> : null}
@@ -2782,7 +2780,11 @@ function renderSelectedActionContent({
   }
   // simple / prompt — render generic inputs from wf.inputs
   if (!wf.inputs?.length) {
-    return <div className="rfs-help">No parameters needed. Click <b>Apply</b> to run.</div>;
+    return (
+      <div className="rfs-help">
+        No parameters needed. Click <b>Apply</b> to run.
+      </div>
+    );
   }
   return (
     <>
@@ -2793,7 +2795,11 @@ function renderSelectedActionContent({
             <div key={inp.key} className="rfs-input-group">
               <label className="rfs-label">{inp.label}</label>
               <div className="rfs-color-row">
-                <input type="color" value={value} onChange={(e) => onInputChange(inp.key, e.target.value)} />
+                <input
+                  type="color"
+                  value={value}
+                  onChange={(e) => onInputChange(inp.key, e.target.value)}
+                />
                 <span className="rfs-color-hex">{value.toUpperCase()}</span>
               </div>
               {inp.help ? <div className="rfs-help">{inp.help}</div> : null}
@@ -2835,29 +2841,25 @@ function renderSelectedActionContent({
           // own resolution is known, annotate the label with the source's
           // bucket and warn if the chosen option would force an upscale —
           // models can't truly invent detail beyond what's in the source.
-          const isResolutionSelect = inp.options.every((o) =>
-            ["1K", "2K", "4K"].includes(o.value),
-          );
+          const isResolutionSelect = inp.options.every((o) => ["1K", "2K", "4K"].includes(o.value));
           const sourceBucket: ResBucket | null =
             isResolutionSelect && sourceWidth && sourceHeight
               ? resBucket(sourceWidth, sourceHeight)
               : null;
-          const currentValue =
-            inputs[inp.key] ?? inp.default ?? inp.options[0].value;
+          const currentValue = inputs[inp.key] ?? inp.default ?? inp.options[0].value;
           const showUpscaleWarn =
             sourceBucket && isUpscale(sourceBucket, currentValue as ResBucket);
           // Topaz upscale_factor — annotate options/warning with the
           // 24 MP output cap. Source × factor² has to stay under 24 MP
           // or the API rejects.
-          const isTopazFactor =
-            wf.id === "topaz-upscale" && inp.key === "upscale_factor";
+          const isTopazFactor = wf.id === "topaz-upscale" && inp.key === "upscale_factor";
           const topazExceeds =
             isTopazFactor && sourceWidth && sourceHeight
-              ? topazExceedsCap(sourceWidth, sourceHeight, parseFloat(currentValue))
+              ? topazExceedsCap(sourceWidth, sourceHeight, Number.parseFloat(currentValue))
               : false;
           const topazProjectedMP =
             isTopazFactor && sourceWidth && sourceHeight
-              ? topazOutputMP(sourceWidth, sourceHeight, parseFloat(currentValue))
+              ? topazOutputMP(sourceWidth, sourceHeight, Number.parseFloat(currentValue))
               : 0;
           return (
             <div key={inp.key} className="rfs-input-group">
@@ -2866,9 +2868,7 @@ function renderSelectedActionContent({
                 {sourceBucket ? (
                   <span className="rfs-label-meta">
                     source is {sourceBucket}
-                    {sourceWidth && sourceHeight
-                      ? ` · ${sourceWidth}×${sourceHeight}`
-                      : ""}
+                    {sourceWidth && sourceHeight ? ` · ${sourceWidth}×${sourceHeight}` : ""}
                   </span>
                 ) : null}
                 {isTopazFactor && sourceWidth && sourceHeight ? (
@@ -2883,11 +2883,10 @@ function renderSelectedActionContent({
                 onChange={(e) => onInputChange(inp.key, e.target.value)}
               >
                 {inp.options.map((o) => {
-                  const isUp =
-                    sourceBucket && isUpscale(sourceBucket, o.value as ResBucket);
+                  const isUp = sourceBucket && isUpscale(sourceBucket, o.value as ResBucket);
                   const exceedsTopaz =
                     isTopazFactor && sourceWidth && sourceHeight
-                      ? topazExceedsCap(sourceWidth, sourceHeight, parseFloat(o.value))
+                      ? topazExceedsCap(sourceWidth, sourceHeight, Number.parseFloat(o.value))
                       : false;
                   return (
                     <option key={o.value} value={o.value}>
@@ -2900,15 +2899,13 @@ function renderSelectedActionContent({
               </select>
               {showUpscaleWarn ? (
                 <div className="rfs-help rfs-help-warn">
-                  Heads up — your source is {sourceBucket}. Generating at{" "}
-                  {currentValue} means upscaling; the model can't add detail
-                  that isn't there.
+                  Heads up — your source is {sourceBucket}. Generating at {currentValue} means
+                  upscaling; the model can't add detail that isn't there.
                 </div>
               ) : topazExceeds ? (
                 <div className="rfs-help rfs-help-warn">
-                  At {currentValue}× this source would output{" "}
-                  {topazProjectedMP.toFixed(1)} MP — over the {TOPAZ_MAX_OUTPUT_MP} MP
-                  output cap. Pick a smaller factor to apply.
+                  At {currentValue}× this source would output {topazProjectedMP.toFixed(1)} MP —
+                  over the {TOPAZ_MAX_OUTPUT_MP} MP output cap. Pick a smaller factor to apply.
                 </div>
               ) : inp.help ? (
                 <div className="rfs-help">{inp.help}</div>
@@ -2935,22 +2932,28 @@ function renderSelectedActionContent({
 // background-color · #F1F1F1"). Falls back to just the workflow id if
 // the workflow isn't found in the catalog (shouldn't happen in
 // practice, but cheap to guard).
-function packageStepSummary(step: PackageRecipeStep): string {
-  const wf = WORKFLOWS.find((w) => w.id === step.workflowId);
+function packageStepSummary(step: PackageRecipeStep, workflows: ReadonlyArray<Workflow>): string {
+  const wf = workflows.find((w) => w.id === step.workflowId);
   const name = wf?.name ?? step.workflowId;
   const paramBits: string[] = [];
   if (step.params.color) paramBits.push(step.params.color);
   if (step.params.aspect_ratio) paramBits.push(step.params.aspect_ratio);
   if (step.params.resolution) paramBits.push(step.params.resolution);
   if (step.params.upscale_factor) paramBits.push(`${step.params.upscale_factor}×`);
-  if (step.params.prompt) paramBits.push(`"${step.params.prompt.slice(0, 30)}${step.params.prompt.length > 30 ? "…" : ""}"`);
+  if (step.params.prompt)
+    paramBits.push(
+      `"${step.params.prompt.slice(0, 30)}${step.params.prompt.length > 30 ? "…" : ""}"`,
+    );
   return paramBits.length > 0 ? `${name} · ${paramBits.join(" · ")}` : name;
 }
 
 // Outpaint runtime expansion percentages (mirror of staticBody in
 // _data/workflows.ts). Multiplied against the source dim so the user
 // can see the canvas they'll get back before hitting Apply.
-const OUTPAINT_EXPAND: Record<string, { top: number; bottom: number; left: number; right: number }> = {
+const OUTPAINT_EXPAND: Record<
+  string,
+  { top: number; bottom: number; left: number; right: number }
+> = {
   "4:5": { top: 13, bottom: 12, left: 0, right: 0 },
   "9:16": { top: 39, bottom: 39, left: 0, right: 0 },
   "16:9": { top: 0, bottom: 0, left: 39, right: 39 },
@@ -2997,7 +3000,9 @@ function Step({
 }) {
   return (
     <div className="rfs-step">
-      <div className={`rfs-step-num${done ? " is-done" : active ? " is-active" : ""}`}>{done ? "" : n}</div>
+      <div className={`rfs-step-num${done ? " is-done" : active ? " is-active" : ""}`}>
+        {done ? "" : n}
+      </div>
       <div className="rfs-step-text">
         <div className="rfs-step-title">{title}</div>
         {sub ? <div className="rfs-step-sub">{sub}</div> : null}
@@ -3047,6 +3052,7 @@ function PackageEditor({
   creativeValue: string;
   setCreativeValue: React.Dispatch<React.SetStateAction<string>>;
 }) {
+  const { workflows } = useShellConfig();
   const [expanded, setExpanded] = useState<number | null>(null);
   const [pickerOpen, setPickerOpen] = useState(false);
 
@@ -3107,9 +3113,7 @@ function PackageEditor({
 
   const updateStepParam = (i: number, key: string, value: string) => {
     setPrep((prev) =>
-      prev.map((s, idx) =>
-        idx === i ? { ...s, params: { ...s.params, [key]: value } } : s,
-      ),
+      prev.map((s, idx) => (idx === i ? { ...s, params: { ...s.params, [key]: value } } : s)),
     );
   };
 
@@ -3131,9 +3135,7 @@ function PackageEditor({
 
   const toggleVariant = (variantId: string) => {
     setVariants((prev) =>
-      prev.map((v) =>
-        v.variant.id === variantId ? { ...v, enabled: !v.enabled } : v,
-      ),
+      prev.map((v) => (v.variant.id === variantId ? { ...v, enabled: !v.enabled } : v)),
     );
   };
 
@@ -3205,16 +3207,37 @@ function PackageEditor({
               ? "The product gets cleaned, dropped into your scene, then sized for each channel."
               : "Prep runs once, then each enabled channel runs its own smart-resize in parallel."}
             {isModified ? (
-              <> You've edited this run — <button className="rfs-link" onClick={onReset}>reset</button> to defaults.</>
+              <>
+                {" "}
+                You've edited this run —{" "}
+                <button type="button" className="rfs-link" onClick={onReset}>
+                  reset
+                </button>{" "}
+                to defaults.
+              </>
             ) : null}
           </>
         ) : prep.length === 0 ? (
-          <>No steps remaining. <button className="rfs-link" onClick={onReset}>Reset</button> to bring back the default chain.</>
+          <>
+            No steps remaining.{" "}
+            <button type="button" className="rfs-link" onClick={onReset}>
+              Reset
+            </button>{" "}
+            to bring back the default chain.
+          </>
         ) : (
           <>
-            {prep.length} step{prep.length === 1 ? "" : "s"} will run head-to-tail on this image. Reorder, edit, or remove anything you don't need.
+            {prep.length} step{prep.length === 1 ? "" : "s"} will run head-to-tail on this image.
+            Reorder, edit, or remove anything you don't need.
             {isModified ? (
-              <> You've edited the chain — <button className="rfs-link" onClick={onReset}>reset</button> to defaults.</>
+              <>
+                {" "}
+                You've edited the chain —{" "}
+                <button type="button" className="rfs-link" onClick={onReset}>
+                  reset
+                </button>{" "}
+                to defaults.
+              </>
             ) : null}
           </>
         )}
@@ -3235,7 +3258,7 @@ function PackageEditor({
 
       <div className="rfs-package-list">
         {prep.map((step, i) => {
-          const wf = WORKFLOWS.find((w) => w.id === step.workflowId);
+          const wf = workflows.find((w) => w.id === step.workflowId);
           const isExpanded = expanded === i;
           return (
             <div key={`${step.workflowId}-${i}`} className="rfs-custom-editor-row">
@@ -3248,7 +3271,7 @@ function PackageEditor({
                   aria-expanded={isExpanded}
                 >
                   <div className="rfs-package-row-name">{step.label}</div>
-                  <div className="rfs-package-row-file">{packageStepSummary(step)}</div>
+                  <div className="rfs-package-row-file">{packageStepSummary(step, workflows)}</div>
                 </button>
                 <div className="rfs-package-row-actions">
                   <button
@@ -3310,10 +3333,7 @@ function PackageEditor({
           doesn't edit each variant's internal mini-chain). */}
       {hasVariants ? (
         <>
-          <div
-            className="rfs-package-section-header"
-            style={{ marginTop: "1rem" }}
-          >
+          <div className="rfs-package-section-header" style={{ marginTop: "1rem" }}>
             <span className="rfs-package-section-title">Where it ships</span>
             <span className="rfs-package-section-meta">
               {enabledVariantCount} of {variants.length} selected
@@ -3337,12 +3357,14 @@ function PackageEditor({
             ))}
           </div>
           <div className="rfs-help" style={{ marginTop: "0.625rem" }}>
-            Each variant runs smart-resize to its channel ratio, scored by Sentinel. Prep stays unscored.
+            Each variant runs smart-resize to its channel ratio, scored by Sentinel. Prep stays
+            unscored.
           </div>
         </>
       ) : (
         <div className="rfs-help" style={{ marginTop: "0.75rem" }}>
-          The final step's output is what Sentinel grades. Intermediate steps are skipped (or gated, if you've turned that on in settings).
+          The final step's output is what Sentinel grades. Intermediate steps are skipped (or gated,
+          if you've turned that on in settings).
         </div>
       )}
     </>
diff --git a/packages/studio/src/components/Toasts.tsx b/packages/studio/src/components/Toasts.tsx
index df5e701..acd5aac 100644
--- a/packages/studio/src/components/Toasts.tsx
+++ b/packages/studio/src/components/Toasts.tsx
@@ -36,6 +36,7 @@ export function Toasts({
           </div>
           {t.onView ? (
             <button
+              type="button"
               className="rfs-toast-action"
               onClick={() => {
                 t.onView?.();
@@ -46,6 +47,7 @@ export function Toasts({
             </button>
           ) : null}
           <button
+            type="button"
             className="rfs-toast-close"
             onClick={() => onDismiss(t.id)}
             aria-label="Dismiss"
diff --git a/packages/studio/src/components/WorkflowsPanel.tsx b/packages/studio/src/components/WorkflowsPanel.tsx
index 949fccd..d48f4bf 100644
--- a/packages/studio/src/components/WorkflowsPanel.tsx
+++ b/packages/studio/src/components/WorkflowsPanel.tsx
@@ -7,26 +7,27 @@
 // agent; today it's an empty state.
 
 import { useEffect, useMemo, useRef, useState } from "react";
-import { WORKFLOWS, type Workflow } from "../data/workflows";
-import { SAMPLES, type SampleAsset } from "../data/samples";
-import { StepParamsForm, StepPicker, defaultStepValues } from "./StepEditor";
-import type { SentinelResult } from "../lib/sentinel";
-import type { PartialStudioHandle } from "../lib/studio-handle";
-import { summarizeRequest } from "../lib/version-summary";
+import type { SampleAsset } from "../data/samples";
+import type { Workflow } from "../data/workflows";
 import {
+  type CustomStep,
+  type CustomWorkflow as CustomWfShape,
   chainForVersion,
   chainIsSavable,
+  createCustomWorkflow,
+  deleteCustomWorkflow,
   reasonChainNotSavable,
   saveCustomWorkflow,
-  createCustomWorkflow,
   updateCustomWorkflow,
   useCustomWorkflows,
-  deleteCustomWorkflow,
-  type CustomStep,
-  type CustomWorkflow as CustomWfShape,
 } from "../lib/custom-workflows";
+import type { SentinelResult } from "../lib/sentinel";
+import { useShellConfig } from "../lib/shell-config";
+import type { PartialStudioHandle } from "../lib/studio-handle";
+import { summarizeRequest } from "../lib/version-summary";
 import { ChatPanel } from "./ChatPanel";
 import { SentinelChip } from "./SentinelBadge";
+import { StepParamsForm, StepPicker, defaultStepValues } from "./StepEditor";
 import { Icon } from "./icons";
 
 // Snapshot of what the user actually asked for when this version was
@@ -150,6 +151,7 @@ export function WorkflowsPanel({
    * that don't want this feature wire-out cleanly. */
   onSelectAsset?: (id: string) => void;
 }) {
+  const { workflows } = useShellConfig();
   const [tab, setTab] = useState<"workflows" | "chat" | "history">("workflows");
   const [query, setQuery] = useState("");
   const customWorkflows = useCustomWorkflows();
@@ -209,16 +211,22 @@ export function WorkflowsPanel({
   }, [selectedWorkflowId]);
 
   const filtered = useMemo(() => {
-    if (!query) return WORKFLOWS;
+    if (!query) return workflows;
     const q = query.toLowerCase();
-    return WORKFLOWS.filter((w) => w.name.toLowerCase().includes(q) || w.desc.toLowerCase().includes(q));
-  }, [query]);
+    return workflows.filter(
+      (w) => w.name.toLowerCase().includes(q) || w.desc.toLowerCase().includes(q),
+    );
+  }, [query, workflows]);
 
   const groups: Array<{ id: string; label: string; items: Workflow[] }> = [
     // Packages first — they're the "all-in-one" outputs, the headline
     // result for marketplace prep. Below them sit the individual
     // primitives that the packages chain under the hood.
-    { id: "package", label: "Marketplace packages", items: filtered.filter((w) => w.group === "package") },
+    {
+      id: "package",
+      label: "Marketplace packages",
+      items: filtered.filter((w) => w.group === "package"),
+    },
     { id: "magic", label: "Magic", items: filtered.filter((w) => w.group === "magic") },
     { id: "compose", label: "Compose", items: filtered.filter((w) => w.group === "compose") },
     { id: "cleanup", label: "Cleanup", items: filtered.filter((w) => w.group === "cleanup") },
@@ -235,17 +243,15 @@ export function WorkflowsPanel({
   // major source of "what is all this stuff?" feedback.
   const hasRecipes = customWorkflows.length > 0;
 
-  const recommendedSet = useMemo(
-    () => new Set(recommendedWorkflowIds),
-    [recommendedWorkflowIds],
-  );
+  const recommendedSet = useMemo(() => new Set(recommendedWorkflowIds), [recommendedWorkflowIds]);
 
   // Breadcrumb context for the focused configure view. Derived here
   // (not in the JSX) because both the breadcrumb and the back button
   // need the same group label.
   const selectedWf = useMemo(
-    () => (selectedWorkflowId ? WORKFLOWS.find((w) => w.id === selectedWorkflowId) ?? null : null),
-    [selectedWorkflowId],
+    () =>
+      selectedWorkflowId ? (workflows.find((w) => w.id === selectedWorkflowId) ?? null) : null,
+    [selectedWorkflowId, workflows],
   );
   const groupLabelFor: Record<string, string> = {
     package: "Marketplace",
@@ -270,22 +276,30 @@ export function WorkflowsPanel({
     <aside className="rfs-right">
       <div className="rfs-tabs">
         <button
+          type="button"
           className={`rfs-tab${tab === "workflows" ? " is-active" : ""}`}
           onClick={() => setTab("workflows")}
         >
           {Icon.workflows}
           Edits
-          <span className="rfs-tab-count">{WORKFLOWS.filter((w) => w.kind !== "soon").length}</span>
+          <span className="rfs-tab-count">{workflows.filter((w) => w.kind !== "soon").length}</span>
         </button>
         <button
+          type="button"
           className={`rfs-tab${tab === "chat" ? " is-active" : ""}`}
           onClick={() => setTab("chat")}
         >
           {Icon.chat}
           Chat
-          <span className="rfs-tab-soon" style={{ background: "var(--rfs-accent-soft)", color: "var(--rfs-accent)" }}>BETA</span>
+          <span
+            className="rfs-tab-soon"
+            style={{ background: "var(--rfs-accent-soft)", color: "var(--rfs-accent)" }}
+          >
+            BETA
+          </span>
         </button>
         <button
+          type="button"
           className={`rfs-tab${tab === "history" ? " is-active" : ""}`}
           onClick={() => setTab("history")}
         >
@@ -315,288 +329,342 @@ export function WorkflowsPanel({
             }}
           />
         ) : isFocused ? (
-        // Focused configure view: hide the search + card grid entirely
-        // so the user can attend to one thing at a time. The breadcrumb
-        // is the only way back to browse mode (clicking the canvas or
-        // a tab also clears selection from the parent).
-        <>
-          <div className="rfs-breadcrumb">
-            <button
-              type="button"
-              className="rfs-breadcrumb-back"
-              onClick={exitFocus}
-              aria-label="Back to all edits"
-            >
-              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.4" strokeLinecap="round" strokeLinejoin="round">
-                <path d="M15 18l-6-6 6-6" />
-              </svg>
-            </button>
-            <span className="rfs-breadcrumb-trail">
-              <button type="button" className="rfs-breadcrumb-link" onClick={exitFocus}>
-                {breadcrumb?.group ?? "Edits"}
+          // Focused configure view: hide the search + card grid entirely
+          // so the user can attend to one thing at a time. The breadcrumb
+          // is the only way back to browse mode (clicking the canvas or
+          // a tab also clears selection from the parent).
+          <>
+            <div className="rfs-breadcrumb">
+              <button
+                type="button"
+                className="rfs-breadcrumb-back"
+                onClick={exitFocus}
+                aria-label="Back to all edits"
+              >
+                <svg
+                  aria-hidden="true"
+                  width="14"
+                  height="14"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="2.4"
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                >
+                  <path d="M15 18l-6-6 6-6" />
+                </svg>
               </button>
-              <span className="rfs-breadcrumb-sep" aria-hidden>·</span>
-              <span className="rfs-breadcrumb-current">{breadcrumb?.name ?? ""}</span>
-            </span>
-          </div>
-          {selectedCustom ? (
-            <CustomReplayPanel
-              custom={selectedCustom}
-              onCancel={() => setSelectedCustomId(null)}
-              onApply={(overrides) => {
-                onRunCustom(selectedCustom, overrides);
-                setSelectedCustomId(null);
-              }}
-            />
-          ) : selectedActionContent ? (
-            <div className="rfs-action-pin is-focused">
-              {selectedActionMeta ? (
-                <ActionHeaderWithExamples
-                  meta={selectedActionMeta}
-                  workflowId={selectedWorkflowId}
-                  activeAssetId={activeAssetId}
-                  onSelectAsset={onSelectAsset}
-                />
-              ) : null}
-              <div className="rfs-action-pin-body">{selectedActionContent}</div>
+              <span className="rfs-breadcrumb-trail">
+                <button type="button" className="rfs-breadcrumb-link" onClick={exitFocus}>
+                  {breadcrumb?.group ?? "Edits"}
+                </button>
+                <span className="rfs-breadcrumb-sep" aria-hidden>
+                  ·
+                </span>
+                <span className="rfs-breadcrumb-current">{breadcrumb?.name ?? ""}</span>
+              </span>
             </div>
-          ) : null}
-          {selectedCustom ? null : selectedActionFooter ? (
-            <footer className="rfs-action-footer">{selectedActionFooter}</footer>
-          ) : null}
-        </>
+            {selectedCustom ? (
+              <CustomReplayPanel
+                custom={selectedCustom}
+                onCancel={() => setSelectedCustomId(null)}
+                onApply={(overrides) => {
+                  onRunCustom(selectedCustom, overrides);
+                  setSelectedCustomId(null);
+                }}
+              />
+            ) : selectedActionContent ? (
+              <div className="rfs-action-pin is-focused">
+                {selectedActionMeta ? (
+                  <ActionHeaderWithExamples
+                    meta={selectedActionMeta}
+                    workflowId={selectedWorkflowId}
+                    activeAssetId={activeAssetId}
+                    onSelectAsset={onSelectAsset}
+                  />
+                ) : null}
+                <div className="rfs-action-pin-body">{selectedActionContent}</div>
+              </div>
+            ) : null}
+            {selectedCustom ? null : selectedActionFooter ? (
+              <footer className="rfs-action-footer">{selectedActionFooter}</footer>
+            ) : null}
+          </>
         ) : (
-        <>
-          <div className="rfs-search">
-            <input
-              placeholder="Search edits…"
-              value={query}
-              onChange={(e) => setQuery(e.target.value)}
-            />
-          </div>
-          <div className="rfs-cards">
-            {/* Custom group only renders when the user already has
+          <>
+            <div className="rfs-search">
+              <input
+                placeholder="Search edits…"
+                value={query}
+                onChange={(e) => setQuery(e.target.value)}
+              />
+            </div>
+            <div className="rfs-cards">
+              {/* Custom group only renders when the user already has
                 saved recipes. The empty-state +New tile was the
                 loudest first-impression of the panel and shipped no
                 value until the user had run a chain through History
                 first — moved to a quieter footer link instead. */}
-            {hasRecipes ? (
-            <div className="rfs-cards-group">
-              <div className="rfs-cards-group-label">
-                <span>Custom</span>
-              </div>
-              <button
-                type="button"
-                className="rfs-card rfs-card-custom-new"
-                onClick={openEditorForNew}
-                title="Build a recipe from scratch"
-              >
-                <div className="rfs-card-icon rfs-card-icon-custom" aria-hidden>
-                  <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-                    <line x1="12" y1="5" x2="12" y2="19" />
-                    <line x1="5" y1="12" x2="19" y2="12" />
-                  </svg>
-                </div>
-                <div className="rfs-card-text">
-                  <div className="rfs-card-name">New recipe</div>
-                  <div className="rfs-card-desc">Build another chain from scratch</div>
-                </div>
-              </button>
-              {customWorkflows.map((cw) => {
-                const isSelected = selectedCustomId === cw.id;
-                return (
-                  <div
-                    key={cw.id}
-                    className={`rfs-card rfs-card-custom${isSelected ? " is-selected" : ""}`}
+              {hasRecipes ? (
+                <div className="rfs-cards-group">
+                  <div className="rfs-cards-group-label">
+                    <span>Custom</span>
+                  </div>
+                  <button
+                    type="button"
+                    className="rfs-card rfs-card-custom-new"
+                    onClick={openEditorForNew}
+                    title="Build a recipe from scratch"
                   >
-                    <button
-                      className="rfs-card-custom-body"
-                      onClick={() => {
-                        const next = isSelected ? null : cw.id;
-                        setSelectedCustomId(next);
-                        if (next) onClearWorkflowSelection?.();
-                      }}
-                    >
-                      <div className="rfs-card-icon rfs-card-icon-custom" aria-hidden>
-                        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-                          <rect x="3" y="3" width="7" height="7" rx="1" />
-                          <rect x="14" y="3" width="7" height="7" rx="1" />
-                          <rect x="14" y="14" width="7" height="7" rx="1" />
-                          <rect x="3" y="14" width="7" height="7" rx="1" />
-                        </svg>
-                      </div>
-                      <div className="rfs-card-text">
-                        <div className="rfs-card-name">{cw.name}</div>
-                        <div className="rfs-card-desc">
-                          {cw.steps.length} step{cw.steps.length === 1 ? "" : "s"}
-                          {": "}
-                          {cw.steps
-                            .map((s) => WORKFLOWS.find((w) => w.id === s.workflowId)?.name ?? s.workflowId)
-                            .join(" · ")}
-                        </div>
-                      </div>
-                    </button>
-                    <button
-                      className="rfs-card-custom-edit"
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        openEditorForExisting(cw);
-                      }}
-                      title="Edit recipe (rename, reorder, add or remove steps)"
-                      aria-label={`Edit recipe ${cw.name}`}
-                    >
-                      <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
-                        <path d="M12 20h9" />
-                        <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z" />
+                    <div className="rfs-card-icon rfs-card-icon-custom" aria-hidden>
+                      <svg
+                        aria-hidden="true"
+                        width="14"
+                        height="14"
+                        viewBox="0 0 24 24"
+                        fill="none"
+                        stroke="currentColor"
+                        strokeWidth="2"
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                      >
+                        <line x1="12" y1="5" x2="12" y2="19" />
+                        <line x1="5" y1="12" x2="19" y2="12" />
                       </svg>
-                    </button>
-                    <button
-                      className="rfs-card-custom-delete"
-                      onClick={(e) => {
-                        e.stopPropagation();
-                        if (window.confirm(`Delete custom edit "${cw.name}"?`)) {
-                          deleteCustomWorkflow(cw.id);
-                          if (isSelected) setSelectedCustomId(null);
-                        }
-                      }}
-                      title="Delete custom edit"
-                      aria-label="Delete custom edit"
-                    >
-                      ×
-                    </button>
-                  </div>
-                );
-              })}
-            </div>
-            ) : null}
-            {groups.map((g) => (
-              <div key={g.id} className="rfs-cards-group">
-                <div className="rfs-cards-group-label">
-                  <span>{g.label}</span>
-                </div>
-                {g.items.map((wf) => {
-                  const applic = wf.applicableHint?.(photoTags);
-                  // Tri-state: "soon" (not built yet) vs.
-                  // "not-applicable" (built, but wrong photo for it)
-                  // vs. enabled. Both disabled states block the click,
-                  // but they read differently — soon is "come back
-                  // later", not-applicable is "swap your photo".
-                  const isSoon = wf.kind === "soon";
-                  const isNotApplicable = !isSoon && !!applic && !applic.ok;
-                  const disabled = isSoon || isNotApplicable;
-                  const isSelected = selectedWorkflowId === wf.id;
-                  // Recommended = the editorial "this is the demo for
-                  // this image" flag from the active asset. Replaces
-                  // the static `wf.feature` always-yellow that used to
-                  // mark ai-edit + reference-inpaint regardless of
-                  // what was on the canvas.
-                  const isRecommended = !disabled && !isSelected && recommendedSet.has(wf.id);
-                  // Native `title` tooltips don't fire on `disabled`
-                  // buttons (and child elements inside them are also
-                  // pointer-events:none in most browsers). For the
-                  // not-applicable case we wrap the disabled button in
-                  // a span carrying the tooltip — the wrapper isn't
-                  // disabled, so the tooltip surfaces normally on
-                  // hover. Soon cards don't need a tooltip.
-                  const cardButton = (
-                    <button
-                      key={wf.id}
-                      className={`rfs-card${isSelected ? " is-selected" : ""}${isRecommended ? " is-recommended" : ""}${isNotApplicable ? " is-not-applicable" : ""}`}
-                      onClick={() => onSelectWorkflow(wf)}
-                      disabled={disabled}
-                    >
-                      <div className="rfs-card-icon">{Icon[wf.id as keyof typeof Icon] ?? null}</div>
-                      <div className="rfs-card-text">
-                        <div className="rfs-card-name">
-                          {wf.name}
-                          {isSoon ? <span className="rfs-card-soon">SOON</span> : null}
-                          {isNotApplicable ? (
-                            <span
-                              className="rfs-card-swap"
-                              aria-label="Different photo would unlock this"
+                    </div>
+                    <div className="rfs-card-text">
+                      <div className="rfs-card-name">New recipe</div>
+                      <div className="rfs-card-desc">Build another chain from scratch</div>
+                    </div>
+                  </button>
+                  {customWorkflows.map((cw) => {
+                    const isSelected = selectedCustomId === cw.id;
+                    return (
+                      <div
+                        key={cw.id}
+                        className={`rfs-card rfs-card-custom${isSelected ? " is-selected" : ""}`}
+                      >
+                        <button
+                          type="button"
+                          className="rfs-card-custom-body"
+                          onClick={() => {
+                            const next = isSelected ? null : cw.id;
+                            setSelectedCustomId(next);
+                            if (next) onClearWorkflowSelection?.();
+                          }}
+                        >
+                          <div className="rfs-card-icon rfs-card-icon-custom" aria-hidden>
+                            <svg
+                              aria-hidden="true"
+                              width="14"
+                              height="14"
+                              viewBox="0 0 24 24"
+                              fill="none"
+                              stroke="currentColor"
+                              strokeWidth="2"
+                              strokeLinecap="round"
+                              strokeLinejoin="round"
                             >
-                              ?
-                            </span>
-                          ) : null}
-                        </div>
-                        <div className="rfs-card-desc">
-                          {isNotApplicable && applic?.reason ? applic.reason : wf.desc}
-                        </div>
+                              <rect x="3" y="3" width="7" height="7" rx="1" />
+                              <rect x="14" y="3" width="7" height="7" rx="1" />
+                              <rect x="14" y="14" width="7" height="7" rx="1" />
+                              <rect x="3" y="14" width="7" height="7" rx="1" />
+                            </svg>
+                          </div>
+                          <div className="rfs-card-text">
+                            <div className="rfs-card-name">{cw.name}</div>
+                            <div className="rfs-card-desc">
+                              {cw.steps.length} step{cw.steps.length === 1 ? "" : "s"}
+                              {": "}
+                              {cw.steps
+                                .map(
+                                  (s) =>
+                                    workflows.find((w) => w.id === s.workflowId)?.name ??
+                                    s.workflowId,
+                                )
+                                .join(" · ")}
+                            </div>
+                          </div>
+                        </button>
+                        <button
+                          type="button"
+                          className="rfs-card-custom-edit"
+                          onClick={(e) => {
+                            e.stopPropagation();
+                            openEditorForExisting(cw);
+                          }}
+                          title="Edit recipe (rename, reorder, add or remove steps)"
+                          aria-label={`Edit recipe ${cw.name}`}
+                        >
+                          <svg
+                            aria-hidden="true"
+                            width="13"
+                            height="13"
+                            viewBox="0 0 24 24"
+                            fill="none"
+                            stroke="currentColor"
+                            strokeWidth="2"
+                            strokeLinecap="round"
+                            strokeLinejoin="round"
+                          >
+                            <path d="M12 20h9" />
+                            <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z" />
+                          </svg>
+                        </button>
+                        <button
+                          type="button"
+                          className="rfs-card-custom-delete"
+                          onClick={(e) => {
+                            e.stopPropagation();
+                            if (window.confirm(`Delete custom edit "${cw.name}"?`)) {
+                              deleteCustomWorkflow(cw.id);
+                              if (isSelected) setSelectedCustomId(null);
+                            }
+                          }}
+                          title="Delete custom edit"
+                          aria-label="Delete custom edit"
+                        >
+                          ×
+                        </button>
                       </div>
-                    </button>
-                  );
-                  return isNotApplicable ? (
-                    <span
-                      key={wf.id}
-                      className="rfs-card-wrap"
-                      title={`${applic?.reason ?? "Not applicable"} — try a different photo`}
-                    >
-                      {cardButton}
-                    </span>
-                  ) : (
-                    cardButton
-                  );
-                })}
-              </div>
-            ))}
-            {/* Quiet footer disclosures for things that don't earn
-                first-class card real estate: pre-release workflows
-                (no actions to take) and the create-recipe entry
-                point when the user has none yet. */}
-            {soonItems.length > 0 ? (
-              <div className="rfs-cards-footer">
-                <button
-                  type="button"
-                  className="rfs-cards-disclosure"
-                  onClick={() => setShowSoon((v) => !v)}
-                  aria-expanded={showSoon}
-                >
-                  <svg
-                    width="10" height="10" viewBox="0 0 24 24" fill="none"
-                    stroke="currentColor" strokeWidth="2.4"
-                    strokeLinecap="round" strokeLinejoin="round"
-                    style={{ transform: showSoon ? "rotate(90deg)" : "none", transition: "transform 120ms ease" }}
-                  >
-                    <path d="M9 6l6 6-6 6" />
-                  </svg>
-                  Coming soon ({soonItems.length})
-                </button>
-                {showSoon ? (
-                  <div className="rfs-cards-group rfs-cards-group-soon">
-                    {soonItems.map((wf) => (
+                    );
+                  })}
+                </div>
+              ) : null}
+              {groups.map((g) => (
+                <div key={g.id} className="rfs-cards-group">
+                  <div className="rfs-cards-group-label">
+                    <span>{g.label}</span>
+                  </div>
+                  {g.items.map((wf) => {
+                    const applic = wf.applicableHint?.(photoTags);
+                    // Tri-state: "soon" (not built yet) vs.
+                    // "not-applicable" (built, but wrong photo for it)
+                    // vs. enabled. Both disabled states block the click,
+                    // but they read differently — soon is "come back
+                    // later", not-applicable is "swap your photo".
+                    const isSoon = wf.kind === "soon";
+                    const isNotApplicable = !isSoon && !!applic && !applic.ok;
+                    const disabled = isSoon || isNotApplicable;
+                    const isSelected = selectedWorkflowId === wf.id;
+                    // Recommended = the editorial "this is the demo for
+                    // this image" flag from the active asset. Replaces
+                    // the static `wf.feature` always-yellow that used to
+                    // mark ai-edit + reference-inpaint regardless of
+                    // what was on the canvas.
+                    const isRecommended = !disabled && !isSelected && recommendedSet.has(wf.id);
+                    // Native `title` tooltips don't fire on `disabled`
+                    // buttons (and child elements inside them are also
+                    // pointer-events:none in most browsers). For the
+                    // not-applicable case we wrap the disabled button in
+                    // a span carrying the tooltip — the wrapper isn't
+                    // disabled, so the tooltip surfaces normally on
+                    // hover. Soon cards don't need a tooltip.
+                    const cardButton = (
                       <button
-                        key={wf.id}
-                        className="rfs-card"
-                        disabled
                         type="button"
+                        key={wf.id}
+                        className={`rfs-card${isSelected ? " is-selected" : ""}${isRecommended ? " is-recommended" : ""}${isNotApplicable ? " is-not-applicable" : ""}`}
+                        onClick={() => onSelectWorkflow(wf)}
+                        disabled={disabled}
                       >
-                        <div className="rfs-card-icon">{Icon[wf.id as keyof typeof Icon] ?? null}</div>
+                        <div className="rfs-card-icon">
+                          {Icon[wf.id as keyof typeof Icon] ?? null}
+                        </div>
                         <div className="rfs-card-text">
                           <div className="rfs-card-name">
                             {wf.name}
-                            <span className="rfs-card-soon">SOON</span>
+                            {isSoon ? <span className="rfs-card-soon">SOON</span> : null}
+                            {isNotApplicable ? (
+                              <span
+                                className="rfs-card-swap"
+                                aria-label="Different photo would unlock this"
+                              >
+                                ?
+                              </span>
+                            ) : null}
+                          </div>
+                          <div className="rfs-card-desc">
+                            {isNotApplicable && applic?.reason ? applic.reason : wf.desc}
                           </div>
-                          <div className="rfs-card-desc">{wf.desc}</div>
                         </div>
                       </button>
-                    ))}
-                  </div>
-                ) : null}
-              </div>
-            ) : null}
-            {!hasRecipes ? (
-              <div className="rfs-cards-footer">
-                <button
-                  type="button"
-                  className="rfs-cards-link"
-                  onClick={openEditorForNew}
-                >
-                  + Create a recipe
-                </button>
-              </div>
-            ) : null}
-          </div>
-        </>
+                    );
+                    return isNotApplicable ? (
+                      <span
+                        key={wf.id}
+                        className="rfs-card-wrap"
+                        title={`${applic?.reason ?? "Not applicable"} — try a different photo`}
+                      >
+                        {cardButton}
+                      </span>
+                    ) : (
+                      cardButton
+                    );
+                  })}
+                </div>
+              ))}
+              {/* Quiet footer disclosures for things that don't earn
+                first-class card real estate: pre-release workflows
+                (no actions to take) and the create-recipe entry
+                point when the user has none yet. */}
+              {soonItems.length > 0 ? (
+                <div className="rfs-cards-footer">
+                  <button
+                    type="button"
+                    className="rfs-cards-disclosure"
+                    onClick={() => setShowSoon((v) => !v)}
+                    aria-expanded={showSoon}
+                  >
+                    <svg
+                      aria-hidden="true"
+                      width="10"
+                      height="10"
+                      viewBox="0 0 24 24"
+                      fill="none"
+                      stroke="currentColor"
+                      strokeWidth="2.4"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      style={{
+                        transform: showSoon ? "rotate(90deg)" : "none",
+                        transition: "transform 120ms ease",
+                      }}
+                    >
+                      <path d="M9 6l6 6-6 6" />
+                    </svg>
+                    Coming soon ({soonItems.length})
+                  </button>
+                  {showSoon ? (
+                    <div className="rfs-cards-group rfs-cards-group-soon">
+                      {soonItems.map((wf) => (
+                        <button key={wf.id} className="rfs-card" disabled type="button">
+                          <div className="rfs-card-icon">
+                            {Icon[wf.id as keyof typeof Icon] ?? null}
+                          </div>
+                          <div className="rfs-card-text">
+                            <div className="rfs-card-name">
+                              {wf.name}
+                              <span className="rfs-card-soon">SOON</span>
+                            </div>
+                            <div className="rfs-card-desc">{wf.desc}</div>
+                          </div>
+                        </button>
+                      ))}
+                    </div>
+                  ) : null}
+                </div>
+              ) : null}
+              {!hasRecipes ? (
+                <div className="rfs-cards-footer">
+                  <button type="button" className="rfs-cards-link" onClick={openEditorForNew}>
+                    + Create a recipe
+                  </button>
+                </div>
+              ) : null}
+            </div>
+          </>
         )
       ) : tab === "chat" ? (
         <ChatPanel studioHandle={studioHandle} activeAssetId={activeAssetId} />
@@ -610,23 +678,26 @@ export function WorkflowsPanel({
             </div>
           ) : (
             <div className="rfs-cards-group">
-              {versions.slice().reverse().map((v) => {
-                const chain = chainForVersion(versions, v.id);
-                const savable = chainIsSavable(chain);
-                const blockReason = !savable ? reasonChainNotSavable(chain) : null;
-                return (
-                  <HistoryCard
-                    key={v.id}
-                    version={v}
-                    isCurrent={v.id === currentVersionId}
-                    onClick={() => onPickVersion(v.id)}
-                    chainLength={chain.length}
-                    canSaveChain={savable}
-                    cannotSaveReason={blockReason}
-                    onSaveChain={(name) => saveCustomWorkflow(name, chain)}
-                  />
-                );
-              })}
+              {versions
+                .slice()
+                .reverse()
+                .map((v) => {
+                  const chain = chainForVersion(versions, v.id);
+                  const savable = chainIsSavable(chain);
+                  const blockReason = !savable ? reasonChainNotSavable(chain) : null;
+                  return (
+                    <HistoryCard
+                      key={v.id}
+                      version={v}
+                      isCurrent={v.id === currentVersionId}
+                      onClick={() => onPickVersion(v.id)}
+                      chainLength={chain.length}
+                      canSaveChain={savable}
+                      cannotSaveReason={blockReason}
+                      onSaveChain={(name) => saveCustomWorkflow(name, chain)}
+                    />
+                  );
+                })}
             </div>
           )}
         </div>
@@ -677,10 +748,8 @@ function HistoryCard({
   };
 
   return (
-    <div
-      className={`rfs-card rfs-history-card${isCurrent ? " is-selected" : ""}`}
-    >
-      <button className="rfs-history-card-head" onClick={onClick}>
+    <div className={`rfs-card rfs-history-card${isCurrent ? " is-selected" : ""}`}>
+      <button type="button" className="rfs-history-card-head" onClick={onClick}>
         <div
           className="rfs-card-icon"
           style={{ background: "transparent", padding: 0, width: 44, height: 44 }}
@@ -695,11 +764,7 @@ function HistoryCard({
           <div className="rfs-history-card-name-row">
             <div className="rfs-card-name">{version.label}</div>
             {showSentinelChip ? (
-              <SentinelChip
-                result={version.sentinel}
-                skipped={sentinelSkipped}
-                size="sm"
-              />
+              <SentinelChip result={version.sentinel} skipped={sentinelSkipped} size="sm" />
             ) : null}
           </div>
           <div className="rfs-card-desc">
@@ -716,10 +781,7 @@ function HistoryCard({
               <dd className="rfs-history-row-value">
                 {r.kind === "swatch" ? (
                   <span className="rfs-history-swatch-row">
-                    <span
-                      className="rfs-history-swatch"
-                      style={{ background: r.value }}
-                    />
+                    <span className="rfs-history-swatch" style={{ background: r.value }} />
                     <span style={{ fontFamily: "ui-monospace, SF Mono, Menlo, monospace" }}>
                       {r.value}
                     </span>
@@ -742,7 +804,11 @@ function HistoryCard({
               className="rfs-history-save-trigger"
               onClick={() => setSavePromptOpen(true)}
               disabled={!canSaveChain}
-              title={canSaveChain ? `Save these ${chainLength} step${chainLength === 1 ? "" : "s"} as a custom edit you can replay` : (cannotSaveReason ?? "")}
+              title={
+                canSaveChain
+                  ? `Save these ${chainLength} step${chainLength === 1 ? "" : "s"} as a custom edit you can replay`
+                  : (cannotSaveReason ?? "")
+              }
             >
               Save these {chainLength} step{chainLength === 1 ? "" : "s"} as custom edit
             </button>
@@ -803,6 +869,7 @@ function CustomReplayPanel({
   onCancel: () => void;
   onApply: (overrides: Record<string, string>) => void;
 }) {
+  const { workflows } = useShellConfig();
   const lastStep = custom.steps[custom.steps.length - 1];
   // Currently overridable params: aspect_ratio + resolution on the
   // final step, when present. Other workflow params are taken from
@@ -820,10 +887,8 @@ function CustomReplayPanel({
   // The override selects pull their option lists from the workflow
   // definition for the last step, so we always reflect the real
   // allowed values (not a hard-coded list that drifts).
-  const lastWf = WORKFLOWS.find((w) => w.id === lastStep?.workflowId);
-  const aspectInput = lastWf?.inputs?.find(
-    (i) => i.key === "aspect_ratio" && i.type === "select",
-  );
+  const lastWf = workflows.find((w) => w.id === lastStep?.workflowId);
+  const aspectInput = lastWf?.inputs?.find((i) => i.key === "aspect_ratio" && i.type === "select");
   const resolutionInput = lastWf?.inputs?.find(
     (i) => i.key === "resolution" && i.type === "select",
   );
@@ -831,8 +896,8 @@ function CustomReplayPanel({
   // Pre-flight: surface missing required inputs BEFORE dispatch so the
   // chain doesn't fail mid-step with a vague "Prompt is required" toast.
   const validationError = useMemo(
-    () => validateRecipeSteps(custom.steps),
-    [custom.steps],
+    () => validateRecipeSteps(custom.steps, workflows),
+    [custom.steps, workflows],
   );
 
   return (
@@ -841,7 +906,17 @@ function CustomReplayPanel({
         <header className="rfs-action-pin-header">
           <div className="rfs-action-pin-header-row">
             <div className="rfs-action-pin-icon" aria-hidden>
-              <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <svg
+                aria-hidden="true"
+                width="18"
+                height="18"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
                 <rect x="3" y="3" width="7" height="7" rx="1" />
                 <rect x="14" y="3" width="7" height="7" rx="1" />
                 <rect x="14" y="14" width="7" height="7" rx="1" />
@@ -851,7 +926,8 @@ function CustomReplayPanel({
             <div className="rfs-action-pin-title">
               <div className="rfs-action-pin-name">{custom.name}</div>
               <div className="rfs-action-pin-desc">
-                Replay these {custom.steps.length} step{custom.steps.length === 1 ? "" : "s"} on the current image
+                Replay these {custom.steps.length} step{custom.steps.length === 1 ? "" : "s"} on the
+                current image
               </div>
             </div>
           </div>
@@ -859,12 +935,13 @@ function CustomReplayPanel({
         <div className="rfs-action-pin-body">
           <ol className="rfs-custom-steps">
             {custom.steps.map((step, i) => {
-              const wf = WORKFLOWS.find((w) => w.id === step.workflowId);
+              const wf = workflows.find((w) => w.id === step.workflowId);
               const params: string[] = [];
               if (step.values?.aspect_ratio) params.push(step.values.aspect_ratio);
               if (step.values?.resolution) params.push(step.values.resolution);
               if (step.values?.color) params.push(step.values.color);
-              if (step.prompt) params.push(`"${step.prompt.slice(0, 40)}${step.prompt.length > 40 ? "…" : ""}"`);
+              if (step.prompt)
+                params.push(`"${step.prompt.slice(0, 40)}${step.prompt.length > 40 ? "…" : ""}"`);
               return (
                 <li key={i} className="rfs-custom-step">
                   <span className="rfs-custom-step-num">{i + 1}</span>
@@ -894,7 +971,9 @@ function CustomReplayPanel({
               </button>
               {showOverride ? (
                 <div className="rfs-custom-override-body">
-                  {aspectInput && aspectInput.type === "select" && overridableKeys.includes("aspect_ratio") ? (
+                  {aspectInput &&
+                  aspectInput.type === "select" &&
+                  overridableKeys.includes("aspect_ratio") ? (
                     <div className="rfs-input-group">
                       <label className="rfs-label">Aspect ratio</label>
                       <select
@@ -905,12 +984,16 @@ function CustomReplayPanel({
                         }
                       >
                         {aspectInput.options.map((o) => (
-                          <option key={o.value} value={o.value}>{o.label}</option>
+                          <option key={o.value} value={o.value}>
+                            {o.label}
+                          </option>
                         ))}
                       </select>
                     </div>
                   ) : null}
-                  {resolutionInput && resolutionInput.type === "select" && overridableKeys.includes("resolution") ? (
+                  {resolutionInput &&
+                  resolutionInput.type === "select" &&
+                  overridableKeys.includes("resolution") ? (
                     <div className="rfs-input-group">
                       <label className="rfs-label">Resolution</label>
                       <select
@@ -921,7 +1004,9 @@ function CustomReplayPanel({
                         }
                       >
                         {resolutionInput.options.map((o) => (
-                          <option key={o.value} value={o.value}>{o.label}</option>
+                          <option key={o.value} value={o.value}>
+                            {o.label}
+                          </option>
                         ))}
                       </select>
                     </div>
@@ -933,8 +1018,11 @@ function CustomReplayPanel({
         </div>
       </div>
       <footer className="rfs-action-footer">
-        <button className="rfs-btn" onClick={onCancel}>Cancel</button>
+        <button type="button" className="rfs-btn" onClick={onCancel}>
+          Cancel
+        </button>
         <button
+          type="button"
           className="rfs-btn rfs-btn-primary"
           onClick={() => onApply(showOverride ? overrides : {})}
           disabled={!!validationError}
@@ -968,6 +1056,7 @@ function CustomEditorPanel({
   onSave: () => void;
   onCancel: () => void;
 }) {
+  const { workflows } = useShellConfig();
   const [pickerOpen, setPickerOpen] = useState(false);
   const [expandedStep, setExpandedStep] = useState<number | null>(null);
 
@@ -1021,13 +1110,10 @@ function CustomEditorPanel({
   // check already gates "no name" / "no steps"; this is the additive
   // case ("steps exist but a required input is blank").
   const stepValidationError = useMemo(
-    () => validateRecipeSteps(draft.steps),
-    [draft.steps],
+    () => validateRecipeSteps(draft.steps, workflows),
+    [draft.steps, workflows],
   );
-  const canSave =
-    draft.steps.length > 0 &&
-    draft.name.trim().length > 0 &&
-    !stepValidationError;
+  const canSave = draft.steps.length > 0 && draft.name.trim().length > 0 && !stepValidationError;
 
   return (
     <>
@@ -1035,7 +1121,17 @@ function CustomEditorPanel({
         <header className="rfs-action-pin-header">
           <div className="rfs-action-pin-header-row">
             <div className="rfs-action-pin-icon" aria-hidden>
-              <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+              <svg
+                aria-hidden="true"
+                width="18"
+                height="18"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
                 <path d="M12 20h9" />
                 <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z" />
               </svg>
@@ -1076,7 +1172,7 @@ function CustomEditorPanel({
           ) : (
             <div className="rfs-package-list">
               {draft.steps.map((step, i) => {
-                const wf = WORKFLOWS.find((w) => w.id === step.workflowId);
+                const wf = workflows.find((w) => w.id === step.workflowId);
                 const isExpanded = expandedStep === i;
                 const summary = stepSummaryText(step, wf);
                 return (
@@ -1164,8 +1260,11 @@ function CustomEditorPanel({
         </div>
       </div>
       <footer className="rfs-action-footer">
-        <button className="rfs-btn" onClick={onCancel}>Cancel</button>
+        <button type="button" className="rfs-btn" onClick={onCancel}>
+          Cancel
+        </button>
         <button
+          type="button"
           className="rfs-btn rfs-btn-primary"
           onClick={onSave}
           disabled={!canSave}
@@ -1199,10 +1298,13 @@ type RecipeValidationError = {
   stepIndex: number;
   message: string;
 };
-function validateRecipeSteps(steps: CustomStep[]): RecipeValidationError | null {
+function validateRecipeSteps(
+  steps: CustomStep[],
+  workflows: ReadonlyArray<Workflow>,
+): RecipeValidationError | null {
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
-    const wf = WORKFLOWS.find((w) => w.id === step.workflowId);
+    const wf = workflows.find((w) => w.id === step.workflowId);
     if (!wf) continue;
 
     // Implicit prompt requirement: prompt/prompt-zip workflows store
@@ -1244,7 +1346,7 @@ function validateRecipeSteps(steps: CustomStep[]): RecipeValidationError | null
 function stepSummaryText(step: CustomStep, wf: Workflow | undefined): string {
   const bits: string[] = [];
   const v = step.values ?? {};
-  if (step.prompt && step.prompt.trim()) {
+  if (step.prompt?.trim()) {
     const p = step.prompt.trim();
     bits.push(`"${p.length > 30 ? `${p.slice(0, 30)}…` : p}"`);
   }
@@ -1282,6 +1384,7 @@ function ActionHeaderWithExamples({
   activeAssetId: string | null;
   onSelectAsset?: (id: string) => void;
 }) {
+  const { samples: catalogSamples } = useShellConfig();
   const [open, setOpen] = useState(false);
   // Recompute matching samples when the workflow changes; reset the
   // open state so an expanded strip from one workflow doesn't bleed
@@ -1292,21 +1395,17 @@ function ActionHeaderWithExamples({
 
   const samples = useMemo<SampleAsset[]>(() => {
     if (!workflowId) return [];
-    return SAMPLES.filter(
-      (s) =>
-        s.recommendedWorkflows?.includes(workflowId) &&
-        s.id !== activeAssetId,
-    ).slice(0, 4);
-  }, [workflowId, activeAssetId]);
+    return catalogSamples
+      .filter((s) => s.recommendedWorkflows?.includes(workflowId) && s.id !== activeAssetId)
+      .slice(0, 4);
+  }, [workflowId, activeAssetId, catalogSamples]);
 
   const hasSamples = samples.length > 0 && !!onSelectAsset;
 
   return (
     <header className={`rfs-action-pin-header${open ? " is-expanded" : ""}`}>
       <div className="rfs-action-pin-header-row">
-        <div className="rfs-action-pin-icon">
-          {Icon[meta.iconKey as keyof typeof Icon] ?? null}
-        </div>
+        <div className="rfs-action-pin-icon">{Icon[meta.iconKey as keyof typeof Icon] ?? null}</div>
         <div className="rfs-action-pin-title">
           <div className="rfs-action-pin-name">{meta.name}</div>
           <div className="rfs-action-pin-desc">{meta.desc}</div>
@@ -1316,21 +1415,21 @@ function ActionHeaderWithExamples({
             type="button"
             className={`rfs-action-examples-toggle${open ? " is-open" : ""}`}
             onClick={() => setOpen((v) => !v)}
-            title={open ? "Hide examples" : `See ${samples.length} sample${samples.length === 1 ? "" : "s"} this works on`}
+            title={
+              open
+                ? "Hide examples"
+                : `See ${samples.length} sample${samples.length === 1 ? "" : "s"} this works on`
+            }
             aria-expanded={open}
           >
             <span aria-hidden>✨</span>
-            <span className="rfs-action-examples-toggle-label">
-              {open ? "Hide" : "Examples"}
-            </span>
+            <span className="rfs-action-examples-toggle-label">{open ? "Hide" : "Examples"}</span>
           </button>
         ) : null}
       </div>
       {open && hasSamples ? (
         <div className="rfs-action-examples">
-          <div className="rfs-action-examples-hint">
-            Try this workflow on a curated demo image:
-          </div>
+          <div className="rfs-action-examples-hint">Try this workflow on a curated demo image:</div>
           <div className="rfs-action-examples-strip">
             {samples.map((s) => (
               <button
@@ -1353,4 +1452,3 @@ function ActionHeaderWithExamples({
     </header>
   );
 }
-
diff --git a/packages/studio/src/components/icons.tsx b/packages/studio/src/components/icons.tsx
index 101c832..dd31bfe 100644
--- a/packages/studio/src/components/icons.tsx
+++ b/packages/studio/src/components/icons.tsx
@@ -6,25 +6,57 @@ import type { ReactNode } from "react";
 export const Icon = {
   // Header
   sidebarHide: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <rect x="3" y="4" width="18" height="16" rx="2" />
       <path d="M9 4v16M14 9l-2 3 2 3" />
     </svg>
   ),
   sidebarShow: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <rect x="3" y="4" width="18" height="16" rx="2" />
       <path d="M9 4v16M11 9l2 3-2 3" />
     </svg>
   ),
   share: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <path d="M16 6l-4-4-4 4M12 2v14" />
       <path d="M5 14v6a2 2 0 002 2h10a2 2 0 002-2v-6" />
     </svg>
   ),
   download: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <path d="M12 4v12M6 12l6 6 6-6M4 20h16" />
     </svg>
   ),
@@ -32,88 +64,220 @@ export const Icon = {
     // Stack-of-pages glyph with a small down arrow on the front sheet.
     // Reads as "bundle of files + download" so the user clocks it as
     // "grab all versions as one file" without needing the tooltip.
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
       <path d="M8 3h7l5 5v11a2 2 0 0 1-2 2H8a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2z" />
       <path d="M4 7v12a2 2 0 0 0 2 2h10" opacity="0.55" />
       <path d="M13 13v4M11 15l2 2 2-2" />
     </svg>
   ),
   link: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
       <path d="M10 13a5 5 0 0 0 7.07 0l3-3a5 5 0 0 0-7.07-7.07l-1.5 1.5" />
       <path d="M14 11a5 5 0 0 0-7.07 0l-3 3a5 5 0 0 0 7.07 7.07l1.5-1.5" />
     </svg>
   ),
   check: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.4" strokeLinecap="round" strokeLinejoin="round">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.4"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
       <path d="M5 12l5 5L20 7" />
     </svg>
   ),
   undo: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <path d="M3 12a9 9 0 0115-6.7L21 8M21 3v5h-5" />
     </svg>
   ),
   redo: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <path d="M21 12a9 9 0 00-15-6.7L3 8M3 3v5h5" />
     </svg>
   ),
   close: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.4">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2.4"
+    >
       <path d="M6 6l12 12M18 6L6 18" />
     </svg>
   ),
   search: (
-    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <circle cx="11" cy="11" r="7" />
       <path d="M20 20l-3.5-3.5" />
     </svg>
   ),
   upload: (
-    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <path d="M12 4v12M6 10l6-6 6 6" />
       <path d="M4 20h16" />
     </svg>
   ),
   generate: (
     // Four-pointed sparkle — the universal "AI made this" affordance.
-    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round">
+    <svg
+      aria-hidden="true"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
       <path d="M12 3l1.7 4.3L18 9l-4.3 1.7L12 15l-1.7-4.3L6 9l4.3-1.7L12 3z" />
       <path d="M19 16l.7 1.8L21.5 18.5l-1.8.7L19 21l-.7-1.8L16.5 18.5l1.8-.7L19 16z" />
     </svg>
   ),
   back: (
-    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+    <svg
+      aria-hidden="true"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
       <path d="M19 12H5M12 19l-7-7 7-7" />
     </svg>
   ),
   refresh: (
-    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+    <svg
+      aria-hidden="true"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
       <path d="M3 12a9 9 0 1 1 3 6.7" />
       <path d="M3 19v-6h6" />
     </svg>
   ),
   compare: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <path d="M12 3v18M5 8l-2 4 2 4M19 8l2 4-2 4" />
     </svg>
   ),
   zoomIn: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <circle cx="11" cy="11" r="7" />
       <path d="M20 20l-3.5-3.5M11 8v6M8 11h6" />
     </svg>
   ),
   zoomOut: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <circle cx="11" cy="11" r="7" />
       <path d="M20 20l-3.5-3.5M8 11h6" />
     </svg>
   ),
   // Tabs
   workflows: (
-    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <rect x="3" y="3" width="7" height="7" rx="1.5" />
       <rect x="14" y="3" width="7" height="7" rx="1.5" />
       <rect x="3" y="14" width="7" height="7" rx="1.5" />
@@ -121,26 +285,58 @@ export const Icon = {
     </svg>
   ),
   chat: (
-    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <path d="M3 7a3 3 0 013-3h12a3 3 0 013 3v8a3 3 0 01-3 3H8l-4 4v-4H6a3 3 0 01-3-3V7z" />
     </svg>
   ),
   history: (
-    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg
+      aria-hidden="true"
+      width="14"
+      height="14"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+    >
       <path d="M3 12a9 9 0 109-9 9 9 0 00-7.6 4.2L3 9" />
       <path d="M3 4v5h5M12 7v5l3 2" />
     </svg>
   ),
   // Workflow card icons
   "ai-edit": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <path d="M3 21l3-1 11-11-2-2L4 18l-1 3z" />
       <path d="M14 7l3 3" />
       <circle cx="20" cy="4" r="1.4" fill="currentColor" />
     </svg>
   ),
   "reference-inpaint": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <rect x="3" y="3" width="18" height="14" rx="2" />
       <path d="M3 13l5-4 4 3" />
       <circle cx="17" cy="8" r="1.5" fill="currentColor" />
@@ -150,13 +346,31 @@ export const Icon = {
   "logo-fix": (
     // T-shirt silhouette with a small badge — reads as "place a logo
     // on the garment" at thumbnail size.
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
       <path d="M7 4l2 2h6l2-2 3 2-2 4h-2v10H6V10H4L2 6z" />
       <circle cx="13.5" cy="11.5" r="2" />
     </svg>
   ),
   "ai-scene": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <path d="M3 19l5-7 4 5 3-3 6 5z" />
       <circle cx="17" cy="7" r="2" />
     </svg>
@@ -165,76 +379,175 @@ export const Icon = {
     // Shopping bag: signals "marketplace bundle" — a package of edits
     // that produces one catalog-ready image. Same visual family as the
     // other icons (1.8px stroke, 24×24 viewBox, currentColor).
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
       <path d="M5 7h14l-1.2 12.2a2 2 0 0 1-2 1.8H8.2a2 2 0 0 1-2-1.8L5 7z" />
       <path d="M9 7V5a3 3 0 0 1 6 0v2" />
       <path d="M9 11v2M15 11v2" />
     </svg>
   ),
   "product-isolation": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <rect x="4" y="4" width="16" height="16" rx="2" strokeDasharray="3 2" />
       <path d="M9 8c2 0 3 2 3 4s1 4 3 4" />
     </svg>
   ),
   outpaint: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <path d="M3 9V3h6M21 9V3h-6M3 15v6h6M21 15v6h-6" />
       <rect x="8" y="8" width="8" height="8" rx="1" />
     </svg>
   ),
   "smart-resize": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <rect x="3" y="3" width="18" height="18" rx="2" />
       <path d="M8 12h8M12 8v8" strokeDasharray="2 2" />
       <path d="M3 8l3-3M21 8l-3-3M3 16l3 3M21 16l-3 3" />
     </svg>
   ),
   "background-color": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <rect x="3" y="3" width="18" height="14" rx="2" />
       <path d="M3 13l5-4 4 3 4-5 5 6" />
     </svg>
   ),
   "background-removal": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8" strokeDasharray="3 2">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+      strokeDasharray="3 2"
+    >
       <rect x="4" y="4" width="16" height="16" rx="2" />
       <circle cx="12" cy="12" r="4" strokeDasharray="0" />
     </svg>
   ),
   "tag-removal": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <path d="M20 12L12 20a2.8 2.8 0 01-4 0l-4-4a2.8 2.8 0 010-4L12 4h8v8z" />
       <circle cx="16.5" cy="7.5" r="1.2" />
     </svg>
   ),
   "object-removal": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <circle cx="12" cy="12" r="8" />
       <path d="M8 12h8" />
     </svg>
   ),
   "model-removal": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <circle cx="9" cy="8" r="3" />
       <path d="M3 21c0-4 3-6 6-6" />
       <path d="M14 14l6 6M20 14l-6 6" />
     </svg>
   ),
   "skin-fix": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <path d="M12 3l2 5 5 1-4 4 1 5-4-3-4 3 1-5-4-4 5-1 2-5z" />
     </svg>
   ),
   "ai-logo": (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <circle cx="12" cy="12" r="9" />
       <circle cx="12" cy="12" r="3" />
       <path d="M12 3v3M12 18v3M3 12h3M18 12h3" />
     </svg>
   ),
   video: (
-    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.8">
+    <svg
+      aria-hidden="true"
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.8"
+    >
       <rect x="3" y="6" width="13" height="12" rx="2" />
       <path d="M16 10l5-3v10l-5-3z" />
     </svg>
diff --git a/packages/studio/src/data/samples.generated.json b/packages/studio/src/data/samples.generated.json
index 29e5074..784001b 100644
--- a/packages/studio/src/data/samples.generated.json
+++ b/packages/studio/src/data/samples.generated.json
@@ -4,203 +4,128 @@
     {
       "id": "sneaker-white",
       "title": "Sneaker — studio",
-      "tags": [
-        "product",
-        "footwear"
-      ],
+      "tags": ["product", "footwear"],
       "aspect_ratio": "1:1",
       "prompt": "Premium minimalist white leather sneaker centered on a clean off-white seamless backdrop, soft top-down studio lighting with a subtle natural shadow underneath, e-commerce catalog hero shot, ultra-detailed fabric and stitching, photorealistic.",
       "url": "https://v3b.fal.media/files/b/0a991a66/8YuTT7o8iAEI5FuH3u81m_2e00493442924f0f9a654023c4eda645.jpg",
       "width": 1024,
       "height": 1024,
-      "recommendedWorkflows": [
-        "background-color",
-        "ai-scene"
-      ]
+      "recommendedWorkflows": ["background-color", "ai-scene"]
     },
     {
       "id": "watch-leather",
       "title": "Wristwatch — leather strap",
-      "tags": [
-        "product",
-        "accessories"
-      ],
+      "tags": ["product", "accessories"],
       "aspect_ratio": "1:1",
       "prompt": "Modern minimalist wristwatch with brown leather strap on a pale beige surface, soft diffused window light from the left, slight cast shadow, three-quarter angle, e-commerce hero shot, ultra-realistic, sharp dial detail.",
       "url": "https://v3b.fal.media/files/b/0a991a67/WK4AAoEW-WP8uTMRHEBEv_b7b616e0f2e94cb8b9d1d98be0317e12.jpg",
       "width": 1024,
       "height": 1024,
-      "recommendedWorkflows": [
-        "ai-scene",
-        "product-isolation"
-      ]
+      "recommendedWorkflows": ["ai-scene", "product-isolation"]
     },
     {
       "id": "perfume-bottle",
       "title": "Perfume bottle — glass",
-      "tags": [
-        "product",
-        "beauty"
-      ],
+      "tags": ["product", "beauty"],
       "aspect_ratio": "3:4",
       "prompt": "Tall clear glass perfume bottle with amber liquid and a brushed-gold cap, on an off-white pedestal, soft studio softbox lighting from above, faint reflection on the surface, premium beauty product photography, ultra-realistic.",
       "url": "https://v3b.fal.media/files/b/0a991a67/wspXRxZt1H_09O0vv1_88_8c0fd4daa8444042b2df13df274e0f6a.jpg",
       "width": 960,
       "height": 1280,
-      "recommendedWorkflows": [
-        "ai-scene",
-        "smart-resize"
-      ]
+      "recommendedWorkflows": ["ai-scene", "smart-resize"]
     },
     {
       "id": "headphones-matte",
       "title": "Headphones — matte black",
-      "tags": [
-        "product",
-        "electronics"
-      ],
+      "tags": ["product", "electronics"],
       "aspect_ratio": "1:1",
       "prompt": "Wireless over-ear headphones in matte charcoal with subtle metallic accents, centered on a clean light-grey background, slight diffuse shadow underneath, premium electronics product shot, photorealistic.",
       "url": "https://v3b.fal.media/files/b/0a991a68/uT_0eO6uBMe5AZg49cS7G_80a503a1793e4c3d9287bed4cb415536.jpg",
       "width": 1024,
       "height": 1024,
-      "recommendedWorkflows": [
-        "background-color",
-        "ai-scene"
-      ]
+      "recommendedWorkflows": ["background-color", "ai-scene"]
     },
     {
       "id": "mug-ceramic",
       "title": "Coffee mug — ceramic",
-      "tags": [
-        "product",
-        "home"
-      ],
+      "tags": ["product", "home"],
       "aspect_ratio": "1:1",
       "prompt": "Hand-thrown ceramic coffee mug with subtle warm-grey glaze on a white surface, slight steam, professional product photography, soft directional shadow, photorealistic.",
       "url": "https://v3b.fal.media/files/b/0a991a68/nqAR5JqAVZCOw25wd7M9y_b18bcdf7466b4512ad09e7b426dfc537.jpg",
       "width": 1024,
       "height": 1024,
-      "recommendedWorkflows": [
-        "ai-scene",
-        "background-color"
-      ]
+      "recommendedWorkflows": ["ai-scene", "background-color"]
     },
     {
       "id": "handbag-tan",
       "title": "Handbag — tan leather",
-      "tags": [
-        "product",
-        "fashion"
-      ],
+      "tags": ["product", "fashion"],
       "aspect_ratio": "3:4",
       "prompt": "Tan leather structured handbag with gold hardware on a clean off-white background, soft directional studio lighting, hero product photography, ultra-realistic, fine grain texture.",
       "url": "https://v3b.fal.media/files/b/0a991a6a/N-5PhbmJhvdGU-IcaD4Js_8bd7e4674772414f82eac3b234f8bf31.jpg",
       "width": 960,
       "height": 1280,
-      "recommendedWorkflows": [
-        "background-removal",
-        "ai-scene",
-        "ai-edit"
-      ]
+      "recommendedWorkflows": ["background-removal", "ai-scene", "ai-edit"]
     },
     {
       "id": "tshirt-ghost",
       "title": "T-shirt — ghost mannequin",
-      "tags": [
-        "product",
-        "fashion"
-      ],
+      "tags": ["product", "fashion"],
       "aspect_ratio": "3:4",
       "prompt": "Crisp white cotton crew-neck t-shirt photographed with the ghost-mannequin technique on a pure white background, even studio lighting, no model, fashion ecommerce, sharp seams visible.",
       "url": "https://v3b.fal.media/files/b/0a991a6a/l0yiYavqEPhEmk2wDsiwF_d52aba1a7c0c4e30bc513ad00919596b.jpg",
       "width": 960,
       "height": 1280,
-      "recommendedWorkflows": [
-        "reference-inpaint",
-        "ai-edit"
-      ]
+      "recommendedWorkflows": ["reference-inpaint", "ai-edit"]
     },
     {
       "id": "chair-lounge",
       "title": "Lounge chair — wooden",
-      "tags": [
-        "product",
-        "furniture"
-      ],
+      "tags": ["product", "furniture"],
       "aspect_ratio": "4:5",
       "prompt": "Modern wooden lounge chair with woven cane back and bouclé cushion on a clean off-white seamless backdrop, studio lighting, furniture catalog photography, photorealistic.",
       "url": "https://v3b.fal.media/files/b/0a991a6a/jTPKtTYCY295QhLdrIV-U_59c834f1d66c4bf69386196b11d7dc80.jpg",
       "width": 1024,
       "height": 1280,
-      "recommendedWorkflows": [
-        "smart-resize",
-        "ai-scene"
-      ]
+      "recommendedWorkflows": ["smart-resize", "ai-scene"]
     },
     {
       "id": "skincare-serum",
       "title": "Skincare serum — glass",
-      "tags": [
-        "product",
-        "beauty"
-      ],
+      "tags": ["product", "beauty"],
       "aspect_ratio": "3:4",
       "prompt": "Clear glass skincare serum bottle with a cream label and matte black dropper top, on a soft beige surface, dappled morning light, dermal product photography, photorealistic.",
       "url": "https://v3b.fal.media/files/b/0a991a6b/ut47U5xpJqHmZ_ut6Bp3f_301b63a9cfc24d1baf2044babd6110f8.jpg",
       "width": 960,
       "height": 1280,
-      "recommendedWorkflows": [
-        "ai-scene",
-        "background-color"
-      ]
+      "recommendedWorkflows": ["ai-scene", "background-color"]
     },
     {
       "id": "model-cream-sweater",
       "title": "On-model — cream sweater",
-      "tags": [
-        "on-model",
-        "fashion"
-      ],
+      "tags": ["on-model", "fashion"],
       "aspect_ratio": "3:4",
       "prompt": "Editorial fashion photo of a woman wearing an oversized cream cashmere sweater and tan trousers, on a soft cream studio backdrop, natural soft lighting, three-quarter view, fashion ecommerce, ultra-realistic skin and fabric detail.",
       "url": "https://v3b.fal.media/files/b/0a991a6c/0-Btj1TAMxreL6zgRQefW_a01b77fd2d374d4796333fce556abcd6.jpg",
       "width": 960,
       "height": 1280,
-      "recommendedWorkflows": [
-        "skin-fix",
-        "model-removal",
-        "reference-inpaint"
-      ]
+      "recommendedWorkflows": ["skin-fix", "model-removal", "reference-inpaint"]
     },
     {
       "id": "lifestyle-sneaker",
       "title": "Lifestyle — sneaker on cobble",
-      "tags": [
-        "lifestyle",
-        "footwear"
-      ],
+      "tags": ["lifestyle", "footwear"],
       "aspect_ratio": "16:9",
       "prompt": "Editorial product photo of a white sneaker resting on a sun-dappled cobblestone street, Mediterranean morning light, cinematic shallow depth of field, ultra-realistic textures, e-commerce campaign style.",
       "url": "https://v3b.fal.media/files/b/0a991a6d/c9XlFqybKQu11rLKkCRLd_b3c1ad06be904e4b8f74acd9bac16fdd.jpg",
       "width": 1344,
       "height": 768,
-      "recommendedWorkflows": [
-        "smart-resize",
-        "outpaint",
-        "product-isolation"
-      ]
+      "recommendedWorkflows": ["smart-resize", "outpaint", "product-isolation"]
     },
     {
       "id": "tshirt-tiger-front",
       "title": "T-shirt — tiger front (mannequin + tag)",
-      "tags": [
-        "product",
-        "fashion",
-        "ghost-mannequin",
-        "has-tag",
-        "has-logo"
-      ],
+      "tags": ["product", "fashion", "ghost-mannequin", "has-tag", "has-logo"],
       "aspect_ratio": "3:4",
       "prompt": "Front view of a crisp white cotton crew-neck t-shirt fitted on a smooth beige tailor's mannequin torso with a wooden neck stand visible. The shirt has a small chest pocket on the right chest. Just above the pocket, an embroidered orange-and-black tiger head emblem the size of the pocket itself, around 4cm tall, sharply detailed thread texture, the brand identity of the shirt. A clearly visible white paper retail hangtag dangles from a thin natural-string loop attached to the inside of the neckline, falling forward over the upper left chest. The hangtag is rectangular, about 4cm by 7cm, and has its own printed branding: a stylized geometric monogram in dark grey at the top (a simple shape, not the tiger), the brand wordmark in a small serif below it, and the price \"$29\" in clean sans-serif at the bottom. Both logos must be sharply readable: the embroidered tiger on the chest AND the printed monogram on the hangtag. Plain warm-grey seamless studio backdrop, soft even studio lighting, gentle shadow under the mannequin base. Photoreal e-commerce ghost-mannequin photography, ultra-detailed fabric weave, no people, 3:4 portrait framing.",
       "url": "https://8b72080bbbd80302c40de95d14ca24ca.r2.cloudflarestorage.com/runflow-general/ed5bb328-a3e5-4f12-a3ae-693640bccdc9/98c7e3a1445ce422.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=e29feb89bdce9df26fc23f73dcd457ff%2F20260513%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20260513T002020Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=d12bb4d0c2245ff0b635c2241edc54d386ebb739fd97e344dfb7558bd6aea9f9",
@@ -216,12 +141,7 @@
     {
       "id": "samba-on-foot-with-tag",
       "title": "Adidas Samba — on-foot with hangtag",
-      "tags": [
-        "on-model",
-        "footwear",
-        "has-tag",
-        "has-logo"
-      ],
+      "tags": ["on-model", "footwear", "has-tag", "has-logo"],
       "aspect_ratio": "4:5",
       "prompt": "Photoreal editorial product photograph of an Adidas Samba OG sneaker worn on a person's right foot, three-quarter view from a slight low angle. The shoe is the classic colorway: white leather upper, black leather T-toe overlay and three-stripes on the lateral side, white \"adidas\" wordmark above the stripes, gum rubber outsole. A paper retail hangtag with the Adidas trefoil printed on cream cardstock dangles from the top eyelet of the laces on a thin twine loop, clearly visible in frame, catching soft light. The model wears cropped grey trousers; only the lower leg from mid-shin down is visible, no socks. Set: muted warm-grey seamless paper backdrop, soft key light from camera-left, gentle floor contact shadow. Sharp focus on the shoe, especially the three-stripes and the hangtag. Editorial product photography, true colors, no extra text or graphics in frame. 4:5 portrait framing.",
       "url": "https://8b72080bbbd80302c40de95d14ca24ca.r2.cloudflarestorage.com/runflow-general/03bc298c-cbc2-48b8-9994-2d172f60ea45/45018803e83e69d9.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=e29feb89bdce9df26fc23f73dcd457ff%2F20260512%2Fauto%2Fs3%2Faws4_request&X-Amz-Date=20260512T222938Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=b1435b4780d47b9179d69098041749adc67702dd2079c3530cf8d2658b9b9eea",
@@ -236,4 +156,4 @@
       ]
     }
   ]
-}
\ No newline at end of file
+}
diff --git a/packages/studio/src/data/workflows.ts b/packages/studio/src/data/workflows.ts
index 6cec3df..5974116 100644
--- a/packages/studio/src/data/workflows.ts
+++ b/packages/studio/src/data/workflows.ts
@@ -47,8 +47,23 @@ export type WorkflowGroup = "magic" | "compose" | "cleanup" | "enhance" | "packa
 
 export type WorkflowInput =
   | { type: "color"; key: string; label: string; default?: string; help?: string }
-  | { type: "text"; key: string; label: string; placeholder?: string; maxlength?: number; help?: string; optional?: boolean }
-  | { type: "textarea"; key: string; label: string; placeholder?: string; maxlength?: number; help?: string }
+  | {
+      type: "text";
+      key: string;
+      label: string;
+      placeholder?: string;
+      maxlength?: number;
+      help?: string;
+      optional?: boolean;
+    }
+  | {
+      type: "textarea";
+      key: string;
+      label: string;
+      placeholder?: string;
+      maxlength?: number;
+      help?: string;
+    }
   | {
       type: "select";
       key: string;
@@ -143,9 +158,9 @@ export type Workflow = {
 const hex2rgb = (hex: string) => {
   const h = hex.replace("#", "");
   return {
-    r: parseInt(h.slice(0, 2), 16),
-    g: parseInt(h.slice(2, 4), 16),
-    b: parseInt(h.slice(4, 6), 16),
+    r: Number.parseInt(h.slice(0, 2), 16),
+    g: Number.parseInt(h.slice(2, 4), 16),
+    b: Number.parseInt(h.slice(4, 6), 16),
   };
 };
 
@@ -517,7 +532,7 @@ export const WORKFLOWS: Workflow[] = [
         input: {
           image_url: img,
           model: vals.model || "Standard V2",
-          upscale_factor: parseFloat(vals.upscale_factor || "2"),
+          upscale_factor: Number.parseFloat(vals.upscale_factor || "2"),
           output_format: "png",
           ...(faceOn
             ? {
@@ -577,7 +592,11 @@ export const WORKFLOWS: Workflow[] = [
       prep: [
         { workflowId: "tag-removal", params: {}, label: "Remove price tag" },
         { workflowId: "model-removal", params: {}, label: "Remove the mannequin" },
-        { workflowId: "background-color", params: { color: "#F1F1F1" }, label: "Apply Zalando grey" },
+        {
+          workflowId: "background-color",
+          params: { color: "#F1F1F1" },
+          label: "Apply Zalando grey",
+        },
       ],
     },
   },
diff --git a/packages/studio/src/headless.ts b/packages/studio/src/headless.ts
index b009ed8..c4bd61a 100644
--- a/packages/studio/src/headless.ts
+++ b/packages/studio/src/headless.ts
@@ -9,12 +9,32 @@ export { BUILTIN_TOOLS, findTool } from "./tools/index.js";
 
 // Prototype-style workflow catalogue + dispatcher (mask/pin/reference
 // kinds; richer than the SDK's defineTool DSL today but pre-1.0).
-export { WORKFLOWS, type Workflow, type WorkflowInput, type WorkflowKind, type WorkflowGroup } from "./data/workflows.js";
+export {
+  WORKFLOWS,
+  type Workflow,
+  type WorkflowInput,
+  type WorkflowKind,
+  type WorkflowGroup,
+} from "./data/workflows.js";
 export { SAMPLES, type SampleAsset } from "./data/samples.js";
-export { runWorkflow, type RunProgress, type RunResult, type RunStatus, type DispatchInputs } from "./lib/runflow.js";
+export {
+  runWorkflow,
+  type RunProgress,
+  type RunResult,
+  type RunStatus,
+  type DispatchInputs,
+} from "./lib/runflow.js";
+
+// Brush + mask creation — framework-free dual-canvas painting engine.
+// The same controller StudioShell uses internally for its mask workflows.
+export { createMaskController } from "./lib/mask.js";
+export type { MaskController, MaskControllerOptions } from "./lib/mask.js";
 
 // Sentinel evaluation client.
-export { evaluate as sentinelEvaluate, taskDescription as sentinelTaskDescription } from "./lib/sentinel.js";
+export {
+  evaluate as sentinelEvaluate,
+  taskDescription as sentinelTaskDescription,
+} from "./lib/sentinel.js";
 export type { Judge, SentinelResult } from "./lib/sentinel.js";
 
 // Endpoint URL registry — the same `URLS` object the bundled Studio
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index 8a4f3a5..8027237 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -15,10 +15,11 @@
  * ```
  */
 
-import { createRoot, type Root } from "react-dom/client";
 import { createElement } from "react";
+import { type Root, createRoot } from "react-dom/client";
 import { StudioShell } from "./components/StudioShell.js";
-import { setStudioUrls, type StudioUrls } from "./lib/urls.js";
+import type { StudioShellProps } from "./lib/shell-config.js";
+import { type StudioUrls, setStudioUrls } from "./lib/urls.js";
 import { injectStyles } from "./styles.js";
 
 export interface ThemeOverrides {
@@ -36,6 +37,11 @@ export interface ThemeOverrides {
 export interface StudioMountOptions {
   /** Endpoint overrides. See `StudioUrls` for the full shape. */
   urls?: Partial<StudioUrls>;
+  /**
+   * Shell customization — workflow catalogue, initial source assets,
+   * sentinel config, copy overrides. See `StudioShellProps`.
+   */
+  props?: StudioShellProps;
   /** `light` | `dark` | `auto` | per-token overrides. Default `dark`. */
   theme?: "light" | "dark" | "auto" | ThemeOverrides;
   /** Inject the default stylesheet into <head>. Default true. */
@@ -62,12 +68,13 @@ export function mount(
   applyThemeOverrides(el, options.theme);
 
   const root = createRoot(el);
-  root.render(createElement(StudioShell));
+  root.render(createElement(StudioShell, options.props ?? {}));
 
   return {
     unmount() {
       root.unmount();
       el.removeAttribute("data-theme");
+      for (const [, cssVar] of THEME_VAR_MAP) el.style.removeProperty(cssVar);
     },
   };
 }
@@ -82,33 +89,41 @@ function applyThemeAttribute(el: HTMLElement, theme: StudioMountOptions["theme"]
   if (theme === "light") mode = "light";
   else if (theme === "auto") {
     mode =
-      typeof window !== "undefined" &&
-      window.matchMedia?.("(prefers-color-scheme: light)").matches
+      typeof window !== "undefined" && window.matchMedia?.("(prefers-color-scheme: light)").matches
         ? "light"
         : "dark";
   }
   el.setAttribute("data-theme", mode);
 }
 
+const THEME_VAR_MAP: Array<[keyof ThemeOverrides, string]> = [
+  ["accent", "--rfs-accent"],
+  ["bg0", "--rfs-bg-0"],
+  ["bg1", "--rfs-bg-1"],
+  ["bg2", "--rfs-bg-2"],
+  ["bg3", "--rfs-bg-3"],
+  ["ink0", "--rfs-ink-0"],
+  ["ink1", "--rfs-ink-1"],
+  ["ink2", "--rfs-ink-2"],
+  ["ink3", "--rfs-ink-3"],
+];
+
 function applyThemeOverrides(el: HTMLElement, theme: StudioMountOptions["theme"]): void {
   if (!theme || typeof theme === "string") return;
-  const map: Array<[keyof ThemeOverrides, string]> = [
-    ["accent", "--rfs-accent"],
-    ["bg0", "--rfs-bg-0"],
-    ["bg1", "--rfs-bg-1"],
-    ["bg2", "--rfs-bg-2"],
-    ["bg3", "--rfs-bg-3"],
-    ["ink0", "--rfs-ink-0"],
-    ["ink1", "--rfs-ink-1"],
-    ["ink2", "--rfs-ink-2"],
-    ["ink3", "--rfs-ink-3"],
-  ];
-  for (const [key, cssVar] of map) {
+  for (const [key, cssVar] of THEME_VAR_MAP) {
     const v = theme[key];
     if (typeof v === "string") el.style.setProperty(cssVar, v);
   }
 }
 
 export { StudioShell } from "./components/StudioShell.js";
+export { resolveShellConfig } from "./lib/shell-config.js";
+export type {
+  StudioShellProps,
+  StudioCopy,
+  StudioSentinelOptions,
+} from "./lib/shell-config.js";
+export type { Workflow } from "./data/workflows.js";
+export type { SampleAsset } from "./data/samples.js";
 export { setStudioUrls, URLS } from "./lib/urls.js";
 export type { StudioUrls } from "./lib/urls.js";
diff --git a/packages/studio/src/lib/chat.ts b/packages/studio/src/lib/chat.ts
index fd516b4..aa01164 100644
--- a/packages/studio/src/lib/chat.ts
+++ b/packages/studio/src/lib/chat.ts
@@ -35,9 +35,7 @@ export type ToolResultBlock = {
 };
 export type ImageBlock = {
   type: "image";
-  source:
-    | { type: "url"; url: string }
-    | { type: "base64"; media_type: string; data: string };
+  source: { type: "url"; url: string } | { type: "base64"; media_type: string; data: string };
 };
 
 export type ContentBlock = TextBlock | ToolUseBlock | ToolResultBlock | ImageBlock;
@@ -84,8 +82,7 @@ export type StudioHandle = {
     captured: CapturedInputs,
     opts?: { intermediate?: boolean },
   ) => Promise<
-    | { ok: true; versionId: string; outputUrl: string; label: string }
-    | { ok: false; error: string }
+    { ok: true; versionId: string; outputUrl: string; label: string } | { ok: false; error: string }
   >;
 };
 
@@ -137,8 +134,7 @@ async function* parseSse(stream: ReadableStream<Uint8Array>): AsyncGenerator<Sse
       if (done) break;
       buffer += decoder.decode(value, { stream: true });
       // SSE events are separated by blank lines
-      let split: number;
-      while ((split = buffer.indexOf("\n\n")) >= 0) {
+      for (let split = buffer.indexOf("\n\n"); split >= 0; split = buffer.indexOf("\n\n")) {
         const raw = buffer.slice(0, split);
         buffer = buffer.slice(split + 2);
         const lines = raw.split("\n");
@@ -236,7 +232,8 @@ export async function streamChatTurn(
         }
       } else if (ev.event === "content_block_delta") {
         const idx = (ev.data as { index: number }).index;
-        const delta = (ev.data as { delta: { type: string; text?: string; partial_json?: string } }).delta;
+        const delta = (ev.data as { delta: { type: string; text?: string; partial_json?: string } })
+          .delta;
         if (delta.type === "text_delta" && typeof delta.text === "string") {
           const block = blocks[idx];
           if (block && block.type === "text") {
@@ -265,7 +262,8 @@ export async function streamChatTurn(
       } else if (ev.event === "message_stop") {
         // done
       } else if (ev.event === "error") {
-        const errMsg = (ev.data as { error?: { message?: string } }).error?.message ?? "stream error";
+        const errMsg =
+          (ev.data as { error?: { message?: string } }).error?.message ?? "stream error";
         return { ok: false, error: errMsg };
       }
     }
@@ -292,8 +290,19 @@ export type DispatchResult = {
   captured: CapturedInputs;
   /** UI-side notes the chat panel needs to react to (e.g. plan to render). */
   uiEffect?:
-    | { kind: "plan_proposed"; steps: { workflow_id: string; description: string }[]; rationale: string; confirmed: boolean }
-    | { kind: "workflow_complete"; workflowId: string; versionId: string; outputUrl: string; label: string }
+    | {
+        kind: "plan_proposed";
+        steps: { workflow_id: string; description: string }[];
+        rationale: string;
+        confirmed: boolean;
+      }
+    | {
+        kind: "workflow_complete";
+        workflowId: string;
+        versionId: string;
+        outputUrl: string;
+        label: string;
+      }
     | { kind: "workflow_failed"; workflowId: string; error: string }
     | { kind: "input_captured"; field: keyof CapturedInputs };
 };
@@ -369,7 +378,8 @@ export async function runTool(
       const hint = String(block.input.hint ?? "Pick a color");
       const def = typeof block.input.default === "string" ? block.input.default : undefined;
       const hex = await handle.requestColor(hint, def);
-      if (hex === null) return { toolResult: err(id, "User cancelled the color picker."), captured };
+      if (hex === null)
+        return { toolResult: err(id, "User cancelled the color picker."), captured };
       next.color = hex;
       return {
         toolResult: ok(
@@ -390,8 +400,7 @@ export async function runTool(
         return { toolResult: err(id, "request_aspect needs at least one option."), captured };
       }
       const allowCustom = !!block.input.allow_custom;
-      const def =
-        typeof block.input.default === "string" ? block.input.default : undefined;
+      const def = typeof block.input.default === "string" ? block.input.default : undefined;
       const value = await handle.requestAspect(hint, options, allowCustom, def);
       if (value === null) {
         return { toolResult: err(id, "User cancelled the aspect ratio picker."), captured };
@@ -407,8 +416,7 @@ export async function runTool(
     }
     case "request_resolution": {
       const hint = String(block.input.hint ?? "Pick a resolution");
-      const def =
-        typeof block.input.default === "string" ? block.input.default : undefined;
+      const def = typeof block.input.default === "string" ? block.input.default : undefined;
       const value = await handle.requestResolution(hint, def);
       if (value === null) {
         return { toolResult: err(id, "User cancelled the resolution picker."), captured };
@@ -439,8 +447,7 @@ export async function runTool(
       if (options.length < 2) {
         return { toolResult: err(id, "request_choice needs at least two options."), captured };
       }
-      const def =
-        typeof block.input.default === "string" ? block.input.default : undefined;
+      const def = typeof block.input.default === "string" ? block.input.default : undefined;
       const value = await handle.requestChoice(hint, options, def);
       if (value === null) {
         return { toolResult: err(id, "User cancelled the choice picker."), captured };
@@ -463,7 +470,10 @@ export async function runTool(
       }
       next.text = text;
       return {
-        toolResult: ok(id, text === "" ? "User skipped the optional text." : `Text captured: "${text}"`),
+        toolResult: ok(
+          id,
+          text === "" ? "User skipped the optional text." : `Text captured: "${text}"`,
+        ),
         captured: next,
         uiEffect: { kind: "input_captured", field: "text" },
       };
@@ -472,7 +482,13 @@ export async function runTool(
       const workflowId = String(block.input.workflow_id ?? "");
       if (!workflowId) return { toolResult: err(id, "Missing workflow_id."), captured };
       const params: Record<string, string> = {};
-      for (const k of ["prompt", "aspect_ratio", "resolution", "color", "product_isolation_prompt"]) {
+      for (const k of [
+        "prompt",
+        "aspect_ratio",
+        "resolution",
+        "color",
+        "product_isolation_prompt",
+      ]) {
         const v = block.input[k];
         if (typeof v === "string" && v.length) params[k] = v;
       }
@@ -531,7 +547,8 @@ export async function runTool(
 let _sessionId: string | null = null;
 export function getSessionId(): string {
   if (_sessionId) return _sessionId;
-  const stored = typeof window !== "undefined" ? window.sessionStorage.getItem("rfs-chat-session") : null;
+  const stored =
+    typeof window !== "undefined" ? window.sessionStorage.getItem("rfs-chat-session") : null;
   if (stored) {
     _sessionId = stored;
     return stored;
diff --git a/packages/studio/src/lib/custom-workflows.ts b/packages/studio/src/lib/custom-workflows.ts
index 0faedaa..1f9c0f8 100644
--- a/packages/studio/src/lib/custom-workflows.ts
+++ b/packages/studio/src/lib/custom-workflows.ts
@@ -32,9 +32,7 @@ export type CustomWorkflow = {
 
 // Workflows that need runtime canvas input. Any chain containing one
 // of these can't be saved as a custom in v1.
-const STATEFUL_WORKFLOW_IDS = new Set([
-  "reference-inpaint",
-]);
+const STATEFUL_WORKFLOW_IDS = new Set(["reference-inpaint"]);
 
 // True if a candidate chain (list of VersionRequests pulled from a
 // version's history) can be persisted verbatim. Used by the Save
diff --git a/packages/studio/src/lib/generation.ts b/packages/studio/src/lib/generation.ts
index d1fe178..6197780 100644
--- a/packages/studio/src/lib/generation.ts
+++ b/packages/studio/src/lib/generation.ts
@@ -50,15 +50,12 @@ export function pickGenerationTier(resolution: GenerationResolution): Generation
   return TIERS[resolution];
 }
 
-export function estimateGenerationCost(
-  resolution: GenerationResolution,
-  count: number,
-): number {
+export function estimateGenerationCost(resolution: GenerationResolution, count: number): number {
   return TIERS[resolution].costUsd * count;
 }
 
 export function formatCostUsd(usd: number): string {
-  if (usd < 0.01) return `< $0.01`;
+  if (usd < 0.01) return "< $0.01";
   return `$${usd.toFixed(2)}`;
 }
 
@@ -157,8 +154,7 @@ export async function dispatchGeneration(
         // The Runflow API normalises edit-output shapes around an
         // `outputs[]` array; fall back to a couple of legacy shapes
         // so a slight schema drift doesn't kill the panel.
-        const outputUrl =
-          out.outputs?.[0]?.url ?? out.image_urls?.[0] ?? out.image?.url ?? null;
+        const outputUrl = out.outputs?.[0]?.url ?? out.image_urls?.[0] ?? out.image?.url ?? null;
         if (!outputUrl) {
           return { ok: false, tier, error: "Run succeeded but no image URL in output" };
         }
diff --git a/packages/studio/src/lib/mask.ts b/packages/studio/src/lib/mask.ts
new file mode 100644
index 0000000..82c819f
--- /dev/null
+++ b/packages/studio/src/lib/mask.ts
@@ -0,0 +1,273 @@
+/**
+ * Brush-mask controller — the dual-canvas painting engine behind the
+ * Studio shell's mask workflows, exposed as a framework-free primitive
+ * so headless consumers (any framework, or none) get working brush +
+ * mask creation without rebuilding it.
+ *
+ * The model: two canvases.
+ *   - A *visible* overlay the host renders on top of the image. Strokes
+ *     land here in a translucent highlight so the user sees what they've
+ *     painted. Sized to the image's on-screen rect (DPR-aware).
+ *   - A *hidden* canvas the controller owns, same CSS size, black
+ *     background + white strokes — the actual mask source.
+ *
+ * `toMaskBlob(naturalWidth, naturalHeight)` scales the hidden canvas to
+ * the image's natural resolution, thresholds to pure black/white, and
+ * returns a PNG blob ready for `rf.assets.upload` / `mask_url` inputs.
+ *
+ * @example
+ * ```ts
+ * const mask = createMaskController({ brushSize: 45 });
+ * mask.attach(overlayCanvas);
+ * mask.syncToDisplay(rect.width, rect.height, window.devicePixelRatio);
+ * canvas.onpointerdown = (e) => mask.beginStroke(e.offsetX, e.offsetY);
+ * canvas.onpointermove = (e) => mask.strokeTo(e.offsetX, e.offsetY);
+ * canvas.onpointerup = () => mask.endStroke();
+ * const blob = await mask.toMaskBlob(img.naturalWidth, img.naturalHeight);
+ * ```
+ */
+
+export interface MaskControllerOptions {
+  /** Brush radius in display pixels. Default 45. */
+  brushSize?: number;
+  /** Fill style for the visible overlay strokes. Default amber at 55%. */
+  overlayStyle?: string;
+  /** Cap for the devicePixelRatio applied to the visible canvas. Default 2. */
+  maxDevicePixelRatio?: number;
+  /** Sample every Nth pixel when computing coverage. Default 8. */
+  coverageSampleStep?: number;
+  /**
+   * Canvas factory for the internal (hidden/full-res) canvases.
+   * Defaults to `document.createElement("canvas")` — override it in
+   * non-DOM environments or tests.
+   */
+  createCanvas?: (width: number, height: number) => HTMLCanvasElement;
+}
+
+export interface MaskController {
+  /** Connect the visible overlay canvas the host renders. */
+  attach(visible: HTMLCanvasElement): void;
+  /** Drop canvas references (e.g. on unmount). */
+  detach(): void;
+  /**
+   * Size both canvases to the image's displayed rect and reset the
+   * mask. Call on image load and on resize.
+   */
+  syncToDisplay(width: number, height: number, devicePixelRatio?: number): void;
+  setBrushSize(px: number): void;
+  brushSize(): number;
+  /** Begin a stroke at canvas-local display coordinates. */
+  beginStroke(x: number, y: number): void;
+  /** Continue the active stroke; interpolates so fast moves don't gap. */
+  strokeTo(x: number, y: number): void;
+  endStroke(): void;
+  isStroking(): boolean;
+  /** Stamp one brush dab without an active stroke. */
+  paintAt(x: number, y: number): void;
+  /** Wipe the mask (visible overlay cleared, hidden back to black). */
+  clear(): void;
+  /** Painted percentage of the canvas, 0..100 (sampled). */
+  coverage(): number;
+  /**
+   * Render the mask at the image's natural resolution as a pure
+   * black/white PNG blob. Null when nothing is attached/synced yet.
+   */
+  toMaskBlob(naturalWidth: number, naturalHeight: number): Promise<Blob | null>;
+}
+
+const DEFAULT_BRUSH_SIZE = 45;
+const DEFAULT_OVERLAY_STYLE = "rgba(251,191,36,0.55)";
+const DEFAULT_MAX_DPR = 2;
+const DEFAULT_COVERAGE_STEP = 8;
+
+/** Stroke interpolation divides by the brush size — keep it finite and ≥ 1. */
+function clampBrushSize(px: number): number {
+  return Number.isFinite(px) && px >= 1 ? px : 1;
+}
+
+function warnOnce(flag: { warned: boolean }, message: string): void {
+  if (flag.warned) return;
+  flag.warned = true;
+  if (typeof console !== "undefined") console.warn(`[createMaskController] ${message}`);
+}
+
+function domCreateCanvas(width: number, height: number): HTMLCanvasElement {
+  if (typeof document === "undefined") {
+    throw new Error("createMaskController: no DOM available — pass `createCanvas` in the options.");
+  }
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  return canvas;
+}
+
+export function createMaskController(opts: MaskControllerOptions = {}): MaskController {
+  const overlayStyle = opts.overlayStyle ?? DEFAULT_OVERLAY_STYLE;
+  const maxDpr = opts.maxDevicePixelRatio ?? DEFAULT_MAX_DPR;
+  const sampleStep = opts.coverageSampleStep ?? DEFAULT_COVERAGE_STEP;
+  const createCanvas = opts.createCanvas ?? domCreateCanvas;
+
+  let size = clampBrushSize(opts.brushSize ?? DEFAULT_BRUSH_SIZE);
+  let visible: HTMLCanvasElement | null = null;
+  let hidden: HTMLCanvasElement | null = null;
+  let stroking = false;
+  let lastPos: { x: number; y: number } | null = null;
+  const notReadyWarning = { warned: false };
+
+  const paintAt = (x: number, y: number) => {
+    if (!visible || !hidden) {
+      warnOnce(
+        notReadyWarning,
+        "painting before attach()/syncToDisplay() does nothing — call both first (see the headless README example).",
+      );
+      return;
+    }
+    const vctx = visible.getContext("2d");
+    if (vctx) {
+      vctx.fillStyle = overlayStyle;
+      vctx.beginPath();
+      vctx.arc(x, y, size, 0, Math.PI * 2);
+      vctx.fill();
+    }
+    const hctx = hidden.getContext("2d");
+    if (hctx) {
+      hctx.fillStyle = "white";
+      hctx.beginPath();
+      hctx.arc(x, y, size, 0, Math.PI * 2);
+      hctx.fill();
+    }
+  };
+
+  return {
+    attach(canvas) {
+      visible = canvas;
+    },
+    detach() {
+      visible = null;
+      hidden = null;
+      stroking = false;
+      lastPos = null;
+    },
+    syncToDisplay(width, height, devicePixelRatio = 1) {
+      if (!visible || width <= 0 || height <= 0) return;
+      const dpr = Math.min(maxDpr, devicePixelRatio || 1);
+      visible.width = Math.round(width * dpr);
+      visible.height = Math.round(height * dpr);
+      if (visible.style) {
+        visible.style.width = `${width}px`;
+        visible.style.height = `${height}px`;
+      }
+      const vctx = visible.getContext("2d");
+      if (vctx) {
+        vctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        vctx.clearRect(0, 0, width, height);
+      }
+      hidden = createCanvas(Math.round(width), Math.round(height));
+      hidden.width = Math.round(width);
+      hidden.height = Math.round(height);
+      const hctx = hidden.getContext("2d", { willReadFrequently: true });
+      if (hctx) {
+        hctx.fillStyle = "black";
+        hctx.fillRect(0, 0, hidden.width, hidden.height);
+      }
+      stroking = false;
+      lastPos = null;
+    },
+    setBrushSize(px) {
+      size = clampBrushSize(px);
+    },
+    brushSize() {
+      return size;
+    },
+    beginStroke(x, y) {
+      stroking = true;
+      lastPos = { x, y };
+      paintAt(x, y);
+    },
+    strokeTo(x, y) {
+      if (!stroking) return;
+      const last = lastPos;
+      if (last) {
+        // Interpolate between samples so a fast drag doesn't leave gaps;
+        // step density scales with the brush so small brushes stay smooth.
+        const dist = Math.hypot(x - last.x, y - last.y);
+        const steps = Math.max(1, Math.ceil(dist / (size * 0.4)));
+        for (let i = 1; i <= steps; i++) {
+          const t = i / steps;
+          paintAt(last.x + (x - last.x) * t, last.y + (y - last.y) * t);
+        }
+      } else {
+        paintAt(x, y);
+      }
+      lastPos = { x, y };
+    },
+    endStroke() {
+      stroking = false;
+      lastPos = null;
+    },
+    isStroking() {
+      return stroking;
+    },
+    paintAt,
+    clear() {
+      if (visible) {
+        const vctx = visible.getContext("2d");
+        vctx?.clearRect(0, 0, visible.width, visible.height);
+      }
+      if (hidden) {
+        const hctx = hidden.getContext("2d");
+        if (hctx) {
+          hctx.fillStyle = "black";
+          hctx.fillRect(0, 0, hidden.width, hidden.height);
+        }
+      }
+      stroking = false;
+      lastPos = null;
+    },
+    coverage() {
+      if (!hidden) return 0;
+      const ctx = hidden.getContext("2d");
+      if (!ctx) return 0;
+      const data = ctx.getImageData(0, 0, hidden.width, hidden.height).data;
+      let white = 0;
+      let total = 0;
+      for (let yy = 0; yy < hidden.height; yy += sampleStep) {
+        for (let xx = 0; xx < hidden.width; xx += sampleStep) {
+          const i = (yy * hidden.width + xx) * 4;
+          if ((data[i] ?? 0) > 200) white += 1;
+          total += 1;
+        }
+      }
+      return total === 0 ? 0 : (white / total) * 100;
+    },
+    async toMaskBlob(naturalWidth, naturalHeight) {
+      if (!hidden || naturalWidth <= 0 || naturalHeight <= 0) {
+        warnOnce(
+          notReadyWarning,
+          "toMaskBlob() before attach()/syncToDisplay() (or with non-positive dimensions) returns null.",
+        );
+        return null;
+      }
+      const out = createCanvas(naturalWidth, naturalHeight);
+      out.width = naturalWidth;
+      out.height = naturalHeight;
+      const ctx = out.getContext("2d", { willReadFrequently: true });
+      if (!ctx) return null;
+      ctx.fillStyle = "black";
+      ctx.fillRect(0, 0, out.width, out.height);
+      ctx.drawImage(hidden, 0, 0, out.width, out.height);
+      const id = ctx.getImageData(0, 0, out.width, out.height);
+      // Threshold to pure B&W — inpaint models want a binary mask, not
+      // the anti-aliased greys the scale-up introduces.
+      for (let i = 0; i < id.data.length; i += 4) {
+        const v = (id.data[i] ?? 0) > 127 ? 255 : 0;
+        id.data[i] = v;
+        id.data[i + 1] = v;
+        id.data[i + 2] = v;
+        id.data[i + 3] = 255;
+      }
+      ctx.putImageData(id, 0, 0);
+      return new Promise((resolve) => out.toBlob((b) => resolve(b), "image/png"));
+    },
+  };
+}
diff --git a/packages/studio/src/lib/resolution.ts b/packages/studio/src/lib/resolution.ts
index 2c3573c..4dc06aa 100644
--- a/packages/studio/src/lib/resolution.ts
+++ b/packages/studio/src/lib/resolution.ts
@@ -32,11 +32,7 @@ export function isResBucket(v: unknown): v is ResBucket {
 // honors the requested param) just confirmed "2K". When `requested`
 // is missing (uploaded photos, samples, workflows that don't take a
 // resolution input), we fall back to the dimension-derived bucket.
-export function displayBucket(
-  width: number,
-  height: number,
-  requested?: string,
-): ResBucket {
+export function displayBucket(width: number, height: number, requested?: string): ResBucket {
   if (isResBucket(requested)) return requested;
   return resBucket(width, height);
 }
@@ -55,17 +51,22 @@ export function formatRes(width: number, height: number): string {
 // Falls back to the reduced gcd form for anything unusual.
 const COMMON_RATIOS: Array<[number, number]> = [
   [1, 1],
-  [4, 5], [5, 4],
-  [9, 16], [16, 9],
-  [9, 21], [21, 9],
-  [3, 4], [4, 3],
-  [2, 3], [3, 2],
+  [4, 5],
+  [5, 4],
+  [9, 16],
+  [16, 9],
+  [9, 21],
+  [21, 9],
+  [3, 4],
+  [4, 3],
+  [2, 3],
+  [3, 2],
 ];
 export function aspectRatioLabel(width: number, height: number): string {
   if (!width || !height) return "";
   const r = width / height;
   let best: [number, number] | null = null;
-  let bestDiff = Infinity;
+  let bestDiff = Number.POSITIVE_INFINITY;
   for (const [w, h] of COMMON_RATIOS) {
     const diff = Math.abs(r - w / h) / (w / h);
     if (diff < bestDiff) {
diff --git a/packages/studio/src/lib/runflow.ts b/packages/studio/src/lib/runflow.ts
index 149ab08..d7308f8 100644
--- a/packages/studio/src/lib/runflow.ts
+++ b/packages/studio/src/lib/runflow.ts
@@ -7,9 +7,10 @@
 // The future Chat tab can call this same function — pass a workflow id
 // + already-resolved inputs and it'll run the same path.
 
+import { Runflow, composePinPrompt, composeRegionPrompt } from "@runflow-io/sdk";
 import type { Workflow } from "../data/workflows";
 
-import { URLS } from "./urls";
+import { URLS, isUrlCustomized } from "./urls";
 // Endpoint constants flow through the module-level URLS registry;
 // callers configure them in mount() via setStudioUrls(). The original
 // prototype hardcoded /demos/api/* paths here.
@@ -46,12 +47,6 @@ export type DispatchInputs = {
   values: Record<string, string>;
 };
 
-function pinPhrase(p: { x: number; y: number }) {
-  const yLabel = p.y < 0.33 ? "upper" : p.y < 0.66 ? "middle" : "lower";
-  const xLabel = p.x < 0.33 ? "left" : p.x < 0.66 ? "center" : "right";
-  return `${yLabel}-${xLabel}`;
-}
-
 // Fetch a remote image through our same-origin proxy to dodge the
 // no-cors-cache "Failed to fetch" trap on cross-origin sources.
 async function fetchSourceBlob(url: string): Promise<Blob> {
@@ -68,12 +63,27 @@ async function fetchSourceBlob(url: string): Promise<Blob> {
 // a deterministic 4xx (auth, payload-too-large, etc.) feel sluggish.
 const UPLOAD_RETRY_DELAYS_MS = [250, 750];
 
-export async function uploadFile(name: string, body: Blob, fallbackType = "image/png"): Promise<string> {
+export async function uploadFile(
+  name: string,
+  body: Blob,
+  fallbackType = "image/png",
+): Promise<string> {
   // Server only accepts PNG/JPEG/WebP. Rewrap if the blob lost its type
   // (e.g. some fetch responses arrive as application/octet-stream).
-  const type = body.type && body.type.startsWith("image/") ? body.type : fallbackType;
+  const type = body.type?.startsWith("image/") ? body.type : fallbackType;
   const file = new File([body], name, { type });
 
+  // Default path: the SDK's presigned flow through the Runflow proxy —
+  // works zero-config because @runflow-io/proxy allows the asset-upload
+  // routes by default (and the SDK retries transient failures itself).
+  // Hosts that explicitly configured a multipart `upload` endpoint (the
+  // pre-0.1 contract) keep their behavior.
+  if (!isUrlCustomized("upload")) {
+    const rf = new Runflow({ baseUrl: URLS.runflowProxy });
+    const asset = await rf.assets.upload(file, { filename: name });
+    return asset.url;
+  }
+
   const totalAttempts = UPLOAD_RETRY_DELAYS_MS.length + 1;
   let lastTransientReason: string | null = null;
 
@@ -147,11 +157,13 @@ async function buildBody(
     };
   }
   if (wf.kind === "pin") {
-    const region = inputs.pin ? pinPhrase(inputs.pin) : "center";
     const text = inputs.prompt || "";
+    const prompt = inputs.pin
+      ? composePinPrompt(inputs.pin, text)
+      : composeRegionPrompt("center", text);
     return {
       input: {
-        prompt: `Edit the ${region} area of this image: ${text}. Photoreal product photography, preserve the rest of the image, true colors and lighting.`,
+        prompt,
         image_urls: [sourceUrl],
       },
     };
@@ -374,8 +386,7 @@ export async function runWorkflow(
       }
       if (status === "succeeded") {
         const out = r.output || {};
-        const outputUrl =
-          out.outputs?.[0]?.url ?? out.image_urls?.[0] ?? out.image?.url ?? null;
+        const outputUrl = out.outputs?.[0]?.url ?? out.image_urls?.[0] ?? out.image?.url ?? null;
         if (!outputUrl) {
           onProgress({ phase: "error", message: "No image in output" });
           return { status: "failed", outputUrl: null, error: "no output url" };
diff --git a/packages/studio/src/lib/sentinel.ts b/packages/studio/src/lib/sentinel.ts
index 7beaf92..99f19ff 100644
--- a/packages/studio/src/lib/sentinel.ts
+++ b/packages/studio/src/lib/sentinel.ts
@@ -87,7 +87,7 @@ export async function evaluate(
     const dispatchJson = (await dispatch.json()) as { eval_id?: string };
     const evalId = dispatchJson.eval_id;
     if (!evalId) {
-      console.warn(`[sentinel] dispatch ok but no eval_id in response`, dispatchJson);
+      console.warn("[sentinel] dispatch ok but no eval_id in response", dispatchJson);
       return { state: "failed", error: "no eval_id in dispatch response" };
     }
 
@@ -163,7 +163,9 @@ export async function evaluate(
             sd.error || sd.error_message || sd.failure_reason || sd.message || null;
           return {
             state: "failed",
-            error: upstreamReason ? `eval failed: ${upstreamReason}` : "eval failed (no reason given)",
+            error: upstreamReason
+              ? `eval failed: ${upstreamReason}`
+              : "eval failed (no reason given)",
           };
         }
       } catch (e) {
@@ -180,7 +182,7 @@ export async function evaluate(
       error: lastPollFail ? `timed out (last poll: ${lastPollFail})` : "timed out",
     };
   } catch (e) {
-    console.warn(`[sentinel] evaluate threw`, e);
+    console.warn("[sentinel] evaluate threw", e);
     return { state: "failed", error: e instanceof Error ? e.message : "network" };
   }
 }
@@ -223,7 +225,9 @@ export function taskDescription(
     case "generate":
       // Text-to-image — the user's prompt IS the brief. Surfaces what
       // they asked for so the judges can score against it directly.
-      return promptText || values.prompt || "Photoreal product photography, the subject is the hero.";
+      return (
+        promptText || values.prompt || "Photoreal product photography, the subject is the hero."
+      );
     default:
       return "Photoreal product photography, the subject is the hero.";
   }
diff --git a/packages/studio/src/lib/shell-config.tsx b/packages/studio/src/lib/shell-config.tsx
new file mode 100644
index 0000000..288e248
--- /dev/null
+++ b/packages/studio/src/lib/shell-config.tsx
@@ -0,0 +1,141 @@
+/**
+ * StudioShell customization — the props surface that makes "fork the
+ * shell for your vertical" real, and the context that distributes the
+ * resolved configuration to every component in the tree.
+ *
+ * Zero props ⇒ identical behavior to the original shell: the built-in
+ * workflow catalogue, the bundled sample assets, Sentinel on, default
+ * copy. Each prop overrides exactly one axis.
+ */
+
+import { createContext, useContext } from "react";
+import { SAMPLES, type SampleAsset } from "../data/samples";
+import { WORKFLOWS, type Workflow } from "../data/workflows";
+import { taskDescription as defaultTaskDescription } from "./sentinel";
+
+export interface StudioSentinelOptions {
+  /**
+   * Run Sentinel quality evaluation on workflow outputs. Default true.
+   * When false, no evals are dispatched and no quality badges render.
+   */
+  enabled?: boolean;
+  /**
+   * Override how the eval's task description is derived from a run.
+   * Defaults to the built-in per-workflow templates.
+   */
+  taskDescription?: (
+    workflowId: string,
+    values: Record<string, string>,
+    promptText?: string,
+  ) => string;
+}
+
+export interface StudioCopy {
+  /** Header brand name. Default "Runflow". */
+  brandName: string;
+  /** Small tag next to the brand. Default "BETA"; "" hides it. */
+  brandTag: string;
+  /** Header avatar initials. Default "RG"; "" hides the avatar. */
+  avatarInitials: string;
+  /** Left rail title. Default "Assets". */
+  assetsTitle: string;
+  /** Canvas empty-state heading. */
+  emptyTitle: string;
+  /** Canvas empty-state subline. */
+  emptySubtitle: string;
+}
+
+/**
+ * StudioShell customization. Two contracts to know:
+ *
+ * - `source` seeds the canvas at MOUNT — changing it later does not
+ *   reset the user's assets (their edit history would be lost).
+ * - Pass stable references for `tools`, `source` arrays, and
+ *   `sentinel.taskDescription`; inline object literals for `copy` and
+ *   `sentinel` are fine (compared field-wise).
+ */
+export interface StudioShellProps {
+  /**
+   * The workflow catalogue the shell offers — cards, chat-agent tools,
+   * package steps. Defaults to the built-in `WORKFLOWS` (import it from
+   * `@runflow-io/studio/headless` to filter/extend). Takes `Workflow[]`
+   * — the card catalogue — NOT the SDK's `ToolDef`s.
+   */
+  tools?: ReadonlyArray<Workflow>;
+  /**
+   * Initial canvas content, read once at mount. A URL string loads as a
+   * single starting asset; an array of `SampleAsset`s replaces the
+   * bundled samples.
+   */
+  source?: string | ReadonlyArray<SampleAsset>;
+  /** Sentinel (quality evaluation) configuration. */
+  sentinel?: StudioSentinelOptions;
+  /** Copy overrides, shallow-merged over the defaults. */
+  copy?: Partial<StudioCopy>;
+}
+
+export interface ResolvedShellConfig {
+  workflows: ReadonlyArray<Workflow>;
+  samples: ReadonlyArray<SampleAsset>;
+  sentinel: {
+    enabled: boolean;
+    taskDescription: (
+      workflowId: string,
+      values: Record<string, string>,
+      promptText?: string,
+    ) => string;
+  };
+  copy: StudioCopy;
+}
+
+export const DEFAULT_COPY: StudioCopy = {
+  brandName: "Runflow",
+  brandTag: "BETA",
+  avatarInitials: "RG",
+  assetsTitle: "Assets",
+  emptyTitle: "No image selected",
+  emptySubtitle: "Pick a sample from the left, or drop your own to get started.",
+};
+
+export function resolveShellConfig(props: StudioShellProps = {}): ResolvedShellConfig {
+  const samples: ReadonlyArray<SampleAsset> =
+    typeof props.source === "string"
+      ? [{ id: "source", title: "Source", url: props.source, tags: [] }]
+      : (props.source ?? SAMPLES);
+  return {
+    workflows: props.tools ?? WORKFLOWS,
+    samples,
+    sentinel: {
+      enabled: props.sentinel?.enabled ?? true,
+      taskDescription: props.sentinel?.taskDescription ?? defaultTaskDescription,
+    },
+    copy: { ...DEFAULT_COPY, ...(props.copy ?? {}) },
+  };
+}
+
+const ShellConfigContext = createContext<ResolvedShellConfig | null>(null);
+
+export const ShellConfigProvider = ShellConfigContext.Provider;
+
+let fallbackConfig: ResolvedShellConfig | null = null;
+let warnedFallback = false;
+
+/**
+ * Read the shell configuration. Components rendered outside a
+ * StudioShell (storybooks, tests) fall back to the defaults — loudly,
+ * because in an app that passed custom props this means the component
+ * silently ignores them.
+ */
+export function useShellConfig(): ResolvedShellConfig {
+  const fromContext = useContext(ShellConfigContext);
+  if (fromContext) return fromContext;
+  const isTest = typeof process !== "undefined" && process.env?.NODE_ENV === "test";
+  if (!warnedFallback && typeof console !== "undefined" && !isTest) {
+    warnedFallback = true;
+    console.warn(
+      "[@runflow-io/studio] a component rendered outside <StudioShell> is using the built-in defaults — custom tools/source/sentinel/copy props do not reach it.",
+    );
+  }
+  if (!fallbackConfig) fallbackConfig = resolveShellConfig({});
+  return fallbackConfig;
+}
diff --git a/packages/studio/src/lib/studio-settings.ts b/packages/studio/src/lib/studio-settings.ts
index 37270dc..1827fd3 100644
--- a/packages/studio/src/lib/studio-settings.ts
+++ b/packages/studio/src/lib/studio-settings.ts
@@ -63,10 +63,7 @@ export function getStudioSettings(): StudioSettings {
 type Listener = (s: StudioSettings) => void;
 const listeners = new Set<Listener>();
 
-export function setStudioSetting<K extends keyof StudioSettings>(
-  key: K,
-  value: StudioSettings[K],
-) {
+export function setStudioSetting<K extends keyof StudioSettings>(key: K, value: StudioSettings[K]) {
   cached = { ...cached, [key]: value };
   write(cached);
   for (const l of listeners) l(cached);
diff --git a/packages/studio/src/lib/urls.ts b/packages/studio/src/lib/urls.ts
index 2ecd74c..c0aafeb 100644
--- a/packages/studio/src/lib/urls.ts
+++ b/packages/studio/src/lib/urls.ts
@@ -28,9 +28,24 @@ export const URLS = {
 
 export type StudioUrls = typeof URLS;
 
+const DEFAULT_URLS: StudioUrls = { ...URLS };
+const customized = new Set<keyof StudioUrls>();
+
 export function setStudioUrls(overrides: Partial<StudioUrls>): void {
   for (const key of Object.keys(overrides) as Array<keyof StudioUrls>) {
     const v = overrides[key];
-    if (typeof v === "string") URLS[key] = v;
+    if (typeof v === "string") {
+      URLS[key] = v;
+      // Passing the default value back (e.g. a full urls object copied
+      // from the docs) is not a customization — only a real override
+      // should switch behavior (like uploads off the presigned path).
+      if (v === DEFAULT_URLS[key]) customized.delete(key);
+      else customized.add(key);
+    }
   }
 }
+
+/** Whether the host overrode an endpoint to a non-default value. */
+export function isUrlCustomized(key: keyof StudioUrls): boolean {
+  return customized.has(key);
+}
diff --git a/packages/studio/src/lib/version-summary.ts b/packages/studio/src/lib/version-summary.ts
index 5aa75fb..de2967a 100644
--- a/packages/studio/src/lib/version-summary.ts
+++ b/packages/studio/src/lib/version-summary.ts
@@ -36,7 +36,7 @@ export function summarizeRequest(req: VersionRequest): SummaryRow[] {
   const v = req.values || {};
 
   // Free-form text — quoted so it visually pops as the user's words.
-  if (req.prompt && req.prompt.trim()) {
+  if (req.prompt?.trim()) {
     rows.push({
       key: "prompt",
       label: PROMPT_LABELS[req.workflowId] ?? "Prompt",
diff --git a/packages/studio/src/styles.css b/packages/studio/src/styles.css
index 9a7ead6..e00a0b6 100644
--- a/packages/studio/src/styles.css
+++ b/packages/studio/src/styles.css
@@ -17,22 +17,22 @@
 */
 
 .rfs-root {
-  --rfs-bg-0: #0A0A0B;
-  --rfs-bg-1: #18181B;
-  --rfs-bg-2: #27272A;
-  --rfs-bg-3: #3F3F46;
-  --rfs-ink-0: #FAFAFA;
-  --rfs-ink-1: #D4D4D8;
-  --rfs-ink-2: #A1A1AA;
-  --rfs-ink-3: #71717A;
-  --rfs-accent: #FBBF24;
-  --rfs-accent-dim: #F59E0B;
-  --rfs-accent-soft: rgba(251,191,36,0.12);
-  --rfs-success: #22C55E;
-  --rfs-danger:  #F87171;
-  --rfs-radius:  12px;
+  --rfs-bg-0: #0a0a0b;
+  --rfs-bg-1: #18181b;
+  --rfs-bg-2: #27272a;
+  --rfs-bg-3: #3f3f46;
+  --rfs-ink-0: #fafafa;
+  --rfs-ink-1: #d4d4d8;
+  --rfs-ink-2: #a1a1aa;
+  --rfs-ink-3: #71717a;
+  --rfs-accent: #fbbf24;
+  --rfs-accent-dim: #f59e0b;
+  --rfs-accent-soft: rgba(251, 191, 36, 0.12);
+  --rfs-success: #22c55e;
+  --rfs-danger: #f87171;
+  --rfs-radius: 12px;
   --rfs-radius-lg: 16px;
-  --rfs-shadow: 0 1px 3px rgba(0,0,0,0.3), 0 8px 24px rgba(0,0,0,0.2);
+  --rfs-shadow: 0 1px 3px rgba(0, 0, 0, 0.3), 0 8px 24px rgba(0, 0, 0, 0.2);
 
   --rfs-left-w: 268px;
   font-family: Outfit, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
@@ -58,7 +58,9 @@
 /* ============ Header ============ */
 .rfs-header {
   grid-area: header;
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   padding: 0 1rem;
   border-bottom: 1px solid var(--rfs-bg-2);
   background: var(--rfs-bg-0);
@@ -66,31 +68,41 @@
   z-index: 5;
 }
 .rfs-brand {
-  display: inline-flex; align-items: center; gap: 0.5rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
   padding: 0.25rem 0.375rem;
 }
 .rfs-brand-mark {
-  width: 36px; height: 12px;
+  width: 36px;
+  height: 12px;
   border-radius: 6px;
-  background: linear-gradient(90deg, #09090B, var(--rfs-accent));
-  box-shadow: inset 0 0 0 1px rgba(255,255,255,0.06);
+  background: linear-gradient(90deg, #09090b, var(--rfs-accent));
+  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.06);
 }
 .rfs-brand-name {
-  font-weight: 800; font-size: 1rem; letter-spacing: -0.03em;
+  font-weight: 800;
+  font-size: 1rem;
+  letter-spacing: -0.03em;
+}
+.rfs-brand-name span {
+  color: var(--rfs-accent);
 }
-.rfs-brand-name span { color: var(--rfs-accent); }
 .rfs-brand-tag {
   margin-left: 0.5rem;
   padding: 2px 6px;
   background: var(--rfs-bg-2);
   color: var(--rfs-ink-2);
-  font-size: 0.6875rem; font-weight: 600;
+  font-size: 0.6875rem;
+  font-weight: 600;
   border-radius: 4px;
   letter-spacing: 0.04em;
 }
 
 .rfs-project {
-  display: flex; align-items: center; gap: 0.5rem;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
   font-size: 0.8125rem;
   color: var(--rfs-ink-2);
 }
@@ -113,7 +125,10 @@
   background: var(--rfs-bg-2);
   border-color: var(--rfs-bg-3);
 }
-.rfs-project-name:disabled { cursor: default; opacity: 0.6; }
+.rfs-project-name:disabled {
+  cursor: default;
+  opacity: 0.6;
+}
 .rfs-project-name-input {
   color: var(--rfs-ink-0);
   background: var(--rfs-bg-1);
@@ -127,10 +142,17 @@
   width: 240px;
 }
 
-.rfs-header-right { display: flex; align-items: center; gap: 0.375rem; }
+.rfs-header-right {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+}
 .rfs-iconbtn {
-  width: 32px; height: 32px;
-  display: inline-flex; align-items: center; justify-content: center;
+  width: 32px;
+  height: 32px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   border-radius: 8px;
   background: transparent;
   border: 1px solid transparent;
@@ -138,35 +160,63 @@
   cursor: pointer;
   transition: background 120ms, color 120ms, border-color 120ms;
 }
-.rfs-iconbtn:hover { background: var(--rfs-bg-2); color: var(--rfs-ink-0); }
-.rfs-iconbtn:disabled { opacity: 0.35; cursor: not-allowed; }
+.rfs-iconbtn:hover {
+  background: var(--rfs-bg-2);
+  color: var(--rfs-ink-0);
+}
+.rfs-iconbtn:disabled {
+  opacity: 0.35;
+  cursor: not-allowed;
+}
 .rfs-btn {
-  display: inline-flex; align-items: center; gap: 0.375rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
   padding: 0.375rem 0.75rem;
   border: 1px solid var(--rfs-bg-3);
   border-radius: 8px;
   background: var(--rfs-bg-1);
   color: var(--rfs-ink-0);
-  font-family: inherit; font-size: 0.8125rem; font-weight: 600;
+  font-family: inherit;
+  font-size: 0.8125rem;
+  font-weight: 600;
   cursor: pointer;
   transition: background 120ms, border-color 120ms;
 }
-.rfs-btn:hover { background: var(--rfs-bg-2); border-color: var(--rfs-bg-3); }
+.rfs-btn:hover {
+  background: var(--rfs-bg-2);
+  border-color: var(--rfs-bg-3);
+}
 .rfs-btn-primary {
   background: var(--rfs-accent);
   border-color: var(--rfs-accent);
-  color: #09090B;
+  color: #09090b;
+}
+.rfs-btn-primary:hover {
+  background: var(--rfs-accent-dim);
+  border-color: var(--rfs-accent-dim);
+}
+.rfs-btn-primary:disabled {
+  background: var(--rfs-bg-3);
+  color: var(--rfs-ink-3);
+  border-color: var(--rfs-bg-3);
+  cursor: not-allowed;
+}
+.rfs-btn:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
 }
-.rfs-btn-primary:hover { background: var(--rfs-accent-dim); border-color: var(--rfs-accent-dim); }
-.rfs-btn-primary:disabled { background: var(--rfs-bg-3); color: var(--rfs-ink-3); border-color: var(--rfs-bg-3); cursor: not-allowed; }
-.rfs-btn:disabled { opacity: 0.4; cursor: not-allowed; }
 .rfs-avatar {
-  width: 28px; height: 28px;
+  width: 28px;
+  height: 28px;
   border-radius: 999px;
-  background: linear-gradient(135deg, #FCD34D, #F59E0B);
-  display: inline-flex; align-items: center; justify-content: center;
-  font-weight: 700; font-size: 0.75rem;
-  color: #09090B;
+  background: linear-gradient(135deg, #fcd34d, #f59e0b);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-weight: 700;
+  font-size: 0.75rem;
+  color: #09090b;
   margin-left: 0.25rem;
 }
 
@@ -175,7 +225,8 @@
   grid-area: left;
   border-right: 1px solid var(--rfs-bg-2);
   background: var(--rfs-bg-0);
-  display: flex; flex-direction: column;
+  display: flex;
+  flex-direction: column;
   min-height: 0;
   overflow: hidden;
 }
@@ -185,7 +236,9 @@
 .rfs-left-header {
   flex-shrink: 0;
   padding: 0.875rem 0.875rem 0.5rem;
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
 }
 .rfs-left-title {
   font-size: 0.6875rem;
@@ -204,13 +257,18 @@
 .rfs-left-upload-btn {
   width: 100%;
   box-sizing: border-box;
-  display: inline-flex; align-items: center; justify-content: center; gap: 0.375rem;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.375rem;
   padding: 0.5rem 0.625rem;
   background: var(--rfs-bg-1);
   border: 1px dashed var(--rfs-bg-3);
   border-radius: 10px;
   color: var(--rfs-ink-1);
-  font-family: inherit; font-size: 0.8125rem; font-weight: 600;
+  font-family: inherit;
+  font-size: 0.8125rem;
+  font-weight: 600;
   cursor: pointer;
   transition: border-color 120ms, color 120ms, background 120ms;
 }
@@ -219,7 +277,9 @@
   color: var(--rfs-accent);
   background: var(--rfs-accent-soft);
 }
-.rfs-left-upload-btn input[type="file"] { display: none; }
+.rfs-left-upload-btn input[type="file"] {
+  display: none;
+}
 
 /* Two-button "+ New asset" row — Upload + Generate. Lays out as a
    flex row so each button takes 50% of the rail. Generate inherits
@@ -229,19 +289,26 @@
 .rfs-left-newasset {
   flex-shrink: 0;
   padding: 0 calc(0.875rem + 6px) 0.75rem 0.875rem;
-  display: flex; gap: 0.4375rem;
+  display: flex;
+  gap: 0.4375rem;
   box-sizing: border-box;
 }
 .rfs-left-newasset-btn {
-  flex: 1; min-width: 0;
+  flex: 1;
+  min-width: 0;
   box-sizing: border-box;
-  display: inline-flex; align-items: center; justify-content: center; gap: 0.375rem;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.375rem;
   padding: 0.5rem 0.5rem;
   background: var(--rfs-bg-1);
   border: 1px dashed var(--rfs-bg-3);
   border-radius: 10px;
   color: var(--rfs-ink-1);
-  font-family: inherit; font-size: 0.8125rem; font-weight: 600;
+  font-family: inherit;
+  font-size: 0.8125rem;
+  font-weight: 600;
   cursor: pointer;
   transition: border-color 120ms, color 120ms, background 120ms;
 }
@@ -250,7 +317,9 @@
   color: var(--rfs-accent);
   background: var(--rfs-accent-soft);
 }
-.rfs-left-newasset-btn input[type="file"] { display: none; }
+.rfs-left-newasset-btn input[type="file"] {
+  display: none;
+}
 .rfs-left-newasset-generate {
   /* Slight accent on idle so the sparkle reads as the "creative"
      option vs. Upload's neutral file-bring-your-own affordance.
@@ -267,35 +336,48 @@
 .rfs-generate-panel {
   flex: 1;
   min-height: 0;
-  display: flex; flex-direction: column;
+  display: flex;
+  flex-direction: column;
   background: var(--rfs-bg-0);
 }
 .rfs-generate-panel-header {
   flex-shrink: 0;
-  display: flex; flex-direction: column; gap: 0.4375rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.4375rem;
   padding: 0.75rem 0.875rem;
   border-bottom: 1px solid var(--rfs-bg-2);
 }
 .rfs-generate-back {
-  display: inline-flex; align-items: center; gap: 0.25rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
   font-size: 0.75rem;
   font-weight: 500;
   align-self: flex-start;
 }
 .rfs-generate-panel-title {
-  display: inline-flex; align-items: center; gap: 0.5rem;
-  font-size: 0.9375rem; font-weight: 700;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.9375rem;
+  font-weight: 700;
   color: var(--rfs-ink-0);
 }
-.rfs-generate-panel-title svg { color: var(--rfs-accent); }
+.rfs-generate-panel-title svg {
+  color: var(--rfs-accent);
+}
 .rfs-generate-panel-body {
   flex-shrink: 0;
-  display: flex; flex-direction: column; gap: 0.75rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
   padding: 0.875rem;
   border-bottom: 1px solid var(--rfs-bg-2);
 }
 .rfs-generate-res-row {
-  display: flex; gap: 0.375rem;
+  display: flex;
+  gap: 0.375rem;
 }
 .rfs-generate-res-btn {
   flex: 1;
@@ -304,11 +386,16 @@
   border: 1px solid var(--rfs-bg-2);
   border-radius: 8px;
   color: var(--rfs-ink-2);
-  font-family: inherit; font-size: 0.75rem; font-weight: 700;
+  font-family: inherit;
+  font-size: 0.75rem;
+  font-weight: 700;
   cursor: pointer;
   transition: background 120ms, color 120ms, border-color 120ms;
 }
-.rfs-generate-res-btn:hover { color: var(--rfs-ink-0); border-color: var(--rfs-bg-3); }
+.rfs-generate-res-btn:hover {
+  color: var(--rfs-ink-0);
+  border-color: var(--rfs-bg-3);
+}
 .rfs-generate-res-btn.is-selected {
   background: var(--rfs-accent-soft);
   color: var(--rfs-accent);
@@ -325,7 +412,10 @@
 }
 .rfs-generate-go {
   width: 100%;
-  display: inline-flex; align-items: center; justify-content: center; gap: 0.4375rem;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.4375rem;
 }
 
 /* In-flight summary — shown above the form while at least one
@@ -334,13 +424,17 @@
    way to launch a brand-new batch without leaving the panel. */
 .rfs-generate-inflight {
   flex-shrink: 0;
-  display: flex; flex-direction: column; gap: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
   padding: 0.75rem 0.875rem;
-  background: rgba(251,191,36,0.06);
+  background: rgba(251, 191, 36, 0.06);
   border-bottom: 1px solid var(--rfs-bg-2);
 }
 .rfs-generate-inflight-status {
-  display: inline-flex; align-items: center; gap: 0.4375rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4375rem;
   font-size: 0.8125rem;
   font-weight: 500;
   color: var(--rfs-ink-0);
@@ -368,7 +462,9 @@
 }
 .rfs-generate-newrun {
   align-self: flex-start;
-  display: inline-flex; align-items: center; gap: 0.375rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
   margin-top: 0.25rem;
   font-size: 0.75rem;
 }
@@ -380,26 +476,37 @@
   min-height: 0;
   overflow-y: auto;
   padding: 0.875rem;
-  display: flex; flex-direction: column; gap: 0.625rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.625rem;
 }
 .rfs-generate-results-label {
-  font-size: 0.625rem; font-weight: 700;
-  letter-spacing: 0.1em; text-transform: uppercase;
+  font-size: 0.625rem;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
   color: var(--rfs-ink-3);
-  display: flex; gap: 0.4375rem;
+  display: flex;
+  gap: 0.4375rem;
 }
 .rfs-generate-tiles {
-  display: grid; grid-template-columns: 1fr 1fr; gap: 0.625rem;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 0.625rem;
 }
 .rfs-generate-tile {
-  display: flex; flex-direction: column; gap: 0.4375rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.4375rem;
   padding: 0.4375rem;
   background: var(--rfs-bg-1);
   border: 1px solid var(--rfs-bg-2);
   border-radius: 10px;
   transition: border-color 140ms;
 }
-.rfs-generate-tile:hover { border-color: var(--rfs-bg-3); }
+.rfs-generate-tile:hover {
+  border-color: var(--rfs-bg-3);
+}
 .rfs-generate-tile-img {
   position: relative;
   aspect-ratio: 1 / 1;
@@ -408,26 +515,36 @@
   background: var(--rfs-bg-0);
 }
 .rfs-generate-tile-img img {
-  width: 100%; height: 100%;
+  width: 100%;
+  height: 100%;
   object-fit: cover;
   display: block;
 }
 .rfs-generate-tile-pending,
 .rfs-generate-tile-failed {
-  position: absolute; inset: 0;
-  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
   gap: 0.5rem;
   padding: 0.625rem;
   text-align: center;
 }
 .rfs-generate-tile-spinner {
-  width: 24px; height: 24px;
+  width: 24px;
+  height: 24px;
   border: 2px solid var(--rfs-bg-3);
   border-top-color: var(--rfs-accent);
   border-radius: 999px;
   animation: rfs-spin 1s linear infinite;
 }
-@keyframes rfs-spin { to { transform: rotate(360deg); } }
+@keyframes rfs-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
 .rfs-generate-tile-phrase {
   font-size: 0.6875rem;
   color: var(--rfs-ink-2);
@@ -446,12 +563,16 @@
 }
 .rfs-generate-tile-sentinel {
   position: absolute;
-  top: 0.4375rem; right: 0.4375rem;
+  top: 0.4375rem;
+  right: 0.4375rem;
 }
 .rfs-generate-tile-sentinel-pending {
-  width: 18px; height: 18px;
-  display: inline-flex; align-items: center; justify-content: center;
-  background: rgba(0,0,0,0.55);
+  width: 18px;
+  height: 18px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.55);
   color: var(--rfs-ink-1);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 999px;
@@ -465,19 +586,24 @@
   border-radius: 6px;
 }
 .rfs-generate-tile-hint-red {
-  background: rgba(248,113,113,0.12);
+  background: rgba(248, 113, 113, 0.12);
   color: var(--rfs-danger);
 }
 .rfs-generate-tile-hint-failed {
-  background: rgba(161,161,170,0.12);
+  background: rgba(161, 161, 170, 0.12);
   color: var(--rfs-ink-2);
 }
 .rfs-generate-tile-actions {
-  display: flex; align-items: center; gap: 0.25rem;
+  display: flex;
+  align-items: center;
+  gap: 0.25rem;
 }
 .rfs-generate-tile-keep {
   flex: 1;
-  display: inline-flex; align-items: center; justify-content: center; gap: 0.25rem;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.25rem;
   padding: 0.4375rem 0.5rem;
   font-size: 0.75rem;
 }
@@ -497,12 +623,19 @@
   scrollbar-width: thin;
   scrollbar-color: var(--rfs-bg-3) transparent;
 }
-.rfs-asset-list::-webkit-scrollbar { width: 6px; }
-.rfs-asset-list::-webkit-scrollbar-track { background: transparent; }
+.rfs-asset-list::-webkit-scrollbar {
+  width: 6px;
+}
+.rfs-asset-list::-webkit-scrollbar-track {
+  background: transparent;
+}
 .rfs-asset-list::-webkit-scrollbar-thumb {
-  background: var(--rfs-bg-3); border-radius: 999px;
+  background: var(--rfs-bg-3);
+  border-radius: 999px;
+}
+.rfs-asset-list::-webkit-scrollbar-thumb:hover {
+  background: var(--rfs-ink-3);
 }
-.rfs-asset-list::-webkit-scrollbar-thumb:hover { background: var(--rfs-ink-3); }
 
 /* Asset cards — square, image fills the entire card edge-to-edge.
    The 1rem grid gap between cards is doing the visual-separation
@@ -545,11 +678,12 @@
    thumbnail. */
 .rfs-asset-count {
   position: absolute;
-  bottom: 6px; right: 6px;
+  bottom: 6px;
+  right: 6px;
   min-width: 22px;
   padding: 2px 7px;
   border-radius: 999px;
-  background: rgba(9,9,11,0.88);
+  background: rgba(9, 9, 11, 0.88);
   backdrop-filter: blur(6px);
   color: var(--rfs-ink-0);
   border: 1px solid var(--rfs-bg-3);
@@ -557,7 +691,7 @@
   font-weight: 700;
   text-align: center;
   line-height: 1;
-  box-shadow: 0 2px 6px rgba(0,0,0,0.3);
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
 }
 
 /* Re-open the rail when collapsed — small floating button */
@@ -572,7 +706,8 @@
 /* ============ Center canvas ============ */
 .rfs-center {
   grid-area: center;
-  display: flex; flex-direction: column;
+  display: flex;
+  flex-direction: column;
   min-height: 0;
   background: var(--rfs-bg-0);
 }
@@ -581,7 +716,8 @@
   min-height: 0;
   position: relative;
   display: flex;
-  align-items: center; justify-content: center;
+  align-items: center;
+  justify-content: center;
   padding: 1.5rem;
   overflow: hidden;
 }
@@ -590,12 +726,15 @@
   color: var(--rfs-ink-2);
 }
 .rfs-canvas-empty h2 {
-  font-size: 1.25rem; font-weight: 700; letter-spacing: -0.02em;
+  font-size: 1.25rem;
+  font-weight: 700;
+  letter-spacing: -0.02em;
   color: var(--rfs-ink-0);
   margin: 0 0 0.5rem;
 }
 .rfs-canvas-empty p {
-  margin: 0; font-size: 0.875rem;
+  margin: 0;
+  font-size: 0.875rem;
   max-width: 360px;
 }
 .rfs-image-frame {
@@ -617,8 +756,12 @@
   user-select: none;
   -webkit-user-drag: none;
 }
-.rfs-canvas.is-pinning .rfs-image-frame img { cursor: crosshair; }
-.rfs-canvas.is-painting .rfs-image-frame img { cursor: cell; }
+.rfs-canvas.is-pinning .rfs-image-frame img {
+  cursor: crosshair;
+}
+.rfs-canvas.is-painting .rfs-image-frame img {
+  cursor: cell;
+}
 
 /* Persistent Compare button — graduated out of the hover tools row so
    the side-by-side scrub is discoverable without the user knowing to
@@ -635,7 +778,7 @@
   gap: 0.375rem;
   height: 32px;
   padding: 0 0.625rem;
-  background: rgba(24,24,27,0.78);
+  background: rgba(24, 24, 27, 0.78);
   backdrop-filter: blur(8px);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 8px;
@@ -650,7 +793,7 @@
 }
 .rfs-canvas-compare-btn:hover:not(:disabled) {
   color: var(--rfs-ink-0);
-  background: rgba(39,39,42,0.92);
+  background: rgba(39, 39, 42, 0.92);
   border-color: var(--rfs-accent);
 }
 .rfs-canvas-compare-btn:disabled {
@@ -667,9 +810,11 @@
    used to live here; it's now a persistent floating button. */
 .rfs-canvas-tools {
   position: absolute;
-  right: 0.625rem; bottom: 0.625rem;
-  display: flex; gap: 0.25rem;
-  background: rgba(24,24,27,0.78);
+  right: 0.625rem;
+  bottom: 0.625rem;
+  display: flex;
+  gap: 0.25rem;
+  background: rgba(24, 24, 27, 0.78);
   backdrop-filter: blur(8px);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 10px;
@@ -683,8 +828,16 @@
 .rfs-canvas-tools:focus-within {
   opacity: 1;
 }
-.rfs-canvas-tools .rfs-iconbtn { color: var(--rfs-ink-1); width: 30px; height: 30px; border-radius: 8px; }
-.rfs-canvas-tools .rfs-iconbtn:hover { background: var(--rfs-bg-2); color: var(--rfs-ink-0); }
+.rfs-canvas-tools .rfs-iconbtn {
+  color: var(--rfs-ink-1);
+  width: 30px;
+  height: 30px;
+  border-radius: 8px;
+}
+.rfs-canvas-tools .rfs-iconbtn:hover {
+  background: var(--rfs-bg-2);
+  color: var(--rfs-ink-0);
+}
 
 /* Info pills inside the canvas-tools group — resolution bucket
    (1K/2K/4K, colour-coded) and aspect ratio. Hover the resolution pill
@@ -692,7 +845,9 @@
    compare/download icon buttons so the canvas stays calm when nobody's
    hovering — info reveals together with the actions. */
 .rfs-canvas-tools-pill {
-  display: inline-flex; align-items: center; justify-content: center;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   height: 30px;
   padding: 0 0.5rem;
   font-size: 0.6875rem;
@@ -702,18 +857,32 @@
   color: var(--rfs-ink-1);
   user-select: none;
 }
-.rfs-canvas-tools-pill[title] { cursor: help; }
-.rfs-canvas-tools-pill-muted { color: var(--rfs-ink-2); font-weight: 600; }
-.rfs-canvas-res-1k { color: #94A3B8; }
-.rfs-canvas-res-2k { color: #38BDF8; }
-.rfs-canvas-res-4k { color: var(--rfs-accent); }
+.rfs-canvas-tools-pill[title] {
+  cursor: help;
+}
+.rfs-canvas-tools-pill-muted {
+  color: var(--rfs-ink-2);
+  font-weight: 600;
+}
+.rfs-canvas-res-1k {
+  color: #94a3b8;
+}
+.rfs-canvas-res-2k {
+  color: #38bdf8;
+}
+.rfs-canvas-res-4k {
+  color: var(--rfs-accent);
+}
 
 .rfs-stage-hint {
   position: absolute;
-  left: 50%; bottom: 1.75rem;
+  left: 50%;
+  bottom: 1.75rem;
   transform: translateX(-50%);
-  display: inline-flex; align-items: center; gap: 0.5rem;
-  background: rgba(24,24,27,0.92);
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  background: rgba(24, 24, 27, 0.92);
   backdrop-filter: blur(8px);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 999px;
@@ -724,30 +893,44 @@
   box-shadow: var(--rfs-shadow);
   z-index: 3;
 }
-.rfs-stage-hint b { color: var(--rfs-accent); font-weight: 600; }
+.rfs-stage-hint b {
+  color: var(--rfs-accent);
+  font-weight: 600;
+}
 .rfs-stage-hint-dot {
-  width: 8px; height: 8px;
+  width: 8px;
+  height: 8px;
   border-radius: 999px;
   background: var(--rfs-accent);
   animation: rfs-pulse-dot 1400ms ease-in-out infinite;
 }
 @keyframes rfs-pulse-dot {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0.4; }
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.4;
+  }
 }
 
 .rfs-canvas-overlay {
-  position: absolute; inset: 1.5rem;
-  background: rgba(10,10,11,0.82);
+  position: absolute;
+  inset: 1.5rem;
+  background: rgba(10, 10, 11, 0.82);
   backdrop-filter: blur(12px);
   border-radius: var(--rfs-radius-lg);
-  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
   gap: 0.625rem;
   color: var(--rfs-ink-0);
   z-index: 4;
 }
 .rfs-spinner {
-  width: 36px; height: 36px;
+  width: 36px;
+  height: 36px;
   border-radius: 999px;
   border: 3px solid var(--rfs-bg-3);
   border-top-color: var(--rfs-accent);
@@ -762,14 +945,15 @@
    has a coherent "studio overlay" look. */
 .rfs-canvas-pending {
   position: absolute;
-  left: 50%; bottom: 1rem;
+  left: 50%;
+  bottom: 1rem;
   transform: translateX(-50%);
   display: inline-flex;
   align-items: center;
   gap: 0.5rem;
   height: 32px;
   padding: 0 0.75rem;
-  background: rgba(24,24,27,0.85);
+  background: rgba(24, 24, 27, 0.85);
   backdrop-filter: blur(8px);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 8px;
@@ -788,23 +972,36 @@
      mid-word — wrap to two lines instead. */
   max-width: calc(100% - 2.5rem);
 }
-.rfs-canvas-pending:hover { border-color: var(--rfs-accent); }
-.rfs-canvas-pending strong { color: var(--rfs-ink-0); font-weight: 700; }
+.rfs-canvas-pending:hover {
+  border-color: var(--rfs-accent);
+}
+.rfs-canvas-pending strong {
+  color: var(--rfs-ink-0);
+  font-weight: 700;
+}
 .rfs-canvas-pending-spinner {
-  width: 12px; height: 12px;
+  width: 12px;
+  height: 12px;
   flex-shrink: 0;
   border-radius: 999px;
-  border: 2px solid rgba(255,255,255,0.18);
+  border: 2px solid rgba(255, 255, 255, 0.18);
   border-top-color: var(--rfs-accent);
   animation: rfs-spin 800ms linear infinite;
 }
-@keyframes rfs-spin { to { transform: rotate(360deg); } }
+@keyframes rfs-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
 
 /* Animated trailing dots after the rotating microcopy phrase. Three
    dots that pulse one after another, like Claude Code's status line.
    Conveys "still working" without a static spinner being the only
    life sign. */
-.rfs-canvas-pending-phrase { display: inline-flex; align-items: baseline; }
+.rfs-canvas-pending-phrase {
+  display: inline-flex;
+  align-items: baseline;
+}
 .rfs-canvas-pending-dots {
   display: inline-flex;
   gap: 2px;
@@ -812,19 +1009,38 @@
   align-items: center;
 }
 .rfs-canvas-pending-dots span {
-  width: 3px; height: 3px;
+  width: 3px;
+  height: 3px;
   border-radius: 999px;
   background: var(--rfs-ink-2);
   animation: rfs-pending-dot 1.2s infinite ease-in-out;
 }
-.rfs-canvas-pending-dots span:nth-child(2) { animation-delay: 0.18s; }
-.rfs-canvas-pending-dots span:nth-child(3) { animation-delay: 0.36s; }
+.rfs-canvas-pending-dots span:nth-child(2) {
+  animation-delay: 0.18s;
+}
+.rfs-canvas-pending-dots span:nth-child(3) {
+  animation-delay: 0.36s;
+}
 @keyframes rfs-pending-dot {
-  0%, 60%, 100% { opacity: 0.25; transform: translateY(0); }
-  30% { opacity: 1; transform: translateY(-1px); }
+  0%,
+  60%,
+  100% {
+    opacity: 0.25;
+    transform: translateY(0);
+  }
+  30% {
+    opacity: 1;
+    transform: translateY(-1px);
+  }
+}
+.rfs-canvas-overlay strong {
+  font-size: 1rem;
+  letter-spacing: -0.01em;
+}
+.rfs-canvas-overlay-sub {
+  color: var(--rfs-ink-2);
+  font-size: 0.8125rem;
 }
-.rfs-canvas-overlay strong { font-size: 1rem; letter-spacing: -0.01em; }
-.rfs-canvas-overlay-sub { color: var(--rfs-ink-2); font-size: 0.8125rem; }
 
 /* Generation skeleton — shown when the active version is a pending
    text-to-image generation (no source image yet). A shimmering
@@ -842,31 +1058,37 @@
   border: 1px solid var(--rfs-bg-2);
 }
 .rfs-canvas-generation-skeleton {
-  position: absolute; inset: 0;
+  position: absolute;
+  inset: 0;
   background: linear-gradient(
     100deg,
-    rgba(39,39,42,0.6) 30%,
-    rgba(63,63,70,0.85) 50%,
-    rgba(39,39,42,0.6) 70%
+    rgba(39, 39, 42, 0.6) 30%,
+    rgba(63, 63, 70, 0.85) 50%,
+    rgba(39, 39, 42, 0.6) 70%
   );
   background-size: 200% 100%;
   animation: rfs-shimmer 2.4s ease-in-out infinite;
 }
 .rfs-canvas-generation-shimmer {
-  position: absolute; inset: 0;
-  background: radial-gradient(
-    600px 240px at center,
-    rgba(251,191,36,0.06),
-    transparent 70%
-  );
+  position: absolute;
+  inset: 0;
+  background: radial-gradient(600px 240px at center, rgba(251, 191, 36, 0.06), transparent 70%);
 }
 @keyframes rfs-shimmer {
-  0%   { background-position: 100% 0; }
-  100% { background-position: -100% 0; }
+  0% {
+    background-position: 100% 0;
+  }
+  100% {
+    background-position: -100% 0;
+  }
 }
 .rfs-canvas-generation-overlay {
-  position: absolute; inset: 0;
-  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
   gap: 1.25rem;
   padding: 2rem;
   text-align: center;
@@ -881,13 +1103,23 @@
      not a hardcoded label. */
   font-style: italic;
 }
-.rfs-canvas-generation-prompt::before { content: "“"; opacity: 0.5; margin-right: 2px; }
-.rfs-canvas-generation-prompt::after  { content: "”"; opacity: 0.5; margin-left: 2px; }
+.rfs-canvas-generation-prompt::before {
+  content: "“";
+  opacity: 0.5;
+  margin-right: 2px;
+}
+.rfs-canvas-generation-prompt::after {
+  content: "”";
+  opacity: 0.5;
+  margin-left: 2px;
+}
 .rfs-canvas-generation-status {
-  display: inline-flex; align-items: center; gap: 0.5rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
   height: 32px;
   padding: 0 0.75rem;
-  background: rgba(24,24,27,0.85);
+  background: rgba(24, 24, 27, 0.85);
   backdrop-filter: blur(8px);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 8px;
@@ -901,13 +1133,15 @@
 .rfs-canvas-generation-failed {
   background: var(--rfs-bg-1);
 }
-.rfs-canvas-generation-failed .rfs-canvas-generation-skeleton { display: none; }
+.rfs-canvas-generation-failed .rfs-canvas-generation-skeleton {
+  display: none;
+}
 .rfs-canvas-generation-failed-pill {
   display: inline-block;
   max-width: 480px;
   padding: 0.5rem 0.875rem;
-  background: rgba(248,113,113,0.12);
-  border: 1px solid rgba(248,113,113,0.32);
+  background: rgba(248, 113, 113, 0.12);
+  border: 1px solid rgba(248, 113, 113, 0.32);
   border-radius: 8px;
   color: var(--rfs-danger);
   font-size: 0.75rem;
@@ -922,12 +1156,13 @@
 .rfs-asset-skeleton,
 .rfs-version-thumb-skeleton {
   display: block;
-  width: 100%; height: 100%;
+  width: 100%;
+  height: 100%;
   background: linear-gradient(
     100deg,
-    rgba(39,39,42,0.6) 30%,
-    rgba(63,63,70,0.85) 50%,
-    rgba(39,39,42,0.6) 70%
+    rgba(39, 39, 42, 0.6) 30%,
+    rgba(63, 63, 70, 0.85) 50%,
+    rgba(39, 39, 42, 0.6) 70%
   );
   background-size: 200% 100%;
   animation: rfs-shimmer 2.4s ease-in-out infinite;
@@ -935,13 +1170,14 @@
 
 .rfs-canvas-error {
   position: absolute;
-  left: 50%; top: 1.75rem;
+  left: 50%;
+  top: 1.75rem;
   transform: translateX(-50%);
-  background: #7F1D1D;
-  border: 1px solid #B91C1C;
+  background: #7f1d1d;
+  border: 1px solid #b91c1c;
   border-radius: 10px;
   padding: 0.5rem 0.875rem;
-  color: #FECACA;
+  color: #fecaca;
   font-size: 0.8125rem;
   font-weight: 500;
   max-width: 80%;
@@ -957,8 +1193,10 @@
 */
 .rfs-sentinel-dot {
   position: absolute;
-  bottom: 5px; right: 5px;
-  width: 11px; height: 11px;
+  bottom: 5px;
+  right: 5px;
+  width: 11px;
+  height: 11px;
   border-radius: 999px;
   border: 2px solid var(--rfs-bg-0);
   box-sizing: content-box;
@@ -976,13 +1214,28 @@
   animation: rfs-sentinel-pulse 1600ms ease-in-out infinite;
 }
 @keyframes rfs-sentinel-pulse {
-  0%, 100% { opacity: 1; transform: scale(1); }
-  50%      { opacity: 0.55; transform: scale(0.82); }
+  0%,
+  100% {
+    opacity: 1;
+    transform: scale(1);
+  }
+  50% {
+    opacity: 0.55;
+    transform: scale(0.82);
+  }
+}
+.rfs-sentinel-dot.is-green {
+  background: var(--rfs-success);
+}
+.rfs-sentinel-dot.is-amber {
+  background: #f59e0b;
+}
+.rfs-sentinel-dot.is-red {
+  background: var(--rfs-danger);
+}
+.rfs-sentinel-dot.is-failed {
+  background: var(--rfs-bg-3);
 }
-.rfs-sentinel-dot.is-green  { background: var(--rfs-success); }
-.rfs-sentinel-dot.is-amber  { background: #F59E0B; }
-.rfs-sentinel-dot.is-red    { background: var(--rfs-danger); }
-.rfs-sentinel-dot.is-failed { background: var(--rfs-bg-3); }
 
 /* Question-mark glyph for the `failed` (eval errored) state — visually
    distinct from the solid red dot of `red` (judges actually failed) so
@@ -1007,32 +1260,53 @@
    is the first thing the user sees on a generated frame. */
 .rfs-sentinel-badge {
   position: absolute;
-  left: 0.625rem; bottom: 0.625rem;
-  display: inline-flex; align-items: center; gap: 0.5rem;
+  left: 0.625rem;
+  bottom: 0.625rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
   padding: 0.4375rem 0.75rem 0.4375rem 0.625rem;
-  background: rgba(24,24,27,0.92);
+  background: rgba(24, 24, 27, 0.92);
   backdrop-filter: blur(8px);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 999px;
   color: var(--rfs-ink-0);
-  font-family: inherit; font-size: 0.75rem; font-weight: 600;
+  font-family: inherit;
+  font-size: 0.75rem;
+  font-weight: 600;
   cursor: pointer;
   z-index: 4;
-  box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+}
+.rfs-sentinel-badge:hover {
+  border-color: var(--rfs-accent);
 }
-.rfs-sentinel-badge:hover { border-color: var(--rfs-accent); }
 .rfs-sentinel-badge .rfs-sentinel-dot {
   position: static;
-  width: 8px; height: 8px;
+  width: 8px;
+  height: 8px;
   border: none;
   flex-shrink: 0;
 }
-.rfs-sentinel-badge.is-green  { color: var(--rfs-success); }
-.rfs-sentinel-badge.is-amber  { color: #F59E0B; }
-.rfs-sentinel-badge.is-red    { color: var(--rfs-danger); }
-.rfs-sentinel-badge.is-pending { color: var(--rfs-accent); }
-.rfs-sentinel-badge.is-failed { color: var(--rfs-ink-3); }
-.rfs-sentinel-badge.is-skipped { color: var(--rfs-ink-3); cursor: help; }
+.rfs-sentinel-badge.is-green {
+  color: var(--rfs-success);
+}
+.rfs-sentinel-badge.is-amber {
+  color: #f59e0b;
+}
+.rfs-sentinel-badge.is-red {
+  color: var(--rfs-danger);
+}
+.rfs-sentinel-badge.is-pending {
+  color: var(--rfs-accent);
+}
+.rfs-sentinel-badge.is-failed {
+  color: var(--rfs-ink-3);
+}
+.rfs-sentinel-badge.is-skipped {
+  color: var(--rfs-ink-3);
+  cursor: help;
+}
 /* Elapsed-time chip on the pending badge — neutral monospace so it
    reads as a clock without competing with the colored state label. */
 .rfs-sentinel-badge-elapsed {
@@ -1047,37 +1321,64 @@
    cards. Same dot palette as the badge but flatter and tooltip-only.
    .sm sits inside a card row; .xs is small enough to overlay a thumb. */
 .rfs-sentinel-chip {
-  display: inline-flex; align-items: center; gap: 0.3125rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.3125rem;
   padding: 0.1875rem 0.4375rem;
-  background: rgba(24,24,27,0.92);
+  background: rgba(24, 24, 27, 0.92);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 999px;
-  font-family: inherit; font-weight: 600;
+  font-family: inherit;
+  font-weight: 600;
   cursor: help;
   white-space: nowrap;
   line-height: 1;
 }
-.rfs-sentinel-chip-sm { font-size: 0.6875rem; }
+.rfs-sentinel-chip-sm {
+  font-size: 0.6875rem;
+}
 .rfs-sentinel-chip .rfs-sentinel-dot {
   position: static;
-  width: 7px; height: 7px;
+  width: 7px;
+  height: 7px;
   border: none;
   flex-shrink: 0;
 }
-.rfs-sentinel-chip.is-green   { color: var(--rfs-success); border-color: rgba(34,197,94,0.4); }
-.rfs-sentinel-chip.is-amber   { color: #F59E0B; border-color: rgba(245,158,11,0.4); }
-.rfs-sentinel-chip.is-red     { color: var(--rfs-danger); border-color: rgba(248,113,113,0.4); }
-.rfs-sentinel-chip.is-pending { color: var(--rfs-accent); border-color: var(--rfs-bg-3); }
-.rfs-sentinel-chip.is-failed  { color: var(--rfs-ink-3); border-color: var(--rfs-bg-3); }
-.rfs-sentinel-chip.is-skipped { color: var(--rfs-ink-3); border-color: var(--rfs-bg-3); }
+.rfs-sentinel-chip.is-green {
+  color: var(--rfs-success);
+  border-color: rgba(34, 197, 94, 0.4);
+}
+.rfs-sentinel-chip.is-amber {
+  color: #f59e0b;
+  border-color: rgba(245, 158, 11, 0.4);
+}
+.rfs-sentinel-chip.is-red {
+  color: var(--rfs-danger);
+  border-color: rgba(248, 113, 113, 0.4);
+}
+.rfs-sentinel-chip.is-pending {
+  color: var(--rfs-accent);
+  border-color: var(--rfs-bg-3);
+}
+.rfs-sentinel-chip.is-failed {
+  color: var(--rfs-ink-3);
+  border-color: var(--rfs-bg-3);
+}
+.rfs-sentinel-chip.is-skipped {
+  color: var(--rfs-ink-3);
+  border-color: var(--rfs-bg-3);
+}
 
 /* xs variant — dot-only, used on version stripe thumbs where text
    would overflow the 56px tile. Hover the dot to read the full
    sentinel state (state label · judges passed · score · top issue). */
 .rfs-sentinel-chip-xs {
-  display: inline-flex; align-items: center; justify-content: center;
-  width: 14px; height: 14px;
-  background: rgba(24,24,27,0.92);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  background: rgba(24, 24, 27, 0.92);
   border: 1.5px solid var(--rfs-bg-3);
   border-radius: 999px;
   cursor: help;
@@ -1085,25 +1386,39 @@
 }
 .rfs-sentinel-chip-xs .rfs-sentinel-dot {
   position: static;
-  width: 7px; height: 7px;
+  width: 7px;
+  height: 7px;
   border: none;
 }
-.rfs-sentinel-chip-xs.is-green   { border-color: var(--rfs-success); }
-.rfs-sentinel-chip-xs.is-amber   { border-color: #F59E0B; }
-.rfs-sentinel-chip-xs.is-red     { border-color: var(--rfs-danger); }
+.rfs-sentinel-chip-xs.is-green {
+  border-color: var(--rfs-success);
+}
+.rfs-sentinel-chip-xs.is-amber {
+  border-color: #f59e0b;
+}
+.rfs-sentinel-chip-xs.is-red {
+  border-color: var(--rfs-danger);
+}
 .rfs-sentinel-chip-xs.is-pending {
   border-color: var(--rfs-accent);
   animation: rfs-sentinel-chip-pulse 1600ms ease-in-out infinite;
 }
 .rfs-sentinel-chip-xs.is-failed,
-.rfs-sentinel-chip-xs.is-skipped { border-color: var(--rfs-bg-3); }
+.rfs-sentinel-chip-xs.is-skipped {
+  border-color: var(--rfs-bg-3);
+}
 /* Same pulse for the sm chip used in compact contexts. */
 .rfs-sentinel-chip.is-pending {
   animation: rfs-sentinel-chip-pulse 1600ms ease-in-out infinite;
 }
 @keyframes rfs-sentinel-chip-pulse {
-  0%, 100% { box-shadow: 0 0 0 0 rgba(96, 165, 250, 0.0); }
-  50%      { box-shadow: 0 0 0 3px rgba(96, 165, 250, 0.18); }
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 rgba(96, 165, 250, 0.0);
+  }
+  50% {
+    box-shadow: 0 0 0 3px rgba(96, 165, 250, 0.18);
+  }
 }
 
 /* Position the chip in the top-left of a version thumb (top-right is
@@ -1111,7 +1426,8 @@
    the title tooltip works without stealing the click from the thumb. */
 .rfs-version-thumb-sentinel {
   position: absolute;
-  top: 6px; left: 6px;
+  top: 6px;
+  left: 6px;
   z-index: 2;
 }
 
@@ -1119,31 +1435,39 @@
    right. The whole head is still a click target — chip relies on the
    native title tooltip so it doesn't need its own click handler. */
 .rfs-history-card-name-row {
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   gap: 0.5rem;
   width: 100%;
 }
 
 .rfs-sentinel-panel {
   position: absolute;
-  left: 0.625rem; bottom: 3.25rem;
+  left: 0.625rem;
+  bottom: 3.25rem;
   width: 280px;
   background: var(--rfs-bg-1);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 12px;
-  box-shadow: 0 8px 28px rgba(0,0,0,0.4);
+  box-shadow: 0 8px 28px rgba(0, 0, 0, 0.4);
   z-index: 5;
   overflow: hidden;
 }
 .rfs-sentinel-panel-header {
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   padding: 0.75rem 0.875rem;
   border-bottom: 1px solid var(--rfs-bg-2);
 }
 .rfs-sentinel-panel-title {
-  font-size: 0.8125rem; font-weight: 700;
+  font-size: 0.8125rem;
+  font-weight: 700;
   letter-spacing: -0.01em;
-  display: flex; align-items: center; gap: 0.5rem;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
 }
 .rfs-sentinel-panel-score {
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
@@ -1152,7 +1476,9 @@
 }
 .rfs-sentinel-judges {
   padding: 0.5rem;
-  display: flex; flex-direction: column; gap: 0.25rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
   max-height: 320px;
   overflow-y: auto;
 }
@@ -1164,11 +1490,18 @@
   font-size: 0.8125rem;
   color: var(--rfs-ink-1);
 }
-.rfs-sentinel-judge.is-pass { background: transparent; }
-.rfs-sentinel-judge.is-fail { background: rgba(248,113,113,0.07); color: var(--rfs-ink-0); }
+.rfs-sentinel-judge.is-pass {
+  background: transparent;
+}
+.rfs-sentinel-judge.is-fail {
+  background: rgba(248, 113, 113, 0.07);
+  color: var(--rfs-ink-0);
+}
 .rfs-sentinel-judge-header {
   width: 100%;
-  display: flex; align-items: center; gap: 0.5rem;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
   padding: 0.5rem 0.625rem;
   background: transparent;
   border: none;
@@ -1178,20 +1511,32 @@
   text-align: left;
   cursor: pointer;
 }
-.rfs-sentinel-judge-header:disabled { cursor: default; }
+.rfs-sentinel-judge-header:disabled {
+  cursor: default;
+}
 .rfs-sentinel-judge-header:hover:not(:disabled) {
-  background: rgba(255,255,255,0.03);
+  background: rgba(255, 255, 255, 0.03);
   border-radius: 8px;
 }
 .rfs-sentinel-judge-mark {
-  width: 16px; height: 16px;
+  width: 16px;
+  height: 16px;
   border-radius: 999px;
-  display: inline-flex; align-items: center; justify-content: center;
-  font-size: 0.625rem; font-weight: 800;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.625rem;
+  font-weight: 800;
   flex-shrink: 0;
 }
-.rfs-sentinel-judge.is-pass .rfs-sentinel-judge-mark { background: rgba(34,197,94,0.18); color: var(--rfs-success); }
-.rfs-sentinel-judge.is-fail .rfs-sentinel-judge-mark { background: rgba(248,113,113,0.18); color: var(--rfs-danger); }
+.rfs-sentinel-judge.is-pass .rfs-sentinel-judge-mark {
+  background: rgba(34, 197, 94, 0.18);
+  color: var(--rfs-success);
+}
+.rfs-sentinel-judge.is-fail .rfs-sentinel-judge-mark {
+  background: rgba(248, 113, 113, 0.18);
+  color: var(--rfs-danger);
+}
 .rfs-sentinel-judge-name {
   flex: 1;
   min-width: 0;
@@ -1214,12 +1559,20 @@
   font-size: 0.6875rem;
   transition: transform 120ms;
 }
-.rfs-sentinel-judge-chev.is-open { transform: rotate(180deg); }
+.rfs-sentinel-judge-chev.is-open {
+  transform: rotate(180deg);
+}
 .rfs-sentinel-judge-body {
   padding: 0 0.625rem 0.625rem 2.125rem;
-  display: flex; flex-direction: column; gap: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.rfs-sentinel-judge-section {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
 }
-.rfs-sentinel-judge-section { display: flex; flex-direction: column; gap: 0.25rem; }
 .rfs-sentinel-judge-section-label {
   font-size: 0.6875rem;
   font-weight: 700;
@@ -1231,7 +1584,9 @@
   list-style: none;
   margin: 0;
   padding: 0;
-  display: flex; flex-direction: column; gap: 4px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
 }
 .rfs-sentinel-judge-issues li {
   font-size: 0.75rem;
@@ -1265,13 +1620,15 @@
 .rfs-sentinel-hardgate {
   margin: 0 0.5rem;
   padding: 0.5rem 0.625rem;
-  background: rgba(248,113,113,0.12);
-  border: 1px solid rgba(248,113,113,0.35);
+  background: rgba(248, 113, 113, 0.12);
+  border: 1px solid rgba(248, 113, 113, 0.35);
   border-radius: 8px;
   font-size: 0.75rem;
   color: var(--rfs-danger);
 }
-.rfs-sentinel-hardgate strong { color: #FCA5A5; }
+.rfs-sentinel-hardgate strong {
+  color: #fca5a5;
+}
 
 /* Curated top_issues / top_strengths summaries — collapsible. */
 .rfs-sentinel-summary {
@@ -1280,8 +1637,11 @@
 }
 .rfs-sentinel-summary-header {
   width: 100%;
-  display: flex; align-items: center; gap: 0.5rem;
-  background: transparent; border: none;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  background: transparent;
+  border: none;
   padding: 0.375rem 0.5rem;
   font-family: inherit;
   font-size: 0.75rem;
@@ -1289,22 +1649,38 @@
   cursor: pointer;
   border-radius: 6px;
 }
-.rfs-sentinel-summary-header:hover { background: rgba(255,255,255,0.03); }
+.rfs-sentinel-summary-header:hover {
+  background: rgba(255, 255, 255, 0.03);
+}
 .rfs-sentinel-summary-icon {
-  width: 16px; height: 16px;
+  width: 16px;
+  height: 16px;
   border-radius: 999px;
-  display: inline-flex; align-items: center; justify-content: center;
-  font-size: 0.6875rem; font-weight: 800;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.6875rem;
+  font-weight: 800;
   flex-shrink: 0;
 }
-.rfs-sentinel-summary-issue .rfs-sentinel-summary-icon { background: rgba(248,113,113,0.18); color: var(--rfs-danger); }
-.rfs-sentinel-summary-strength .rfs-sentinel-summary-icon { background: rgba(34,197,94,0.18); color: var(--rfs-success); }
-.rfs-sentinel-summary-title { flex: 1; }
+.rfs-sentinel-summary-issue .rfs-sentinel-summary-icon {
+  background: rgba(248, 113, 113, 0.18);
+  color: var(--rfs-danger);
+}
+.rfs-sentinel-summary-strength .rfs-sentinel-summary-icon {
+  background: rgba(34, 197, 94, 0.18);
+  color: var(--rfs-success);
+}
+.rfs-sentinel-summary-title {
+  flex: 1;
+}
 .rfs-sentinel-summary-list {
   list-style: none;
   margin: 0;
   padding: 0.25rem 0.5rem 0.5rem;
-  display: flex; flex-direction: column; gap: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
   max-height: 220px;
   overflow-y: auto;
 }
@@ -1352,45 +1728,60 @@
 /* Pin marker */
 .rfs-pin {
   position: absolute;
-  width: 0; height: 0;
+  width: 0;
+  height: 0;
   pointer-events: none;
   z-index: 5;
 }
 .rfs-pin-dot {
   position: absolute;
-  left: -7px; top: -7px;
-  width: 14px; height: 14px;
+  left: -7px;
+  top: -7px;
+  width: 14px;
+  height: 14px;
   border-radius: 999px;
   background: var(--rfs-accent);
-  border: 2px solid #0A0A0B;
-  box-shadow: 0 2px 12px rgba(251,191,36,0.55);
+  border: 2px solid #0a0a0b;
+  box-shadow: 0 2px 12px rgba(251, 191, 36, 0.55);
 }
 .rfs-pin-pulse {
   position: absolute;
-  left: -16px; top: -16px;
-  width: 32px; height: 32px;
+  left: -16px;
+  top: -16px;
+  width: 32px;
+  height: 32px;
   border-radius: 999px;
   border: 2px solid var(--rfs-accent);
   opacity: 0.6;
   animation: rfs-pulse 1500ms ease-out infinite;
 }
 @keyframes rfs-pulse {
-  0%   { transform: scale(0.6); opacity: 0.6; }
-  100% { transform: scale(1.3); opacity: 0; }
+  0% {
+    transform: scale(0.6);
+    opacity: 0.6;
+  }
+  100% {
+    transform: scale(1.3);
+    opacity: 0;
+  }
 }
 
 /* Brush mask canvas */
 .rfs-mask-canvas {
-  position: absolute; inset: 0;
+  position: absolute;
+  inset: 0;
   pointer-events: auto;
   cursor: cell;
   touch-action: none;
 }
 .rfs-brush-toolbar {
   position: absolute;
-  left: 1.75rem; top: 1.75rem;
-  display: inline-flex; align-items: center; gap: 0.625rem;
-  background: rgba(24,24,27,0.92);
+  left: 1.75rem;
+  top: 1.75rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.625rem;
+  background: rgba(24, 24, 27, 0.92);
   backdrop-filter: blur(8px);
   border: 1px solid var(--rfs-bg-3);
   border-radius: 10px;
@@ -1398,25 +1789,41 @@
   z-index: 3;
 }
 .rfs-brush-label {
-  font-size: 0.6875rem; font-weight: 700;
-  letter-spacing: 0.08em; text-transform: uppercase;
+  font-size: 0.6875rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
   color: var(--rfs-ink-3);
 }
-.rfs-brush-range { width: 100px; accent-color: var(--rfs-accent); }
+.rfs-brush-range {
+  width: 100px;
+  accent-color: var(--rfs-accent);
+}
 .rfs-brush-size {
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
   font-size: 0.75rem;
   color: var(--rfs-ink-2);
-  min-width: 36px; text-align: right;
+  min-width: 36px;
+  text-align: right;
 }
 .rfs-brush-clear {
-  background: none; border: none;
+  background: none;
+  border: none;
   color: var(--rfs-accent);
-  font-family: inherit; font-size: 0.75rem; font-weight: 600;
-  cursor: pointer; padding: 0.125rem 0.375rem; border-radius: 6px;
+  font-family: inherit;
+  font-size: 0.75rem;
+  font-weight: 600;
+  cursor: pointer;
+  padding: 0.125rem 0.375rem;
+  border-radius: 6px;
+}
+.rfs-brush-clear:hover:not(:disabled) {
+  background: var(--rfs-accent-soft);
+}
+.rfs-brush-clear:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
 }
-.rfs-brush-clear:hover:not(:disabled) { background: var(--rfs-accent-soft); }
-.rfs-brush-clear:disabled { opacity: 0.4; cursor: not-allowed; }
 .rfs-brush-divider {
   width: 1px;
   height: 18px;
@@ -1426,33 +1833,45 @@
 .rfs-brush-confirm {
   background: var(--rfs-accent);
   border: none;
-  color: #09090B;
-  font-family: inherit; font-size: 0.75rem; font-weight: 700;
+  color: #09090b;
+  font-family: inherit;
+  font-size: 0.75rem;
+  font-weight: 700;
   padding: 0.3125rem 0.625rem;
   border-radius: 6px;
   cursor: pointer;
 }
-.rfs-brush-confirm:hover:not(:disabled) { background: var(--rfs-accent-dim); }
-.rfs-brush-confirm:disabled { opacity: 0.4; cursor: not-allowed; }
+.rfs-brush-confirm:hover:not(:disabled) {
+  background: var(--rfs-accent-dim);
+}
+.rfs-brush-confirm:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
 
 /* Version stripe under canvas */
 .rfs-version-stripe {
   flex-shrink: 0;
-  display: flex; align-items: center; gap: 0.5rem;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
   padding: 0.625rem 1.25rem;
   border-top: 1px solid var(--rfs-bg-2);
   background: var(--rfs-bg-0);
   overflow-x: auto;
 }
 .rfs-version-stripe-label {
-  font-size: 0.6875rem; font-weight: 700;
-  letter-spacing: 0.08em; text-transform: uppercase;
+  font-size: 0.6875rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
   color: var(--rfs-ink-3);
   flex-shrink: 0;
 }
 .rfs-version-thumb {
   flex-shrink: 0;
-  width: 56px; height: 56px;
+  width: 56px;
+  height: 56px;
   border-radius: 8px;
   overflow: hidden;
   background: var(--rfs-bg-1);
@@ -1466,12 +1885,17 @@
   transition: border-color 160ms;
 }
 .rfs-version-thumb img {
-  width: 100%; height: 100%; object-fit: cover; display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
 }
 /* In-flight workflow — image at low opacity, ring pulses, spinner
    centred on the thumb. Visually distinct from a sentinel-pending
    thumb (which uses the same pulsing border but has the real image). */
-.rfs-version-thumb.is-pending img { opacity: 0.4; }
+.rfs-version-thumb.is-pending img {
+  opacity: 0.4;
+}
 .rfs-version-thumb.is-pending {
   border-color: var(--rfs-accent);
   animation: rfs-border-pulse 1500ms ease-in-out infinite;
@@ -1488,8 +1912,9 @@
   pointer-events: none;
 }
 .rfs-version-thumb-spinner-ring {
-  width: 18px; height: 18px;
-  border: 2px solid rgba(255,255,255,0.25);
+  width: 18px;
+  height: 18px;
+  border: 2px solid rgba(255, 255, 255, 0.25);
   border-top-color: var(--rfs-accent);
   border-radius: 999px;
   animation: rfs-spin 800ms linear infinite;
@@ -1499,23 +1924,36 @@
   border-color: var(--rfs-accent);
   animation: rfs-border-pulse 1500ms ease-in-out infinite;
 }
-.rfs-version-thumb.sentinel-green  { border-color: var(--rfs-success); }
-.rfs-version-thumb.sentinel-amber  { border-color: #F59E0B; }
-.rfs-version-thumb.sentinel-red    { border-color: var(--rfs-danger); }
-.rfs-version-thumb.sentinel-failed { border-color: var(--rfs-bg-3); }
+.rfs-version-thumb.sentinel-green {
+  border-color: var(--rfs-success);
+}
+.rfs-version-thumb.sentinel-amber {
+  border-color: #f59e0b;
+}
+.rfs-version-thumb.sentinel-red {
+  border-color: var(--rfs-danger);
+}
+.rfs-version-thumb.sentinel-failed {
+  border-color: var(--rfs-bg-3);
+}
 /* Selection ring sits OUTSIDE the border so a sentinel-colored frame
    can coexist with the selected affordance. */
 .rfs-version-thumb.is-current {
   box-shadow: 0 0 0 2px var(--rfs-accent);
 }
 @keyframes rfs-border-pulse {
-  0%, 100% { border-color: var(--rfs-accent); }
-  50%      { border-color: rgba(251,191,36,0.4); }
+  0%,
+  100% {
+    border-color: var(--rfs-accent);
+  }
+  50% {
+    border-color: rgba(251, 191, 36, 0.4);
+  }
 }
 .rfs-version-thumb-label {
   position: absolute;
   inset: auto 0 0 0;
-  background: linear-gradient(180deg, transparent 0%, rgba(9,9,11,0.85) 100%);
+  background: linear-gradient(180deg, transparent 0%, rgba(9, 9, 11, 0.85) 100%);
   color: var(--rfs-ink-0);
   font-size: 0.625rem;
   font-weight: 600;
@@ -1531,28 +1969,39 @@
    matches a 4K canvas badge. */
 .rfs-version-thumb-res {
   position: absolute;
-  top: 3px; right: 3px;
-  display: inline-flex; align-items: center; justify-content: center;
-  min-width: 18px; height: 14px;
+  top: 3px;
+  right: 3px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 14px;
   padding: 0 4px;
   border-radius: 999px;
   font-size: 0.5625rem;
   font-weight: 700;
   letter-spacing: 0.04em;
-  background: rgba(24,24,27,0.9);
+  background: rgba(24, 24, 27, 0.9);
   color: var(--rfs-ink-0);
   pointer-events: none;
 }
-.rfs-version-thumb-res-1k { color: #94A3B8; }
-.rfs-version-thumb-res-2k { color: #38BDF8; }
-.rfs-version-thumb-res-4k { color: var(--rfs-accent); }
+.rfs-version-thumb-res-1k {
+  color: #94a3b8;
+}
+.rfs-version-thumb-res-2k {
+  color: #38bdf8;
+}
+.rfs-version-thumb-res-4k {
+  color: var(--rfs-accent);
+}
 
 /* ============ Right rail (workflows / chat / history) ============ */
 .rfs-right {
   grid-area: right;
   border-left: 1px solid var(--rfs-bg-2);
   background: var(--rfs-bg-0);
-  display: flex; flex-direction: column;
+  display: flex;
+  flex-direction: column;
   min-height: 0;
 }
 .rfs-tabs {
@@ -1562,39 +2011,60 @@
 }
 .rfs-tab {
   flex: 1;
-  display: inline-flex; align-items: center; justify-content: center; gap: 0.375rem;
-  background: transparent; border: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.375rem;
+  background: transparent;
+  border: none;
   padding: 0.875rem 0.5rem;
-  font-family: inherit; font-size: 0.8125rem; font-weight: 600;
+  font-family: inherit;
+  font-size: 0.8125rem;
+  font-weight: 600;
   color: var(--rfs-ink-3);
   cursor: pointer;
   border-bottom: 2px solid transparent;
   margin-bottom: -1px;
   transition: color 120ms, border-color 120ms;
 }
-.rfs-tab:hover:not(:disabled) { color: var(--rfs-ink-0); }
-.rfs-tab.is-active { color: var(--rfs-ink-0); border-bottom-color: var(--rfs-accent); }
-.rfs-tab:disabled { color: var(--rfs-ink-3); cursor: not-allowed; }
+.rfs-tab:hover:not(:disabled) {
+  color: var(--rfs-ink-0);
+}
+.rfs-tab.is-active {
+  color: var(--rfs-ink-0);
+  border-bottom-color: var(--rfs-accent);
+}
+.rfs-tab:disabled {
+  color: var(--rfs-ink-3);
+  cursor: not-allowed;
+}
 .rfs-tab-soon {
   display: inline-block;
   background: var(--rfs-bg-2);
   color: var(--rfs-ink-2);
-  font-size: 0.5625rem; font-weight: 700;
+  font-size: 0.5625rem;
+  font-weight: 700;
   padding: 1px 5px;
   border-radius: 3px;
   letter-spacing: 0.04em;
   margin-left: 4px;
 }
 .rfs-tab-count {
-  display: inline-flex; align-items: center; justify-content: center;
-  min-width: 18px; height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 18px;
+  height: 16px;
   padding: 0 5px;
   background: var(--rfs-bg-2);
   border-radius: 999px;
   font-size: 0.625rem;
   color: var(--rfs-ink-2);
 }
-.rfs-tab.is-active .rfs-tab-count { background: var(--rfs-accent-soft); color: var(--rfs-accent); }
+.rfs-tab.is-active .rfs-tab-count {
+  background: var(--rfs-accent-soft);
+  color: var(--rfs-accent);
+}
 
 .rfs-search {
   flex-shrink: 0;
@@ -1611,14 +2081,17 @@
   border: 1px solid var(--rfs-bg-2);
   border-radius: 8px;
   color: var(--rfs-ink-0);
-  font-family: inherit; font-size: 0.8125rem;
+  font-family: inherit;
+  font-size: 0.8125rem;
 }
 .rfs-search input:focus {
   outline: none;
   border-color: var(--rfs-accent);
   background: var(--rfs-bg-0);
 }
-.rfs-search input::placeholder { color: var(--rfs-ink-3); }
+.rfs-search input::placeholder {
+  color: var(--rfs-ink-3);
+}
 
 /* Breadcrumb shown in the focused configure view — replaces the
    search bar + card grid so the user can attend to one workflow at
@@ -1627,14 +2100,19 @@
    to browse. */
 .rfs-breadcrumb {
   flex-shrink: 0;
-  display: flex; align-items: center; gap: 0.5rem;
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
   padding: 0.625rem 0.875rem;
   border-bottom: 1px solid var(--rfs-bg-2);
   background: var(--rfs-bg-0);
 }
 .rfs-breadcrumb-back {
-  display: inline-flex; align-items: center; justify-content: center;
-  width: 28px; height: 28px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
   background: transparent;
   border: 1px solid var(--rfs-bg-2);
   border-radius: 8px;
@@ -1649,23 +2127,33 @@
   background: var(--rfs-bg-1);
 }
 .rfs-breadcrumb-trail {
-  display: inline-flex; align-items: baseline; gap: 0.375rem;
+  display: inline-flex;
+  align-items: baseline;
+  gap: 0.375rem;
   font-size: 0.75rem;
   color: var(--rfs-ink-2);
   min-width: 0;
 }
 .rfs-breadcrumb-link {
-  background: none; border: none; padding: 0;
+  background: none;
+  border: none;
+  padding: 0;
   font: inherit;
   color: var(--rfs-ink-2);
   cursor: pointer;
 }
-.rfs-breadcrumb-link:hover { color: var(--rfs-ink-0); }
-.rfs-breadcrumb-sep { color: var(--rfs-ink-3); }
+.rfs-breadcrumb-link:hover {
+  color: var(--rfs-ink-0);
+}
+.rfs-breadcrumb-sep {
+  color: var(--rfs-ink-3);
+}
 .rfs-breadcrumb-current {
   color: var(--rfs-ink-0);
   font-weight: 600;
-  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
   min-width: 0;
 }
 
@@ -1674,18 +2162,26 @@
   min-height: 0;
   overflow-y: auto;
   padding: 0 0.875rem 0.5rem;
-  display: flex; flex-direction: column; gap: 1rem;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
 }
 .rfs-cards-group-label {
-  font-size: 0.625rem; font-weight: 700;
-  letter-spacing: 0.1em; text-transform: uppercase;
+  font-size: 0.625rem;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
   color: var(--rfs-ink-3);
   padding: 0 0.125rem;
   margin-top: 0.25rem;
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
 }
 .rfs-cards-group {
-  display: flex; flex-direction: column; gap: 0.375rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
 }
 
 /* Quiet footer rows below the live workflow groups — house the
@@ -1694,11 +2190,15 @@
    scrollable rfs-cards container so they only show when scrolled
    into view, keeping the first impression tight. */
 .rfs-cards-footer {
-  display: flex; flex-direction: column; gap: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
   margin-top: 0.25rem;
 }
 .rfs-cards-disclosure {
-  display: inline-flex; align-items: center; gap: 0.375rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
   align-self: flex-start;
   padding: 0.375rem 0.5rem;
   background: transparent;
@@ -1738,7 +2238,9 @@
 }
 
 .rfs-card {
-  display: flex; align-items: center; gap: 0.625rem;
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
   padding: 0.625rem;
   background: var(--rfs-bg-1);
   border: 1px solid transparent;
@@ -1749,7 +2251,9 @@
   position: relative;
   transition: background 120ms, border-color 120ms;
 }
-.rfs-card:hover:not(:disabled) { background: var(--rfs-bg-2); }
+.rfs-card:hover:not(:disabled) {
+  background: var(--rfs-bg-2);
+}
 /* Selected state is purely a transitional cue now — the cards grid
    collapses into the focused configure view as soon as a card is
    picked, so the chrome only flashes for one frame. Border-only,
@@ -1764,9 +2268,12 @@
    asset has no recommendation for this card. */
 .rfs-card.is-recommended .rfs-card-icon {
   background: var(--rfs-accent);
-  color: #09090B;
+  color: #09090b;
+}
+.rfs-card:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
 }
-.rfs-card:disabled { cursor: not-allowed; opacity: 0.5; }
 /* Wrapper around a disabled card — carries the tooltip that a
    disabled <button> can't surface natively. `display: contents` so
    the wrapper doesn't add a layout box; the card sits in the
@@ -1800,18 +2307,27 @@
   flex-shrink: 0;
 }
 .rfs-card-icon {
-  width: 32px; height: 32px;
+  width: 32px;
+  height: 32px;
   border-radius: 8px;
   background: var(--rfs-bg-2);
-  display: flex; align-items: center; justify-content: center;
+  display: flex;
+  align-items: center;
+  justify-content: center;
   color: var(--rfs-ink-1);
   flex-shrink: 0;
 }
-.rfs-card-text { flex: 1; min-width: 0; }
+.rfs-card-text {
+  flex: 1;
+  min-width: 0;
+}
 .rfs-card-name {
-  font-weight: 600; font-size: 0.8125rem;
+  font-weight: 600;
+  font-size: 0.8125rem;
   color: var(--rfs-ink-0);
-  display: flex; align-items: center; gap: 0.375rem;
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
 }
 .rfs-card-desc {
   font-size: 0.6875rem;
@@ -1823,7 +2339,8 @@
   display: inline-block;
   background: var(--rfs-bg-2);
   color: var(--rfs-ink-2);
-  font-size: 0.5625rem; font-weight: 700;
+  font-size: 0.5625rem;
+  font-weight: 700;
   padding: 1px 5px;
   border-radius: 3px;
   letter-spacing: 0.04em;
@@ -1834,11 +2351,15 @@
    and a small delete affordance on the right. */
 .rfs-card-custom {
   padding: 0;
-  display: flex; align-items: stretch; gap: 0;
+  display: flex;
+  align-items: stretch;
+  gap: 0;
 }
 .rfs-card-custom-body {
   flex: 1;
-  display: flex; align-items: center; gap: 0.625rem;
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
   padding: 0.625rem;
   background: transparent;
   border: none;
@@ -1868,14 +2389,28 @@
   cursor: pointer;
   opacity: 0;
   transition: opacity 140ms, color 140ms, background 140ms;
-  display: inline-flex; align-items: center; justify-content: center;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+.rfs-card-custom-edit {
+  font-size: 0.875rem;
+}
+.rfs-card-custom-delete {
+  font-size: 1.25rem;
+  font-weight: 400;
 }
-.rfs-card-custom-edit { font-size: 0.875rem; }
-.rfs-card-custom-delete { font-size: 1.25rem; font-weight: 400; }
 .rfs-card-custom:hover .rfs-card-custom-edit,
-.rfs-card-custom:hover .rfs-card-custom-delete { opacity: 1; }
-.rfs-card-custom-edit:hover { color: var(--rfs-ink-0); background: var(--rfs-bg-2); }
-.rfs-card-custom-delete:hover { color: var(--rfs-danger); }
+.rfs-card-custom:hover .rfs-card-custom-delete {
+  opacity: 1;
+}
+.rfs-card-custom-edit:hover {
+  color: var(--rfs-ink-0);
+  background: var(--rfs-bg-2);
+}
+.rfs-card-custom-delete:hover {
+  color: var(--rfs-danger);
+}
 
 /* "+ New recipe" tile — first item in the Custom group, always
    visible so the user can build a recipe from scratch without first
@@ -1883,7 +2418,9 @@
    dashed-accent border so it reads as a creative affordance, not a
    saved item. */
 .rfs-card-custom-new {
-  display: flex; align-items: center; gap: 0.625rem;
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
   padding: 0.625rem;
   background: transparent;
   border: 1px dashed var(--rfs-bg-3);
@@ -1896,7 +2433,7 @@
 }
 .rfs-card-custom-new:hover {
   border-color: var(--rfs-accent);
-  background: rgba(24,24,27,0.4);
+  background: rgba(24, 24, 27, 0.4);
 }
 .rfs-card-custom-new .rfs-card-icon-custom {
   background: var(--rfs-accent-soft);
@@ -1910,26 +2447,36 @@
   list-style: none;
   margin: 0;
   padding: 0;
-  display: flex; flex-direction: column; gap: 0.4375rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.4375rem;
 }
 .rfs-custom-step {
-  display: flex; align-items: flex-start; gap: 0.5rem;
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
   padding: 0.4375rem 0.5rem;
-  background: rgba(24,24,27,0.4);
+  background: rgba(24, 24, 27, 0.4);
   border: 1px solid var(--rfs-bg-2);
   border-radius: 8px;
 }
 .rfs-custom-step-num {
   flex-shrink: 0;
-  width: 18px; height: 18px;
+  width: 18px;
+  height: 18px;
   border-radius: 999px;
   background: var(--rfs-bg-2);
   color: var(--rfs-ink-1);
-  display: inline-flex; align-items: center; justify-content: center;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   font-size: 0.625rem;
   font-weight: 700;
 }
-.rfs-custom-step-text { flex: 1; min-width: 0; }
+.rfs-custom-step-text {
+  flex: 1;
+  min-width: 0;
+}
 .rfs-custom-step-name {
   font-size: 0.75rem;
   font-weight: 600;
@@ -1958,9 +2505,13 @@
   cursor: pointer;
   padding: 0;
 }
-.rfs-custom-override-toggle:hover { text-decoration: underline; }
+.rfs-custom-override-toggle:hover {
+  text-decoration: underline;
+}
 .rfs-custom-override-body {
-  display: flex; flex-direction: column; gap: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
   margin-top: 0.5rem;
 }
 /* Pre-flight validation for recipes — surfaces "step N: input is
@@ -1969,8 +2520,8 @@
 .rfs-custom-replay-validation {
   margin-top: 0.625rem;
   padding: 0.4375rem 0.625rem;
-  background: rgba(248,113,113,0.10);
-  border: 1px solid rgba(248,113,113,0.32);
+  background: rgba(248, 113, 113, 0.1);
+  border: 1px solid rgba(248, 113, 113, 0.32);
   border-radius: 6px;
   font-size: 0.75rem;
   color: var(--rfs-danger);
@@ -1983,7 +2534,9 @@
    the title attribute so the explanation surfaces on hover over any
    part of the control. */
 .rfs-header-toggle {
-  display: inline-flex; align-items: center; gap: 0.5rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
   padding: 0.25rem 0.5rem;
   border-radius: 8px;
   cursor: pointer;
@@ -1992,17 +2545,22 @@
   color: var(--rfs-ink-2);
   transition: color 120ms ease, background 120ms ease;
 }
-.rfs-header-toggle:hover { color: var(--rfs-ink-0); background: var(--rfs-bg-1); }
+.rfs-header-toggle:hover {
+  color: var(--rfs-ink-0);
+  background: var(--rfs-bg-1);
+}
 .rfs-header-toggle input[type="checkbox"] {
   /* Hide the native control; the styled track below is the visual. */
   position: absolute;
-  width: 1px; height: 1px;
+  width: 1px;
+  height: 1px;
   opacity: 0;
   pointer-events: none;
 }
 .rfs-header-toggle-track {
   position: relative;
-  width: 28px; height: 16px;
+  width: 28px;
+  height: 16px;
   border-radius: 999px;
   background: var(--rfs-bg-3);
   transition: background 140ms ease;
@@ -2010,8 +2568,10 @@
 }
 .rfs-header-toggle-knob {
   position: absolute;
-  top: 2px; left: 2px;
-  width: 12px; height: 12px;
+  top: 2px;
+  left: 2px;
+  width: 12px;
+  height: 12px;
   border-radius: 999px;
   background: var(--rfs-ink-1);
   transition: transform 140ms ease, background 140ms ease;
@@ -2021,7 +2581,7 @@
 }
 .rfs-header-toggle input:checked ~ .rfs-header-toggle-track .rfs-header-toggle-knob {
   transform: translateX(12px);
-  background: #09090B;
+  background: #09090b;
 }
 .rfs-header-toggle input:focus-visible ~ .rfs-header-toggle-track {
   outline: 2px solid var(--rfs-accent);
@@ -2041,7 +2601,9 @@
   gap: 0.5rem;
 }
 .rfs-history-card-head {
-  display: flex; align-items: center; gap: 0.625rem;
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
   padding: 0;
   border: none;
   background: transparent;
@@ -2056,7 +2618,9 @@
    form when clicked. The Save flash sits in for ~2s after a
    successful save. */
 .rfs-history-save-row {
-  display: flex; flex-wrap: wrap; align-items: center;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
   gap: 0.4375rem;
   padding-top: 0.25rem;
 }
@@ -2082,7 +2646,9 @@
   cursor: not-allowed;
 }
 .rfs-history-save-form {
-  display: flex; align-items: center; gap: 0.375rem;
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
   width: 100%;
 }
 .rfs-history-save-input {
@@ -2096,7 +2662,10 @@
   font-family: inherit;
   font-size: 0.75rem;
 }
-.rfs-history-save-input:focus { outline: none; border-color: var(--rfs-accent); }
+.rfs-history-save-input:focus {
+  outline: none;
+  border-color: var(--rfs-accent);
+}
 .rfs-history-save-flash {
   font-size: 0.6875rem;
   font-weight: 600;
@@ -2104,16 +2673,19 @@
   padding: 0.25rem 0.5rem;
 }
 .rfs-history-request {
-  display: flex; flex-direction: column;
+  display: flex;
+  flex-direction: column;
   gap: 0.25rem;
   margin: 0;
   padding: 0.5rem 0.625rem;
-  background: rgba(24,24,27,0.4);
+  background: rgba(24, 24, 27, 0.4);
   border: 1px solid var(--rfs-bg-2);
   border-radius: 8px;
 }
 .rfs-history-row {
-  display: flex; align-items: baseline; gap: 0.5rem;
+  display: flex;
+  align-items: baseline;
+  gap: 0.5rem;
   font-size: 0.6875rem;
   line-height: 1.4;
 }
@@ -2139,25 +2711,37 @@
   font-style: italic;
   color: var(--rfs-ink-0);
 }
-.rfs-history-row-quote .rfs-history-row-value::before { content: "“"; color: var(--rfs-ink-3); }
-.rfs-history-row-quote .rfs-history-row-value::after { content: "”"; color: var(--rfs-ink-3); }
-.rfs-history-swatch-row { display: inline-flex; align-items: center; gap: 0.4375rem; }
+.rfs-history-row-quote .rfs-history-row-value::before {
+  content: "“";
+  color: var(--rfs-ink-3);
+}
+.rfs-history-row-quote .rfs-history-row-value::after {
+  content: "”";
+  color: var(--rfs-ink-3);
+}
+.rfs-history-swatch-row {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4375rem;
+}
 .rfs-history-swatch {
-  width: 14px; height: 14px;
+  width: 14px;
+  height: 14px;
   border-radius: 4px;
   border: 1px solid var(--rfs-bg-3);
   flex-shrink: 0;
 }
 .rfs-history-card.is-selected .rfs-history-request {
-  background: rgba(251,191,36,0.06);
-  border-color: rgba(251,191,36,0.25);
+  background: rgba(251, 191, 36, 0.06);
+  border-color: rgba(251, 191, 36, 0.25);
 }
 
 /* Pinned action region (visible when a card is selected) */
 .rfs-action-pin {
   flex-shrink: 0;
   max-height: min(50vh, 460px);
-  display: flex; flex-direction: column;
+  display: flex;
+  flex-direction: column;
   border-top: 1px solid var(--rfs-bg-2);
   background: var(--rfs-bg-1);
 }
@@ -2176,12 +2760,16 @@
 }
 .rfs-action-pin-header {
   flex-shrink: 0;
-  display: flex; flex-direction: column; gap: 0.625rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.625rem;
   padding: 0.75rem 0.875rem;
   border-bottom: 1px solid var(--rfs-bg-2);
 }
 .rfs-action-pin-header-row {
-  display: flex; align-items: center; gap: 0.625rem;
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
 }
 /* Examples affordance — collapsed = a subtle pill in the header row;
    expanded = a horizontal strip of curated demo thumbnails the user
@@ -2189,7 +2777,9 @@
    at least one curated sample for the selected workflow, and it
    never auto-opens. Speed users see a quiet sparkle and ignore it. */
 .rfs-action-examples-toggle {
-  display: inline-flex; align-items: center; gap: 0.25rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
   padding: 0.25rem 0.5rem;
   background: transparent;
   border: 1px solid var(--rfs-bg-3);
@@ -2212,9 +2802,13 @@
   border-color: var(--rfs-accent);
   background: var(--rfs-accent-soft);
 }
-.rfs-action-examples-toggle-label { letter-spacing: 0.02em; }
+.rfs-action-examples-toggle-label {
+  letter-spacing: 0.02em;
+}
 .rfs-action-examples {
-  display: flex; flex-direction: column; gap: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
   padding-top: 0.5rem;
   border-top: 1px dashed var(--rfs-bg-2);
 }
@@ -2224,14 +2818,18 @@
   line-height: 1.4;
 }
 .rfs-action-examples-strip {
-  display: flex; gap: 0.5rem;
+  display: flex;
+  gap: 0.5rem;
   overflow-x: auto;
-  margin: 0 -0.25rem; padding: 0 0.25rem 0.25rem;
+  margin: 0 -0.25rem;
+  padding: 0 0.25rem 0.25rem;
 }
 .rfs-action-example {
   flex: 0 0 auto;
   width: 88px;
-  display: flex; flex-direction: column; gap: 0.25rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
   padding: 0;
   background: transparent;
   border: none;
@@ -2241,7 +2839,8 @@
   color: inherit;
 }
 .rfs-action-example img {
-  width: 88px; height: 88px;
+  width: 88px;
+  height: 88px;
   object-fit: cover;
   border-radius: 8px;
   border: 1px solid var(--rfs-bg-2);
@@ -2259,33 +2858,47 @@
   text-overflow: ellipsis;
 }
 .rfs-action-pin-icon {
-  width: 30px; height: 30px;
+  width: 30px;
+  height: 30px;
   border-radius: 8px;
   background: var(--rfs-accent);
-  color: #09090B;
-  display: flex; align-items: center; justify-content: center;
+  color: #09090b;
+  display: flex;
+  align-items: center;
+  justify-content: center;
   flex-shrink: 0;
 }
-.rfs-action-pin-title { flex: 1; min-width: 0; }
+.rfs-action-pin-title {
+  flex: 1;
+  min-width: 0;
+}
 .rfs-action-pin-name {
-  font-size: 0.875rem; font-weight: 700;
+  font-size: 0.875rem;
+  font-weight: 700;
   letter-spacing: -0.01em;
 }
 .rfs-action-pin-desc {
-  font-size: 0.6875rem; color: var(--rfs-ink-2);
+  font-size: 0.6875rem;
+  color: var(--rfs-ink-2);
   margin-top: 1px;
-  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 .rfs-action-pin-body {
   flex: 1;
   min-height: 0;
   overflow-y: auto;
   padding: 0.875rem;
-  display: flex; flex-direction: column; gap: 0.875rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.875rem;
 }
 .rfs-action-footer {
   flex-shrink: 0;
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   gap: 0.5rem;
   padding: 0.75rem 0.875rem;
   border-top: 1px solid var(--rfs-bg-2);
@@ -2293,11 +2906,18 @@
 }
 
 /* ============ Form inputs ============ */
-.rfs-input-group { display: flex; flex-direction: column; gap: 0.375rem; }
+.rfs-input-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+}
 .rfs-label {
-  font-size: 0.75rem; font-weight: 600;
+  font-size: 0.75rem;
+  font-weight: 600;
   color: var(--rfs-ink-1);
-  display: flex; align-items: baseline; justify-content: space-between;
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
   gap: 0.5rem;
 }
 .rfs-label-meta {
@@ -2306,15 +2926,21 @@
   color: var(--rfs-ink-3);
   letter-spacing: 0.02em;
 }
-.rfs-help { font-size: 0.6875rem; color: var(--rfs-ink-3); line-height: 1.4; }
+.rfs-help {
+  font-size: 0.6875rem;
+  color: var(--rfs-ink-3);
+  line-height: 1.4;
+}
 .rfs-help-warn {
-  color: #F59E0B;
+  color: #f59e0b;
   background: rgba(245, 158, 11, 0.08);
   border: 1px solid rgba(245, 158, 11, 0.22);
   border-radius: 6px;
   padding: 0.4375rem 0.5625rem;
 }
-.rfs-text, .rfs-textarea, .rfs-select {
+.rfs-text,
+.rfs-textarea,
+.rfs-select {
   /* Border-box so width:100% includes padding + border. The action
      panel padding hid the overflow before, but the recipe editor's
      name input made it visible — same pattern, same fix. */
@@ -2325,10 +2951,16 @@
   border: 1px solid var(--rfs-bg-3);
   border-radius: 8px;
   color: var(--rfs-ink-0);
-  font-family: inherit; font-size: 0.8125rem;
+  font-family: inherit;
+  font-size: 0.8125rem;
+}
+.rfs-text::placeholder,
+.rfs-textarea::placeholder {
+  color: var(--rfs-ink-3);
 }
-.rfs-text::placeholder, .rfs-textarea::placeholder { color: var(--rfs-ink-3); }
-.rfs-text:focus, .rfs-textarea:focus, .rfs-select:focus {
+.rfs-text:focus,
+.rfs-textarea:focus,
+.rfs-select:focus {
   outline: none;
   border-color: var(--rfs-accent);
 }
@@ -2339,11 +2971,18 @@
   height: 84px;
   line-height: 1.4;
 }
-.rfs-color-row { display: flex; align-items: center; gap: 0.5rem; }
+.rfs-color-row {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
 .rfs-color-row input[type="color"] {
-  width: 40px; height: 32px; padding: 0;
+  width: 40px;
+  height: 32px;
+  padding: 0;
   background: transparent;
-  border: 1px solid var(--rfs-bg-3); border-radius: 6px;
+  border: 1px solid var(--rfs-bg-3);
+  border-radius: 6px;
   cursor: pointer;
 }
 .rfs-color-hex {
@@ -2355,46 +2994,79 @@
 
 /* Step indicator */
 .rfs-step {
-  display: flex; align-items: flex-start; gap: 0.625rem;
+  display: flex;
+  align-items: flex-start;
+  gap: 0.625rem;
   padding: 0.625rem;
   background: var(--rfs-bg-0);
   border: 1px solid var(--rfs-bg-2);
   border-radius: 10px;
 }
 .rfs-step-num {
-  width: 22px; height: 22px;
+  width: 22px;
+  height: 22px;
   border-radius: 999px;
   background: var(--rfs-bg-2);
   color: var(--rfs-ink-2);
-  font-size: 0.6875rem; font-weight: 700;
-  display: inline-flex; align-items: center; justify-content: center;
+  font-size: 0.6875rem;
+  font-weight: 700;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   flex-shrink: 0;
 }
-.rfs-step-num.is-active { background: var(--rfs-accent); color: #09090B; }
-.rfs-step-num.is-done { background: var(--rfs-success); color: #052e16; }
-.rfs-step-num.is-done { font-size: 0; }
+.rfs-step-num.is-active {
+  background: var(--rfs-accent);
+  color: #09090b;
+}
+.rfs-step-num.is-done {
+  background: var(--rfs-success);
+  color: #052e16;
+}
+.rfs-step-num.is-done {
+  font-size: 0;
+}
 .rfs-step-num.is-done::before {
   content: "";
-  width: 9px; height: 5px;
+  width: 9px;
+  height: 5px;
   border-left: 2px solid #052e16;
   border-bottom: 2px solid #052e16;
   transform: rotate(-45deg) translate(1px, -2px);
 }
 .rfs-step-text {
-  display: flex; flex-direction: column; gap: 0.25rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
   min-width: 0;
 }
-.rfs-step-title { font-size: 0.8125rem; font-weight: 600; color: var(--rfs-ink-0); }
-.rfs-step-sub { font-size: 0.6875rem; color: var(--rfs-ink-2); }
+.rfs-step-title {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--rfs-ink-0);
+}
+.rfs-step-sub {
+  font-size: 0.6875rem;
+  color: var(--rfs-ink-2);
+}
 .rfs-link {
-  background: none; border: none;
+  background: none;
+  border: none;
   color: var(--rfs-accent);
-  font-family: inherit; font-size: inherit; font-weight: 600;
-  cursor: pointer; padding: 0;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: 600;
+  cursor: pointer;
+  padding: 0;
   text-decoration: none;
 }
-.rfs-link:hover:not(:disabled) { text-decoration: underline; }
-.rfs-link:disabled { color: var(--rfs-ink-3); cursor: not-allowed; }
+.rfs-link:hover:not(:disabled) {
+  text-decoration: underline;
+}
+.rfs-link:disabled {
+  color: var(--rfs-ink-3);
+  cursor: not-allowed;
+}
 
 /* Reference uploader */
 .rfs-drop {
@@ -2413,17 +3085,23 @@
   color: var(--rfs-accent);
   background: var(--rfs-accent-soft);
 }
-.rfs-drop input[type="file"] { display: none; }
+.rfs-drop input[type="file"] {
+  display: none;
+}
 .rfs-ref-preview {
-  display: flex; align-items: center; gap: 0.625rem;
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
   padding: 0.5rem;
   border: 1px solid var(--rfs-bg-3);
   border-radius: 10px;
   background: var(--rfs-bg-0);
 }
 .rfs-ref-preview img {
-  width: 56px; height: 56px;
-  object-fit: cover; border-radius: 8px;
+  width: 56px;
+  height: 56px;
+  object-fit: cover;
+  border-radius: 8px;
   background: var(--rfs-bg-2);
 }
 
@@ -2499,14 +3177,18 @@
   color: var(--rfs-accent);
   background: var(--rfs-accent-soft);
 }
-.rfs-ref-add input[type="file"] { display: none; }
+.rfs-ref-add input[type="file"] {
+  display: none;
+}
 .rfs-ref-add-icon {
   font-size: 1.25rem;
   font-weight: 400;
   line-height: 1;
   color: var(--rfs-ink-1);
 }
-.rfs-ref-add:hover .rfs-ref-add-icon { color: var(--rfs-accent); }
+.rfs-ref-add:hover .rfs-ref-add-icon {
+  color: var(--rfs-accent);
+}
 .rfs-ref-cap-note {
   align-self: center;
   font-size: 0.6875rem;
@@ -2517,21 +3199,28 @@
 /* Chat / history empty states */
 .rfs-empty {
   flex: 1;
-  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
   padding: 2rem 1.5rem;
   text-align: center;
   color: var(--rfs-ink-2);
 }
 .rfs-empty-icon {
-  width: 48px; height: 48px;
+  width: 48px;
+  height: 48px;
   border-radius: 999px;
   background: var(--rfs-bg-1);
-  display: flex; align-items: center; justify-content: center;
+  display: flex;
+  align-items: center;
+  justify-content: center;
   margin-bottom: 0.75rem;
   color: var(--rfs-ink-3);
 }
 .rfs-empty h3 {
-  font-size: 0.9375rem; font-weight: 700;
+  font-size: 0.9375rem;
+  font-weight: 700;
   color: var(--rfs-ink-0);
   margin: 0 0 0.375rem;
 }
@@ -2563,9 +3252,15 @@
   flex-direction: column;
   gap: 0.25rem;
 }
-.rfs-chat-msg-user { align-items: flex-end; }
-.rfs-chat-msg-assistant { align-items: flex-start; }
-.rfs-chat-msg-system { align-items: stretch; }
+.rfs-chat-msg-user {
+  align-items: flex-end;
+}
+.rfs-chat-msg-assistant {
+  align-items: flex-start;
+}
+.rfs-chat-msg-system {
+  align-items: stretch;
+}
 .rfs-chat-bubble {
   max-width: 85%;
   padding: 0.5rem 0.75rem;
@@ -2577,7 +3272,7 @@
 }
 .rfs-chat-msg-user .rfs-chat-bubble {
   background: var(--rfs-accent);
-  color: #09090B;
+  color: #09090b;
   border-bottom-right-radius: 4px;
   font-weight: 500;
 }
@@ -2597,13 +3292,16 @@
   font-size: 0.6875rem;
   color: var(--rfs-ink-2);
 }
-.rfs-chat-tool-icon { font-size: 0.6875rem; opacity: 0.7; }
+.rfs-chat-tool-icon {
+  font-size: 0.6875rem;
+  opacity: 0.7;
+}
 .rfs-chat-tool-result {
   font-size: 0.6875rem;
   color: var(--rfs-ink-3);
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
   padding: 4px 8px;
-  background: rgba(255,255,255,0.02);
+  background: rgba(255, 255, 255, 0.02);
   border-radius: 6px;
   border-left: 2px solid var(--rfs-bg-2);
 }
@@ -2623,7 +3321,11 @@
   flex-direction: column;
   gap: 0.5rem;
 }
-.rfs-chat-plan-header { display: flex; flex-direction: column; gap: 4px; }
+.rfs-chat-plan-header {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
 .rfs-chat-plan-eyebrow {
   font-size: 0.625rem;
   letter-spacing: 0.1em;
@@ -2653,10 +3355,11 @@
   border-radius: 8px;
 }
 .rfs-chat-plan-num {
-  width: 22px; height: 22px;
+  width: 22px;
+  height: 22px;
   border-radius: 999px;
   background: var(--rfs-accent);
-  color: #09090B;
+  color: #09090b;
   font-size: 0.6875rem;
   font-weight: 700;
   display: inline-flex;
@@ -2664,8 +3367,17 @@
   justify-content: center;
   flex-shrink: 0;
 }
-.rfs-chat-plan-step-text { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
-.rfs-chat-plan-step-desc { font-size: 0.8125rem; color: var(--rfs-ink-0); line-height: 1.35; }
+.rfs-chat-plan-step-text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+.rfs-chat-plan-step-desc {
+  font-size: 0.8125rem;
+  color: var(--rfs-ink-0);
+  line-height: 1.35;
+}
 .rfs-chat-plan-step-id {
   font-size: 0.625rem;
   color: var(--rfs-ink-3);
@@ -2737,21 +3449,34 @@
   align-self: flex-start;
 }
 .rfs-chat-thinking-dot {
-  width: 6px; height: 6px;
+  width: 6px;
+  height: 6px;
   border-radius: 999px;
   background: var(--rfs-ink-3);
   animation: rfs-chat-bounce 1200ms infinite ease-in-out;
 }
-.rfs-chat-thinking-dot:nth-child(2) { animation-delay: 150ms; }
-.rfs-chat-thinking-dot:nth-child(3) { animation-delay: 300ms; }
+.rfs-chat-thinking-dot:nth-child(2) {
+  animation-delay: 150ms;
+}
+.rfs-chat-thinking-dot:nth-child(3) {
+  animation-delay: 300ms;
+}
 @keyframes rfs-chat-bounce {
-  0%, 60%, 100% { opacity: 0.35; transform: scale(0.85); }
-  30%           { opacity: 1; transform: scale(1.1); }
+  0%,
+  60%,
+  100% {
+    opacity: 0.35;
+    transform: scale(0.85);
+  }
+  30% {
+    opacity: 1;
+    transform: scale(1.1);
+  }
 }
 .rfs-chat-error {
-  background: rgba(248,113,113,0.1);
+  background: rgba(248, 113, 113, 0.1);
   color: var(--rfs-danger);
-  border: 1px solid rgba(248,113,113,0.4);
+  border: 1px solid rgba(248, 113, 113, 0.4);
   padding: 8px 10px;
   border-radius: 10px;
   font-size: 0.75rem;
@@ -2785,22 +3510,31 @@
   border-color: var(--rfs-accent);
   background: var(--rfs-bg-0);
 }
-.rfs-chat-input::placeholder { color: var(--rfs-ink-3); }
-.rfs-chat-input:disabled { opacity: 0.5; cursor: not-allowed; }
+.rfs-chat-input::placeholder {
+  color: var(--rfs-ink-3);
+}
+.rfs-chat-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
 .rfs-chat-footer-actions {
   display: flex;
   justify-content: space-between;
   align-items: center;
   gap: 0.375rem;
 }
-.rfs-chat-send { margin-left: auto; }
+.rfs-chat-send {
+  margin-left: auto;
+}
 
 /* Chat header — thin strip above the transcript with the Reset
    button. Always visible inside the Chat tab so a stuck transcript
    can be wiped without hunting through the footer. */
 .rfs-chat-header {
   flex-shrink: 0;
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   padding: 0.5rem 0.75rem;
   border-bottom: 1px solid var(--rfs-bg-2);
   background: var(--rfs-bg-0);
@@ -2813,7 +3547,9 @@
   color: var(--rfs-ink-3);
 }
 .rfs-chat-reset {
-  display: inline-flex; align-items: center; gap: 0.375rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.375rem;
   background: none;
   border: 1px solid transparent;
   color: var(--rfs-ink-2);
@@ -2830,11 +3566,15 @@
   background: var(--rfs-bg-2);
   border-color: var(--rfs-bg-3);
 }
-.rfs-chat-reset:disabled { opacity: 0.4; cursor: not-allowed; }
+.rfs-chat-reset:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
 
 /* Color picker bubble — preset swatches + native picker + hex input */
 .rfs-chat-color {
-  display: flex; flex-direction: column;
+  display: flex;
+  flex-direction: column;
   gap: 0.5rem;
   margin-top: 4px;
   padding: 0.625rem;
@@ -2850,22 +3590,27 @@
 .rfs-chat-color-swatch {
   aspect-ratio: 1 / 1;
   border-radius: 999px;
-  border: 1px solid rgba(255,255,255,0.12);
+  border: 1px solid rgba(255, 255, 255, 0.12);
   cursor: pointer;
   padding: 0;
   position: relative;
   transition: transform 80ms;
 }
-.rfs-chat-color-swatch:hover { transform: scale(1.08); }
+.rfs-chat-color-swatch:hover {
+  transform: scale(1.08);
+}
 .rfs-chat-color-swatch.is-picked {
   border-color: var(--rfs-accent);
   box-shadow: 0 0 0 2px var(--rfs-accent), 0 0 0 4px var(--rfs-bg-1);
 }
 .rfs-chat-color-row {
-  display: flex; align-items: center; gap: 6px;
+  display: flex;
+  align-items: center;
+  gap: 6px;
 }
 .rfs-chat-color-native {
-  width: 32px; height: 32px;
+  width: 32px;
+  height: 32px;
   padding: 0;
   border: 1px solid var(--rfs-bg-3);
   border-radius: 6px;
@@ -2883,7 +3628,10 @@
   color: var(--rfs-ink-0);
   text-transform: uppercase;
 }
-.rfs-chat-color-hex:focus { outline: none; border-color: var(--rfs-accent); }
+.rfs-chat-color-hex:focus {
+  outline: none;
+  border-color: var(--rfs-accent);
+}
 
 /* ============ Chat: aspect-ratio bubble ============
    Wrapping pill row of "[shape] [label]" buttons. Each pill is
@@ -2894,7 +3642,9 @@
    stretches to fill the chat-message column so wrapping works. */
 .rfs-chat-aspect {
   align-self: stretch;
-  display: flex; flex-direction: column; gap: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
   padding: 0.375rem 0 0;
 }
 .rfs-chat-aspect-grid {
@@ -2903,7 +3653,9 @@
   gap: 6px;
 }
 .rfs-chat-aspect-tile {
-  display: inline-flex; align-items: center; gap: 6px;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
   height: 28px;
   padding: 0 10px 0 6px;
   border: 1px solid var(--rfs-bg-3);
@@ -2926,8 +3678,10 @@
    centres inside this box. */
 .rfs-chat-aspect-shape-wrap {
   display: inline-flex;
-  align-items: center; justify-content: center;
-  width: 16px; height: 16px;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
   flex-shrink: 0;
 }
 .rfs-chat-aspect-shape {
@@ -2949,7 +3703,9 @@
   color: var(--rfs-ink-0);
 }
 .rfs-chat-aspect-custom {
-  display: flex; align-items: center; gap: 0.375rem;
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
   padding: 0.4375rem 0.5625rem;
   border: 1px dashed var(--rfs-bg-3);
   border-radius: 8px;
@@ -2976,10 +3732,14 @@
   font-size: 0.8125rem;
   text-align: center;
 }
-.rfs-chat-aspect-num:focus { outline: none; border-color: var(--rfs-accent); }
+.rfs-chat-aspect-num:focus {
+  outline: none;
+  border-color: var(--rfs-accent);
+}
 .rfs-chat-aspect-num::-webkit-inner-spin-button,
 .rfs-chat-aspect-num::-webkit-outer-spin-button {
-  -webkit-appearance: none; margin: 0;
+  -webkit-appearance: none;
+  margin: 0;
 }
 
 /* ============ Chat: resolution bubble ============
@@ -2987,7 +3747,9 @@
    resolution pill (1K=slate, 2K=sky, 4K=amber). Source-bucket meta sits
    below the segments; upscale warning reuses .rfs-help-warn. */
 .rfs-chat-resolution {
-  display: flex; flex-direction: column; gap: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
   padding: 0.5rem 0;
 }
 .rfs-chat-resolution-segmented {
@@ -3011,22 +3773,38 @@
   cursor: pointer;
   transition: background 140ms, color 140ms;
 }
-.rfs-chat-resolution-btn:hover { color: var(--rfs-ink-0); }
+.rfs-chat-resolution-btn:hover {
+  color: var(--rfs-ink-0);
+}
 .rfs-chat-resolution-btn.is-picked {
   background: var(--rfs-bg-3);
   color: var(--rfs-ink-0);
 }
-.rfs-chat-resolution-btn-1k.is-picked { color: #94A3B8; background: rgba(148,163,184,0.18); }
-.rfs-chat-resolution-btn-2k.is-picked { color: #38BDF8; background: rgba(56,189,248,0.18); }
-.rfs-chat-resolution-btn-4k.is-picked { color: var(--rfs-accent); background: var(--rfs-accent-soft); }
+.rfs-chat-resolution-btn-1k.is-picked {
+  color: #94a3b8;
+  background: rgba(148, 163, 184, 0.18);
+}
+.rfs-chat-resolution-btn-2k.is-picked {
+  color: #38bdf8;
+  background: rgba(56, 189, 248, 0.18);
+}
+.rfs-chat-resolution-btn-4k.is-picked {
+  color: var(--rfs-accent);
+  background: var(--rfs-accent-soft);
+}
 .rfs-chat-resolution-meta {
   font-size: 0.6875rem;
   color: var(--rfs-ink-3);
   letter-spacing: 0.01em;
 }
-.rfs-chat-resolution-meta strong { color: var(--rfs-ink-1); font-weight: 700; }
+.rfs-chat-resolution-meta strong {
+  color: var(--rfs-ink-1);
+  font-weight: 700;
+}
 .rfs-chat-resolution-actions {
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   gap: 0.5rem;
 }
 
@@ -3034,7 +3812,9 @@
    Vertical button stack — single-click submits. Falls back when no
    workflow-specific tool fits. */
 .rfs-chat-choice {
-  display: flex; flex-direction: column; gap: 0.375rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
   padding: 0.5rem 0;
 }
 .rfs-chat-choice-btn {
@@ -3067,29 +3847,37 @@
   position: fixed;
   inset: 0;
   z-index: 60;
-  background: rgba(10,10,11,0.92);
+  background: rgba(10, 10, 11, 0.92);
   backdrop-filter: blur(8px);
   display: flex;
   flex-direction: column;
 }
 .rfs-compare-header {
   flex-shrink: 0;
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   padding: 1rem 1.25rem;
   border-bottom: 1px solid var(--rfs-bg-2);
   background: var(--rfs-bg-0);
 }
 .rfs-compare-title {
-  display: inline-flex; align-items: center; gap: 0.625rem;
-  font-size: 0.9375rem; font-weight: 700;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.625rem;
+  font-size: 0.9375rem;
+  font-weight: 700;
   letter-spacing: -0.01em;
 }
 .rfs-compare-title-mark {
-  width: 28px; height: 28px;
+  width: 28px;
+  height: 28px;
   border-radius: 8px;
   background: var(--rfs-accent);
-  color: #09090B;
-  display: inline-flex; align-items: center; justify-content: center;
+  color: #09090b;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
 }
 .rfs-compare-title-meta {
   margin-left: 0.5rem;
@@ -3099,7 +3887,11 @@
   text-transform: uppercase;
   color: var(--rfs-ink-3);
 }
-.rfs-compare-header-actions { display: flex; gap: 0.5rem; align-items: center; }
+.rfs-compare-header-actions {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+}
 
 .rfs-compare-body {
   flex: 1;
@@ -3119,7 +3911,9 @@
 }
 .rfs-compare-pane-header {
   flex-shrink: 0;
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   gap: 0.5rem;
 }
 .rfs-compare-pane-label {
@@ -3166,7 +3960,9 @@
   cursor: grab;
   user-select: none;
 }
-.rfs-compare-stage:active { cursor: grabbing; }
+.rfs-compare-stage:active {
+  cursor: grabbing;
+}
 .rfs-compare-stage img {
   max-width: 100%;
   max-height: 100%;
@@ -3196,7 +3992,8 @@
   user-select: none;
 }
 .rfs-compare-sync input[type="checkbox"] {
-  width: 16px; height: 16px;
+  width: 16px;
+  height: 16px;
   accent-color: var(--rfs-accent);
   cursor: pointer;
 }
@@ -3212,7 +4009,9 @@
 }
 
 @media (max-width: 900px) {
-  .rfs-compare-body { grid-template-columns: 1fr; }
+  .rfs-compare-body {
+    grid-template-columns: 1fr;
+  }
 }
 
 /* ============ Toasts ============
@@ -3239,24 +4038,40 @@
   border: 1px solid var(--rfs-bg-3);
   border-left-width: 3px;
   border-radius: 12px;
-  box-shadow: 0 12px 28px rgba(0,0,0,0.5);
+  box-shadow: 0 12px 28px rgba(0, 0, 0, 0.5);
   animation: rfs-toast-in 220ms cubic-bezier(0.4, 0, 0.2, 1);
 }
-.rfs-toast-success { border-left-color: var(--rfs-success); }
-.rfs-toast-warning { border-left-color: #F59E0B; }
-.rfs-toast-error   { border-left-color: var(--rfs-danger); }
+.rfs-toast-success {
+  border-left-color: var(--rfs-success);
+}
+.rfs-toast-warning {
+  border-left-color: #f59e0b;
+}
+.rfs-toast-error {
+  border-left-color: var(--rfs-danger);
+}
 @keyframes rfs-toast-in {
-  from { transform: translateX(40px); opacity: 0; }
-  to   { transform: translateX(0); opacity: 1; }
+  from {
+    transform: translateX(40px);
+    opacity: 0;
+  }
+  to {
+    transform: translateX(0);
+    opacity: 1;
+  }
 }
 .rfs-toast-thumb {
-  width: 40px; height: 40px;
+  width: 40px;
+  height: 40px;
   object-fit: cover;
   border-radius: 8px;
   flex-shrink: 0;
   background: var(--rfs-bg-2);
 }
-.rfs-toast-text { flex: 1; min-width: 0; }
+.rfs-toast-text {
+  flex: 1;
+  min-width: 0;
+}
 .rfs-toast-title {
   font-size: 0.8125rem;
   font-weight: 700;
@@ -3275,7 +4090,7 @@
 .rfs-toast-action {
   flex-shrink: 0;
   background: var(--rfs-accent);
-  color: #09090B;
+  color: #09090b;
   border: none;
   font-family: inherit;
   font-size: 0.75rem;
@@ -3284,10 +4099,13 @@
   border-radius: 8px;
   cursor: pointer;
 }
-.rfs-toast-action:hover { background: var(--rfs-accent-dim); }
+.rfs-toast-action:hover {
+  background: var(--rfs-accent-dim);
+}
 .rfs-toast-close {
   flex-shrink: 0;
-  width: 24px; height: 24px;
+  width: 24px;
+  height: 24px;
   background: transparent;
   border: none;
   color: var(--rfs-ink-3);
@@ -3297,7 +4115,10 @@
   align-items: center;
   justify-content: center;
 }
-.rfs-toast-close:hover { background: var(--rfs-bg-2); color: var(--rfs-ink-0); }
+.rfs-toast-close:hover {
+  background: var(--rfs-bg-2);
+  color: var(--rfs-ink-0);
+}
 
 /* Focus ring on all interactive */
 .rfs-root button:focus-visible,
@@ -3315,51 +4136,72 @@
    skip steps before clicking Apply. Per-run only; the workflow
    definition isn't mutated. */
 .rfs-package-list {
-  display: flex; flex-direction: column; gap: 0.375rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
 }
 .rfs-package-row {
-  display: flex; align-items: center; gap: 0.625rem;
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
   padding: 0.5rem 0.625rem;
   background: var(--rfs-bg-0);
   border: 1px solid var(--rfs-bg-2);
   border-radius: 10px;
 }
 .rfs-package-row-num {
-  width: 22px; height: 22px;
+  width: 22px;
+  height: 22px;
   border-radius: 999px;
   background: var(--rfs-bg-2);
   color: var(--rfs-ink-2);
-  font-size: 0.6875rem; font-weight: 700;
-  display: inline-flex; align-items: center; justify-content: center;
+  font-size: 0.6875rem;
+  font-weight: 700;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   flex-shrink: 0;
 }
 .rfs-package-row-text {
-  display: flex; flex-direction: column; gap: 0.125rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
   min-width: 0;
   flex: 1;
 }
 .rfs-package-row-name {
-  font-size: 0.8125rem; font-weight: 600; color: var(--rfs-ink-0);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--rfs-ink-0);
 }
 .rfs-package-row-file {
-  font-size: 0.6875rem; color: var(--rfs-ink-3);
+  font-size: 0.6875rem;
+  color: var(--rfs-ink-3);
   font-family: ui-monospace, "SF Mono", Menlo, monospace;
-  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 .rfs-package-row-actions {
-  display: inline-flex; align-items: center; gap: 0.25rem;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
   flex-shrink: 0;
 }
 .rfs-package-row-btn {
-  width: 24px; height: 24px;
+  width: 24px;
+  height: 24px;
   border-radius: 6px;
   background: transparent;
   border: 1px solid var(--rfs-bg-2);
   color: var(--rfs-ink-2);
-  font-size: 0.875rem; line-height: 1;
+  font-size: 0.875rem;
+  line-height: 1;
   font-family: inherit;
   cursor: pointer;
-  display: inline-flex; align-items: center; justify-content: center;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   transition: background 120ms ease, color 120ms ease, border-color 120ms ease;
 }
 .rfs-package-row-btn:hover:not(:disabled) {
@@ -3381,7 +4223,9 @@
    Subtle uppercase title + a muted meta count (e.g. "3 steps" or
    "5 of 5 selected"). */
 .rfs-package-section-header {
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   margin: 0.25rem 0 0.5rem;
   padding-bottom: 0.375rem;
   border-bottom: 1px solid var(--rfs-bg-2);
@@ -3404,10 +4248,13 @@
    picks above a custom textarea; selecting a chip writes its prompt
    into the textarea, typing custom text deselects all chips. */
 .rfs-package-creative {
-  display: flex; flex-direction: column;
+  display: flex;
+  flex-direction: column;
 }
 .rfs-package-creative-chips {
-  display: flex; flex-wrap: wrap; gap: 0.375rem;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.375rem;
   margin-bottom: 0.5rem;
 }
 .rfs-package-creative-chip {
@@ -3427,9 +4274,9 @@
   color: var(--rfs-ink-0);
 }
 .rfs-package-creative-chip.is-on {
-  background: var(--rfs-accent, #FBBF24);
-  border-color: var(--rfs-accent, #FBBF24);
-  color: #09090B;
+  background: var(--rfs-accent, #fbbf24);
+  border-color: var(--rfs-accent, #fbbf24);
+  color: #09090b;
 }
 .rfs-package-creative-textarea {
   font-family: inherit;
@@ -3448,7 +4295,7 @@
 }
 .rfs-package-creative-textarea:focus {
   outline: none;
-  border-color: var(--rfs-accent, #FBBF24);
+  border-color: var(--rfs-accent, #fbbf24);
 }
 .rfs-package-creative-textarea::placeholder {
   color: var(--rfs-ink-3);
@@ -3459,10 +4306,14 @@
    row is itself the clickable target (label-wrapped) so hits register
    anywhere from the checkbox to the ratio chip. */
 .rfs-package-variant-list {
-  display: flex; flex-direction: column; gap: 0.3125rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.3125rem;
 }
 .rfs-package-variant-row {
-  display: flex; align-items: center; gap: 0.625rem;
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
   padding: 0.5rem 0.625rem;
   background: var(--rfs-bg-0);
   border: 1px solid var(--rfs-bg-2);
@@ -3479,7 +4330,8 @@
   background: color-mix(in srgb, var(--rfs-accent, #4f46e5) 6%, var(--rfs-bg-0));
 }
 .rfs-package-variant-row input[type="checkbox"] {
-  width: 16px; height: 16px;
+  width: 16px;
+  height: 16px;
   flex-shrink: 0;
   accent-color: var(--rfs-accent, #4f46e5);
   cursor: pointer;
@@ -3527,7 +4379,9 @@
   border-top: none;
 }
 .rfs-custom-editor .rfs-action-pin-body {
-  display: flex; flex-direction: column; gap: 0.875rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.875rem;
 }
 .rfs-custom-editor-steps-label {
   font-size: 0.6875rem;
@@ -3538,7 +4392,9 @@
   margin-top: 0.125rem;
 }
 .rfs-custom-editor-row {
-  display: flex; flex-direction: column; gap: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0;
 }
 .rfs-custom-editor-row .rfs-package-row {
   border-radius: 10px;
@@ -3550,7 +4406,9 @@
 }
 .rfs-custom-editor-row-text {
   flex: 1;
-  display: flex; flex-direction: column; gap: 0.125rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
   min-width: 0;
   background: transparent;
   border: none;
@@ -3566,16 +4424,20 @@
   border-radius: 4px;
 }
 .rfs-custom-editor-step-params {
-  display: flex; flex-direction: column; gap: 0.625rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.625rem;
   padding: 0.625rem;
-  background: rgba(24,24,27,0.45);
+  background: rgba(24, 24, 27, 0.45);
   border: 1px solid var(--rfs-bg-2);
   border-top: none;
   border-bottom-left-radius: 10px;
   border-bottom-right-radius: 10px;
 }
 .rfs-custom-editor-add {
-  display: inline-flex; align-items: center; justify-content: center;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
   padding: 0.5rem 0.625rem;
   background: transparent;
   border: 1px dashed var(--rfs-bg-3);
@@ -3590,17 +4452,21 @@
 .rfs-custom-editor-add:hover {
   border-color: var(--rfs-accent);
   color: var(--rfs-accent);
-  background: rgba(24,24,27,0.4);
+  background: rgba(24, 24, 27, 0.4);
 }
 .rfs-custom-editor-picker {
-  display: flex; flex-direction: column; gap: 0.5rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
   padding: 0.625rem;
-  background: rgba(24,24,27,0.45);
+  background: rgba(24, 24, 27, 0.45);
   border: 1px solid var(--rfs-bg-2);
   border-radius: 10px;
 }
 .rfs-custom-editor-picker-header {
-  display: flex; align-items: center; justify-content: space-between;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
   font-size: 0.6875rem;
   font-weight: 600;
   color: var(--rfs-ink-3);
@@ -3608,14 +4474,18 @@
   letter-spacing: 0.06em;
 }
 .rfs-custom-editor-picker-list {
-  display: flex; flex-direction: column; gap: 0.375rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
   /* No inner scroll: the editor body is the single scroll context,
      so the picker can grow to its content and the user scrolls the
      whole rail. Inside the package action panel (capped pin) the
      body still scrolls; nothing renders cropped here. */
 }
 .rfs-custom-editor-picker-item {
-  display: flex; align-items: center; gap: 0.625rem;
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
   padding: 0.5rem 0.625rem;
   background: var(--rfs-bg-0);
   border: 1px solid var(--rfs-bg-2);
@@ -3628,7 +4498,7 @@
 }
 .rfs-custom-editor-picker-item:hover {
   border-color: var(--rfs-accent);
-  background: rgba(24,24,27,0.6);
+  background: rgba(24, 24, 27, 0.6);
 }
 
 @media (max-width: 1100px) {
@@ -3642,7 +4512,9 @@
 .rfs-mobile-fab,
 .rfs-mobile-backdrop,
 .rfs-sheet-close,
-.rfs-canvas-info { display: none; }
+.rfs-canvas-info {
+  display: none;
+}
 
 /* ============================================================
    Mobile (≤768px)
@@ -3688,16 +4560,32 @@
   .rfs-header-toggle {
     display: none;
   }
-  .rfs-brand-mark { width: 24px; height: 10px; flex-shrink: 0; }
-  .rfs-brand-name { font-size: 0.875rem; flex-shrink: 0; }
-  .rfs-project { min-width: 0; flex: 1; }
+  .rfs-brand-mark {
+    width: 24px;
+    height: 10px;
+    flex-shrink: 0;
+  }
+  .rfs-brand-name {
+    font-size: 0.875rem;
+    flex-shrink: 0;
+  }
+  .rfs-project {
+    min-width: 0;
+    flex: 1;
+  }
   .rfs-project-name {
     max-width: 100%;
     padding: 0.25rem 0.375rem;
     font-size: 0.8125rem;
   }
-  .rfs-project-name-input { width: 100%; max-width: 220px; }
-  .rfs-header-right { gap: 0.125rem; flex-shrink: 0; }
+  .rfs-project-name-input {
+    width: 100%;
+    max-width: 220px;
+  }
+  .rfs-header-right {
+    gap: 0.125rem;
+    flex-shrink: 0;
+  }
   /* Hide undo/redo + share on mobile. Versions stripe is the canonical
      undo/redo affordance; share is rarely needed mid-edit on a phone. */
   .rfs-header-right .rfs-iconbtn[aria-label="Step to previous version"],
@@ -3709,18 +4597,23 @@
     padding: 0.4375rem 0.625rem;
     font-size: 0.8125rem;
   }
-  .rfs-iconbtn { width: 36px; height: 36px; }
+  .rfs-iconbtn {
+    width: 36px;
+    height: 36px;
+  }
 
   /* ---------- Left rail as slide-over drawer ---------- */
   .rfs-left {
     position: fixed;
-    top: 48px; left: 0; bottom: 0;
+    top: 48px;
+    left: 0;
+    bottom: 0;
     width: min(86vw, 340px);
     border-right: 1px solid var(--rfs-bg-2);
     transform: translateX(-100%);
     transition: transform 240ms cubic-bezier(0.32, 0.72, 0, 1);
     z-index: 30;
-    box-shadow: 8px 0 32px rgba(0,0,0,0.5);
+    box-shadow: 8px 0 32px rgba(0, 0, 0, 0.5);
     /* Cover bottom safe area on devices with home indicators. */
     padding-bottom: env(safe-area-inset-bottom);
     visibility: hidden;
@@ -3747,12 +4640,21 @@
     padding: 0.875rem;
     gap: 1rem;
   }
-  .rfs-left-newasset-btn { padding: 0.625rem 0.5rem; min-height: 40px; }
+  .rfs-left-newasset-btn {
+    padding: 0.625rem 0.5rem;
+    min-height: 40px;
+  }
 
   /* ---------- Center / canvas ---------- */
-  .rfs-center { grid-area: center; }
-  .rfs-canvas { padding: 0.5rem; }
-  .rfs-canvas-empty p { max-width: 320px; }
+  .rfs-center {
+    grid-area: center;
+  }
+  .rfs-canvas {
+    padding: 0.5rem;
+  }
+  .rfs-canvas-empty p {
+    max-width: 320px;
+  }
 
   /* Mobile chrome cleanup. The desktop canvas-tools row (resolution +
      aspect + copy-link + download + copy-as-file) collided with the
@@ -3760,9 +4662,18 @@
      version stripe thumbs carry a 1K/2K/4K badge, Export in the header
      is the canonical download CTA. Hide it on phones — info that's
      still useful (quality + size) moves into a small "?" toggle. */
-  .rfs-canvas-tools { display: none; }
-  .rfs-canvas-compare-btn { top: 0.5rem; right: 0.5rem; height: 36px; padding: 0 0.75rem; }
-  .rfs-canvas-compare-btn-label { display: inline; }
+  .rfs-canvas-tools {
+    display: none;
+  }
+  .rfs-canvas-compare-btn {
+    top: 0.5rem;
+    right: 0.5rem;
+    height: 36px;
+    padding: 0 0.75rem;
+  }
+  .rfs-canvas-compare-btn-label {
+    display: inline;
+  }
 
   /* "?" info chip — tap to reveal resolution / aspect / dimensions.
      Uses the native <details>/<summary> toggle so no React state is
@@ -3794,7 +4705,9 @@
     cursor: pointer;
     user-select: none;
   }
-  .rfs-canvas-info-btn::-webkit-details-marker { display: none; }
+  .rfs-canvas-info-btn::-webkit-details-marker {
+    display: none;
+  }
   .rfs-canvas-info[open] .rfs-canvas-info-btn {
     color: var(--rfs-ink-0);
     border-color: var(--rfs-accent);
@@ -3829,8 +4742,14 @@
     border-left: 1px solid var(--rfs-bg-3);
     margin-left: 0.125rem;
   }
-  .rfs-image-frame { border-radius: var(--rfs-radius); }
-  .rfs-stage-hint { bottom: 1rem; font-size: 0.75rem; padding: 0.4375rem 0.75rem; }
+  .rfs-image-frame {
+    border-radius: var(--rfs-radius);
+  }
+  .rfs-stage-hint {
+    bottom: 1rem;
+    font-size: 0.75rem;
+    padding: 0.4375rem 0.75rem;
+  }
 
   /* Sentinel badge moves to the TOP-LEFT corner so it no longer fights
      the bottom-right hover tools (now hidden anyway) and isn't covered
@@ -3855,13 +4774,19 @@
        so the last thumb isn't covered by the button. */
     scroll-padding-right: 7rem;
   }
-  .rfs-version-stripe-label { display: none; }
-  .rfs-version-thumb { width: 60px; height: 60px; }
+  .rfs-version-stripe-label {
+    display: none;
+  }
+  .rfs-version-thumb {
+    width: 60px;
+    height: 60px;
+  }
 
   /* ---------- Right panel as bottom sheet ---------- */
   .rfs-right {
     position: fixed;
-    left: 0; right: 0;
+    left: 0;
+    right: 0;
     /* Anchor with top + height (both in dvh) so the sheet's bottom
        tracks the dynamic viewport. Using `bottom: 0` on iOS Safari
        sticks to the LARGE viewport bottom — i.e. underneath the URL
@@ -3876,7 +4801,7 @@
     border-top-left-radius: 18px;
     border-top-right-radius: 18px;
     background: var(--rfs-bg-0);
-    box-shadow: 0 -16px 48px rgba(0,0,0,0.55);
+    box-shadow: 0 -16px 48px rgba(0, 0, 0, 0.55);
     transform: translateY(100%);
     transition: transform 260ms cubic-bezier(0.32, 0.72, 0, 1);
     z-index: 35;
@@ -3901,8 +4826,10 @@
   .rfs-right::before {
     content: "";
     position: absolute;
-    top: 8px; left: 50%;
-    width: 36px; height: 4px;
+    top: 8px;
+    left: 50%;
+    width: 36px;
+    height: 4px;
     margin-left: -18px;
     background: var(--rfs-bg-3);
     border-radius: 999px;
@@ -3914,11 +4841,21 @@
   .rfs-right > .rfs-breadcrumb {
     padding-top: 18px;
   }
-  .rfs-tab { padding: 1rem 0.5rem; font-size: 0.875rem; min-height: 52px; }
+  .rfs-tab {
+    padding: 1rem 0.5rem;
+    font-size: 0.875rem;
+    min-height: 52px;
+  }
   /* The pinned action region stops being capped at 50vh — inside the
      sheet there's nothing above it competing for space. */
-  .rfs-action-pin { max-height: none; flex: 1; }
-  .rfs-action-pin-body { padding: 1rem; gap: 1rem; }
+  .rfs-action-pin {
+    max-height: none;
+    flex: 1;
+  }
+  .rfs-action-pin-body {
+    padding: 1rem;
+    gap: 1rem;
+  }
   .rfs-action-footer {
     padding: 0.875rem 1rem;
     padding-bottom: max(0.875rem, env(safe-area-inset-bottom));
@@ -3947,18 +4884,22 @@
     height: 48px;
     padding: 0 1.125rem;
     background: var(--rfs-accent);
-    color: #09090B;
+    color: #09090b;
     font-family: inherit;
     font-size: 0.9375rem;
     font-weight: 700;
     letter-spacing: -0.01em;
     border: none;
     border-radius: 999px;
-    box-shadow: 0 8px 24px rgba(0,0,0,0.45), 0 0 0 1px rgba(255,255,255,0.05);
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45), 0 0 0 1px rgba(255, 255, 255, 0.05);
     cursor: pointer;
   }
-  .rfs-mobile-fab svg { color: #09090B; }
-  .rfs-mobile-fab:active { transform: translateY(1px); }
+  .rfs-mobile-fab svg {
+    color: #09090b;
+  }
+  .rfs-mobile-fab:active {
+    transform: translateY(1px);
+  }
   /* Tuck the FAB away while a sheet or drawer is up so it doesn't
      overlap the active surface. */
   .rfs-root.is-right-open .rfs-mobile-fab,
@@ -3970,22 +4911,42 @@
   .rfs-mobile-backdrop {
     display: block;
     position: fixed;
-    background: rgba(0,0,0,0.55);
+    background: rgba(0, 0, 0, 0.55);
     backdrop-filter: blur(2px);
     border: none;
     padding: 0;
     cursor: default;
     animation: rfs-fade-in 160ms ease-out;
   }
-  .rfs-mobile-backdrop-left { top: 48px; left: 0; right: 0; bottom: 0; z-index: 25; }
-  .rfs-mobile-backdrop-right { inset: 0; z-index: 32; }
-  @keyframes rfs-fade-in { from { opacity: 0; } to { opacity: 1; } }
+  .rfs-mobile-backdrop-left {
+    top: 48px;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    z-index: 25;
+  }
+  .rfs-mobile-backdrop-right {
+    inset: 0;
+    z-index: 32;
+  }
+  @keyframes rfs-fade-in {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
 
   .rfs-sheet-close {
     position: fixed;
-    top: 8px; right: 12px;
-    width: 36px; height: 36px;
-    display: inline-flex; align-items: center; justify-content: center;
+    top: 8px;
+    right: 12px;
+    width: 36px;
+    height: 36px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
     background: var(--rfs-bg-1);
     border: 1px solid var(--rfs-bg-3);
     border-radius: 999px;
@@ -3993,7 +4954,9 @@
     z-index: 40;
     cursor: pointer;
   }
-  .rfs-sheet-close:active { transform: scale(0.95); }
+  .rfs-sheet-close:active {
+    transform: scale(0.95);
+  }
 
   /* ---------- Toasts span the top edge so they're tappable ---------- */
   .rfs-toasts {
@@ -4002,12 +4965,23 @@
     right: 0.5rem;
     max-width: none;
   }
-  .rfs-toast { padding: 0.75rem; }
-  .rfs-toast-action { padding: 0.5rem 0.875rem; min-height: 40px; }
+  .rfs-toast {
+    padding: 0.75rem;
+  }
+  .rfs-toast-action {
+    padding: 0.5rem 0.875rem;
+    min-height: 40px;
+  }
 
   /* ---------- Misc tap-target bumps inside the sheet ---------- */
-  .rfs-card { padding: 0.875rem; }
-  .rfs-package-row-btn { width: 32px; height: 32px; font-size: 1rem; }
+  .rfs-card {
+    padding: 0.875rem;
+  }
+  .rfs-package-row-btn {
+    width: 32px;
+    height: 32px;
+    font-size: 1rem;
+  }
   /* Custom recipe delete/edit buttons appear on hover on desktop — show
      them on mobile so they're reachable with a tap. */
   .rfs-card-custom-edit,
@@ -4018,13 +4992,20 @@
 
 /* Smaller phones: tighten the project name. */
 @media (max-width: 380px) {
-  .rfs-project-name { max-width: 96px; }
-  .rfs-project-name-input { width: 96px; }
+  .rfs-project-name {
+    max-width: 96px;
+  }
+  .rfs-project-name-input {
+    width: 96px;
+  }
 }
 
 /* Honor reduced-motion for the sheet/drawer slide. */
 @media (prefers-reduced-motion: reduce) {
-  .rfs-left, .rfs-right { transition: none; }
+  .rfs-left,
+  .rfs-right {
+    transition: none;
+  }
 }
 
 /* Stop the body from rubber-banding when a sheet is open on iOS Safari. */
diff --git a/packages/studio/src/tools/index.ts b/packages/studio/src/tools/index.ts
index 1fdf85e..68ad5a4 100644
--- a/packages/studio/src/tools/index.ts
+++ b/packages/studio/src/tools/index.ts
@@ -12,9 +12,10 @@
  */
 
 import {
-  defineTool,
   type ToolDef,
   colorInput,
+  composePinPrompt,
+  defineTool,
   extractFirstImageUrl,
   imageInput,
   imageOutput,
@@ -75,16 +76,12 @@ export const aiEdit = defineTool({
     }),
   },
   output: { image: imageOutput() },
-  buildRequest: ({ image, pin, instruction }) => {
-    const yLabel = pin.y < 0.33 ? "upper" : pin.y < 0.66 ? "middle" : "lower";
-    const xLabel = pin.x < 0.33 ? "left" : pin.x < 0.66 ? "center" : "right";
-    return {
-      input: {
-        prompt: `Edit the ${yLabel}-${xLabel} area of this image: ${instruction}. Photoreal product photography, preserve the rest of the image, true colors and lighting.`,
-        image_urls: [image],
-      },
-    };
-  },
+  buildRequest: ({ image, pin, instruction }) => ({
+    input: {
+      prompt: composePinPrompt(pin, instruction),
+      image_urls: [image],
+    },
+  }),
   extractOutput: extractImage,
 });
 
diff --git a/packages/studio/tests/mask.test.ts b/packages/studio/tests/mask.test.ts
new file mode 100644
index 0000000..cff2b36
--- /dev/null
+++ b/packages/studio/tests/mask.test.ts
@@ -0,0 +1,234 @@
+import { describe, expect, it } from "vitest";
+import { createMaskController } from "../src/lib/mask.js";
+
+/**
+ * Minimal canvas fake with a real(ish) rasterizer: fills arcs and rects
+ * onto an RGBA pixel grid so coverage() and the B&W threshold are
+ * exercised on actual pixels, not mocks.
+ */
+function fakeCanvas(width = 0, height = 0) {
+  let data = new Uint8ClampedArray(0);
+  let fillStyleValue = "";
+  let pendingArc: { x: number; y: number; r: number } | null = null;
+
+  const canvas = {
+    width,
+    height,
+    style: {} as Record<string, string>,
+    getContext(kind: string) {
+      if (kind !== "2d") return null;
+      ensure();
+      return ctx;
+    },
+    toBlob(cb: (b: Blob | null) => void, type?: string) {
+      ensure();
+      cb(new Blob([new Uint8Array(data)], { type: type ?? "image/png" }));
+    },
+  };
+
+  function ensure() {
+    const want = canvas.width * canvas.height * 4;
+    if (data.length !== want) data = new Uint8ClampedArray(want);
+  }
+  function setPixel(x: number, y: number, v: number) {
+    if (x < 0 || y < 0 || x >= canvas.width || y >= canvas.height) return;
+    const i = (y * canvas.width + x) * 4;
+    data[i] = v;
+    data[i + 1] = v;
+    data[i + 2] = v;
+    data[i + 3] = 255;
+  }
+  function styleToValue(): number {
+    return fillStyleValue === "white" ? 255 : 0;
+  }
+
+  const ctx = {
+    set fillStyle(v: string) {
+      fillStyleValue = v;
+    },
+    get fillStyle() {
+      return fillStyleValue;
+    },
+    setTransform() {},
+    clearRect() {
+      ensure();
+      data.fill(0);
+    },
+    fillRect(x: number, y: number, w: number, h: number) {
+      ensure();
+      const v = styleToValue();
+      for (let yy = Math.floor(y); yy < y + h; yy++)
+        for (let xx = Math.floor(x); xx < x + w; xx++) setPixel(xx, yy, v);
+    },
+    beginPath() {
+      pendingArc = null;
+    },
+    arc(x: number, y: number, r: number) {
+      pendingArc = { x, y, r };
+    },
+    fill() {
+      ensure();
+      if (!pendingArc) return;
+      const v = styleToValue();
+      const { x, y, r } = pendingArc;
+      for (let yy = Math.floor(y - r); yy <= y + r; yy++)
+        for (let xx = Math.floor(x - r); xx <= x + r; xx++)
+          if ((xx - x) ** 2 + (yy - y) ** 2 <= r * r) setPixel(xx, yy, v);
+    },
+    getImageData(_x: number, _y: number, w: number, h: number) {
+      ensure();
+      // Return a live copy of the grid clipped to the request.
+      const out = new Uint8ClampedArray(w * h * 4);
+      for (let yy = 0; yy < h; yy++)
+        for (let xx = 0; xx < w; xx++) {
+          const si = (yy * canvas.width + xx) * 4;
+          const di = (yy * w + xx) * 4;
+          out[di] = data[si] ?? 0;
+          out[di + 1] = data[si + 1] ?? 0;
+          out[di + 2] = data[si + 2] ?? 0;
+          out[di + 3] = data[si + 3] ?? 0;
+        }
+      return { data: out, width: w, height: h };
+    },
+    putImageData(id: { data: Uint8ClampedArray; width: number; height: number }) {
+      ensure();
+      for (let yy = 0; yy < id.height; yy++)
+        for (let xx = 0; xx < id.width; xx++) {
+          const si = (yy * id.width + xx) * 4;
+          setPixel(xx, yy, id.data[si] ?? 0);
+        }
+    },
+    drawImage(
+      src: ReturnType<typeof fakeCanvas>,
+      _dx: number,
+      _dy: number,
+      dw: number,
+      dh: number,
+    ) {
+      ensure();
+      // Nearest-neighbour scale of the source fake onto this canvas.
+      const sctx = src.getContext("2d");
+      if (!sctx) return;
+      const sdata = sctx.getImageData(0, 0, src.width, src.height);
+      for (let yy = 0; yy < dh; yy++)
+        for (let xx = 0; xx < dw; xx++) {
+          const sx = Math.min(src.width - 1, Math.floor((xx / dw) * src.width));
+          const sy = Math.min(src.height - 1, Math.floor((yy / dh) * src.height));
+          const si = (sy * src.width + sx) * 4;
+          setPixel(xx, yy, sdata.data[si] ?? 0);
+        }
+    },
+  };
+
+  return canvas;
+}
+
+type AnyCanvas = ReturnType<typeof fakeCanvas>;
+
+function setup(brushSize = 20) {
+  const created: AnyCanvas[] = [];
+  const ctl = createMaskController({
+    brushSize,
+    createCanvas: (w, h) => {
+      const c = fakeCanvas(w, h);
+      created.push(c);
+      return c as unknown as HTMLCanvasElement;
+    },
+  });
+  const visible = fakeCanvas();
+  ctl.attach(visible as unknown as HTMLCanvasElement);
+  ctl.syncToDisplay(200, 100, 1);
+  return { ctl, visible, created };
+}
+
+describe("createMaskController", () => {
+  it("starts empty and reports 0 coverage", () => {
+    const { ctl } = setup();
+    expect(ctl.coverage()).toBe(0);
+  });
+
+  it("a stroke raises coverage; clear() resets it", () => {
+    const { ctl } = setup(20);
+    ctl.beginStroke(100, 50);
+    ctl.endStroke();
+    const after = ctl.coverage();
+    expect(after).toBeGreaterThan(0);
+    ctl.clear();
+    expect(ctl.coverage()).toBe(0);
+  });
+
+  it("strokeTo interpolates so a fast drag has no gaps", () => {
+    const { ctl } = setup(10);
+    ctl.beginStroke(10, 50);
+    // One big jump — interpolation should paint the span between.
+    ctl.strokeTo(190, 50);
+    ctl.endStroke();
+    // A point midway along the drag must be painted.
+    const mid = ctl.coverage();
+    expect(mid).toBeGreaterThan(5); // a long painted band, not two dots
+  });
+
+  it("ignores strokeTo without beginStroke and tracks isStroking", () => {
+    const { ctl } = setup();
+    expect(ctl.isStroking()).toBe(false);
+    ctl.strokeTo(50, 50);
+    expect(ctl.coverage()).toBe(0);
+    ctl.beginStroke(50, 50);
+    expect(ctl.isStroking()).toBe(true);
+    ctl.endStroke();
+    expect(ctl.isStroking()).toBe(false);
+  });
+
+  it("toMaskBlob produces a full-res, thresholded mask", async () => {
+    const { ctl, created } = setup(20);
+    ctl.beginStroke(100, 50);
+    ctl.endStroke();
+    const blob = await ctl.toMaskBlob(400, 200);
+    expect(blob).not.toBeNull();
+    // The out canvas is the last one created by the factory (after the
+    // hidden canvas); inspect its pixels: only 0 or 255, with both present.
+    const out = created[created.length - 1];
+    expect(out?.width).toBe(400);
+    expect(out?.height).toBe(200);
+    const ctx = out?.getContext("2d");
+    const px = ctx ? ctx.getImageData(0, 0, 400, 200).data : new Uint8ClampedArray(0);
+    let whites = 0;
+    let blacks = 0;
+    for (let i = 0; i < px.length; i += 4) {
+      const v = px[i] ?? 0;
+      expect(v === 0 || v === 255).toBe(true);
+      if (v === 255) whites++;
+      else blacks++;
+    }
+    expect(whites).toBeGreaterThan(0);
+    expect(blacks).toBeGreaterThan(0);
+  });
+
+  it("toMaskBlob is null before any sync", async () => {
+    const ctl = createMaskController({
+      createCanvas: (w, h) => fakeCanvas(w, h) as unknown as HTMLCanvasElement,
+    });
+    expect(await ctl.toMaskBlob(100, 100)).toBeNull();
+  });
+
+  it("syncToDisplay applies the devicePixelRatio cap to the visible canvas", () => {
+    const { visible, ctl } = setup();
+    ctl.syncToDisplay(200, 100, 3); // capped at 2
+    expect(visible.width).toBe(400);
+    expect(visible.height).toBe(200);
+    expect(visible.style.width).toBe("200px");
+  });
+
+  it("setBrushSize changes the painted dab size", () => {
+    const { ctl } = setup(4);
+    ctl.beginStroke(100, 50);
+    ctl.endStroke();
+    const small = ctl.coverage();
+    ctl.clear();
+    ctl.setBrushSize(40);
+    ctl.beginStroke(100, 50);
+    ctl.endStroke();
+    const big = ctl.coverage();
+    expect(big).toBeGreaterThan(small);
+  });
+});
diff --git a/packages/studio/tests/shell-config.test.tsx b/packages/studio/tests/shell-config.test.tsx
new file mode 100644
index 0000000..2177cce
--- /dev/null
+++ b/packages/studio/tests/shell-config.test.tsx
@@ -0,0 +1,87 @@
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { StudioShell } from "../src/components/StudioShell.js";
+import { SAMPLES } from "../src/data/samples.js";
+import { WORKFLOWS } from "../src/data/workflows.js";
+import { taskDescription } from "../src/lib/sentinel.js";
+import { DEFAULT_COPY, resolveShellConfig } from "../src/lib/shell-config.js";
+
+describe("resolveShellConfig", () => {
+  it("zero props resolves to the built-in catalogue, samples, sentinel on, default copy", () => {
+    const c = resolveShellConfig({});
+    expect(c.workflows).toBe(WORKFLOWS);
+    expect(c.samples).toBe(SAMPLES);
+    expect(c.sentinel.enabled).toBe(true);
+    expect(c.sentinel.taskDescription).toBe(taskDescription);
+    expect(c.copy).toEqual(DEFAULT_COPY);
+  });
+
+  it("tools replaces the workflow catalogue", () => {
+    const custom = [WORKFLOWS[0], WORKFLOWS[1]].filter(Boolean);
+    const c = resolveShellConfig({ tools: custom });
+    expect(c.workflows).toBe(custom);
+    expect(c.samples).toBe(SAMPLES); // other axes untouched
+  });
+
+  it("source as a URL string becomes a single starting asset", () => {
+    const c = resolveShellConfig({ source: "https://cdn.example/photo.jpg" });
+    expect(c.samples).toHaveLength(1);
+    expect(c.samples[0]).toMatchObject({
+      id: "source",
+      url: "https://cdn.example/photo.jpg",
+      tags: [],
+    });
+  });
+
+  it("source as an array replaces the samples", () => {
+    const custom = [{ id: "a", title: "A", url: "https://cdn/a.png", tags: ["on-model"] }];
+    const c = resolveShellConfig({ source: custom });
+    expect(c.samples).toBe(custom);
+  });
+
+  it("sentinel can be disabled and its task description overridden", () => {
+    const fn = () => "judge against the brand guide";
+    const c = resolveShellConfig({ sentinel: { enabled: false, taskDescription: fn } });
+    expect(c.sentinel.enabled).toBe(false);
+    expect(c.sentinel.taskDescription).toBe(fn);
+  });
+
+  it("copy shallow-merges over the defaults", () => {
+    const c = resolveShellConfig({ copy: { brandName: "Estates", brandTag: "" } });
+    expect(c.copy.brandName).toBe("Estates");
+    expect(c.copy.brandTag).toBe("");
+    expect(c.copy.assetsTitle).toBe(DEFAULT_COPY.assetsTitle);
+  });
+});
+
+describe("StudioShell props (render smoke)", () => {
+  it("renders with zero props — original branding and samples", () => {
+    const html = renderToString(createElement(StudioShell, {}));
+    expect(html).toContain("rfs-root");
+    expect(html).toContain("flow"); // Run<span>flow</span>
+    expect(html).toContain("BETA");
+    expect(html).toContain("Assets");
+  });
+
+  it("applies copy + source + tools overrides", () => {
+    const html = renderToString(
+      createElement(StudioShell, {
+        tools: WORKFLOWS.filter((w) => w.id === "background-removal"),
+        source: "https://cdn.example/listing.jpg",
+        sentinel: { enabled: false },
+        copy: {
+          brandName: "Estates Studio",
+          brandTag: "",
+          assetsTitle: "Listings",
+          avatarInitials: "",
+        },
+      }),
+    );
+    expect(html).toContain("Estates Studio");
+    expect(html).not.toContain("rfs-brand-tag");
+    expect(html).toContain("Listings");
+    expect(html).toContain("https://cdn.example/listing.jpg");
+    expect(html).not.toContain("rfs-avatar");
+  });
+});
diff --git a/packages/studio/tests/tools.test.ts b/packages/studio/tests/tools.test.ts
index 6d72bf5..bf9e1c1 100644
--- a/packages/studio/tests/tools.test.ts
+++ b/packages/studio/tests/tools.test.ts
@@ -1,3 +1,4 @@
+import { mergeToolValues } from "@runflow-io/sdk";
 import { describe, expect, it } from "vitest";
 import {
   BUILTIN_TOOLS,
@@ -7,7 +8,6 @@ import {
   findTool,
   smartResize,
 } from "../src/tools/index.js";
-import { mergeToolValues } from "@runflow-io/sdk";
 
 describe("builtin tools catalogue", () => {
   it("covers every original workflow", () => {
@@ -73,7 +73,9 @@ describe("builtin tools catalogue", () => {
       image: "https://cdn/photo.png",
       prompt: "on a windswept rooftop at golden hour",
     } as never);
-    const body = aiScene.buildRequest(merged) as { input: { prompt: string; image_urls: string[] } };
+    const body = aiScene.buildRequest(merged) as {
+      input: { prompt: string; image_urls: string[] };
+    };
     expect(body.input.prompt).toMatch(/Place the subject of this image on a windswept rooftop/);
     expect(body.input.image_urls).toEqual(["https://cdn/photo.png"]);
   });
diff --git a/packages/studio/tests/urls.test.ts b/packages/studio/tests/urls.test.ts
new file mode 100644
index 0000000..100a9eb
--- /dev/null
+++ b/packages/studio/tests/urls.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { URLS, isUrlCustomized, setStudioUrls } from "../src/lib/urls.js";
+
+describe("setStudioUrls customization tracking", () => {
+  it("re-passing the default value is not a customization", () => {
+    setStudioUrls({ upload: "/api/runflow/upload" });
+    expect(isUrlCustomized("upload")).toBe(false);
+  });
+
+  it("a non-default value marks the endpoint customized; defaults restore it", () => {
+    setStudioUrls({ upload: "/my/custom/upload" });
+    expect(isUrlCustomized("upload")).toBe(true);
+    expect(URLS.upload).toBe("/my/custom/upload");
+    setStudioUrls({ upload: "/api/runflow/upload" });
+    expect(isUrlCustomized("upload")).toBe(false);
+  });
+});