@12ui/design 0.2.4 → 0.2.6

package/skills/design-convert/SKILL.md

@@ -5,35 +5,22 @@ description: "Convert a PNG, JPEG, or WebP image into a structured LayerDoc with
 
 # Design Convert
 
-Convert one finished source image once, preserve its base LayerDoc conversion,
-then export every required representation from that same structured source.
-Integrate code output into the target repository and verify fidelity and
-behavior.
+Convert one finished image once, keep its base LayerDoc conversion, and derive
+every required format from that structured source. Integrate code output into
+the target project and verify the real result.
 
 ## Prepare
 
-1. Accept a static, non-interlaced PNG, JPEG, or WebP source.
-2. Inspect its dimensions and intended CSS viewport. For a high-density mobile
-   capture, use the intended layout width rather than device pixels.
-3. Inspect the target repository's instructions, framework, styling, language,
-   routes, package manager, components, assets, and validation commands.
-4. Run `12ui auth status` and `12ui capabilities --json`.
-5. Build project profiles from the exact `projectProfileSchema` and
-   `projectProfiles` capability entries the installed CLI reports. Every
-   profile requires `version`, `framework`, `styling`, `language`, and
-   `packaging`; `version` must be `1`.
-6. Derive a stable idempotency key from the project, source-image SHA-256,
-   viewport, model, and conversion revision.
-
-Never invent output, substitute cached results, or repeat extraction to produce
-another format. Before dispatch, persist the exact source digest, output, model,
-width, idempotency key, and origin in the run directory. The conversion CLI
-prints operation/result metadata to stdout; it does not create a separate
-request-evidence file.
-
-## Create one base LayerDoc conversion
-
-Create the structured source once:
+Inspect the source dimensions and intended CSS viewport. Inspect the target
+project's instructions, framework, routes, components, assets, styling,
+dependencies, and validation commands. Work under the system temporary
+directory and derive a stable idempotency key from the project, source hash,
+viewport, model, and workflow revision.
+
+Accepted input is a static PNG, JPEG, or WebP. Never invent output, use cached
+results, or repeat extraction merely to obtain another format.
+
+## Create the base LayerDoc
 
 ```bash
 set -o pipefail
@@ -45,16 +32,10 @@ set -o pipefail
   --out <run-dir>/base.layerdoc.json | tee <run-dir>/base-result.json
 ```
 
-Preserve the returned source conversion ID, LayerDoc, associated asset
-directory and manifest, captured CLI stdout, and exact request record. This
-conversion ID is the source for all later exports.
-
-For a long operation, add `--detach` to the create command and omit `--out`,
-which is not materialized by a detached create. Capture its JSON stdout, then
-finish the same operation with all required resume arguments:
+Preserve the source conversion ID, LayerDoc, assets, manifest, and stdout. For
+a detached create, capture its ID and resume that same operation:
 
 ```bash
-set -o pipefail
 12ui convert <source-image> \
   --output layerdoc \
   --model standard \
@@ -67,83 +48,52 @@ set -o pipefail
   --out <run-dir>/base.layerdoc.json
 ```
 
-If create emitted an operation ID, diagnose or resume that ID and do not submit
-another conversion. If create failed before emitting an ID, `resume` is
-impossible: repeat the exact create command with the same stable idempotency key
-so the service can return the original operation without repeating paid work.
+If create emitted an ID, resume it. If it failed before emitting one, repeat
+the exact request with the same idempotency key.
 
 ## Export from the base conversion
 
-Export one or more supported outputs with:
+Use one command with comma-separated outputs. The CLI starts independent
+exports in parallel without repeating image extraction:
 
 ```bash
 12ui export <source-conversion-id> \
-  --output <format> \
-  --out-dir <destination-directory> \
+  --output html,html_fixed,svg,png,jpg,webp,pdf,psd,pptx,sketch \
+  --out-dir <run-dir>/exports \
   --idempotency-key <stable-export-key>
 ```
 
