@12ui/design 0.2.75 → 0.2.77

package/skills/12ui-design/scene.md

@@ -1,172 +1,43 @@
 # Rebuild a design image as a live 3D scene
 
-Use this when asked to recreate a design or concept image (hero shot, product on a surface, landing-page render,
-illustrated scene) as a live Three.js scene with real geometry, materials, light and a few interactions, not a
-projection of the picture. Solve the camera from landmarks, model the objects, then check the result from the source
-camera and from 15 degrees either side. Everything runs on this machine through `12ui scene`: no account, no model
-call, no network. `12ui scene --help` lists the tools and `12ui scene <verb> --help` explains each one.
+Real geometry and light, the page as real HTML over it, 2-3 clicks and drag orbit. `12ui convert` builds the page layer in the background while you model the scene; then merge the two, render and fix. `12ui scene <verb> --help` explains each verb.
 
-## The rule
+- **Model the objects.** The source goes on geometry only as a flat printed surface (a screen, a label, a poster).
+- **Page text stays the converted HTML.** Do not rebuild its text, buttons, logo or fonts yourself.
+- **Hold at +-15 degrees.** No object turns into a card, no floor smears, no edge opens.
 
-- **Model the objects.** Boxes, slabs, lathes, extrusions, instanced detail, procedural textures, physical materials,
-  real lights and shadows. If it is solid in the picture it is solid in the scene.
-- **Use the source image only as a reference** for colour, layout and mood, and as a texture on **flat printed things**
-  (a screen, a label, a poster, a sleeve print). Never paint the whole picture onto geometry, and never bake shading
-  or a reflection into a texture that should be lit.
-- **It must hold at +-15 degrees and beyond.** You are trading some landing-view exactness (proportions, exact colour,
-  a display font) for a scene that is real from every angle. That is the point. Say so in your report.
-- **Everything is modelled procedurally.** There is no image-to-mesh step: a box, lathe, extrusion or instanced
-  field covers the objects a design image shows.
-- Budget 12 to 20 render passes. Stop when passes stop improving the worst mismatch.
+**1. Start.** Run this first, in the folder with `source.png`. Convert's `auto` engine uses Codex when it is ready and the 12ui API otherwise. `convert-run` must be a new folder: a retry uses a new name. `serve --detach` prints a pid: stop that server only with `kill <pid>`.
 
-## Setup (once)
+    nohup 12ui convert source.png --output html --engine auto --out-dir convert-run > convert.log 2>&1 < /dev/null &
+    12ui scene init .
+    12ui scene serve . --port <port> --detach
 
-Work in one folder, with the source image copied into it:
+**2. Camera: solve once.** Pick 6-8 landmarks, corners of clearly rectangular objects read to the pixel, at least one off the main plane. Write `spec.json` (format in `12ui scene solve --help`), run `12ui scene solve spec.json --out cam.json`, paste its `camera.js` line into `camera.js` and set `PIVOT` to the subject centre. rms 1-4 px is good; fix one misread landmark or pin fov at most once, then accept it. If the output starts with `degenerate`, do what its first warning says. Place objects by ray or rect, not by eye: `12ui scene ray cam.json --plane-y 0 u,v` lands an object's base on the ground; `12ui scene rect cam.json --corners "TLu,TLv;TRu,TRv;BRu,BRv;BLu,BLv" --plane-y 0` poses a flat rectangle.
 
