@12ui/design 0.2.11 → 0.2.13

package/skills/design/references/selection-contract.md

@@ -66,7 +66,13 @@ prompt text so a resumed run cannot silently select different evidence.
       "rejectionReasons": []
     }
   ],
+  "recommendation": {
+    "candidateId": "<recommended candidate id, or null when the run indicated none>",
+    "source": "<where the recommendation came from, or null>"
+  },
   "winner": "A",
+  "selectionSource": "<recommended|override|no-recommendation>",
+  "selectionOverrideReason": "<why the recommendation was not followed, or null>",
   "rationale": "<visible, brief-specific rationale>"
 }
 ```
@@ -79,6 +85,16 @@ has no rejection reasons; every other candidate has at least one specific
 visible reason. Set `providerIdempotencyEnforced` only to the recorded CLI
 value.
 
+Set `selectionSource` to `recommended` when the winner is the recommended
+candidate, `override` when it is not, and `no-recommendation` when the run
+indicated none. Use null `recommendation` fields in that last case. An
+`override` requires a specific `selectionOverrideReason` — an explicit user
+preference, a brief or steering directive the recommendation could not see, or a
+named visible defect in the recommended candidate — and keeps
+`selectionOverrideReason` null in every other case. A flow that also writes
+`design-run.json` records the same pair there, the reason under
+`selection_override_reason`.
+
 Keep `corpus.fallback` null for the recommended Balanced result. If Direct or
 Adventurer was used after a complete Balanced set failed the brief, replace it
 with `{ "fromMode": "balanced", "reason": "<visible failure>",

package/skills/design-convert/SKILL.md

@@ -22,6 +22,11 @@ results, or repeat extraction merely to obtain another format.
 
 ## Create the base LayerDoc
 
+Conversion is slow paid work: expect about **4 minutes** for a 1440px source at
+`--model standard`. The command blocks for that whole time and streams stage
+progress to stderr. It has not hung — never kill it and never re-issue it with a
+different idempotency key.
+
 ```bash
 set -o pipefail
 12ui convert <source-image> \
@@ -32,6 +37,50 @@ set -o pipefail
   --out <run-dir>/base.layerdoc.json | tee <run-dir>/base-result.json
 ```
 
+### When responsive HTML is one of the required formats
+
+Ask for it in the SAME command. The export's reference generation and per-anchor
+conversions then run alongside the conversion instead of queueing behind it, so
+the pair costs about **5 minutes** in total rather than the ~8 minutes a convert
+followed by a separate export costs. Prices are identical either way.
+
+```bash
+set -o pipefail
+12ui convert <source-image> \
+  --output layerdoc \
+  --model standard \
+  --width <intended-css-width> \
+  --export html \
+  --export-quality standard \
+  --idempotency-key <stable-key> \
+  --out <run-dir>/base.layerdoc.json \
+  --export-out <run-dir>/exports/export.responsive.html | tee <run-dir>/base-result.json
+```
+
+One blocking command, both artifacts on disk, no background-and-poll
+choreography. The result JSON carries the base conversion under `id` and the
+export conversion under `export.id`. If the export half fails the command exits
+non-zero, but the base LayerDoc is still written and its ID is still reported —
+retry only the export, with `12ui export <source-conversion-id> --output html`.
+
+Use `--export html` whenever responsive HTML is wanted. Use the plain form when
+it is not: the fused form buys a responsive export every time.
+
+### The exported page is the deliverable
+
+The responsive HTML is the page, not a bag of parts. Adopt it by default: keep
+its document, structure, classes, and anchor bindings, and build the surface by
+adapting and composing that document — wire routing, real copy, state, and
+interactions into it, wrap it as a section when the target page is larger than
+the converted screen, and extend its visual system into anything it does not
+cover.
+
+Do not mine it for assets and re-author the markup around them. That discards
+the converted design and lands the page back on the generic defaults the
+conversion was bought to avoid. When something in the export is wrong, fix it in
+the export's own markup. Rebuild from scratch only when the export cannot carry
+the surface at all, and say so explicitly in the report when you do.
+
 Preserve the source conversion ID, LayerDoc, assets, manifest, and stdout. For
 a detached create, capture its ID and resume that same operation:
 
@@ -54,7 +103,10 @@ the exact request with the same idempotency key.
 ## Export from the base conversion
 
 Use one command with comma-separated outputs. The CLI starts independent
-exports in parallel without repeating image extraction:
+exports in parallel without repeating image extraction. Every format except
+`html` is fast (seconds to about a minute); `html` is responsive HTML and takes
+about **4 minutes** on its own, which is why it is worth folding into the
+convert command above when it is needed at all.
 
 ```bash
 12ui export <source-conversion-id> \
@@ -87,7 +139,8 @@ deleting it to force another run.
 Inspect generated files and dependencies before merging the smallest coherent
 set into the target. Preserve project routing, tokens, components,
 accessibility, dependency policy, and unrelated changes; remove duplicate
-generated scaffolding.
+generated scaffolding. The exported document goes in as the page; the
+integration work is adapting it to the project, not replacing it.
 
 Run focused checks in parallel when they do not contend for outputs. Launch
 web/native examples, exercise interactions, and compare source and responsive