@12ui/design 0.2.12 → 0.2.14

package/dist/selection-record.js

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import { readFile, writeFile } from 'node:fs/promises';
+import { readBatchAttempt, imageBatchAttemptPath } from './image-generation-batch-attempt.js';
+import { imageAttemptPath } from './image-generation-evidence.js';
+import { readImageGenerationAttemptFile } from './image-generation-staging.js';
+/**
+ * `selection.json`, version 6 — the same contract the skill used to ask an
+ * agent to hand-assemble from four other files. Every field here is copied
+ * from durable evidence the run already wrote, which is the point: a record
+ * assembled by hand can disagree with the run it describes, and this one
+ * cannot.
+ *
+ * The recommendation protocol is preserved exactly: `recommended` when the
+ * winner is the recommended candidate, `override` when it is not (and then a
+ * specific reason is required), `no-recommendation` when the run indicated
+ * none.
+ */
+export const SELECTION_RECORD_VERSION = 6;
+export const buildSelectionRecord = async (args) => {
+    const now = args.now ?? (() => new Date());
+    const { draft } = args;
+    if (!draft.generation.candidates.some((candidate) => candidate.id === args.winner)) {
+        throw new Error(`Candidate ${args.winner} is not in this run. It has`
+            + ` ${draft.generation.candidates.map((candidate) => candidate.id).join(', ')}.`);
+    }
+    const batchAttemptPath = imageBatchAttemptPath(draft.generation.manifestPath);
+    const batch = await readBatchAttempt(batchAttemptPath);
+    const candidates = await Promise.all(draft.generation.candidates.map(async (candidate) => {
+        const attemptEvidencePath = imageAttemptPath(candidate.outputPath);
+        const attempt = await readImageGenerationAttemptFile(attemptEvidencePath);
+        const bytes = await readFile(candidate.outputPath).catch(() => null);
+        return {
+            id: candidate.id,
+            path: candidate.outputPath,
+            sha256: attempt?.outputSha256
+                ?? (bytes ? createHash('sha256').update(bytes).digest('hex') : null),
+            prompt: candidate.prompt,
+            promptSha256: candidate.promptSha256,
+            directionReferenceId: candidate.referenceId,
+            direction: candidate.direction,
+            generationReferencePath: candidate.referencePath,
+            generationReferenceSha256: candidate.referenceSha256,
+            referenceMode: draft.referenceMode,
+            provider: attempt?.provider ?? batch?.provider ?? null,
+            idempotencyKey: candidate.idempotencyKey,
+            // Only ever the recorded CLI value, never an assumed guarantee.
+            providerIdempotencyEnforced: attempt?.providerIdempotencyEnforced === true,
+            attemptEvidencePath,
+            rejectionReasons: candidate.id === args.winner
+                ? []
+                : args.rejectionReasons?.[candidate.id] ?? [],
+        };
+    }));
+    const recommendation = args.recommendation ?? { candidateId: null, source: null };
+    const selectionSource = recommendation.candidateId === null
+        ? 'no-recommendation'
+        : recommendation.candidateId === args.winner
+            ? 'recommended'
+            : 'override';
+    if (selectionSource === 'override' && !args.reason.trim()) {
+        throw new Error('Overriding the recommended candidate requires a specific reason');
+    }
+    const reskin = draft.mode === 'structure-preserving-reskin';
+    return {
+        version: SELECTION_RECORD_VERSION,
+        createdAt: now().toISOString(),
+        requestSummary: draft.query,
+        viewportMode: 'first-viewport',
+        designMode: draft.mode,
+        redesignSource: {
+            originalPath: draft.redesignSource?.path ?? null,
+            originalSha256: draft.redesignSource?.sha256 ?? null,
+            preparedPath: draft.redesignSource?.path ?? null,
+            preparedSha256: draft.redesignSource?.sha256 ?? null,
+            preparation: 'none',
+        },
+        contract: { preserve: [], change: [] },
+        referencePolicy: {
+            retrieval: draft.redesignSource ? 'text-and-redesign-source' : 'text-only',
+            generation: reskin ? 'redesign-source-only' : 'one-corpus-image-per-candidate',
+            imagesPerGeneration: 1,
+        },
+        corpus: {
+            query: draft.corpus.query,
+            mode: draft.corpus.mode,
+            fallback: null,
+            idempotencyKey: draft.corpus.idempotencyKey,
+            setId: draft.corpus.setId,
+            references: draft.corpus.references.map((reference) => ({
+                id: reference.id,
+                path: reference.path,
+                sha256: reference.sha256,
+                aspect: reference.aspect,
+            })),
+        },
+        generation: {
+            referenceMode: draft.referenceMode,
+            manifestPath: draft.generation.manifestPath,
+            manifestSha256: draft.generation.manifestSha256,
+            batchAttemptPath,
+        },
+        candidates,
+        recommendation,
+        winner: args.winner,
+        selectionSource,
+        selectionOverrideReason: selectionSource === 'override' ? args.reason.trim() : null,
+        rationale: args.reason.trim(),
+    };
+};
+export const writeSelectionRecord = async (file, record) => {
+    await writeFile(file, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+};
+export const readSelectionRecord = async (file) => {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+//# sourceMappingURL=selection-record.js.map

package/dist/selection-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection-record.js","sourceRoot":"","sources":["../src/selection-record.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12ui/design",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "type": "module",
   "description": "The canonical 12UI CLI, SDK, MCP server, and visual interface design skills",
   "main": "dist/index.js",

package/skills/design/SKILL.md

@@ -1,246 +1,61 @@
 ---
 name: design
-description: "REQUIRED for all visual interface tasks (UI, Web, Mobile). Uses design-search to find high-quality references with strong UX and personality, image generation to explore distinctive directions, and design-convert to turn the chosen design into ready-to-use code quickly. Use for creating, redesigning, or implementing interfaces; it routes finished screenshots directly to conversion and keeps tiny edits code-only."
+description: "Required for non-trivial UI creation and redesign (web, app,
+mobile): explores distinctive, corpus-grounded visual directions as images,
+then converts the chosen one into production-ready code."
 ---
 
 # Design
 
-Author the visual direction before coding it. Code-first agents tend toward
-safe, generic visual defaults. Corpus-conditioned generation introduces a
-wider visual vocabulary and more personality; converting the chosen image
-then preserves that direction with near-pixel-perfect fidelity much faster
-than recreating it manually.
-
-## Choose the route
-
-- Finished screenshot or mockup to reproduce faithfully: use `design-convert`
-  directly.
-- Existing screenshot supplied as a redesign source: choose an exploratory
-  redesign or a structure-preserving reskin below. It is not a corpus
-  inspiration image.
-- Small visual edit: change the existing project code. Do not search, generate,
-  or convert.
-- Only one pipeline stage is wanted, or no local image provider is available:
-  use `design-search` for references, `design-draft` for hosted candidate
-  generation, `design-branch` to expand one approved design into the remaining
-  screens, and `design-convert` for code and other formats.
-- Rough brief, new interface, or major redesign: use the workflow below.
-
-## Authored workflow
-
-### 1. Inspect and search
-
-Inspect the project before designing: its instructions, framework, routes,
-components, assets, conventions, validation commands, and existing user
-changes. Create the run directory under the system temporary directory.
-
-If there is a redesign source, state a short preserve/change contract before
-searching. Choose one mode:
-
-- `exploratory-redesign`: preserve only named product/UX constraints and allow
-  layout and visual language to change.
-- `structure-preserving-reskin`: preserve the named information architecture,
-  content hierarchy, and interactions; change only the named visual qualities.
-
-If the source is a long page or contains more than the target screen, crop the
-relevant first viewport into the system temporary run directory before search
-or generation. Keep and hash both the original and prepared crop; do not make
-the image model solve a whole-page composition inside one viewport.
-
-Search with the CLI; do not make a separate brief file:
-
-```bash
-12ui corpus inspire \
-  --query "<product, audience, surface, primary goal, personality>" \
-  --mode balanced \
-  --count 4 \
-  --out-dir <run-dir>/references
-```
-
-`balanced` is the recommended mode and the default. Run it once; do not compare
-all three modes speculatively. Change modes only after inspecting a complete
-Balanced set and recording why it failed the brief:
-
-- Use `--mode direct` when Balanced is visually competent but semantically
-  diffuse or misses the literal product or screen requested.
-- Use `--mode adventurer` when Balanced is on-brief but too conventional or
-  repetitive to author four meaningfully distinct directions.
-
-Use at most one fallback mode in a new output directory. A transport error,
-ambiguous request, underfilled set, or interrupted download is not a retrieval
-failure: resume the original Balanced attempt with `12ui corpus resume` and do
-not switch modes.
-
-For either redesign mode, add the existing screenshot to retrieval:
-
-```bash
-12ui corpus inspire \
-  --query "<preserve/change contract and desired direction>" \
-  --mode balanced \
-  --reference-image <redesign-source.png> \
-  --count 4 \
-  --out-dir <run-dir>/references
-```
-
-This performs one image-and-text-conditioned search. The redesign source stays
-distinct from the four returned corpus inspirations.
-
-Use the four real downloaded images in endpoint order. `manifest.json` records
-the locked mode, IDs, paths, hashes, and returned provenance. Preserve that
-order and evidence; do not rerank or invent a composite score. If interrupted,
-run `12ui corpus resume --out-dir <run-dir>/references` rather than starting
-another search.
-
-### 2. Generate four directions
-
-Generate only the first viewport, one primary app state, or one mobile screen.
-Do not squeeze the whole page or journey into one canvas. Prefer full-bleed
-imagery where useful, strong hierarchy, breathing room, and sound UX. Make the
-result striking at first glance, but keep the prompt to a few sentences and
-let the image model choose layout, style, palette, typography, and detail.
-
-For new interfaces and exploratory redesigns, use this shape as guidance, not
-a form to fill mechanically:
-
-```text
-Create one distinctive [desktop/mobile] [interface] for [product and purpose].
-It should feel [desired quality]. Show only [first viewport / primary state /
-single screen], with [primary goal] immediately clear. Use the attached image
-as loose visual inspiration, not a template. Leave breathing room and choose
-the visual language yourself. Fill the canvas without a device or presentation
-frame.
-```
-
-For a structure-preserving reskin, be explicit about what is fixed but leave
-visual choices open:
-
-```text
-Reskin this [desktop/mobile] interface for [product and purpose]. Preserve the
-attached source's information architecture, content hierarchy, primary actions,
-and interactions. Change only [named visual qualities]. Show the first viewport
-or primary screen and choose the palette, typography, spacing, and detail.
-Fill the canvas without a device or presentation frame.
-```
-
-Map corpus reference 1 to candidate A, 2 to B, 3 to C, and 4 to D. Before
-writing the prompts, derive one short, visibly grounded direction from each
-paired corpus reference—such as airy editorial, tactile retail, cinematic, or
-playful illustration. Use that as the candidate's one desired quality, and
-make the four directions meaningfully different. Do not describe the whole
-reference or prescribe its layout, palette, or techniques.
-
-Use exactly one image reference per generation; never combine images:
-
-- New interface or `exploratory-redesign`: each candidate uses its paired
-  corpus image. The redesign source conditions search but is not also attached
-  to generation.
-- `structure-preserving-reskin`: every candidate uses the redesign source as
-  its sole image reference. Its paired corpus image contributes only the short
-  textual direction above; do not attach that corpus image to generation.
-
-Write one batch manifest in the run directory with four candidates:
-
-```json
-{
-  "version": 1,
-  "projectRoot": "<absolute-project-root>",
-  "provider": "auto",
-  "aspect": "landscape",
-  "referenceMode": "inspiration",
-  "candidates": [
-    {
-      "id": "A",
-      "prompt": "<short candidate prompt>",
-      "reference": "<single-generation-reference-path>",
-      "out": "<run-dir>/candidates/A.png",
-      "idempotencyKey": "<stable-A-key>"
-    }
-  ]
-}
-```
-
-Include A-D, each with its one allowed image reference, unique PNG output, and
-stable key. Set the top-level `referenceMode` to `inspiration` for new and
-exploratory candidates, or `preserve-structure` when the redesign source is
-the sole reference. This is persisted semantic evidence; GPT Image 2 already
-processes image inputs at fixed high fidelity, so do not add `input_fidelity`.
-Then run one foreground command:
-
-```bash
-12ui image generate-batch --manifest <run-dir>/generation.json
-```
-
-The CLI chooses and preflights one provider, reserves all four attempts, starts
-all four provider calls concurrently, waits for every result, and records start
-and completion evidence. Do not replace this with four built-in imagegen calls
-from one host task: that tool path may queue them serially. Never retry a failed
-or ambiguous candidate, switch providers after dispatch, use cached samples, or
-leave generation in detached background work.
-
-### 3. Select
-
-Inspect all candidates at original detail. Choose the best eligible direction
-for the brief, hierarchy, usability, personality, accessibility, feasibility,
-and ability to extend into the rest of the product.
-
-Treat common model palettes as neutral, not evidence of quality. Neon lime on
-dark and orange on light should win only when the brief or paired reference
-supports them. Prefer a specific, repeatable visual system over an impressive
-hero that gives no direction for later screens. Use corpus metrics only as
-provenance or a tie-breaker between visibly strong candidates.
-
-Write `<run-dir>/selection.json` using
-[the selection contract](references/selection-contract.md). Record exact
-prompts, original/prepared redesign-source paths and hashes, preserve/change contract, design mode,
-reference policy, corpus directions, candidate paths and hashes, winner,
-specific rejection reasons, and visible rationale.
-
-### 4. Extend and convert
-
-If the winner represents the complete simple surface, convert only that winner
-with `design-convert` and continue to integration.
-
-When the first image intentionally omitted later page viewports, routes, or app
-states, freeze the winner as the sole visual reference for every continuation.
-Plan 2-16 useful continuations. Prompt only the state, content, actions, and
-route purpose that must change; do not redescribe palette, typography, layout,
-style, or visual techniques. Set the continuation batch `referenceMode` to
-`inspiration`: the winner supplies the visual system, not a first-viewport
-composition to clone. Never attach a corpus image, composite, prior
-continuation, or predecessor. If a particular app-state edit must preserve the
-winner's exact structure, put only those edits in a separate
-`preserve-structure` batch rather than changing the continuation default.
-
-Submit the winner's base LayerDoc conversion in detached mode, then immediately
-run one foreground `12ui image generate-batch` for all continuations so image
-generation overlaps the base conversion. Inspect every result before accepting
-it. Convert accepted continuation images concurrently with distinct stable
-idempotency keys; never retry or replace an ambiguous generation.
-
-Budget about 4 minutes per conversion at `--model standard`. When a surface also
-needs responsive HTML, ask for it in the same command with `--export html`
-rather than exporting afterwards — the export then overlaps the conversion and
-the pair costs about 5 minutes instead of about 8, at the same price. One
-blocking command replaces the create-then-poll-then-export sequence.
-
-For ordered viewports of one continuous page, use the conversion package API
-to preserve page order. Integrate independent web routes, app states, or mobile
-screens as separate surfaces. Record the run in `<run-dir>/continuations.json`
-using [the continuation contract](references/continuation-contract.md).
-
-If conversion is interrupted, resume its ID or repeat the exact create request
-with the same idempotency key; do not convert another candidate as a shortcut.
-
-### 5. Integrate and verify
-
-Inspect generated files before merging the smallest coherent set into the
-project. Preserve routing, components, tokens, accessibility, dependencies,
-and unrelated changes. Add the exact copy, interactions, responsive behavior,
-later sections, and routes intentionally omitted from the first-viewport prompt
-while extending the visual system from the winner and accepted continuations.
-
-Run focused checks, launch the real interface, exercise interactions, and
-compare it with the winner at the source viewport plus representative narrower
-and wider widths. Report corpus and generation IDs/evidence, candidate hashes,
-selection rationale, conversion ID, integrated files, validation, and visible
-differences.
+Code-generating models converge on a narrow band of visual defaults — the
+same fonts, palettes, and layouts across unrelated products — and a model
+cannot see its own convergence from inside it. This skill escapes that:
+corpus-grounded image generation explores genuinely different visual
+directions, and converting the chosen image preserves it with near-pixel
+fidelity, faster and truer than recreating it by hand. Once you have a
+single screen then `12ui branch` extends it into a full page or app with
+consistent, professional quality design. That is why the flow below beats
+designing directly in code, even when coding the interface yourself feels
+quicker.
+
+## 1. Explore — four directions
+
+    12ui draft --query "<product, audience, surface, goal, personality>"
+
+Creates the run directory and prints its path — pass it to every later
+command. Searches the corpus for four diverse references and generates one
+one-viewport candidate steered by each, returning immediately.
+`12ui draft status <run-dir>` reports progress (typically ~90s).
+Redesigns: `--redesign-source <png> --mode exploratory|reskin`.
+
+## 2. Select
+
+    12ui select <run-dir> --winner B --reason "<rationale>"
+
+If the run indicates a recommended candidate, prefer it; overriding it
+requires a stated reason.
+
+## 3. Execute
+
+For a single fold, view, or state:
+
+    12ui convert <run-dir>/candidates/B.png --export html
+
+Runs ~5 minutes with streamed progress.
+
+For a full page or a multi-page site or app — the winner is viewport 1 of
+the first page; it needs no separate conversion:
+
+    12ui branch execute <run-dir> \
+      --concept "<what the rest of the surface must cover>" \
+      --scope page|site --convert html
+
+The server plans the screens; the command dispatches, downloads, and
+converts one package per page. Returns immediately;
+`12ui branch status <run-dir>` reports progress (~10–25 min typical).
+Per-page HTML lands in `<run-dir>/branch/pages/`.
+
+## 4. Integrate
+
+The exported HTML is the page: build the surface around its document —
+copy, routes, state, interactions — rather than replacing it.

package/skills/design-branch/SKILL.md

@@ -1,130 +1,50 @@
 ---
 name: design-branch
-description: "Expand one approved design into a coherent multi-screen site or app, generate every planned screen in dependency order, and download the ordered pages. Use after a design is chosen to produce its remaining routes, viewports, and app states."
+description: "Required whenever the deliverable is more than one viewport — a
+full page, a multi-route site, or an app with several states: expands one
+approved design into every planned screen and converts each page as one
+ordered package. Not for a single above-the-fold screen."
 ---
 
-# Design Branch
+# Design branch
 
-Branch one approved design into the rest of the product. The server plans the
-screens and their dependencies; dispatch each screen only when the plan allows
-it, and keep every paid screen addressable.
+One approved screen fixes the visual system; branching extends it across the
+rest of the surface with consistent, professional quality instead of
+re-deriving the design once per screen. The server plans the screens and
+their dependencies; one command executes the whole plan and keeps every paid
+screen addressable, so a retry never repeats paid work.
 
-## Start the run
+## 1. Execute
 
-A branch run is a create run with `"source": "build"`. It starts from exactly one
-of an earlier create candidate or an uploaded image — sending both, or neither,
-is `400 invalid_request`.
+    12ui branch execute <run-dir> \
+      --concept "<product, audience, what the rest of the surface must cover>" \
+      --scope page|site --convert html
 
-```bash
-curl -sS -X POST "$ORIGIN/api/v1/create" \
-  -H "Authorization: Bearer $TWELVE_UI_API_KEY" \
-  -H 'content-type: application/json' \
-  -H "Idempotency-Key: <stable-run-key>" \
-  -d '{
-    "source": "build",
-    "concept": "<product, audience, and what the rest of the surface must cover>",
-    "winner": { "createRunId": "crt-<run>", "slot": "a" }
-  }' | tee <run-dir>/branch.json
-```
+The run directory is the one `12ui draft` printed; the starting design is
+the candidate `12ui select` recorded there. `--scope page` grows that screen
+into viewports 2..n of its own page; `--scope site` adds sibling routes and
+app states as well. The server plans 2-8 screens (`--max-screens` trims the
+plan). `--convert html` converts each finished page as one ordered package;
+omitting it stops at downloaded PNGs.
 
-Start from an image instead of a winner with
-`"referenceImage": {"data": "<base64>", "mediaType": "image/png", "sha256": "<hex>"}`,
-at most 6 MB decoded and matching its magic bytes.
+To start from something else, pass a fresh directory plus exactly one of
+`--winner-run crt-<id> --winner-slot <slot>` — an earlier hosted candidate,
+whose bytes never leave the server — or `--winner-image <file>` with a PNG,
+JPEG, or WebP. The starting design is viewport 1 of the first page; it needs
+no separate conversion.
 
-`concept` is required and capped at 600 characters. `aspect` is optional and
-inherits the winner's run; set `landscape`, `portrait`, or `square` only to
-override it. There is no screen count, seed, or candidates field: the server
-plans 2-8 screens into slots `a`-`h` and trims a longer plan to that cap.
+## 2. Follow
 
-Work under the system temporary directory, set `ORIGIN` to `TWELVE_UI_ORIGIN`
-or `https://12ui.com`, and authenticate as for any create run —
-`Authorization: Bearer <key>` scoped to `design.corpus.retrieve`, or a browser
-`x-session-token`. `Idempotency-Key` is
-required and derives the run ID; the same key with the same body replays `200`,
-and with a changed body answers `409 idempotency_conflict`.
+    12ui branch status <run-dir>
 
-The claim runs the planner inline and takes roughly ten to twenty seconds before
-answering, and buys no image. `502 build_plan_failed` means planning failed
-before any image spend: retry the same request with the same key.
+Execute returns immediately and the run continues on its own (~10-25 min
+typical; add `--wait` to block instead). Status reports per-screen progress
+and the next action. `12ui branch resume <run-dir>` continues an interrupted
+run, replaying already-settled screens for free.
 
-## Read the plan
+## 3. Collect
 
-`plan.pages[]` gives each page's `index`, `kind` (`source` or `additional`),
-`title`, `pageType`, `surfaceType`, `purpose`, and its ordered `slots`. Page 0 is
-the approved design's own page and is absent when that screen already ends the
-page. `plan.statusUpdate` is written to be shown verbatim.
-
-Each `candidates[]` entry adds `pageIndex`, `viewportOrdinal` (continuations of
-the approved screen start at 2), `header`, `footer`, `pageEndsHere`,
-`dependsOnSlot`, and `content`. Preserve that grouping and order; it is the site
-structure, not a ranking to redo.
-
-## Dispatch in plan order
-
-Dispatch every screen whose dependencies are already settled, concurrently. Each
-request blocks until that screen settles.
-
-```bash
-curl -sS -X POST "$ORIGIN/api/v1/create/<run-id>/candidates/b" \
-  -H "Authorization: Bearer $TWELVE_UI_API_KEY" \
-  -H 'content-length: 0'
-```
-
-Two gates hold a screen back, and both answer `409` with a nested error object
-carrying `code` and `dependsOn`:
-
-- `dependency_pending`: the screen continues `dependsOn`; generate that slot
-  first.
-- `footer_reference_pending`: the screen closes a page and waits for the first
-  footer-bearing screen in plan order to draw the site footer. Once that seed has
-  failed, later footer screens proceed without it.
-
-Send no `Idempotency-Key` on dispatch: an unkeyed repeat replays the settled
-screen for free. A new key on a settled slot buys one more image for that screen
-and leaves its siblings untouched, so reserve it for an explicit redraw request.
-`409 candidate_in_flight` means another caller holds the slot — wait a few
-seconds and read the run.
-
-## Poll and download
-
-```bash
-curl -sS "$ORIGIN/api/v1/create/<run-id>" \
-  -H "Authorization: Bearer $TWELVE_UI_API_KEY" | tee <run-dir>/status.json
-```
-
-There is no run-level progress: count candidate `status` values, which are
-`pending`, `dispatched`, `succeeded`, and `failed`. A `failed` screen is a
-settled, paid outcome, not a transient error. Download each succeeded screen
-with the same headers:
-
-```bash
-curl -sS "$ORIGIN/api/v1/create/<run-id>/candidates/b/image" \
-  -H "Authorization: Bearer $TWELVE_UI_API_KEY" \
-  -o <run-dir>/screens/b.png
-```
-
-Runs expire seven days after the claim and then answer `410 expired`.
-
-## Quota
-
-A branch run is charged per dispatched screen rather than at the claim: one
-image against the daily allowance — 20 per UTC day for an account, 12 for an
-anonymous caller — then the prepaid wallet for the overflow. An exhausted
-allowance without a funded wallet is `429 quota_exhausted` with `retry-after`; a
-funded account that cannot cover a screen is `402 insufficient_funds`, and that
-screen is not persisted. Decide which screens the task needs before dispatching.
-
-## Hand off
-
-Keep the plan's grouping: `plan.pages[].slots` is the order viewports stack down
-one page, and page order is site order with the approved design first.
-
-- Ordered viewports of one continuous page: submit them as one conversion
-  package (`POST /api/v1/convert/package`, read back with
-  `GET /api/v1/convert/package/<package-id>`) so page order and stitching are
-  preserved. Every viewport of a page must share one width.
-- One independent route, app state, or mobile screen: `design-convert` on that
-  PNG.
-
-Report the run ID, planned pages and slots, each screen's slot, status, and
-hash, any regeneration, and the conversion package or conversion IDs.
+Screens land in `<run-dir>/branch/screens/<slot>.png` and per-page HTML in
+`<run-dir>/branch/pages/<page-id>.html`, materialized when the run reaches a
+terminal state. Each exported page is the page: build the surface around its
+document rather than replacing it.