12ui CLI

With Node on macOS, Linux, or Windows:

npx -y @12ui/design skill install

Or the npm-free installer for macOS and Linux:

curl -fsSL https://12ui.com/install.sh | sh

Either route installs the 12ui-design skill, pins the CLI, and signs you in; both need Node 22.13 or newer. The installer write-probes configured XDG data paths first, then ~/.local, then a private TMPDIR-scoped session root. It prints the exact data root and launcher, labels temporary files and PATH exports as session-only, and keeps any npm cache it creates under the selected writable data root rather than assuming ~/.npm. On Windows the normal locations are %APPDATA%\npm\12ui.cmd and %LOCALAPPDATA%\12ui. Installs are atomic and roll back on failure, and an unrecognised 12ui launcher already on disk is refused rather than replaced. See the skill page for what the skill does.

CLI only

For the binary without the agent skills:

npx -y @12ui/design cli install

curl -fsSL https://12ui.com/install-cli.sh | sh

Both install or update the pinned CLI alone - same SHA-256-verified bundle, same paths, same atomicity, rollback, and refusal to replace an unrecognised launcher - and they write no skills and open no browser. Re-running reports the CLI is already current, and each run points at 12ui auth login to connect an account and 12ui skill install for the full agent setup. npx -y @12ui/design cli install still downloads the pinned release into the managed directory rather than leaving the ephemeral npx copy in place, so the 12ui on your PATH is a verified, stable install. Take this route for a shell or CI that only needs the binary; take the full setup above when an agent should get the skills too.

12ui auth      login | connect | status | logout
12ui skill     install | status | print | remove
12ui cli       install | status
12ui corpus    inspire | resume
12ui draft     --concept <text> [--candidates 2-16]
12ui next      <run-dir or run-id> [--wait]
12ui review    <run-dir> | --all
12ui branch    execute | resume
12ui prototype <branch-run-dir>
12ui convert   <image, layerdoc, or conversion id>
12ui convert   package
12ui resume    <conversion-id>
12ui capabilities
12ui mcp

12ui --help prints this usage on stderr and exits 0, and 12ui <command> --help adds that command's purpose, behavior, safety guidance, next steps, and full invocation - including forms the summary leaves out (convert package --template, skill print, skill remove). 12ui --version (or 12ui version) prints the installed package version. Bare 12ui is not a help command - it falls through to convert, which refuses and names what was missing.

Flags are long-form only: --name value, never -n and never --name=value. --dry-run, --force, --help, --json, --quiet, --skip-auth, --template, --version, and --wait take no value; every other advertised flag consumes the next argument and errors if one is missing. Every command accepts --origin <url> and --api-key <key> to override the stored configuration, and --quiet to silence progress.

The conversion commands stream stage progress to stderr with an expected duration, because a command that prints nothing for four minutes reads as a hang - and a retry buys the work twice. --quiet silences the progress lines; stdout stays machine-readable either way.

Draft keeps every candidate dispatch request in the foreground, then returns with generation owned server-side. Run 12ui next <run-dir> --wait to repair any recorded slots that never started, poll, and download. branch execute and branch resume keep every network request in the foreground through terminal status. convert also blocks because its result is the command's own output.

There is one status surface: 12ui next <run-dir | run-id>, which dispatches on the shape of its argument and answers for a hosted draft, a branch run, or a conversion. A bare read never dispatches work. For a recorded draft, --wait idempotently dispatches only pending slots, then blocks with a heartbeat and downloads successful images; settled effects are never bought again.

12ui review <run-dir> starts an ephemeral localhost server, prints its URL, and opens it in the browser. Use 12ui review --all to find automatic draft workspaces in the current system temp directory and runs under the current project's .12ui directory. It never listens on a network interface. An explicit directory is searched for draft, branch, and conversion markers, so it may be the run itself or a parent containing several stored runs.

The review page places draft candidates side by side, shows branch screens and exported HTML pages, opens a branch prototype, and renders conversion output. These are the CLI's existing local-state conventions: automatic drafts use system-temp 12ui-* directories with draft.json and candidates/ (src/draft-workspace.ts); branch output uses <run-dir>/branch/{screens,pages,prototype} (src/branch-run-record.ts); commands append artifact paths to <workspace>/journal.jsonl (src/run-journal.ts); and conversions write beside their input unless --out-dir selects a workspace (src/cli-convert-command.ts).

Save writes the item's note and optional Pick or Approve mark atomically to <run-dir>/review.json with mode 0600. Reloading the page reads that file again. Agents can consume its stable shape directly:

{
  "version": 1,
  "updatedAt": "2026-08-21T01:23:45.000Z",
  "items": {
    "draft-candidate-a-0123abcd": {
      "feedback": {
        "note": "Keep the hierarchy and reduce the footer.",
        "mark": "pick",
        "updatedAt": "2026-08-21T01:23:45.000Z"
      },
      "edits": [{
        "id": "edit-0123abcd",
        "prompt": "Change the heading to Northstar notes.",
        "createdAt": "2026-08-21T01:25:00.000Z",
        "editOperationId": "edit-operation-id",
        "renderOperationId": "render-operation-id",
        "original": "screen.layerdoc.json",
        "layerdoc": "review/edits/edit-0123abcd.layerdoc.json",
        "html": "review/edits/edit-0123abcd.html"
      }]
    }
  }
}

Item keys are stable hashes of their item kind and run-relative path. mark is "pick", "approve", or null; edits is absent until one succeeds.

When a reviewed item is a LayerDoc and conversion credentials are configured, Apply submits the typed text request to the existing POST /api/v1/edit endpoint and puts the edited fixed render beside the original. The page states the price and asks for confirmation first; it never edits automatically. Design edits use the daily allowance when available or cost $0.03, and an explicitly requested image action can add $0.02-$0.30. Successful edited LayerDocs and fixed HTML renders are stored under <run-dir>/review/edits/ and recorded in the same review.json item.

Every completed branch with HTML has an explicit Prototype action. It runs the same post-export pipeline as 12ui prototype; review never starts it on page load. A prototype holding page offers Fill this gap only when credentials are configured. The button states $0.48+ before confirmation: $0.03 for one Standard preserve-structure image claim, $0.45 for its Standard HTML conversion, plus the cheap per-screen label calls when the prototype is rebuilt. The original branch evidence stays immutable; the filled page and updated plan live in a private prototype source overlay, with a durable receipt beside it.

