@12ui/design 0.2.20 → 0.2.21

package/skills/design-branch/SKILL.md

@@ -16,7 +16,8 @@ One approved screen fixes the visual system; branching extends it across the
 rest of the surface with consistent, professional quality instead of
 re-deriving the design once per screen. The server plans the screens and
 their dependencies; one command executes the whole plan and keeps every paid
-screen addressable, so a retry never repeats paid work.
+screen addressable, so a retry never repeats paid work. Use it whenever the
+deliverable is more than one viewport; a single fold is a plain convert.
 
 ## 1. Execute
 
@@ -27,25 +28,20 @@ screen addressable, so a retry never repeats paid work.
 The run directory is the one `12ui draft` printed; the starting design is
 the candidate `12ui select` recorded there. `--scope page` grows that screen
 into viewports 2..n of its own page; `--scope site` adds sibling routes and
-app states as well. The server plans 2-8 screens (`--max-screens` trims the
-plan). `--convert html` converts each finished page as one ordered package;
-omitting it stops at downloaded PNGs.
-
-To start from something else, pass a fresh directory plus exactly one of
-`--winner-run crt-<id> --winner-slot <slot>` — an earlier hosted candidate,
-whose bytes never leave the server — or `--winner-image <file>` with a PNG,
-JPEG, or WebP. The starting design is viewport 1 of the first page; it needs
-no separate conversion.
+app states as well. `--convert html` converts each finished page as one
+ordered package; omitting it stops at downloaded PNGs. A run with no draft
+behind it takes a fresh directory and names its own starting design — the
+command refuses with both spellings if none is given. Either way the starting
+design is viewport 1 of the first page; it needs no separate conversion.
 
 ## 2. Follow
 
-    12ui branch status <run-dir>
+    12ui next <run-dir>
 
-Execute returns immediately and the run continues on its own (typically
-5–15 min, up to ~30 for large runs; add `--wait` to block instead).
-Status reports per-screen progress
-and the next action. `12ui branch resume <run-dir>` continues an interrupted
-run, replaying already-settled screens for free.
+Execute returns immediately; `12ui next` reports progress and the one command
+to run next, and `--wait` blocks instead of polling.
+`12ui branch resume <run-dir>` continues an interrupted run, replaying
+already-settled screens for free.
 
 ## 3. Collect
 

package/skills/design-convert/SKILL.md

@@ -21,13 +21,8 @@ fidelity, faster and truer than recreating the design by hand.
     12ui convert <source-image> --export html
 
 Converts the image to a LayerDoc and exports responsive HTML alongside it in
-one blocking command (~5 minutes, progress streamed to stderr; ~4 minutes
-without `--export html`). `--model fast|standard|pro` and
-`--width <intended-css-px>` steer the conversion; `--out` and `--export-out`
-place the artifacts. The result JSON carries the conversion under `id` and
-the export under `export.id`. If the export half fails, the LayerDoc is
-still written — retry only the export with
-`12ui export <id> --output html`.
+one blocking command, which is faster than converting and then exporting.
+The result carries the conversion under `id` and the export under `export.id`.
 
 ## 2. Export more formats
 
@@ -35,11 +30,11 @@ still written — retry only the export with
       --out-dir <dir> --idempotency-key <stable-key>
 
 Derives further formats from the finished conversion without repeating
-extraction; independent exports run in parallel, and every format except
-`html` takes seconds to about a minute. Outputs: `html`, `html_fixed`,
-`svg`, `png`, `jpg`, `webp`, `pdf`, `psd`, `pptx`, `sketch`, `web_project`,
-`app_project`. Reusing the same key replays a finished export instead of
-buying it again. Project outputs take a profile matching the target project:
+extraction, and independent exports run in parallel. Outputs: `html`,
+`html_fixed`, `svg`, `png`, `jpg`, `webp`, `pdf`, `psd`, `pptx`, `sketch`,
+`web_project`, `app_project`. Reusing the same key replays a finished export
+instead of buying it again. Project outputs take a profile matching the
+target project:
 
     --web-profile '{"version":1,"framework":"react","styling":"tailwind","language":"typescript","packaging":"page"}'
     --app-profile '{"version":1,"framework":"expo","styling":"native","language":"typescript","packaging":"screen"}'
@@ -59,9 +54,9 @@ relative to the manifest; independent routes are separate page entries:
         { "id": "a", "image": "screens/a.png" },
         { "id": "b", "image": "screens/b.png" } ] } ] }
 
-Runs ~5-8 minutes, writing `<out-dir>/<page-id>.html` per page plus
-`package.result.json`. A viewport may carry `"sourceConversionId": "<id>"`
-to reuse an already succeeded conversion of the same bytes for free.
+Writes `<out-dir>/<page-id>.html` per page plus `package.result.json`. A
+viewport may carry `"sourceConversionId": "<id>"` to reuse an already
+succeeded conversion of the same bytes for free.
 
 ## 4. Integrate
 

