@12ui/design 0.2.7 → 0.2.8

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

@@ -0,0 +1,60 @@
+# Continuation evidence contract
+
+Write `continuations.json` when the selected first viewport does not cover the
+complete interface. The winner remains the sole reference for every generation.
+
+```json
+{
+  "version": 1,
+  "createdAt": "<ISO-8601>",
+  "selectionPath": "<absolute selection.json path>",
+  "winner": {
+    "id": "A",
+    "path": "<absolute winner PNG path>",
+    "sha256": "<winner sha256>"
+  },
+  "baseConversion": {
+    "idempotencyKey": "<stable key>",
+    "conversionId": "<base LayerDoc conversion id>",
+    "resultEvidencePath": "<absolute result evidence path>"
+  },
+  "generation": {
+    "referenceMode": "inspiration",
+    "manifestPath": "<absolute batch manifest path>",
+    "manifestSha256": "<sha256>",
+    "batchAttemptPath": "<absolute batch attempt path>"
+  },
+  "continuations": [
+    {
+      "id": "viewport-2",
+      "kind": "<continuous-page|web-route|app-state|mobile-screen>",
+      "order": 2,
+      "prompt": "<semantic content, actions, state, and route purpose only>",
+      "promptSha256": "<sha256>",
+      "referencePath": "<same winner path>",
+      "referenceSha256": "<same winner sha256>",
+      "outputPath": "<absolute generated PNG path>",
+      "outputSha256": "<sha256>",
+      "attemptEvidencePath": "<absolute attempt path>",
+      "accepted": true,
+      "rejectionReason": null,
+      "conversionId": "<accepted image conversion id or null>",
+      "conversionEvidencePath": "<absolute evidence path or null>"
+    }
+  ],
+  "integration": {
+    "mode": "<ordered-package|independent-surfaces>",
+    "packageEvidencePath": "<absolute package evidence path or null>"
+  }
+}
+```
+
+Include 2-16 continuation entries. Every entry must repeat the winner path and
+hash; never substitute a corpus image, composite, prior continuation, or
+predecessor. The default continuation batch uses `inspiration`, because the
+winner supplies a visual system rather than a first-viewport composition to
+clone. If an intentional app-state edit must preserve exact structure, record
+it in a separate `preserve-structure` batch. Preserve rejected generations
+with a visible reason and null conversion fields. For `ordered-package`,
+record the package evidence and keep continuous-page order exact. Never store
+credentials or invent IDs or hashes.

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

@@ -5,10 +5,27 @@ prompt text so a resumed run cannot silently select different evidence.
 
 ```json
 {
-  "version": 3,
+  "version": 5,
   "createdAt": "<ISO-8601>",
   "requestSummary": "<concise implementation contract>",
   "viewportMode": "<first-viewport|primary-state|single-screen|complete-simple-surface>",
+  "designMode": "<new-interface|exploratory-redesign|structure-preserving-reskin>",
+  "redesignSource": {
+    "originalPath": "<absolute source path, or null when absent>",
+    "originalSha256": "<source sha256, or null when absent>",
+    "preparedPath": "<absolute crop or original path, or null when absent>",
+    "preparedSha256": "<prepared sha256, or null when absent>",
+    "preparation": "<none|first-viewport-crop>"
+  },
+  "contract": {
+    "preserve": ["<specific constraint>"],
+    "change": ["<specific intended change>"]
+  },
+  "referencePolicy": {
+    "retrieval": "<text-only|text-and-redesign-source>",
+    "generation": "<one-corpus-image-per-candidate|redesign-source-only>",
+    "imagesPerGeneration": 1
+  },
   "corpus": {
     "query": "<exact query>",
     "idempotencyKey": "<manifest value>",
@@ -28,6 +45,7 @@ prompt text so a resumed run cannot silently select different evidence.
     ]
   },
   "generation": {
+    "referenceMode": "<inspiration|preserve-structure>",
     "manifestPath": "<absolute generation manifest path>",
     "manifestSha256": "<sha256>",
     "batchAttemptPath": "<absolute batch attempt path>"
@@ -39,9 +57,11 @@ prompt text so a resumed run cannot silently select different evidence.
       "sha256": "<sha256>",
       "prompt": "<exact prompt>",
       "promptSha256": "<sha256>",
-      "referenceId": "<id-1>",
-      "referencePath": "<absolute path>",
-      "referenceSha256": "<sha256>",
+      "directionReferenceId": "<paired corpus id-1>",
+      "direction": "<short visibly grounded text direction>",
+      "generationReferencePath": "<paired corpus path or redesign-source path>",
+      "generationReferenceSha256": "<sha256>",
+      "referenceMode": "<inspiration|preserve-structure>",
       "provider": "<codex|openai>",
       "idempotencyKey": "<stable key>",
       "providerIdempotencyEnforced": false,
@@ -60,3 +80,13 @@ from the batch and candidate attempt files. Never store credentials or invent
 IDs, metrics, or provider guarantees. The winner has no rejection reasons;
 every other candidate has at least one specific visible reason. Set
 `providerIdempotencyEnforced` only to the recorded CLI value.
+
+For `new-interface`, use null redesign-source paths/hashes, `text-only` retrieval, and one
+paired corpus image per generation. For `exploratory-redesign`, record the
+original and prepared source for retrieval but still use one paired corpus
+image per generation. For `structure-preserving-reskin`, use the prepared
+redesign source as the sole generation
+image for all four candidates; each paired corpus image is represented only by
+its short textual `direction`. Never attach the redesign source and a corpus
+image to the same generation. Use `inspiration` reference mode for the first two
+cases and `preserve-structure` for the last.

package/skills/design-search/SKILL.md

@@ -36,6 +36,24 @@ Add `--aspect landscape|portrait|square` when the target is known. Prefer
 direct `--query`; use `--query-file` only when quoting genuinely requires it.
 Add `--origin` only when the task deliberately targets another deployment.
 
+For a redesign, distinguish the user's existing interface from corpus
+inspiration. Send that redesign source into retrieval so visual structure can
+condition the ranked space alongside the text:
+
+```bash
+12ui corpus inspire \
+  --query "<what to preserve, what to change, desired direction>" \
+  --reference-image <existing-interface.png> \
+  --count 4 \
+  --out-dir <references-dir>
+```
+
+The command accepts one PNG, JPEG, or WebP source, records its absolute path,
+SHA-256, media type, and size locally, and uploads its bytes privately for one
+image-and-text embedding. The source is not one of the returned references and
+its bytes are not persisted by 12UI. If the same source path changes before a
+resume, stop rather than silently searching with different evidence.
+
 The command reserves the output directory, records request/response evidence,
 downloads full images in parallel, and writes `manifest.json`. Validate the
 count, unique IDs, decodable files, and hashes. Return the exact endpoint order
@@ -56,5 +74,6 @@ references. If resume remains ambiguous or underfilled, report the stable key
 and evidence path and stop.
 
 Hand off the manifest path, idempotency key, set ID, ordered IDs, image paths,
-hashes, returned metrics, and usage notice. A `design` run requires exactly
-four valid references before generation.
+hashes, returned metrics, redesign-source evidence when present, and usage
+notice. A `design` run requires exactly four valid references before
+generation.