-The literal downstream output identifiers are `html` (responsive HTML),
-`html_fixed` (fixed HTML), `svg`, `png`, `jpg` (JPEG), `webp`, `pdf`, `psd`,
-`pptx`, `sketch`, `web_project`, and `app_project`. Request only identifiers
-reported by `12ui capabilities --json`.
+Request only needed outputs. The identifiers are `html`, `html_fixed`, `svg`,
+`png`, `jpg`, `webp`, `pdf`, `psd`, `pptx`, `sketch`, `web_project`, and
+`app_project`.
 
-The destination directory may already exist. The CLI creates missing parent
-directories, but refuses before any API request when a selected output, its
-asset directory, or `export-manifest.json` already exists; never remove those
-collisions merely to force another dispatch.
-
-Independent exports may run in parallel because they all reference the same
-immutable base conversion. Reuse the source conversion ID; never repeat image
-extraction for export fan-out.
-
-Web and native project exports require an exact schema-and-matrix-derived
-profile:
+Project outputs require an exact profile appropriate to the inspected target:
 
 ```bash
 12ui export <source-conversion-id> \
-  --output web_project \
+  --output web_project,app_project \
   --web-profile '{"version":1,"framework":"react","styling":"tailwind","language":"typescript","packaging":"page"}' \
-  --out-dir <run-dir>/web-export \
-  --idempotency-key <stable-web-export-key>
-```
-
-```bash
-12ui export <source-conversion-id> \
-  --output app_project \
   --app-profile '{"version":1,"framework":"expo","styling":"native","language":"typescript","packaging":"screen"}' \
-  --out-dir <run-dir>/native-export \
-  --idempotency-key <stable-native-export-key>
+  --out-dir <run-dir>/projects \
+  --idempotency-key <stable-project-export-key>
 ```
 
-Never guess a profile or silently change it after dispatch. Preserve every
-export conversion ID and its relationship to the one base source conversion.
-
-## Integrate code output
-
-1. Extract generated project archives into an isolated temporary directory.
-2. Inspect files and dependencies before copying them.
-3. Merge the smallest coherent set into the target repository. Preserve
-   existing routing, tokens, components, accessibility patterns, dependency
-   policy, and unrelated user changes.
-4. Reuse repository-owned assets and primitives where they are the source of
-   truth.
-5. Remove duplicate generated scaffolding after integration.
-
-## Verify
-
-- Run focused typecheck, tests, lint, and build checks in parallel when their
-  outputs do not conflict.
-- Launch every generated web or native example and exercise its interactions.
-- Compare the launched result with the source at the intended viewport plus
-  representative narrower and wider viewports.
-- Render or open PDF, PSD, PPTX, and Sketch artifacts with appropriate tooling;
-  inspect their structure, dimensions, assets, and visible fidelity.
-- Inspect SVG and raster exports at original resolution.
-- Correct integration defects in project code. For a conversion defect,
-  preserve the conversion ID and visible evidence before deciding whether a
-  changed source or conversion revision warrants a new base conversion.
-
-Report the source digest and base conversion ID, associated assets, every
-export format/profile/conversion ID, integrated files, launches and
-interactions, validation results, and remaining visual differences.
+Do not guess or change a profile after dispatch. The CLI refuses destination
+collisions before sending API requests; preserve existing evidence rather than
+deleting it to force another run.
+
+## Integrate and verify
+
+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.
+
+Run focused checks in parallel when they do not contend for outputs. Launch
+web/native examples, exercise interactions, and compare source and responsive
+viewports. Open or render document/design exports and inspect structure,
+dimensions, assets, and visible fidelity. Preserve conversion IDs and evidence
+for any defect.
+
+Report the source hash, base conversion ID and assets, each export ID/profile,
+integrated files, launches, checks, and remaining visible differences.

package/skills/design-search/SKILL.md

@@ -5,36 +5,17 @@ description: "Search the 12UI Design Corpus from a rough UI, web, or mobile conc
 
 # Design Search
 