-    12ui scene init <scene-dir>
-    12ui scene serve <scene-dir> --port <port>
-
-`init` writes the starter (`index.html`, `camera.js`, `scene.js`, `lib.js`, `gobo.js`, `main.js`) and three.js r186 in
-`vendor/` (no build step, an importmap), and refuses to overwrite anything already there. `serve` binds 127.0.0.1 and
-prints its PID; stop it by that PID when done, never by a name pattern.
-
-The starter already gives you the renderer, tone mapping, the solved camera, a contain-fit frame, orbit about a pivot,
-click-to-toggle actions, and the capture contract (`window.__ready`, `window.__scene.{actions,setOrbit,setAction,reset,render}`).
-`buildScene(scene, renderer, camera)` gets the renderer (PMREM env maps) and camera (gobos, overlays).
-You write `scene.js` (split into modules by object once it grows: `box.js`, `floor.js`, `textures.js`, `actions.js`).
-Page text and buttons are real DOM inside `#stage`, positioned in source pixels.
-
-## 1. Camera first
-
-Everything else is placed through the camera, so solve it before modelling anything.
-
-1. Read the source at full size. Pick **6 to 8 landmarks**: corners of the most clearly rectangular objects (a box, a
-   screen, a table edge, a sleeve, a book), read to the pixel. Include at least one landmark off the main plane, or
-   the field of view is ambiguous. Read them yourself from the image; zoom crops help. If a landmark residual is
-   large later, you misread it.
-2. Write `spec.json` and solve (`12ui scene solve --help` has the format). World coordinates are yours: choose a
-   unit (an object height of 1, or a floor at y = 0), let unknown dimensions be `free`, pin a scale with `"fix"`.
-
-       12ui scene solve spec.json --out cam.json
-
-   rms should be 1 to 4 px. Roll is pinned to 0 unless you set `"solve_roll": true`. Read the `warnings` and
-   `fovSensitivity`: flat-lay and table shots are near top-down and coplanar, where fov is not determined by
-   landmarks. Pin it (`"fix": {"fov": 35}`; 20-30 product shot, 35-50 normal, 60+ wide) or add an off-plane landmark
-   such as an object's top edge above its base. A non-square object of unknown depth: fix its width, `free` its depth.
-3. Paste the printed `camera.js` line into the starter's `camera.js` (degrees, same keys as `cam.json`, plus the `clip`
-   near/far, which must stay tight: far/near under about 100). Set `PIVOT` to the subject centre.
-4. **Place objects by ray, not by eye.** Cast the source pixel of an object's base onto the ground plane, or solve a
-   rectangle directly, then check with `project`:
-
-       12ui scene ray cam.json --plane-y 0 836,691 1237,749
-       12ui scene rect cam.json --corners "TLu,TLv;TRu,TRv;BRu,BRv;BLu,BLv" --plane-y 0
-       12ui scene rect cam.json --corners "TLu,TLv;TRu,TRv;BRu,BRv;BLu,BLv" --width 0.6 --height 0.4
-       12ui scene project cam.json 0.1,0,0.3
-
-   `--plane-y` is a rectangle flat on a surface; `--width` and `--height` are a tilted one of known size. Render once
-   with plain grey boxes at the solved positions. If the silhouettes overlay the source, the rest is modelling and
-   light. If not, fix the camera now: nothing downstream repairs it. A rectangle seen from one view is ambiguous in
-   lean versus depth (give `--width` alone to solve the other side); use what you know (it rests on the floor, it
-   leans on the wall) and force draw order when something ends up inside another object.
-
-## 2. Model and material, per object type
+**3. Model, while convert runs.** Leave the page text to convert. Build each object in `scene.js` as the table says. Thin parts get real thickness. Colours: `12ui scene colors source.png --box x0,y0,x1,y1`. Light like the source: one key placed by the shadows, a low fill, `contactShadow` under things; keep textures light. Add 2-3 click actions on separate objects (`apply(t)`, as in the starter `scene.js`); drag orbit is built in.
 
 | Object | Build |
 |---|---|
-| Box, carton, crate, wall, table | `BoxGeometry` with real wall thickness, or five walls plus hinged flaps. Bevel visible edges. |
-| Book, card, drive, phone, laptop deck, sleeve | `slabGeometry(w,h,t,r)` from `lib.js` (rounded extrude, clean cap UVs), a page block and boards for a book. |
-| Cup, jar, bottle, vinyl, bucket, lamp | `LatheGeometry` from a profile you read off the silhouette. Vinyl grooves: concentric bands in a roughness and colour canvas. |
+| Box, carton, crate, wall, table | `BoxGeometry` with real wall thickness, or five walls plus hinged flaps; bevel edges. |
+| Book, card, phone, laptop, sleeve | `slabGeometry(w,h,t,r)` from `lib.js`; a page block and boards for a book. |
+| Cup, jar, bottle, vinyl, lamp | `LatheGeometry` from a profile read off the silhouette. |
 | Logos, rings, outlines, ribbons | `ExtrudeGeometry` of a `Shape`, or a canvas texture if it is printed flat. |