Keys are personal and carry two scopes: design.convert for conversion and edit endpoints, and design.corpus.retrieve for corpus, hosted draft, and branch endpoints. A verified key is stored mode-0600 at $XDG_CONFIG_HOME/12ui/credentials.json or ~/.config/12ui/credentials.json. If those private locations are unusable and TWELVE_UI_CONFIG is not explicit, the same mode-0600 file is stored at $TMPDIR/12ui-<uid>/config/credentials.json, the CLI reports that exact path as environment-lifetime storage, and later commands in the same managed environment rediscover it. Credentials are never written into the workspace; an explicit TWELVE_UI_CONFIG remains authoritative and fails loudly when unusable.

12ui auth login

Opens the browser device-approval page, mints a personal key, verifies it, and stores it. Prints the credential file path. Note that auth login asks for design.convert only - use skill install when you also need corpus, draft, and branch access, since it requests whichever scopes the selected skills need.

TWELVE_UI_API_KEY is imported the same way --api-key is, which makes CI setup a single environment variable.

12ui auth connect CODE

Exchanges the one-time code shown after signing in at /connect-cli, verifies the personal credential, and stores it through the same private credential path as browser approval. The code works once and expires after 15 minutes. This is the paste-back path when a sandbox cannot mint a coded approval link directly.

12ui auth status

Verifies the stored key against each supported scope and prints the account id, credential id, granted scopes, and origin. When the key includes design.convert it also prints the live quota snapshot from /api/v1/convert/quota. Add --json for one machine-readable object; --login-origin <url> overrides the identity origin. Errors when no credential is configured.

12ui auth logout

Revokes the key upstream, then deletes the local credential file. Accepts --login-origin <url>.

One skill ships in the package: 12ui-design. It covers reference search, drafting, branching, and conversion. The former canonical name design and the four stage skills that used to ship beside it are retired; skill install removes a recognized old copy while preserving locally modified files.

Six clients are supported: Codex, Claude Code, Grok, Cursor, Antigravity, and Copilot. Omit --client and the CLI discovers every installation it can find, including every ~/.codex* profile and CODEX_HOME when it points somewhere else. The skill is written to <client home>/skills/12ui-design. --client <name> targets one client, and --home <dir> overrides that client's home - it requires --client, because a custom home cannot be discovered.

12ui skill install

Installs or updates the skill, pins the CLI, enables each skill in the Codex profile config, retires recognised legacy installations, and sets up credentials. Reports installed, replaced, or already current per target, so re-running it is the supported way to update.

12ui-design needs both design.convert and design.corpus.retrieve, and only those scopes are requested. Credentials are committed last: if any earlier step fails, a freshly minted key is revoked rather than left behind.

12ui skill status

Prints each target's state - not_installed, current, or different - plus whether Codex has the skill enabled, and whether credentials are configured and where. It compares files on disk and makes no network calls, so it reports that a credential file exists without verifying the key. --json emits the same report as one object.

12ui skill print

Writes one skill's SKILL.md to stdout. Requires --skill.

12ui skill remove

Removes the selected skill directories from the selected targets and reports what was and was not there. Credentials are retained, so a later reinstall needs no new sign-in.

12ui cli manages the pinned binary on its own, with no skills and no credential step. It is the update path for an install made with npx -y @12ui/design cli install or curl -fsSL https://12ui.com/install-cli.sh | sh.

12ui cli install

Installs or updates the pinned CLI - the launcher at ~/.local/bin/12ui and its versioned bundle under ~/.local/share/12ui - and nothing else. Re-running is idempotent and reports that the CLI is already current. Finishes by pointing at 12ui auth login and 12ui skill install.

12ui cli status

Prints the pinned version, the launcher path, and the data root, or reports that no managed CLI is installed. --json emits the same report as one object.

12ui corpus inspire

One paid Design Corpus query. Downloads the full reference images in parallel, verifies each one, and writes a content-hashed manifest into a new output directory.

12ui corpus inspire \
  --query "Editorial architecture homepage with warm materiality" \
  --count 4 \
  --out-dir ./references

hedge is the default: it returns an evidence-bearing ranked slate built to spread the first references across distinct directions while holding the query. It is the one mode a --reference-image search cannot use, because the corpus refuses a hedge query that carries an image, so name direct, balanced, or adventurer for one of those. direct stays close to the literal query, balanced weighs relevance, quality, and variety evenly, and adventurer follows the query's most distinctive directions. The modes are locked server-side. The retired --kind, --wildness, --seed, and --aspect flags now fail with an explicit message rather than being ignored.

Before dispatch the CLI writes inspire-attempt.json with the exact request and its idempotency key. A completed run also holds manifest.json, inspire-evidence.json with the upstream response, the numbered reference files, and a digest receipt per image under .reference-receipts/. Command output is JSON: the set id, mode, seed, output directory, manifest path, and references.

12ui corpus resume

Finishes an interrupted inspire in the same output directory, reusing the attempt's idempotency key. The service returns the original stored response or reports it still pending; it never dispatches a second paid embedding. Takes --out-dir <dir>. Use this after a transport error or a failed image download instead of running another search.

Draft owns the whole explore flow: which reference steers which candidate, how the service run and slots are identified, where the run lives, and when each real image is downloaded.

12ui draft

The explore step. One paid corpus search, one hosted /api/v1/create run, and one service-owned image effect per candidate slot.

12ui draft --concept "Editorial architecture studio homepage for independent practices" --candidates 4

It creates a resumable run directory under the system temp root and prints that path as its first line. It searches the corpus in hedge mode with no flag - one reference per candidate slot, spread across distinct directions while holding the concept - pairs one reference with each stable hosted slot, claims one run, records draft.json, and keeps every pending-slot dispatch request in the foreground. In-flight, succeeded, and failed slots are durable service states and are never posted again. Add --wait, or follow with 12ui next <run-dir> --wait, to poll and download successful PNGs into candidates/.