package/skills/design-draft/SKILL.md

@@ -12,49 +12,30 @@ description: "Required to draft candidate interface designs through the
 
 For a public-directory install, run `npx -y @12ui/design skill install --skill design-draft` once. It pins the CLI and verifies this skill's account scopes.
 
-Buy one small set of candidate designs and keep every one addressable. This
-uses the hosted create API through credential-aware `12ui create` commands —
-not the local `12ui draft` command, which runs a four-candidate version of the
-same flow. Use it for more slots, per-slot references, or tighter direction
-control.
-
-## 1. Claim the run
-
-    12ui create claim \
-      --concept "<product, audience, surface, goal, personality>" \
-      --aspect landscape \
-      --candidates '[
-        {"slot":"a","direction":"<short direction>"},
-        {"slot":"b","direction":"<short direction>",
-         "referenceId":"gen-<corpus-id>"}
-      ]'
-
-Use `--candidates @candidates.json` for a long list. The concept is at most 600
-characters. One run holds 1–96 candidates in slots `a`–`cr`, with one aspect:
-`landscape` (1536x1024), `portrait` (1024x1536), or `square` (1024x1024).
-Each candidate has a meaningfully different direction and at most one corpus
-`referenceId`. Alternatively, add `--reference-image <png|jpeg|webp>` and set
-`"useReferenceImage":true` on the slots it should guide. `--mode
-preserve-structure` keeps that image's layout; the default is `inspiration`.
-
-The command derives a stable idempotency key from the request, claims the run,
-and prints its `id`. Claiming buys nothing.
-
-## 2. Dispatch every slot
-
+Buy one small set of candidate designs and keep every one addressable. Use
+this when the run needs more than the four candidates `12ui draft` produces
+in one step, a corpus reference or direction per slot, or tighter control
+over what each slot explores.
+
+    12ui create claim --concept "<product, audience, surface, goal, personality>" \
+      --candidates '[{"slot":"a","direction":"<short direction>"},
+                     {"slot":"b","direction":"<short direction>",
+                      "referenceId":"gen-<corpus-id>"}]'
     12ui create dispatch <run-id>
-
-Dispatches all unsettled slots concurrently and blocks until they return (up
-to about 2.5 minutes each). Add `--slot a,b` to select slots. A failed
-candidate is a settled, paid outcome. If the command is interrupted, generation
-continues; do not claim another run.
-
-## 3. Follow and download
-
-    12ui create status <run-id>
     12ui create download <run-id> --out-dir <directory>
 
-Status reads durable run state. Download writes every succeeded PNG; add
-`--slot a,b` to select slots. Runs expire seven days after the claim. A winner
-can seed `12ui branch execute --winner-run <run-id> --winner-slot <slot>`
-without re-uploading its bytes.
+Each command prints the next; `12ui next <run-id>` reports what is still
+generating, and `--wait` blocks until every slot settles.
+
+The judgement is the brief and the slots. One aspect covers the whole run —
+`landscape` (1536x1024), `portrait` (1024x1536), `square` (1024x1024) — and
+directions must be meaningfully different from each other, since four
+paraphrases of one idea buy four of the same design. A slot takes at most one
+reference: `referenceId` names a corpus reference, or `"useReferenceImage":
+true` conditions it on the run-level `--reference-image`, whose
+`preserve-structure` mode keeps that image's layout. A run holds 1-96
+candidates in slots `a`-`cr` and expires seven days after the claim.
+
+A candidate that comes back `failed` is a settled, paid outcome rather than a
+transient error. A winning candidate seeds a branch run as
+`--winner-run <run-id> --winner-slot <slot>` without re-uploading its bytes.

package/skills/design-search/SKILL.md

@@ -16,8 +16,7 @@ The corpus has already explored, ranked, and diversified the design space,
 so retrieval returns real reference images in a considered order rather than
 another model's guess. Use it when the references themselves are the
 deliverable — surveying a space, gathering comparators, or conditioning work
-you drive yourself. (`12ui draft` already runs this retrieval when drafting
-designs.)
+you drive yourself. `12ui draft` already runs this retrieval when drafting.
 
 ## 1. Search
 
@@ -25,11 +24,9 @@ designs.)
       --query "<product, audience, surface, goal, personality>" \
       --out-dir .12ui/<slug>/references
 
-Retrieves four diverse references (`--count <n>`, up to 48), downloads the
-full images into the output directory, and writes `manifest.json` — the
-completion record with the ranked order, reference IDs, and hashes. Blocks
-~20-40 seconds with progress on stderr. Preserve the returned order; the
-ranking is the product.
+Downloads the full images into the output directory and writes
+`manifest.json` — the completion record with the ranked order, reference IDs,
+and hashes. Preserve the returned order; the ranking is the product.
 
 `--mode direct|balanced|adventurer` trades literal query adherence against
 exploration; `balanced` is the default. For a redesign,