-| Rows of small things (keys, grass, bricks, sand, pins) | `InstancedMesh` with per-instance jitter in scale, rotation, colour. |
-| Terrain, sand, cloth | Displaced plane plus a grain normal or bump map; never a photo. |
-| Flat printed surface | Canvas texture, or the source region rectified (section 4). |
-
-Materials: `MeshStandardMaterial` or `MeshPhysicalMaterial` (clearcoat for lacquer, glass, varnish; roughness map for
-scuffs). Make surface textures procedural on a canvas (`canvasTex`, `grain` in `lib.js`): fibres and speckle for kraft
-or paper, weave for cloth, streaks for brushed metal, value noise for concrete. **Sample the source for colour** before
-you tune: `12ui scene colors source.png --box x0,y0,x1,y1` gives the hex to use; comparing regions against a render
-afterwards gives brightness ratios to correct light, not paint.
-
-Give thin parts real thickness (a sleeve, card or book is 1 to 2 percent of its width, not zero), and keep it consistent
-with the source's shadow length: a long crisp shadow from a thin object means a low light, not a thicker object.
-Glossy discs, lacquer and glass want an environment map, not more lights: `studioEnv(renderer)` from `lib.js`,
-assigned to those materials only.
-
-Light like the source: one key (spot or directional) placed by where the shadows fall, a low hemisphere or ambient
-fill, a warm or cool bounce on the side faces if they read lit. Add `contactShadow` under everything that sits on a
-surface. For a glossy floor use `reflections()` from `lib.js` (mirrored, jittered copies with fade) and a sheen strip;
-planar reflection is often the biggest single win. Window light and leaf shadows: a `SpotLight.map` gobo drawn in
-source-image pixels and resampled through the solved camera, so it lands where drawn and stays real light: the
-starter's `gobo.js` (its header has the recipe and the orientation, which is verified; do not flip anything by hand).
-Volumetric beams: an additive open cone. Use `ACESFilmicToneMapping`, `SRGBColorSpace`, and shadow bias about -0.0004.
-Do not use `PCFSoftShadowMap` (removed in r186).
-
-## 3. Layout and page text
-
-Real DOM for real page text: headline, nav, buttons, body copy, callout labels, in `#stage` at source pixel
-coordinates. Pick the display font by rendering candidate faces at the measured cap height in a strip next to a source
-crop and choosing the closest glyph shapes, then fit the measured line width with a `scaleX` on a span (`data-fit`).
-
-Fonts are local only. Copy a `.ttf`, `.otf` or `.woff2` into the scene folder (from the user's project or an installed
-system font) and load it with `@font-face { src: url(./file.woff2) }`, or use a face that is already installed. Never
-link a hosted font stylesheet: capture blocks it, and its `remote requests blocked` and `fonts:` lines show a missing
-face. Leader lines are SVG whose end dots track 3D anchors (`Object3D.getWorldPosition(v).project(camera)`), so they
-follow the orbit. Never render page text into the 3D scene.
-
-## 4. Screens and app UI
-
-- **Flat and static** (default): flatten the screen quad to a texture, then map it on the screen face of the device
-  slab. Remove painted glare and shadows in the crop, cover any bezel bleed, and light the screen with an emissive map
-  so it reads as lit.
-
-      12ui scene rectify source.png --corners "TLu,TLv;TRu,TRv;BRu,BRv;BLu,BLv" --size 1200x800 --out screen.png
-
-- **Live and editable screens**, only if the user asks for one. Optional, needs network: `12ui convert <crop.png> --output html`.
-  Put the result in a `CSS3DRenderer` layer (`vendor/addons/renderers/CSS3DRenderer.js`) with the same camera, or as
-  an iframe texture; keep the rectified crop as the offline default in the report.
-- A wall of screens, a dashboard, cards on a wall: same recipe per screen, one rectified crop each.
-
-## 5. The self-review loop (this is the work)
-
-After every pass, render and compare:
-
-    12ui scene capture http://127.0.0.1:<port>/index.html --out-dir shots/i01 --size 1536x1024
-    12ui scene sheet source.png shots/i01/landing.png shots/i01/az-15.png shots/i01/az+15.png --out shots/i01/sheet.png
-    12ui scene blend source.png shots/i01/landing.png --out shots/i01/blend.png
-    12ui scene colors source.png shots/i01/landing.png --exclude "x0,y0,x1,y1;x0,y0,x1,y1"
-
-`capture` writes `landing`, `az-15/-10/+10/+15` and `act-<name>` (each action at t = 1), then prints
-`remote requests blocked: N`, `fonts: N loaded, M failed` and any console errors. A blocked count above 0 is a defect:
-the scene reached for something off this machine; make it local. If capture reports that Chromium is missing, run the
-install command it prints once, then retry. Custom views: `half=0:0:lid=0.5` (name=azimuth:elevation:action=t,...).
-Debug an object with `--hide vinyl` (name substring; name your groups), `--eval "js"`, `--size 900x600` for fast passes.
-
-`colors` lists the worst cells of a grid; `--exclude` the boxes covered by DOM text (or `--exclude-dom boxes.json`),
-or the text cells read as error. `--region "name:x0,y0,x1,y1;name:x0,y0,x1,y1"` compares named regions instead.
-
-Open the sheet and the blend (source, render, 50 percent overlay, difference) and look. Fix the **single largest
-mismatch** in this order: camera and silhouettes, object proportions, light direction and value, colour, then texture
-detail. Log one line per pass (what looked wrong, what you changed). Look at `az-15` and `az+15` every time: if an
-object turns into a card, a floor smears, or an edge opens, that is a real defect the landing view hides. Stop when
-the biggest gap left is texture realism. Headless software GL is slow (a few fps); do not chase framerate, but keep
-triangle counts sane (under about 500k) and do not run 9-tap reflections on everything.
+| Rows of small things (keys, grass, bricks) | `InstancedMesh`, jittered per instance in scale, rotation, colour. |
+| Terrain, sand, cloth | Displaced plane with gentle, low-frequency relief plus a grain bump map; never a photo. |
+| Flat printed surface | Canvas texture, or the source region flattened with `12ui scene rectify`. |
 