The hosted service owns the image provider and its paid-effect ledger. The caller authenticates with the 12ui credential only; draft never reads a Codex session, OPENAI_API_KEY, or project .env.

The run directory holds references/ with corpus evidence, draft.json with the hosted run and stable slots, draft.dispatch.json with the owning foreground process, candidates/A-P.png as requested, and draft.complete.json with image digests and byte counts.

12ui next

12ui next <run-dir | run-id> is the one surface for "what is happening and what do I do". It takes one argument and works out whether it names a draft directory, a branch directory, a crt- hosted run, a conversion id, or a journal-backed workspace.

It reports state from durable local and hosted records, elapsed time against what is typical, and one next command. A bare invocation is read-only. For a draft directory, --wait refreshes the exact hosted run id recorded in draft.json, repairs only pending slots, and never replaces settled work.

--wait blocks with a heartbeat until the run is terminal, which removes the need to invent a sleep loop. --json prints the record alone, with no human line.

12ui branch grows one approved design into the rest of a surface: the server plans the screens, and the CLI dispatches them in dependency order, downloads them in page order, and converts each whole page as one package.

12ui branch execute

One foreground command for the entire choreography. It holds the owning execution channel through every network request and returns at terminal status.

12ui branch execute \
  --start <run-dir>/candidates/A.png \
  --concept "Studio marketing site for independent architects" \
  --scope page \
  --convert html \
  --prototype

--start names the approved PNG, JPEG, or WebP explicitly. A draft candidate is just a local image, so no selection record or separate generation command stands between approval and branching. Branch creates a unique run directory when --out-dir is omitted and keeps its records under branch/, with per-page HTML in branch/pages/ and an optional clickable artifact in branch/prototype/.

The claim runs the planner inline in 10 to 20 seconds and buys no image. Each screen then costs up to about 2.5 minutes - the server's provider budget - and continuations of one page are serial because each continues the previous. Budget about 10 to 14 minutes for --scope page and 15 to 25 for --scope site, plus about 6 minutes per page conversion.

Dispatch is unkeyed on purpose: an unkeyed repeat replays a settled screen for free, while a new key on a settled slot buys another image. The run key, each redraw key, and each package key are derived, never hand-written.

The out-dir holds branch.attempt.json (written before any spend, and refused if one already exists so only --resume may proceed), branch.plan.json, branch.progress.json, screens/<slot>.png materialized atomically at the end, pages/<page-id>.html when converting, and branch.complete.json. That last file is the sentinel: written once at a terminal state with every slot's status, hash, and byte count, every blocked slot and the failure that blocked it, and each page's package and conversion ids. Its absence means the run is still going, never that it failed.

With --prototype, the post-export stage separates application states, canonicalizes shared shells, derives navigation from branch.plan.json, preserves real page content, and creates honest holding pages for planned routes that have no export yet. One cheap product-provider call labels ambiguous controls on each exported screen with the strict four-way schema navigate | dropdown | modal | none; deterministic links, forms, and plan edges win when facts conflict. Add --polish explicitly to apply the 11 retained deterministic rules after build; a harm-guarded proposal that is unsafe is reverted and logged, and the runtime gates consume the polished copy. The polish report, manifest, and run journal retain per-rule fired, silent, and reverted counts. Missing HTML or plan, legacy viewport ids, and runtime failures stop publication. Any safe action demotion, holding page, skipped shell transplant, shell size residual, or untested script direction remains a warning or degradation and measured fact in proto-manifest.json.

A failed screen is settled, paid work. Every screen downstream of it is marked blocked with the cause named, and the run reaches a terminal state instead of polling for something that can never arrive. Some screens failing parks the run rather than failing it: whole pages are still converted and the gaps are reported.

12ui branch resume

Continues an interrupted run from the recorded inputs: 12ui branch resume <run-dir>.

Follow a branch run with 12ui next <run-dir>. It accepts either the draft run directory or the branch directory inside it, reports the per-slot tally, how long the current screen has been generating against its typical duration, and every blocked slot. It reads the local snapshot and refreshes from the service when credentials are available, so it still answers offline.

12ui prototype

Builds the same clickable artifact for an existing, terminal branch run that already has exported HTML:

12ui prototype <run-dir> [--polish]

The argument may be the branch directory itself or its parent run directory. The command reads the branch completion and plan, performs one cheap label call per exported screen through the product API, optionally polishes with --polish, replaces branch/prototype/ atomically only after every runtime gate passes, and prints the manifest path, label cost, and warnings as JSON. Playwright's Chromium registry is cache/ms-playwright inside the same XDG, HOME, or session data root selected for the managed CLI. If Chromium is absent, the command stops before labeling and prints the exact version-matched install command; it never downloads a browser on its own. It never claims a new branch screen or converts an image. Repeating it uses stable label keys, so settled calls replay rather than buying duplicate labels.

12ui convert

Converts one PNG, JPEG, or WebP - or a public LayerDoc v2 JSON file - into any supported output. A finished LayerDoc conversion ID can instead derive several formats at once. The command waits for every requested result and writes it with its signed raster artifacts.

12ui convert ./screen.png --output html --out-dir ./screen

Outputs are layerdoc, html, html_fixed, svg, png, jpg, webp, pdf, psd, pptx, and sketch.

For image input, --output html writes both the LayerDoc and responsive HTML through one fused request:

12ui convert ./screen.png --output html --out-dir ./screen

The responsive work starts alongside conversion, so the pair finishes in about the same wall time as conversion alone. Leave the blocking command running; progress streams to stderr. If the shell is interrupted after admission, 12ui resume <conversion-id> recovers the original files from the CLI's local purchase record.

12ui convert package

Submits ordered viewports of one or more pages as one package conversion per page, which is what preserves page order and stitching. Converting a stacked page one image at a time loses both.

12ui convert package --manifest ./package.json --out-dir ./pages

The manifest is version 1 with an output, an optional model and responsiveQuality, and a pages array. Each page needs an id and a viewports array; each viewport needs an id and an image path resolved relative to the manifest. Ordinals default to declaration order. A viewport may add sourceConversionId to reuse an already succeeded conversion of exactly those bytes - no upload and no second paid conversion - though the local image is still named so the CLI can prove the bytes.