-Turn a rough interface concept into real, local visual-reference files using
-the authenticated 12UI Design Corpus. The service has already explored,
-ranked, and diversified the design space. Preserve its result order and
-metrics; do not invent a second ranking.
-
-## Prepare the query
-
-Compose a concise query that describes:
-
-- product, audience, and user goal;
-- surface: UI, web, or mobile;
-- desired personality, visual energy, and useful contrasts; and
-- target viewport when known.
-
-Describe the design problem rather than inventorying every section, control,
-or exact string that the finished product will contain.
-
-Do not name brands to imitate or ask to copy logos, names, or text. Corpus
-images are inspiration rather than templates. Preserve the usage notice
-returned by the service.
-
-Verify the account with `12ui auth status`. When a local development setup has
-a separate Login origin, include its documented `--login-origin <origin>`.
-Keep one CLI installation and one Login/Worker pair for the entire request and
-any resume.
+Turn a rough interface concept into real local reference images. The corpus has
+already explored, ranked, and diversified the design space; preserve its order
+and returned evidence rather than inventing another ranking.
 
 ## Search
 
-Standalone search defaults to four references. Respect an explicit requested
-count instead of forcing four:
+Write a concise query covering the product, audience, primary goal, surface,
+and desired personality. Describe the design problem, not every section,
+control, exact string, or brand to imitate.
+
+Standalone search defaults to four results:
 
 ```bash
 12ui corpus inspire \
@@ -42,7 +23,7 @@ count instead of forcing four:
   --out-dir <references-dir>
 ```
 
-For an explicit count:
+Respect an explicit requested count:
 
 ```bash
 12ui corpus inspire \
@@ -51,44 +32,29 @@ For an explicit count:
   --out-dir <references-dir>
 ```
 
-Prefer direct `--query` invocation. Use `--query-file` only when a genuinely
-long query or shell quoting makes it necessary; the CLI persists the exact
-query in its attempt, evidence, and manifest.
-
-Add `--origin <origin>` only when targeting a specific verified deployment.
-Use `--wildness` only when the user or orchestrating workflow requests it. Do
-not add guessed filters that could turn a metered request into an empty set.
-
-`corpus inspire` reserves the output directory, saves request and response
-evidence, downloads full images, and writes `manifest.json`. Confirm the
-manifest count, unique IDs, decodable image files, and digest receipts.
+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.
 
-Return references in the exact endpoint order. Report the endpoint-provided
-rank, distance, diversity, quality, or other metrics exactly as returned. Do
-not recalculate, reorder, average, normalize, or silently discard entries.
+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
+and each reference's role, arm, cell, relevance, relevance percentile, and
+quality percentile. Do not recalculate, reorder, average, or normalize them.
 
-## Resume without another search
+## Resume
 
-If an attempt is interrupted, ambiguous, or only partly downloaded, retain its
-directory and run:
+For an interrupted or ambiguous attempt, keep its directory and run:
 
 ```bash
 12ui corpus resume --out-dir <references-dir>
 ```
 
-Pass the exact original `--origin` when the attempt recorded one. Resume reuses
-the saved idempotency key and completes the same operation or downloads. Do not
-delete evidence, start a replacement request, or overwrite bytes that disagree
-with their saved digest.
-
-If `manifest.json` already exists, verify and reuse it. If the response is
-underfilled, duplicated, corrupt, or still ambiguous after resume, report the
-stable idempotency key and evidence path and stop. Never fill missing slots
-with cached or invented references.
-
-## Handoff
+Reuse a valid completed manifest. Never delete evidence, start a replacement
+request for the unchanged query, or fill missing slots with cached or invented
+references. If resume remains ambiguous or underfilled, report the stable key
+and evidence path and stop.
 
-Provide the manifest path, stable idempotency key, returned set ID, ordered
-reference IDs, local image paths, exact returned metrics, usage notice, and
-resume evidence. When called by `design`, it must hand back exactly four valid
-references before generation can begin.
+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.