-## 6. Interactions
+**4. Merge, when convert is done.** Run `12ui scene merge convert-run .`. It reads the run the way its engine wrote it, puts the page's styles in `<head>` and its body in `#stage` at the source frame, copies the files the page uses, and lists its images, with the source box `x0,y0,x1,y1` where the run declares one. While convert is still running it says so and writes nothing: keep modelling and merge later. Then:
+- Run it again with `--drop <image>,...` naming the image(s) the 3D scene replaces; it removes every `<img>` and `url()` using them. Each merge replaces the last one, edits inside it included, so do the steps below after it.
+- In `index.html`, clear the background of the box that held the 3D image and of any wrapper over the 3D area, so the canvas under `#stage` shows through. Panels over flat page area keep theirs.
+- Capture blocks remote fonts. If merge printed `fonts:`, fetch them and point the page at the local copy:
 
-Two or three, each on a **separate object**, each a pure function `apply(t)` of `t` in 0..1 (the starter's `actions`
-registry, click a mesh to toggle, ease in and out): a **hinge** (lid, flap, cover, door: a Group at the hinge line,
-rotate it), a **lift** (book, cup, card: translate along its own up axis with a small tilt), a **slide** (drive, paper,
-drawer: translate along its own axis, optionally rotate slightly). Optional small extras: a lit-to-dark toggle,
-a bucket tipping upright. Also give pointer-drag or arrow-key orbit clamped to +-15 degrees, and one or two labelled
-buttons in `#stage` that call `__scene.toggle(name)`. Verify with a real click in the headless page as well as
-`setAction`, and capture each action at t = 1 from the landing camera.
+      mkdir -p fonts && grep -o 'https://fonts.googleapis.com/[^"]*' index.html | xargs curl -s > fonts/fonts.css
+      for u in $(grep -o 'https://fonts.gstatic.com/[^)]*' fonts/fonts.css); do curl -s "$u" -o "fonts/${u##*/}"; done
+      perl -pi -e 's#https://fonts.gstatic.com/[^)]*/##' fonts/fonts.css
+      perl -pi -e 's#https://fonts.googleapis.com/[^"]*#fonts/fonts.css#' index.html
 
-## 7. Report
+If convert fails, or merge says it stopped, recover it as the CLI prints: `12ui next convert-run`, then the `12ui resume` it names. If convert still fails, report that it failed and stop.
 