Every viewport of a page must share one width: the CLI checks locally and refuses before spending, because the server rejects a mismatched page at admission after the viewports would already have been paid for. Expect about 5 to 8 minutes for a multi-viewport page at output: html. Results land as <out-dir>/<page-id>.<ext> plus package.result.json naming the package id, each page's conversion id, and each file's digest.

12ui resume

Waits for an existing conversion and downloads it.

12ui resume <conversion-id>

Bare resume uses the original filenames recorded when this CLI bought the conversion; --out-dir keeps those basenames in a different directory. For an older or externally created purchase, the power form --output <format> --out <file> collects one named operation. --timeout-ms applies; --model, --width, --responsive-quality, and --detach are rejected.

Derive from a conversion

Pass a finished LayerDoc conversion ID to convert to derive several formats. The base LayerDoc is downloaded once and requested formats are dispatched concurrently.

12ui convert <source-conversion-id> \
  --output html_fixed,pdf,psd,pptx,sketch \
  --out-dir ./exports \
  --idempotency-key product-exports-v1

The source must be a succeeded layerdoc conversion. Results are named after the format - export.responsive.html, export.fixed.html, export.pdf, and so on. The command refuses before any API request if a selected output, its asset directory, or export-manifest.json already exists, and it writes that manifest with the source digest, stable request evidence, and every result or failure.

12ui capabilities

Prints the machine-readable capability document: accepted inputs and outputs, conversion models, the --width bounds, responsive qualities, duration hints, status commands, and durable journal/receipt contracts. Output is always JSON, so --json is accepted but changes nothing.

12ui mcp

Starts the Model Context Protocol server on stdio, exposing one tool, design.convert, backed by the same convert endpoints as the CLI. Pass imagePath for image input or layerdocPath for LayerDoc v2 JSON, the exact profile object for project outputs, and an optional idempotencyKey. Accepts --origin and --api-key.

Prefer hosted tools and platform-managed sign-in? Connect the six-tool remote MCP server without installing the CLI.

The skill is plain markdown with a trigger description, so installing it is only a way to put that markdown where an agent will read it; 12ui skill print --skill 12ui-design writes it to stdout. It drives the CLI commands above.

For direct integration, the API page is the prose contract and the OpenAPI documents are canonical: convert-v1, create-v1, and corpus-v1. The same package exports a typed SDK - TwelveUiConversionClient, TwelveUiCorpusClient, and TwelveUiConversionPackageClient - for Node consumers that would rather not shell out.

0.2.70 rejects incompatible local conversion flags and missing or non-file source images before dispatch, and clarifies that the local conversion owner must remain running until completion. Hosted plans preserve qualified retain constraints and complete notes, with bounded diagnostics for invalid provider retain output. PDF export uses the updated browser runtime to preserve transparent gradients; missing-browser errors and export help provide the exact install command for that runtime.

0.2.69 creates missing parent directories before saving local conversion receipts, so a new nested output path no longer fails with ENOENT.

0.2.68 includes the complete local Codex conversion and export runtime in published packages and platform downloads. Release validation now verifies that every runtime file survives build-artifact staging and restoration. This supersedes the incomplete 0.2.67 npm package; upgrade with npx -y @12ui/design@0.2.68 cli install.

0.2.67 uses Balanced retrieval automatically when a Hedge query exceeds 400 normalized characters, preserving the complete query and recording the reason. Draft accepts an optional separate --corpus-query caption while keeping the full concept for image generation. Corpus failures now preserve the service error and diagnostic evidence so a rejected request is distinguishable from an uncertain response. Its published npm package omitted the local native runtime and is superseded by 0.2.68.

0.2.65 makes Standard the $0.03 per-candidate Draft profile and adds Pro at $0.10 per candidate. Use 12ui draft --profile pro for Pro, or omit the flag for Standard. New runs retain their selected profile, while historical Draft runs continue from their recorded receipts.

0.2.64 adds Standard and Pro Draft profiles. Use 12ui draft --profile pro for Pro, or keep the default Standard profile. Both profiles use the existing $0.06 Draft candidate SKU; profile selection does not add a customer surcharge. The hosted request, durable receipt, cost accounting, and MCP result retain their canonical provider model identity. The legacy --image-model flag remains a CLI compatibility alias.

0.2.63 lets 12ui branch execute preserve an interrupted branch run after a lost response: it observes the durable run instead of submitting a second paid request, keeps an unresolved handle when the observation deadline or cancellation arrives, and resumes only when the server confirms that a slot was not admitted. Recovered dependencies still wait for their recorded parent, and late replies cannot update a completed local invocation.

0.2.62 makes the reference search behind 12ui draft run hedge with no flag: each candidate slot gets its own reference, spread across distinct directions while holding the concept. The mode comes from the same definition as 12ui corpus inspire, so the command line has one reference-search default and the Worker no longer decides it; the browser corpus picker is unchanged. --corpus-mode direct|balanced|adventurer chooses another and retrieves the wider twelve-reference slate instead. A search conditioned on your own image - 12ui draft --reference, and every 12ui improve draft stage, which always carries its own capture - keeps that wider slate, because the corpus refuses a hedge query that carries an image; improve therefore searches balanced, and --corpus-mode hedge is refused at the flag rather than after a capture or mid-run. Improve records the mode you name in improve.json, and a resume must repeat it or drop the flag: naming a different one is refused before anything is bought, because the references were bought under the recorded mode. 12ui corpus inspire --reference-image follows the same rule and no longer sends a hedge query the corpus rejects. Because the references genuinely differ, drafting the same concept again buys a new draft rather than replaying the old one - a draft already claimed in the same working directory still resumes instead of re-buying. 12ui corpus inspire also reads the rest of your flags before it quotes a price, so a --count outside its bounds or an unreadable --query-file is refused without a paid-work line. The same release makes an improve run's own report say what it bought and how each plan scored. The kit README now reads purchases from the run record, written as each stage settles, instead of the journal's terminal line, which is appended too late for the buying invocation to read - four of five kits in the last sanity run printed "nothing purchased against this kit" over ids their own improve.json was recording. A purchase names a buyer only when the journal left that invocation the only open one and the stage settled at or after it started; otherwise the row reads not recorded, and a replay reads the receipt rather than writing one. Each id is noted once in the record, so a kit with sixteen purchases no longer loses one to the end line's entry cap, and the cap marker itself is never counted as a purchase. The DOM coverage gate records three verdicts where it recorded two: passed means the threshold was met, emitted-low-overlap means the plan is anchored and under it, blocked is unchanged. The kit README, the recheck summary, and the /improve brief all read that verdict, so a page emitted under the threshold is no longer reported as having passed the gate.

