@12ui/design 0.2.13 → 0.2.15

package/skills/design/SKILL.md

@@ -1,287 +1,64 @@
 ---
 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.
+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.
 
-## Choose the route
+## 1. Explore — four directions
 
-- 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.
+    12ui draft --query "<product, audience, surface, goal, personality>"
 
-## Authored workflow
+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`.
 
-### 1. Inspect and search
+## 2. Select
 
-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.
+    12ui select <run-dir> --winner B --reason "<rationale>"
 
-If there is a redesign source, state a short preserve/change contract before
-searching. Choose one mode:
+If the run indicates a recommended candidate, prefer it; overriding it
+requires a stated reason.
 
-- `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.
+## 3. Execute
 
-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.
+For a single fold, view, or state:
 
-Search with the CLI; do not make a separate brief file:
+    12ui convert <run-dir>/candidates/B.png --export html
 
-```bash
-12ui corpus inspire \
-  --query "<product, audience, surface, primary goal, personality>" \
-  --mode balanced \
-  --count 4 \
-  --out-dir <run-dir>/references
-```
+Runs ~5 minutes with streamed progress.
 
-`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:
+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:
 
-- 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.
+    12ui branch execute <run-dir> \
+      --concept "<what the rest of the surface must cover>" \
+      --scope page|site --convert html
 
-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.
+The server plans the screens; the command dispatches, downloads, and
+converts one package per page. Returns immediately;
+`12ui branch status <run-dir>` reports progress (typically 5–15 min;
+large runs can take up to ~30 min).
+Wait for it rather than building the same pages by hand in the meantime —
+they are already being produced and paid for.
+Per-page HTML lands in `<run-dir>/branch/pages/`.
 
-For either redesign mode, add the existing screenshot to retrieval:
+## 4. Integrate
 
-```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.
-
-Expect about **90 seconds** of blocking for four candidates. The command has not
-hung: never kill it, never background it, and never list the candidates
-directory to decide whether it worked. Nothing lands there until the batch is
-terminal, and then everything appears at once — the four PNGs, their attempt
-evidence, and `<run-dir>/candidates/generation.complete.json`. Poll that
-sentinel if you must poll anything. It is written only at a terminal state and
-records each candidate's status, sha256, and byte count; its absence means
-still running, never failed.
-
-If the command was interrupted, re-run the identical command with `--resume`. A
-resume delivers candidates that were already generated and re-requests only
-those the provider provably never billed, so it can never buy a candidate
-twice. It refuses a batch that already completed, and its refusal names the
-candidates already on disk — read those rather than generating again.
-
-### 3. Select
-
-Inspect all candidates at original detail. Looking at them is not optional: your
-judgment is the channel through which anything the run could not compute gets
-into the decision.
-
-If the run indicates a recommended candidate, prefer it. Overriding the
-recommendation is legitimate and expected when the context warrants — an
-explicit user preference, a brief or steering directive the recommendation could
-not see, or a visible defect in the recommended image are all good reasons — and
-an override must state its reason. If no recommendation is indicated, select on
-the criteria below as usual.
-
-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. Record whether the
-recommendation was followed or overridden, and for an override the reason. When
-the flow also writes a `design-run.json`, record the same pair there, the reason
-under `selection_override_reason`, alongside its existing selection fields.
-
-### 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. Both
-commands block for those durations and stream progress; neither has hung.
-
-The exported HTML is the deliverable page. Adapt and compose it: keep its
-document, structure, classes, and anchor bindings, and build the surface around
-that document — routing, real copy, state, interactions, and the later sections
-the first-viewport prompt deliberately omitted. Do not mine the export for its
-images and re-author the markup: that discards the design you just chose and
-paid to convert, and the page lands back on generic defaults. Fix defects in the
-export's own markup. Rebuild from scratch only when the export cannot carry the
-surface at all, and report it explicitly when you do.
-
-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. The converted export goes in as the page; integration is
-adapting it to the project, not replacing it. 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.
+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,51 @@
 ---
 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 (typically
+5–15 min, up to ~30 for large runs; 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.