-Say what you built (objects, interactions), the camera rms and worst landmark, how many render passes, the paths of
-the contact sheet and captures, the capture's `remote requests blocked` and `fonts:` lines, and the remaining gaps
-against the source (fonts, texture realism, proportions). Do not claim a pixel match; claim a real scene that reads as
-the source from the landing camera and holds at +-15 degrees.
+**5. Check.** Run `12ui scene capture http://127.0.0.1:<port>/index.html --out-dir shots/i01 --orbit=-15,15` (a new `shots/iNN` each time) and look at `landing`, `az-15` and `az+15`; `remote requests blocked` above 0 is a defect. Fix the biggest mismatch first (placement, silhouettes, light, colour) and capture again. Stop when landing reads as the source and +-15 holds.
 
-Ports and processes: use only the ports you were given; stop your servers by the PID `serve` printed; never kill by
-name pattern. Keep output small: `init` copies three.js once per scene folder, and captures go under `shots/`.
+**6. Report** in two lines: the URL and what you built (objects, interactions); the landing capture path and what still differs.

package/skills/12ui-design/session.md

@@ -1,161 +0,0 @@
-# Persistent local workflow
-
-Use one local workspace for related work. The CLI and MCP share the same operation service; choose whichever is available. Neither preparation nor artifact import needs a 12ui account. A session handoff lets this conversation use its native tools without extracting credentials or launching a nested coding agent.
-
-## Prepare and import
-
-Import an existing reference once:
-
-    12ui workflow import <image.png> --workspace <workspace> --media-type image/png --role reference
-
-Use an absolute source path when the file is outside the workspace. Relative imported paths resolve inside the workspace, not the shell's current directory. The returned artifact identifies stored bytes by path, hash, size and media type. Put returned artifact objects in the request's `inputs`; do not invent hashes or use expiring remote URLs as durable input identities.
-
-Write a request JSON file. A new design direction can start with:
-
-```json
-{
-  "capability": "image",
-  "prompt": "Design an editorial architecture homepage with warm materials, clear project navigation and restrained typography. Use the attached references as visual context.",
-  "inputs": [],
-  "output": { "kind": "image" }
-}
-```
-
-    12ui workflow prepare <request.json> --workspace <workspace> --key <stable-operation-key>
-
-Preparation returns the persistent operation ID. Reusing the same key with the same request recovers that operation; changed intent needs a new key. Use separate operations for candidates, selected-page expansion, image edits, labels and implementation so dependent work can reuse verified outputs.
-
-`text`, `image`, `image-edit`, `code` and `convert` are distinct capabilities. Output kinds are `json`, `image`, `html` and `project`; JSON may include an output schema. Keep provider credentials, environment dumps and private authentication state out of prompts, parameters and result files.
-
-## Execute in the current session
-
-    12ui workflow execute <operation-id> --workspace <workspace> --providers session --session-capabilities image
-
-Declare the capability of this request only after confirming its tool is available. For an image edit use `image-edit`; for implementation use `code`. A session route returns a handoff with the frozen prompt, input artifacts, expected output, public parameters, work/evidence directories and `attemptNumber`. Keep that attempt number with the returned result or failure; it prevents an old session from settling a newer attempt. Use its selected project directory for implementation; do not edit a different project. This claims the operation before generation. Execute it once using the available native tool, preserve its returned output, and register that output. Do not mistake the handoff for a generated result.
-
-Write a result JSON file using actual existing local files:
-
-```json
-{
-  "files": [
-    { "path": "/absolute/generated-image.png", "mediaType": "image/png", "role": "candidate" }
-  ]
-}
-```
-
-For structured text, use `value` with the requested JSON object. Include `providerRequestId` and `usage` only when actually supplied by the provider; do not estimate missing quota or image price from an account-wide percentage.
-
-    12ui workflow register <operation-id> --workspace <workspace> --attempt <handoff-attempt-number> --result <result.json>
-    12ui workflow status <operation-id> --workspace <workspace>
-
-Registration copies and hashes file artifacts. Use the registered artifacts as inputs to the next prepared operation. Continue from this stored state after a restart, conversation change or executor change. Registration and schema validation establish an artifact contract, not visual approval; inspect the image/browser before accepting it for dependent work.
-
-For an `implement` operation, the service records a baseline of the explicit `projectCwd` before the handoff. Make the actual changes in that project, then register a normal result with `value` containing your report and optional `files` for real additional receipts. Registration compares the project with its saved baseline and adds verified project-change evidence and changed-file artifacts automatically. Do not fabricate that evidence JSON or use a provider receipt as proof of implementation. No changed files produces `project_no_changes`; a claimed no-op is not a successful implementation. Report actual browser/test checks separately: verified file changes do not prove those checks passed, and the service does not invent validation evidence.
-
-For a successful recipe plan, prepare its dependent operations deterministically:
-
-    12ui workflow continue <plan-operation-id> --workspace <workspace>
-
-Continue returns `readyOperationIds`, children, verified artifacts and waiting/blocked state. It does not execute models. Execute each ready operation with the intended provider policy, register its result, then continue the same parent plan again. Draft continuation creates candidate image operations; branch continuation unlocks later slots only after their actual dependency artifacts exist. A redesign plan continues to a draft plan, then to its candidate images. Repeated continuation reuses child IDs. Generic prepared requests have no recipe expansion; prepare their next dependent operation explicitly from registered artifacts.
-
-## Provider selection and cost
-
-    12ui workflow capabilities --session-capabilities text,image,image-edit,code
-
-Only declare the subset actually available. Without a session image tool, a Codex or Claude text CLI is not an image provider. Default routing considers session, Codex, Claude, OpenAI and 12ui in order, filtering for the requested capability and explicit funding permission. Limit `--providers` when a particular execution boundary is required.
-
-Subscription execution consumes the user's model allowance and local resources. OpenAI API execution requires its key and authorization; 12ui execution requires its service credentials and authorization. Set `--allow-paid openai` or `--allow-paid 12ui` only when the user has authorized that provider's spend for this work. A configured key alone does not authorize either. Preparation does not imply authorization for later paid fallback.
-
-The OpenAI adapter requires an explicit account-available model: set public `parameters.model` on a generic request, or use `OPENAI_MODEL` for text/generated HTML and `OPENAI_IMAGE_MODEL` for images. `OPENAI_API_KEY` and `TWELVE_UI_API_KEY` identify separately funded routes; never put keys in requests or results. Native subprocesses remove API-key/provider overrides from their environment. Codex text/code execution is unavailable unless the user trusts their existing CLI configuration, including configured tools and hooks: pass `--trust-codex-config` on execution or discovery only with that authorization. Its read-only text sandbox does not isolate remote tool effects. This opt-in is independent of paid-provider authorization and is unnecessary for the current session's tools. Claude uses supported safe mode, empty MCP configuration and a fixed file-tool set for code; it cannot run shell tests, and its text path currently rejects image attachments. Run project checks in the parent session. Use the session for visual planning, labels and review when it can inspect images. OpenAI code produces HTML without running a project; 12ui code uses its conversion path. Neither is an implementation executor for an existing project.
-
-An unavailable provider can be skipped before dispatch. After a dispatch, a failure is not permission to buy the same work elsewhere. Follow the saved failure disposition: only a recorded proof of non-dispatch or a terminal no-output failure can make another provider eligible. An ambiguous outcome stays in reconciliation; preserve it and recover the actual result before any new dispatch. Do not clear state, change the key or repeatedly execute a handoff to work around this boundary.
-
-If a session tool refuses, is denied permission or has an uncertain outcome, preserve that evidence and record a failure JSON containing `code`, `message` and `disposition`:
-
-    12ui workflow fail <operation-id> --workspace <workspace> --attempt <handoff-attempt-number> --failure <failure.json>
-
-Use `terminal-stop` for refusals or permission denials and `ambiguous` when dispatch/output is uncertain. Neither permits fallback. Use `not-dispatched` or `terminal-no-output` only with actual evidence establishing that outcome; elapsed time, a missing screenshot or a new session is not proof. An ambiguous operation can be completed by registering its recovered original result, not by downgrading the failure to enable another call.
-
-An accepted hosted job with a failed download, or a completed response whose output is malformed, remains in reconciliation under its original operation and attempt. Recover the original provider output and dependencies, validate them and register them against that same attempt. Keep provider IDs and retained responses; do not regenerate or switch providers to repair a delivery failure. Refusals and permission denials remain terminal stops.
-
-## Recipes and MCP
-
-Workflow recipes prepare the same persistent operations. They are request builders, not a hosted pipeline or a guarantee that images/code have already been generated.
-
-| Recipe | Input JSON | Prepared work |
-| --- | --- | --- |
-| `draft` | `concept`, optional `candidates`, `references`, `retain`, `content`, `aspect` | Text plan of distinct candidate prompts; continue it to prepare image operations. |
-| `branch` | `concept`, approved `source`, optional `scope`, `maxScreens`, `references` | Text plan of pages and ordered viewport slots; preserve the existing root and generate only additional slots. |
-| `edit` | `source`, `prompt`, optional `references`, `quality` | Image edit of the first source. |
-| `redesign` | `source`, `direction`, optional `references` | Text concept/retain/corpus-query plan; image generation and implementation are subsequent operations. |
-| `labels` | `source`, optional `context` | JSON labels and proposed interactions; not working behavior. |
-| `review` | `source`, optional `target`, `context`, `criteria` | Evidence-based visual findings and limitations; no numeric quality score, runtime verification or automatic repair. |
-| `convert` | `source`, optional `prompt`, `output`, `native` | Editable HTML/code by default. LayerDoc requires explicit native conversion and its supported provider. |
-| `implement` | absolute existing `projectCwd`, `targets`, optional `prompt` | Code changes in that selected project; preserve source changes and verify real behavior. |
-
-Image paths inside recipe JSON and file paths inside result JSON are relative to the workspace unless absolute. The JSON specification/result file passed to the CLI itself is read relative to the shell's current directory. For example, save `{"concept":"An editorial architecture homepage","candidates":4}` as the draft specification:
-
-    12ui workflow draft <draft-spec.json> --workspace <workspace> --key <draft-plan-key>
-
-Execute that operation with a text-capable session, register the JSON plan, and continue it to obtain stable candidate operation IDs. Inspect candidate images before selecting one for branch or implementation. Check installed help before relying on optional fields; generic `prepare` remains available for an explicit request.
-
-## Capture, review and portable output
-
-Capture a running local or public page with local Chromium:
-
-    12ui workflow capture <http-or-https-url> --workspace <workspace> --width 1440 --height 900 --full-page
-
-This stores screenshot, DOM and manifest artifacts without model work. It uses a fresh unauthenticated browser, not the user's signed-in browser profile. Inspect `requestedUrl`, `capturedUrl` and `redirected` plus the actual image before treating it as application evidence. For an authenticated interface, capture with an available authorized session browser and import that screenshot instead. Chromium must already be available locally.
-
-Prepare a review specification with current screenshot `source`, optional approved `target` and `criteria`:
-
-    12ui workflow review <review-spec.json> --workspace <workspace> --key <review-key>
-
-Execute and register its findings like any text operation with image inputs. A screenshot review cannot prove route behavior, accessibility-tree semantics or tests. Use actual browser and project tools for those checks; prepare only justified corrections after inspection.
-
-For session-generated HTML, register the entrypoint and every asset with their original relative paths. For example:
-
-```json
-{
-  "files": [
-    { "path": "/absolute/generated/index.html", "mediaType": "text/html", "role": "entrypoint", "relativePath": "index.html" },
-    { "path": "/absolute/generated/assets/style.css", "mediaType": "text/css", "role": "asset", "relativePath": "assets/style.css" }
-  ]
-}
-```
-
-Preserve image, font, script and stylesheet mappings; copying only the HTML can break its references. The SDK's `collectBundleFiles(directory, entrypoint)` returns mapped file entries for an isolated generated-output directory; register those entries through the same operation service. Never collect a whole existing project checkout or credential directory. Project changes stay in the selected project; provider receipts alone are not a portable project.
-
-    12ui workflow export <operation-id> --workspace <workspace> --destination <new-output-directory>
-
-Export verifies stored bytes and retains the logical paths. A new or empty directory is required; an identical previous export is reused and differing existing files are refused. Export does not execute a model, convert to another native format, publish a site or validate browser behavior.
-
-## Prototype interaction labels
-
-For an existing converted branch, prepare labels from its actual DOM candidates and known destinations:
-
-    12ui prototype <run-dir> --labels workflow --workspace <workspace>
-
-This performs local browser inventory/analysis and returns `awaiting_labels` with stable operation IDs. It does not dispatch a model or read hosted credentials. Execute each prepared operation through the shared workflow service with an available text provider, then register its JSON using the handoff's attempt number. For a dispatched/reconciling operation, recover its existing result instead of executing again. Repeat the same prototype command once those operations succeed; it consumes the exact completed results and runs the normal build/runtime gates. Legacy branch resume will not replace an `awaiting_labels` pause with hosted label calls.
-
-These operations freeze the real candidate IDs, screen, destinations and source HTML/plan/completion evidence. Generic image `workflow labels` annotations cannot be substituted. Each candidate requires exactly one supported action; unknown navigation targets, duplicate IDs and contradictory payloads are rejected before success. Ambiguous controls should be `none`; local-page outputs permit only navigation to known real pages or `none`. Existing links/forms and deterministic rules retain precedence. A prototype dialog demonstrates behavior; it does not execute a backend task.
-
-For converted branches, a semantic dropdown may label any evidenced menu trigger, regardless of its analyzer kind. Registration preserves the supplied option strings. The existing builder normalizes and deduplicates them; fewer than three usable choices produce an inert control with a recorded `dropdown_options_incomplete` degradation.
-
-The prototype manifest records source custody, operation IDs, provider, funding and reported usage. Its label `costMicros` counts only new hosted prototype-label calls; zero there does not imply free workflow model execution. Repeating preparation or moving the saved branch/workspace preserves IDs when the bound source content and candidate facts are unchanged. The source binding covers HTML, plan, completion and candidate facts, not a snapshot of every remotely linked asset.
-
-Standalone prototype still defaults to `--labels none`. Explicit `--labels 12ui` selects the older hosted per-screen route; it is separate from these local workflow operations.
-
-## Verified native LayerDoc
-
-Native LayerDoc registration requires a canonical public LayerDoc v2 document with role `layerdoc` and `relativePath: "document.layerdoc.json"`, a role `layerdoc-assets` sidecar mapped to `layerdoc-assets.json`, and every referenced raster as a mapped role `asset` file. The sidecar uses schema `12ui.layerdoc-assets.v1`; its `assets` maps each canonical `artifactId` to `{path, sha256, mediaType}`. Paths identify retained local bytes. All files need portable relative mappings, and hashes, media types and declared pixel dimensions must agree with those bytes. Keep canonical artifact identities; do not insert invented URLs or relabel arbitrary JSON as LayerDoc.
-
-Read a completed native operation locally:
-
-    12ui workflow layerdoc <operation-id> --workspace <workspace>
-
-The SDK equivalents are `loadWorkflowLayerDoc({workspace, operationId})` and, for a relocated exported directory, `loadLayerDocBundle({directory})`. They return the canonical `document`, absolute `documentPath` and `manifestPath`, plus `assets` keyed by artifact ID with verified local `path`, `relativePath`, `sha256` and `mediaType`. Raster dimensions are validated against the document. This is a verified local reader contract, not an offline editor or a new conversion.
-
-The standard hosted `12ui convert <layerdoc.json>` path does not consume this sidecar bundle. It requires supported hydrated HTTP asset references; uploading local assets and hydrating those references needs a separate API path that is not supplied by the reader. Do not upload the raw canonical JSON alone and claim its local assets will follow.
-
-The MCP equivalents are `design.workflow.prepare`, `design.workflow.execute`, `design.workflow.register`, `design.workflow.continue`, `design.workflow.fail`, `design.workflow.status`, `design.workflow.import`, `design.workflow.capabilities`, `design.workflow.capture`, `design.workflow.export` and `design.workflow.layerdoc`. Recipes use `design.workflow.prepare` with `recipe` and `input`; registration and failure use the handoff's `attemptNumber`. MCP execution and discovery accept `trustCodexConfig` for the same explicit Codex configuration trust boundary. Use the tool's supplied schema. They call the same service and obey the same provider authorization, custody and reconciliation rules as the CLI. Do not log into 12ui merely to prepare, inspect or register local operations.