0.2.61 makes hedge the default reference-search mode for the CLI and its MCP surface, so 12ui corpus inspire with no --mode spreads its first references across distinct directions while holding the query; --mode direct|balanced|adventurer still selects the others, and the browser corpus picker is unchanged.

0.2.60 makes improve caller-expiry copy say that the conversion was last observed running server-side, rather than asserting current server state. That observation-qualified result carries through the CLI, conversion client, and conversion-stage error surface while retaining the caller's deadline, stalled/terminal record semantics, and same idempotency key: the wait still does not buy another conversion.

0.2.59 ends an improve conversion wait on the bound the caller declared instead of falling back to fixed-layout HTML early, and reports a server-side wait that shows no progress as stalled at that bound; classifies hosted-draft settlement failures into the five concrete journal classes and rejects arbitrary declared classes; requires explicit negative carrier proof before a clean-output ground is accepted, so a duplicated responsive carrier can no longer pass as clean; and gives each captured page its own redesign candidate instead of reusing one winner image across every page of a multi-page improve.

0.2.58 hardens improve fallback reporting, capture-identity gating, durable records, raster handling, and artifact downloads.

0.2.57 makes the improve pick mandatory and hardens the improve kit: the CLI never converts a candidate nobody chose (exit 0 with an INCOMPLETE kit means nothing was picked yet) and a drafts-only README leads with the exact --from pick --pick <slot> command; the bootstrap session token is never stored in the kit (redacted triple + digest, honest refusal on resume without it); every added-icon SVG ships an img-safe file with its declared colour plus an inline sibling; stages[].outcome carries the truthful per-stage result; improve refuses to spend when capture landed on a different page; the wait never buys a second conversion; the kit stays out of the repository it improves; the responsive stall the fixed-layout fallback hides is surfaced; the token patch no longer imports a hosted font; the stall file is replaced when the stage settles; the --direction limit and the length written are named. Corpus hedge in this release: balanced drafts download 12 references with bounded retry, so a single failed download no longer aborts the draft.

0.2.56 makes the 12ui improve kit self-explanatory: the kit README opens with honest per-stage status and, on a stall, the recovery commands; an assets table names each extracted file's role (clean plate, cutout, upscaled copy) and what never to discard; the plan leads with the raster layers to carry before tokens and ends with a commit checklist; stalled or stopped runs write plan/STALL.md; the run ends with a summary that says INCOMPLETE first when a stage did not settle; 12ui next reports in progress with the hosted run's age instead of a success sentence; several candidates without --pick now stop after the draw and print the continue command; a stalled conversion is retried once and a stopped one is resumed, never orphaned; and the skill's improve companion documents asset roles, the raster-first rule and the stall playbook.

0.2.55 keeps 12ui improve moving when responsive HTML fails, is absent, or cannot finish: root and site-page conversions retain their successful LayerDocs, derive fixed-layout HTML free when possible, warn in the durable kit, and continue to their plans. It also adds --responsive-quality standard|pro, one spaced retry for temporary unavailability, and --fresh replacement with the abandoned conversion id recorded.

0.2.54 adds the 12ui improve verb for URL or image input, --direction steering, --target alignment mode, and kit output.

0.2.53 keeps internal provider, model, stage, and runtime diagnostics out of customer conversion problems, including failed viewport detail in accepted-partial package receipts. Release preflight now also pins the Open Design plugin manifest, its MCP command, and its root-skill fallback to the published CLI version.

Draft now bounds corpus-reference fetches, autonomously reclaims receipt-free stranded candidate dispatches, and aborts bounded CLI dispatch requests for safe re-dispatch. Unsupported 12ui draft --dry-run refuses before buying anything.

Browser verification measures the delivered anchor canvas, selects responsive bands at that width before capture, and records the 4096 px guard instead of silently clamping away right-edge evidence.

0.2.52 repairs five always-broken conversion mechanisms: s04 icon containment, s05 upscale perimeters and typographic lockups, and s07 repeated rules and surface patterns.

Paid validation also closes the lockup instruction boundary: only multi-part text logos may declare row geometry, while one-line wordmarks, headings, and other text stay on their ordinary typography contract instead of parking a conversion with an invalid one-row lockup.

Page-rhythm spacing now admits section breathing only from measured section boundaries, real available air, page scale, and bounded paint probes, with explicit refusals for diagrams and unsafe growth.

Branch content slots now travel from create planning through conversion-package manifests into HTML binding and static site exports, including paragraph reflow and a typed content-slots.json artifact for downstream editorial filling.

Prototype verification now proves trigger reachability across every retained action, respects nested inert and disabled boundaries, and keeps rejected prototype candidates as explicit review evidence.

0.2.51 prevents partially covered clean raster regions from suppressing whole panels during ground-ink publication. The shared publication contract now carries ground ink only when the selected raster covers the target's complete canvas-clipped paint box, preserving legitimate fully covered cases while keeping partially covered Lantern Fund panels live.

0.2.50 preserves quoted CSS values at the inline-style boundary and aligns raster validation with each provider's declared pixel plane while keeping Standard alpha on Pixelcut unless FeynoBG is explicitly enabled. Materialization now records classified per-lane cutout failures and uses only ownership-proved source recovery; responsive exports retain live child work across lost heartbeats and reuse completed work without weakening completeness. The redesign path removes its separate logo-pinning machinery while keeping logos through the declared semantic retain policy without carrying unrelated brand style.

0.2.49 adds the resumable 12ui redesign command with hosted direction planning, capture-time brand-asset inventory, exact-byte logo pinning through conversion, and local bench and acceptance evidence. CLI help and wait-state reporting are now honest, and proven responsive entity links can be persisted on explicit opt-in. Responsive conversion can re-emit a single missing text leaf when its owner, order, template, paint ownership, fit, and structural safety are all proved; the shared owner-growth path no longer double-moves flow siblings. Prototype polish aligns measured insets while guarding containment and hit-testing, and verification now preserves unique nested action ownership while comparing canonical shell runtime geometry without false failures.

0.2.48 restores hosted prototype labeling by replacing D1's overlong wildcard match with an exact bounded prefix comparison. Prototype runs now resume from validated per-screen manifests, replayed labels count as zero current-run spend, and branch conversion receipts live in the resumable workspace and fail loudly when their evidence is corrupt or unwritable. The new read-only 12ui spend command reports account-scoped settled charges, sponsorship, wallet, quota, and operator-visible provider cost from GET /api/v1/spend.

0.2.47 makes sponsored corpus searches complete in the same request cycle by validating the directly updated attempt's returned identity and completed state instead of interpreting trigger-inclusive D1 change telemetry as direct-row cardinality. Genuine no-op and contradictory completions remain rejected; the CLI client is otherwise unchanged.

0.2.46 supersedes the stopped 0.2.45 deployment with an explicit acknowledgement for the sponsorship-ledger trigger replacements and a local-wall regression that applies the deploy guard's exact rules to every migration that was unapplied when 0.2.45 stopped. The triggers are recreated in the same migration transaction without deleting table rows or user data.

0.2.45 adds opt-in prototype polish: run 12ui prototype <run-dir> --polish, or add --polish to 12ui branch execute ... --prototype. After the prototype build, the stage runs 11 retained deterministic, harm-guarded rules; runtime verification consumes the polished output, and the manifest and journal record each rule as fired, silent, or reverted.

0.2.44 keeps conversion pipeline v204 and resume contract v39 while responsive HTML advances to v39. Responsive packaging now reads the effective anchor-canvas geometry across the full CSS cascade, and source-proven adjacent text roles prevent unsupported mobile input-size raises. Prototype-v5 isolates transplanted shell identities, publishes recoverable dropdown and static-page degradations with durable receipts, and refuses to reuse pre-v5 prototype artifacts.

0.2.43 completes the six-tool MCP review contract with annotation titles, standard permission hints, and explicit parameter types. Prototype-v4 accepts semantic action arrays, deterministically recovers safe current-screen and incomplete-dropdown decisions, and gives each paid label attempt a versioned input-digest identity while replaying prior usable labels. Conversion pipeline v204, resume contract v39, and responsive HTML v38 are unchanged.

0.2.42 advances conversion pipeline v204 and responsive HTML v38. Responsive pages retain declared menu content and repair exact scalar-value conflicts behind durable coverage facts, while page-derived CSS adds checked, focus-visible, and hover states without scripts or geometry changes. Declared-layer ownership now rejects contaminated shadow probes, and explicit model shadows remain authoritative.

0.2.41 advances conversion pipeline v203 with truthful cross-band semantic diagnostics and audited prepared-source icon paint ownership, while guarded mobile box growth improves 130 proven text shortfalls without introducing overflow. Branch packages can roll only revision-incompatible pages onto the current contract while reusing exact successful constituents; large local PNG work now streams before the Worker memory ceiling, and prototype actions clear fixed review framing before hit-testing. The release also adds the append-only branch rollover ledger and keeps shipped v202 work on its original v37 resume contract.

0.2.40 advances conversion pipeline v202 so detached LayerDoc responsive exports, including Branch and packaged page children, finalize an explicit empty icon paint plan during prepare and idempotently at resumed anchor entry instead of parking. Source-backed icon plans remain strict, and v201 work parked at this producer seam can resume under the unchanged v37 contract.

0.2.39 moves the hosted MCP surface to the dedicated https://mcp.12ui.com/ resource identity. The Worker now serves Streamable HTTP and canonical OAuth protected-resource metadata only on that exact custom domain, retires the old 12ui.com/mcp surface, and updates the public connection instructions while keeping conversion pipeline v201 unchanged.

0.2.38 advances conversion pipeline v201 with terminal icon-match records that remain joinable after merged extraction, behind resume contract v37 so v200 records are never reinterpreted. Responsive terminal detail now derives buyer-safe progress copy from durable paid-stage evidence, and the responsive owner-clearance policy moves only whole later owners when exact or strong cross-band links prove that two declared owners collide, preserving geometry whenever that proof is absent. The website removes the retired homepage design grid and places Install plugin first on /versus and at the top of the Skill and CLI install sections.

0.2.37 advances conversion pipeline v200 with exact icon paint ownership and source-bound responsive icon lineage, while ra3 child identity now carries both that lineage and each anchor's declared purpose behind a fresh resume fence. Converted controls emit native checkbox, radio, and switch semantics; source-declared list peers share an exact left rail; and proven mobile anchor text can rise to a readable size without moving its box. Branch creation inherits the winning canvas, and prototype-v3 preserves per-band holding, honest partial-review receipts, poststep resume, canonical shell consistency, and active navigation across the assembled site. Static export v19 carries the new checkable-control representation without reusing v18 bytes.

0.2.36 opens the MCP endpoint to standards-compliant clients with path-aware protected-resource discovery and surface-scoped CORS. Conversion pipeline v199 removes the retired dense-document cap in favor of the live provider-schema boundary, prepares generative clean inputs before candidate retention, refuses responsive success when required bands are missing, publishes exact ground-ink carriage facts, centers control text only from accepted source-ink evidence, and normalizes repeated icon families only when every local member has a no-loss candidate. Branch packaging now exports the longest successful page prefix with an explicit accepted-partial receipt while keeping a failed required winner page terminal.

0.2.35 adds reference-led Draft generation without silently preserving the old page. Pass a local PNG, JPEG, or WebP, or an HTTP(S) image, with 12ui draft --reference; the original bytes reach every candidate, retain style by default, and explicitly exclude layout, content, and assets. --retain accepts comma-separated semantics when another policy is deliberate, while --retain layout is the explicit structure-preserving opt-in and --mode reskin remains its shorthand. Create claims normalize and persist that retain policy, reject contradictory or unsupported reference requests before dispatch, and tell the image model what to preserve without restating excluded semantics. This release also keeps Create run identities byte-for-byte compatible while making their NUL separator reviewable in source, and derives the CLI page's hero version from this changelog so the two cannot drift again.

0.2.34 gives converted interfaces more faithful structure. Conversion pipeline v196 cleans measured text ink out of independently extracted underline decorations, anchors labels beside proven single-side control icons, emits repeated proportional-font label and trailing-count rows as real columns, and clips flush child photos to their parent card corners. Each conversion rule is fact-gated with paired silent cases.

0.2.33 hardens installation, account reuse, and prototype browser lookup in managed environments. An ENOENT while preparing an automatic CLI candidate now advances through XDG and HOME to the existing private TMPDIR fallback, while explicit credential paths still fail loudly. Credential storage follows the same XDG, HOME, then session ladder: the final fallback is a mode-0600 $TMPDIR/12ui-<uid>/config/credentials.json file that the launcher preserves and later commands rediscover for the environment lifetime, never a workspace path. Prototype inventory and runtime verification now resolve Chromium at cache/ms-playwright inside that selected CLI data root; a missing browser stops before labeling with an exact version-matched install command and no raw Playwright stack, with no automatic download. The npm-free macOS/Linux installer remains the bootstrap path when npm's own cache is unusable before 12ui code starts.

0.2.32 keeps managed-sandbox network ownership honest. Draft candidate dispatch requests and branch execute or resume now stay in the foreground; draft returns only after no slot remains pending, while 12ui next <run-dir> --wait repairs exactly the recorded slots that never started, polls, and downloads without buying settled effects again. A bare next reports a pending draft with zero running slots as an exited dispatcher and prints that recovery command instead of claiming generation is progressing. CLI installation now write-probes XDG, HOME, and a TMPDIR session fallback in order, uses an installer-owned writable npm cache, and labels temporary files and PATH exports as session-only. Conversion pipeline v194 expands sparse companion text only when declared extraction facts prove it is missing, accounts and reclaims the exact retained raster working set under isolate pressure, and retries failed R2 persistence from already-settled provider bytes without buying the provider output again.

0.2.31 makes CLI authentication work honestly across restricted shells and sandboxes. Device-code minting and one-time link exchange now use same-origin 12ui.com proxy routes, while every identity request has a 15-second deadline and one timeout-only retry. A coded link can be completed in the browser or pasted back with 12ui auth connect CODE; /connect-cli also explains that paste-code path when opened without a code. The macOS/Linux installer now honors XDG data locations for both the pinned bundle and launcher, and an unwritable private credential location degrades to session-only use instead of writing into the project. When neither 12ui.com nor the login service can mint a code, the CLI names the failure and the connect-code recovery command instead of presenting a bare link as completable.

0.2.30 turns a completed HTML branch into an honest clickable prototype. Add --prototype to 12ui branch execute, or run 12ui prototype <run-dir> later, to derive state pages, shared shells, plan-backed navigation, content, and holding pages; one cheap four-way label call per exported screen resolves ambiguous controls while deterministic facts retain precedence. The staged pipeline imports the population-tested shell and dropdown fixes, hard-gates missing or legacy input, runtime failures, zero-action real pages, invalid dropdowns, and majority holdings, and records every lesser holding ratio, shell skip/residual, and untested script direction for review. 12ui review exposes Prototype per branch and an explicit $0.51+ Fill this gap action on holding pages, with no automatic spend and no mutation of original branch evidence. Responsive HTML also joins the pinned page ground to the source edge pixels, eliminating wide-screen background seams in emitter v32.

0.2.29 adds 12ui review for local draft, branch, and conversion comparison and edits; reclaims orphaned 12ui next --wait locks; and keeps decorated controls clickable while the CLI connection page stays out of search indexes.

0.2.28 renames the bundled skill from design to 12ui-design, including its directory, frontmatter, agent metadata, installer copy, and Open Design wiring. A normal 12ui skill install recognizes every frozen historical design bundle, removes that old directory, removes its exact stale Codex config registration, and installs only 12ui-design; a locally modified old copy is preserved. The public plugin publisher now emits the same identity and install path.

0.2.27 stops two ways a run could lose work you had already paid for. A poll blip no longer abandons a running conversion: when a status check comes back 5xx, times out, is rate-limited, or never answers at all, the CLI keeps polling on one bounded policy — up to 12 consecutive failures or five minutes, backing off from the poll interval to 30 seconds and honouring Retry-After — instead of throwing on the first one. Until now any poll error the service did not explicitly mark retryable ended the wait, so 12ui convert, 12ui convert package, and branch execute --convert could each walk away from a paid conversion that went on to succeed. A missing or unauthorized operation still stops immediately, and your own cancellation is still honoured. And a site run no longer silently loses the approved design: the plan always carries the page your winning screen starts, so that page is staged and converted rather than dropped; --max-screens now names exactly which screens and which whole pages it left out, in the plan, the run summary, and the progress narration; and a run that skips a planned page reports partial rather than succeeded, so 12ui next tells you a page is missing instead of calling the run done. One behaviour change to know about: a page-scope run whose plan ends at the approved screen now buys one conversion of that screen, where it previously delivered nothing at all.

0.2.26 makes responsive exports work again for API clients; the plan's revision is now opaque per the contract. Every release before this one validated the anchor plan a conversion carries against a closed list of revision names and re-derived the anchor topology the service had chosen, so when the service changed how it prices anchors on 2026-08-15 — buying a direction only when its band can actually be placed — your CLI refused the whole operation with "invalid responsive plan", including responsive exports it had already paid for and that had already finished. --output html, --export html, and resume on a completed export all work again, and the revision is now read as the opaque string the published contract always said it was, so the next pricing change costs you nothing. If you are still on an older release the service withholds the plan from you rather than handing you one you refuse; nothing you read is missing.

0.2.25 brings two things you will notice immediately. Briefs are no longer cut short: --concept and --query accept 1200 characters rather than 600, a raise a blind A/B settled — long briefs cost nothing in screen quality, and trimming one cost you tokens — and when a brief really is too long the refusal now names the counted length, how much to trim, where the cut detail belongs, and that nothing was sent and nothing was bought, with no claim that a shorter brief designs better. And the five bundled design skills become one: design now covers exploring, selecting, converting, branching, and searching in a single body smaller than the old convert skill alone, because a measured trial found the four specialist skills bought no routing precision (27/27 against 26/27) while every task paid for their descriptions. 12ui skill install migrates the old copies out of every agent home automatically, and a copy you edited yourself is preserved rather than removed.

0.2.24 brings three things. The MCP server grows from one tool to seven: alongside design.convert there are now design.convert.status, design.corpus.status, design.corpus.inspire, design.corpus.resume, design.draft.status, and design.branch.status, and the package ships an Open Design plugin bundle that wires them up. 12ui next <conversion-id> now answers for real production conversions (previously it recognised only rehearsal ids and refused yours), a blocking convert writes progress into its run journal so next from a second shell gets a live answer, and converting the same image bytes twice while the first run is still working tells you so before it spends. And the CLI declares its own version on every request in an X-12UI-Client-Version header: the service reads it to decide what your installed LayerDoc parser can be handed, removing a field added after your version was built instead of making the whole document unreadable — while the bundled parsers now accept and preserve fields they do not recognise, so the next such field costs nothing at all.

0.2.23 makes each bundled skill's setup condition explicit: run the one-time installer only when the 12ui CLI is not present. The installer still installs the CLI and verifies the account scopes required by the selected skill.

0.2.22 standardizes the product name as lowercase 12ui across the npm package, public plugin, generated documentation, marketplace copy, and future public release records. Existing X-12UI-Public-* HTTP header names remain unchanged because they are protocol identifiers rather than branding.

0.2.21 is a simplification pass: the CLI got smaller, and what is left tells you the truth. 12ui next <run-dir | run-id | batch-manifest> replaces draft status, branch status, image batch-status, and create status - one command, one argument, whatever kind of run you point it at. It reports what is moving, how long it has been going against what is typical (re-quoted once the typical is passed, instead of leaving you holding a stale promise), and one next command that exists; --wait blocks with a heartbeat for any run, so you never have to invent a sleep loop. --json is honoured, which it was not on any of the four commands that advertised it.

The help stops making promises the code does not keep. Seven documented-but-ignored flags are gone, --origin/--api-key/--quiet moved to a footer because they apply everywhere, and a refusal now quotes the same usage line --help prints instead of a second copy written from memory - the two disagreed in five places. 12ui <command> --help prints one command in full, including the forms the summary no longer lists. 12ui select drops three flags nobody used, one of which could never do what its own documentation showed, and reads the run's recommendation from the run instead of asking you to type it back.

Two things now say something useful at the moment they can still save you money: 12ui convert takes a directory for --out and writes both the document and the page inside it, and a document written with no page names the command that renders it. 12ui export tells you when the conversion already carries an export rather than quietly selling you a second one, and 12ui draft --redesign-source points at building a finished design before it starts redrawing it. Conversions bought through 12ui mcp are now recorded in the run journal like every other paid call. The skills lost about a fifth of their text - curl choreography, flag spellings, and quoted durations that the commands themselves now report. 0.2.20 publishes the five design skills and canonical API contracts through the public 12ui Design plugin. Directory-only skill installs now carry a scope-aware one-time setup command, and design-draft uses the credential-aware 12ui create commands instead of requiring an exported bearer token. Package metadata and documentation links now resolve to public sources.

0.2.19 removes an SDK surface that should never have shipped. 0.2.18 added two package-recovery methods built for one specific conversion, with that customer's identifiers compiled into the published bundle; both methods, their response type, and the API routes behind them are gone. Nothing else in the CLI changes - the methods refused every input but the one they were written for, so no working call can break. Release checks now bind this page to the published version, so a release that forgets its changelog entry fails before it ships.

0.2.18 added those two internal package-recovery methods. Use 0.2.19 instead.

0.2.17 gave every workspace-bearing command a run journal, so 12ui draft, 12ui branch, and 12ui export record what they did and where they put it, and a later command can read that instead of guessing. Refusals became typed rather than prose, so a caller can tell a disproven attachment from an expired run without matching on message text, and a usage error now prints without a credential check first - a missing flag says so instead of demanding an API key it never needed.

0.2.16 took 12ui skill install to all six supported agents. Claude Code, Codex, Grok, Cursor, Antigravity, and Copilot each receive the same skill bundle from one run - one user-scoped home per agent, byte-identical text everywhere - and an agent that is not on the machine is reported as a skip, never an error; 12ui skill status --json names the skipped clients. The skill frontmatter now parses under strict YAML readers, conversion receipts live in your 12ui home instead of beside your images, and a draft retry continues the dead run's directory rather than starting a sibling.

0.2.15 made 12ui branch fast and legible. Pages convert in parallel (bounded, --page-concurrency), each page starts converting as soon as its own screens land, and an approved winner's conversion is reused instead of re-bought when a receipt proves those exact bytes already converted - a refused reuse costs one silent retry, never the page. Progress reads honestly while you poll: viewport counts, running children, and time-in-stage keep advancing even while a percent holds, and 12ui branch status reports per-package progress. 12ui convert package --template prints the manifest template.

0.2.14 moved the design pipeline's mechanics out of prose and into commands: 12ui draft runs the whole explore step (its own run directory, corpus search, four steered candidates), 12ui select records the choice, 12ui branch execute <run-dir> grows the chosen screen into a page or site, 12ui create claims and dispatches hosted generation, and 12ui export derives its idempotency key.

0.2.13 made image generate-batch crash-safe: candidates are materialized atomically, a generation.complete.json sentinel publishes the terminal result, and --resume recovers an interrupted batch without buying any candidate twice.

0.2.12 added convert --export html - one command that converts and exports responsive HTML together - along with streamed stage progress and duration hints on the long conversion commands.

0.2.11 added the 12ui cli command family and renamed the drafting skill design-create to design-draft.

Earlier releases lack only those changes; every other command, flag, and default on this page is identical back to 0.2.9.

Paid work is metered the same way whichever surface calls it. See pricing for rates and the free daily allowance.