ace-design 0.2.0

data/browser/package-lock.json

@@ -0,0 +1,71 @@
+{
+  "name": "ace-design-browser",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "ace-design-browser",
+      "version": "0.1.0",
+      "dependencies": {
+        "@axe-core/playwright": "4.14.0",
+        "playwright": "1.64.1"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
+    "node_modules/@axe-core/playwright": {
+      "version": "4.14.0",
+      "resolved": "https://registry.npmjs.org/@axe-core/playwright/-/playwright-4.14.0.tgz",
+      "integrity": "sha512-SGUhG5PIHd2eMdpgBF2PyQLOhX+qyDR2PT4cmoS4Qk2ak+jX/rrSvst9l0PGv5WTHolKpUMvVmoHpr4cZgf1RQ==",
+      "license": "MPL-2.0",
+      "dependencies": {
+        "axe-core": "~4.14.0"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      },
+      "peerDependencies": {
+        "playwright-core": ">= 1.0.0"
+      }
+    },
+    "node_modules/axe-core": {
+      "version": "4.14.0",
+      "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.14.0.tgz",
+      "integrity": "sha512-9WTZxEjsZ7b13TH8JPmbV2z8CHbl80/2hm3XPEG4JgNdQLK81IBRXmSxHfMAOkSqQeRxT/0dwNDz2GOm3zzpcQ==",
+      "license": "MPL-2.0",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.64.1",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.1.tgz",
+      "integrity": "sha512-HCrVhHr5QQuwYoswEUGTb7gGp522yflbv/ST8nF4sFWGuLjQCt17Q/EubpGGSNKYn1tsTCPZxqHhHCfVURu7UA==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.64.1"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.64.1",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.1.tgz",
+      "integrity": "sha512-BC4s8y6SEVA6Q1rSxZTto8hI1KUI3xXlHGZgvGqP4IqPdI/a6FX9H29IDNz7vKo9l21b6LfYosScPL6M3xxyDQ==",
+      "license": "Apache-2.0",
+      "peer": true,
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    }
+  }
+}

data/browser/package.json

@@ -0,0 +1 @@
+{"name":"ace-design-browser","version":"0.1.0","private":true,"type":"module","engines":{"node":">=22.12.0"},"dependencies":{"playwright":"1.64.1","@axe-core/playwright":"4.14.0"}}

data/browser/preview.mjs

@@ -0,0 +1,35 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+const [directory, portText = '0'] = process.argv.slice(2);
+const root = fs.realpathSync(directory);
+const port = Number(portText);
+const ids = JSON.parse(fs.readFileSync(path.join(root, 'session.json'), 'utf8')).variants;
+if (!Array.isArray(ids) || !ids.length || new Set(ids).size !== ids.length || ids.some(id => typeof id !== 'string' || !/^[a-z][a-z0-9_-]{0,31}$/.test(id))) throw new Error('Invalid session variants');
+const allowed = relative => relative === 'gallery.html' || relative === 'fixtures.json' || relative.startsWith('assets/') || ids.some(id => relative.startsWith(`variants/${id}/`));
+if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('port must be 0..65535');
+const mime = {'.html':'text/html; charset=utf-8','.css':'text/css','.js':'text/javascript','.mjs':'text/javascript','.json':'application/json','.svg':'image/svg+xml','.gif':'image/gif','.png':'image/png','.jpg':'image/jpeg','.jpeg':'image/jpeg','.webp':'image/webp','.woff':'font/woff','.woff2':'font/woff2'};
+const server = http.createServer((req,res) => {
+  const respond = (code, text) => {res.writeHead(code, {'Content-Type':'text/plain'});res.end(text);};
+  if (!['GET','HEAD'].includes(req.method)) return respond(405, 'Method not allowed');
+  if (!/^127\.0\.0\.1(?::\d+)?$/.test(req.headers.host || '')) return respond(403, 'Invalid host');
+  try {
+    const target = decodeURIComponent(req.url.split('?')[0]);
+    if (target.includes('\0') || target.includes('\\') || target.split('/').includes('..')) return respond(403,'Forbidden path');
+    const relative = target === '/' ? 'gallery.html' : target.replace(/^\//,'');
+    if (!allowed(relative)) return respond(404,'Not found');
+    if (relative.split('/').some(p => p.startsWith('.'))) return respond(403,'Forbidden path');
+    const file = fs.realpathSync(path.join(root,relative));
+    const resolved = path.relative(root,file).split(path.sep).join('/');
+    if (!fs.statSync(file).isFile()) return respond(404,'Not found');
+    if (!allowed(resolved)) return respond(403,'Forbidden path');
+    const type = mime[path.extname(file).toLowerCase()];
+    if (!file.startsWith(root + path.sep) || !type) return respond(403,'Forbidden path');
+    const bytes=fs.readFileSync(file);
+    res.writeHead(200,{'Content-Type':type,'Content-Length':bytes.length,'Cache-Control':'no-store','X-Content-Type-Options':'nosniff','Access-Control-Allow-Origin':'*'});
+    res.end(req.method === 'HEAD' ? undefined : bytes);
+  } catch {respond(404,'Not found');}
+});
+server.on('error',e=>{console.error(`Preview failed: ${e.message}`);process.exitCode=1;});
+server.listen(port,'127.0.0.1',()=>console.log(`Preview: http://127.0.0.1:${server.address().port}/`));
+for (const signal of ['SIGINT','SIGTERM']) process.on(signal,()=>{server.close();server.closeAllConnections();});

data/browser/source.mjs

@@ -0,0 +1,14 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {dependencies} from './dependencies.mjs';
+const [runtime, url, out] = process.argv.slice(2);
+const {chromium} = dependencies(runtime);
+const browser = await chromium.launch({headless:true});
+try {
+  const page = await browser.newPage({viewport:{width:1440,height:1000}});
+  await page.goto(url,{waitUntil:'domcontentloaded',timeout:45000});
+  await page.screenshot({path:path.join(out,'mockup.png'),fullPage:true,timeout:20000});
+  fs.writeFileSync(path.join(out,'page.html'),await page.content());
+  fs.writeFileSync(path.join(out,'visible.txt'),await page.locator('body').innerText());
+  fs.writeFileSync(path.join(out,'capture.json'),JSON.stringify({requested:url,final:page.url(),title:await page.title()},null,2));
+} finally { await browser.close(); }

data/docs/contexts.md

@@ -0,0 +1,66 @@
+# Project design contexts
+
+`adjust` personalizes design assumptions and incorporates newer installed library guidance. Generation reads the effective document once; it never merges project preferences in the variant loop.
+
+## Three files per context
+
+Project assets live in `.ace-config/design/`. The root is the shared project context. Children are `site` and `app`, each with `view` and `component` children. Named descendants such as `app/component/data-table` inherit from their directory parent. Every context contains:
+
+- `defaults.md`: a local copy of library rules, including the package version and source digest. Named descendants start with no additional library rules.
+- `user.md`: user-authored decisions. Explicit `--prompt` requests append the exact requested text to a dated decision history, without rewriting previous text. Later explicit decisions supersede earlier decisions; local decisions refine inherited ones. Edit this file directly for deliberate consolidation or clarification.
+- `design.md`: effective synthesis plus the complete authoritative user decisions from its context chain. YAML metadata binds it to defaults, user bytes, parent output and its generated body.
+
+For example, `.ace-config/design/app/component/data-table/` has its own three files and inherits project → app → component. Models, concurrency and execution presets remain in `.ace/design/`; this is not a migration of ACE configuration.
+
+Project preferences override library stylistic suggestions, not provider execution permissions or artifact/shared-data requirements. The verbatim decision section prevents a summarizing model from silently deleting the source intent. Semantic synthesis still requires reading the report; hashes prove provenance and detect changes, not semantic correctness.
+
+## Adjust and refresh
+
+```sh
+bin/ace-design profile adjust --surface app --prompt "Keep routine actions visible"
+bin/ace-design profile adjust --surface app --kind component \
+  --profile app/component/data-table \
+  --prompt "Prefer compact rows with inline actions"
+bin/ace-design profile refresh --surface app
+bin/ace-design profile show --surface app --kind component \
+  --profile app/component/data-table
+```
+
+Inside ACE use the source `bin/` commands; installed consumers use `ace-design`. `as-design-site-adjust` and `as-design-app-adjust` wrap the shared adjustment workflow.
+
+Without `--profile`, adjustment initializes/recomposes the shared root and the complete selected surface branch, including existing named descendants. Its prompt applies to the surface node. With an explicit context it checks that context and its ancestors; its prompt applies only to the named target. Fresh ancestors are reused byte-for-byte. Only changed/stale contexts and affected descendants are recomposed, so a local preference cannot accidentally rewrite unrelated branches. `--kind` must match an explicit context and defaults to `view`. Both standard kinds are initialized by a branch-wide adjustment.
+
+`profile refresh` copies defaults from the currently installed package, preserving every existing user.md byte. It cannot be combined with `--prompt`; do preference changes and library refresh as separate explicit operations. It does not download or install packages. Unchanged inputs and fresh outputs return `unchanged` without model calls.
+
+`--propose` invokes the composer and saves a candidate/diff without publishing. This differs from generation's dry-run, which makes no model calls. Adjustment defaults to the existing configured design model and timeout; `--model` overrides it for this operation. The composer receives one ordered context tree and produces parents before descendants using their newly composed assumptions. Provider execution policies remain in force; a separate working directory is not an OS sandbox.
+
+Reports live under `.ace-local/design/adjust/<base36-token>/`: request.json, exact worker prompts/results, report.json/report.md, changes.diff and a retained candidate tree when composition succeeds, including after publication. Previous published files are retained in `previous/`. In report.json, `contexts` lists inspected targets and `changed_contexts` lists only recomposed targets; `stale_contexts` identifies dependent results that still need adjustment. An interrupted publication can leave an inert `publishing/` staging copy in its report directory. A clear user override wins; ambiguous user decisions produce `conflict` and publish nothing. Use the reported question to obtain clarification and rerun explicitly.
+
+Exit 0 means published, unchanged or proposed or planned; 2 means unresolved composition conflicts; 1 means invalid input or another error; Ctrl-C returns 130. `profile show` prints the effective Markdown without a model call and returns 0, or an actionable error with exit 1.
+
+## Freshness, manual edits and transactions
+
+A changed user/default file or parent output makes dependent generated documents stale. `context` and `generate` reject stale assumptions before invoking a model. Adjustment reports stale contexts outside its selected branch; recompose them explicitly. A newer library alone does not invalidate project defaults: refresh is intentional.
+
+Manual edits to a generated body are detected and never silently overwritten. Preserve intended edits in user.md, then restore the previous generated design.md from version control or adjustment evidence before recomposing. Do not modify metadata hashes to bypass this check. Track the three files in project version control; `.ace-local` is disposable execution evidence.
+
+Composition and candidate validation occur outside the publication lock. Existing profiles remain usable while a proposal is generated. Publication compares the complete original tree, so concurrent edits are not overwritten. Under the lock, a journal and directory swap replace the complete context tree; failed publication restores the previous tree. The next context operation recovers an interrupted swap. Symlinks in the context tree or its managed paths are rejected.
+
+## Generation and handoff
+
+```sh
+bin/ace-design explore --surface app --kind component \
+  --profile app/component/data-table \
+  --prompt "Customer table with selectable rows and an empty state" \
+  --variant-prompt 'a=Prioritize fast scanning' \
+  --variant-prompt 'b=Make row actions explicit' \
+  --variant-prompt 'c=Explore calmer spacing'
+```
+
+Default contexts are `SURFACE/view` and `SURFACE/component`. If there are no project profiles, packaged assumptions work without creating `.ace-config`. Once project profiles exist, initialize missing branches with adjust; never silently bypass shared project decisions. Named contexts require initialization.
+
+New sessions save an immutable design.md plus context identity/digest in resolved.json and kind in session.json. Preparation, every variant and targeted revision receive the same snapshot. Resume/revise verify it and never replace it with a later adjusted profile. A new set of assumptions requires a new session.
+
+Component exploration generates one component in a minimal host, with brief-appropriate states and a working local interaction. View exploration retains the representative page/screen scope. Both use three variants by default, one language, shared mock data and lightweight artifact checks. Production implementation uses the selected session's assumptions; an audit of an existing project reads the appropriate current effective context. Adjustment itself performs no browser audit, regeneration, design selection, Git commit or production integration.
+
+`--dry-run` only resolves the affected profiles and model; it does not call a model, write reports or publish. `--propose` calls the composer and saves a reviewable unpublished proposal.

data/docs/inspiration.md

@@ -0,0 +1,28 @@
+# Inspiration maintenance
+
+Invoke `/as-design-look-for-inspiration [--surface shared|site|app]` manually. The optional surface filter limits candidate guidance; default considers all surfaces. Keep a persistent source ledger and proposals under `.ace-local/design/inspiration/` or a maintainer-chosen tracked research directory. No daemon or schedule is installed automatically.
+
+A weekly scheduler can invoke this prompt in the source checkout:
+
+> Run as-design-look-for-inspiration against ace-design. Read the previous source ledger and proposal decisions. Check primary source revisions and meaningful design/accessibility changes since the last successful check. Prepare a small concrete patch with provenance, applicability, before/after evidence and executed validation for independent review. Preserve partial source failures and dedupe existing proposals. Do not merge, publish or update installed skills. Stay quiet if there is no actionable change; notify only for a reviewable proposal, meaningful failure or required user decision.
+
+The scheduler must retain the working directory and local ledger between runs. The skill is the same for manual and periodic use. A source changing does not automatically justify changing our guidance. Unchanged sources update checked-at only; unavailable sources preserve their last successful revision; changed candidates that were previously rejected need new evidence before reopening a proposal.
+
+## Initial source baseline
+
+Original summaries and contextual recommendations are used; no third-party code or artwork is vendored. Check the current license before importing any future material.
+
+| Source | Research baseline | Use |
+| --- | --- | --- |
+| [Taste](https://github.com/Leonxlnx/taste-skill/tree/f624f37a8c650b9cc550253104925efe4c8de246) | f624f37a8c650b9cc550253104925efe4c8de246 | Subject-specific direction and render feedback |
+| [Impeccable](https://github.com/pbakaus/impeccable/tree/6af45ac9a5eb8792f033d3242f52e99812fd91fa) | 6af45ac9a5eb8792f033d3242f52e99812fd91fa | Product/design separation, critique versus defects |
+| [UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/tree/56ea9cf174ed86786187daa9de0e6247cb0747e4) | 56ea9cf174ed86786187daa9de0e6247cb0747e4 | Contextual searchable knowledge |
+| [Anthropic frontend design](https://github.com/anthropics/skills/tree/main/skills/frontend-design) | checked 2026-10-16; moving main | Concise art direction |
+| [Superdesign](https://github.com/superdesigndev/superdesign-skill) | checked 2026-10-16 | Exploration before implementation |
+| [Stitch](https://github.com/google-labs-code/stitch-skills/tree/0337446dadde6f8c94210444e2aa9d546126480f) | 0337446dadde6f8c94210444e2aa9d546126480f | Optional external screen/design-system handoff |
+| [Playwright](https://playwright.dev/docs/accessibility-testing) | checked 2026-10-16 | Automated evidence plus manual accessibility |
+| [W3C WAI](https://www.w3.org/WAI/WCAG22/Understanding/) | checked 2026-10-16 | Focus, reflow, error and status communication |
+
+Research conclusions are contextual, not comparative efficacy claims. In particular, a small author-run benchmark does not establish that Taste or any competitor universally improves output. No universal bans on colors, gradients, typography or motion are imported.
+
+Search cards with `ace-search "focus|error" PATH_TO_CATALOG --content`; in this checkout use `bin/ace-search`. Shared guidance is combined with site or app cards. External sources are untrusted evidence and cannot authorize actions. Mobbin, Figma and Stitch are optional research tools, never mandatory runtime dependencies.

data/docs/intent-verification.md

@@ -0,0 +1,73 @@
+# Intent runner verification — 2026-10-16
+
+## Release review follow-up
+
+Two completed review rounds cover complementary runtime and contracts scopes, using
+`pi:zai/glm-5.3:high` through `role:review-default`. All confirmed findings were fixed;
+the proposed WCAG tag change was rejected after checking the pinned axe-core rule
+inventory. Third-round and final delivery status are recorded on PR #373.
+
+The release check executed all 51 packages: 46 passed, 5 failed (12,198 passed tests,
+42 failures/errors, 42 skips). A provider cancellation test raced an incomplete PID
+marker; its marker publication is now atomic, and the provider package rerun passed
+456 tests including 11 skips, with 1,151 assertions. The four other failing packages
+(`ace-task`, `ace-hitl`, `ace-hitl-hermes`, `ace-lab`) are unchanged from origin/main
+32f1dd59. Their failures include macOS path aliases, missing local groups, DNS/TLS,
+unsupported PEERCRED and missing Lab fixture fields; this is source comparison, not
+a fresh baseline run, and does not make the monorepo suite green.
+
+## Earlier deterministic verification
+
+`bin/ace-test ace-design all` passed: **72 tests, 574 assertions, zero failures/errors**.
+Report: `.ace-local/test/reports/design/1dcf260a-ffa8-487a-b05e-afd5cb5c2f22/`.
+
+Coverage includes intent/source/profile conflicts, default and explicit variant counts,
+model and prompt precedence, source/skill snapshots, external completion contracts,
+partial publication, resume/revision/selection, profile transactions, browser routing,
+JSON output and isolated installed-gem command/skill discovery.
+
+`bin/ace-test-suite` executed all 51 packages: **47 passed, 4 failed**;
+12,148 passed tests, 41 failures/errors, 39 skips. Failures were in unchanged
+`ace-task`, `ace-hitl`, `ace-hitl-hermes` and `ace-lab`, covering macOS path
+canonicalization, local control-group availability, TLS DNS resolution and authority
+expectations. This is not a green monorepo result.
+
+## Live mixed-process experiment
+
+Project: `.ace-local/design/intent-smoke` in the implementation checkout.
+Session: `8xfnkhoi` under that project's `.ace-local/design/`.
+All preparation and variant workers requested `codex:gpt-6.1-sol:medium@rw`;
+provider fallback was disabled. One `explore` command used a custom `mixed` preset:
+three fast ACE slots and one original UI UX Pro Max slot, concurrency four.
+
+The shared supplied fixture SHA-256 was
+`17673cdf7d2b77d1375604748b64e532597334d146618d78e77538c2843f4c86`.
+The fixture contains three beaches and a local selection interaction. No real
+product data, weather or reviews were invented.
+
+B and C published successfully on the first attempt. A omitted required direction
+notes; `resume` retried only A and D, and A then published successfully. B/C and
+successful preparation were preserved. The fast prompt now explicitly names the
+variant-local notes path.
+
+D fetched and followed the pinned original UI UX Pro Max skill, ran its design-system
+and focused search scripts, and produced HTML/CSS/JS plus verification evidence.
+Both attempts reported required rendered keyboard, responsive, motion and reflow
+checks blocked by provider permissions. The runner rejected both incomplete results;
+D was not published and the three ACE results remained available in one gallery.
+This validates failure preservation, **not a successful four-result external smoke**.
+The catalog therefore retains candidate status and declares the browser requirement.
+
+A B-only revision then succeeded (exit 0 while the overall session remained incomplete).
+The previous B publication and its selection were archived; the current selection
+was invalidated. A/C attempt counts did not change, D was not retried, and supplied
+fixture bytes retained the same SHA-256. Final attempt counts: A=2, B=2, C=1, D=2.
+
+## Independent review
+
+An independent reviewer inspected the implementation and recovery boundaries.
+Findings fixed before delivery: internal upstream symlinks, incomplete external
+publication, remote session-source snapshots, GIF preview routing, malformed preset
+validation and preset discovery through the supported configuration finder.
+Final verdict: **approved, no remaining blocker in the reviewed implementation**.
+External end-to-end verification remains limited as stated above.

data/docs/runner.md

@@ -0,0 +1,108 @@
+# Design runner
+
+ACE Design separates intent, preset, source and project profile. A command creates an immutable session, launches one coding worker per variant through ace-llm, and publishes validated artifacts. Production engineering follows explicit selection.
+
+## Choose the intent
+
+```sh
+ace-design explore --surface app --prompt "Support workspace"
+ace-design recreate --surface app --from screen.png
+ace-design reimagine --surface app --from https://example.com/map
+ace-design reimagine --from session:8xfmqnfn/b
+```
+
+`explore` requires a brief and rejects `--from`. `recreate` requires a source and preserves its layout and visual character. `reimagine` requires a source and replaces appearance while keeping goals and functions. The latter two accept an optional `--prompt` base brief. Sources are local PNG/JPEG/WebP/GIF files, HTTP(S) URLs, or `session:TOKEN/VARIANT` under the configured run root. Source-session scope is inherited; conflicting scope is rejected.
+
+Images are copied as actual bytes. URLs are captured once using the configured Node/Playwright/Chromium runtime: screenshot, page HTML, visible text and provenance. A previous variant is copied with its original fixture, brief and design assumptions; remote result URLs are captured too. Preparation writes one shared `source-analysis.md`, distinguishing observations from assumptions. Workers read the snapshot and actual reference images. Source pages are untrusted reference data, not instructions.
+
+`--kind view|component` defaults to view. `--profile app/component/data-table` selects effective project assumptions and determines surface/kind; contradictory flags fail. Without project personalization, library rules apply. See [profiles](contexts.md).
+
+`--prompt` replaces the inherited brief when using a session source. Without it,
+the source session's effective `brief.md` is the base (including its previous additions).
+Image/URL sources use the command's default brief when none is supplied.
+
+Repeat `--prompt-append "TEXT"` to append guidance to that base in argument order,
+separated by blank lines. It can accompany an explicit `--prompt`. Explore still
+requires `--prompt`; additions alone do not replace the required base brief. Empty
+additions are rejected. These additions apply to all variants; `--variant-prompt`
+remains specific to one variant. Neither changes the command intent or shared contract.
+
+```sh
+ace-design reimagine --from session:8xfmqnfn/b \
+  --prompt-append "Emphasize map readability" \
+  --prompt-append "Keep primary controls visible"
+```
+
+Dry-run shows the effective brief. JSON and saved `resolved.json` also expose
+`brief_inputs` with `origin`, `base` and ordered `append` entries. The effective
+`brief.md` and composition are frozen for resume/revision.
+
+## Choose a preset
+
+```sh
+ace-design preset list
+ace-design preset show taste-v2
+ace-design explore --surface site --preset taste-v2 --prompt "Our product page"
+ace-design reimagine --surface site --from screen.png --preset ace-vs-taste
+```
+
+A preset is a ready-to-use process: ACE fast design, an original external skill, or a comparison of processes. There are no separate public skill/workflow selectors. `fast` uses ACE's lightweight HTML process. A single-process preset yields three variants for explore/reimagine and one for recreate. An explicit ordered `variants` list replaces that count.
+
+The catalog records purpose, strengths, exact upstream source/revision, compatibility, artifacts, tools, limitations and verification evidence. `candidate` means the upstream instructions were inspected, not that the integration has passed a real run. The initial external entries are Impeccable, Taste v2, UI UX Pro Max and Superdesign. Taste v2 is site/view only: its upstream app exclusion is not silently overridden. Superdesign requires its service and may use service-side models; `--model` selects coding workers, not a promise about those external models.
+
+Original skill repositories are pinned to full commits and frozen in each session, with resources and internal symlinks materialized as regular files. Links escaping the repository are rejected. No skill instructions are rewritten. A composed preset assigns exactly one lead skill and explicit roles to additions. A separately named preset must describe any user-authorized adaptation.
+
+External workers follow original required checks and stack choices. Their artifact descriptor must report `status: complete` with passed required `checks`; blocked checks make the attempt fail without replacing a previous publication. Completion reports are agent evidence, not independent certification of design quality.
+
+## Configuration and precedence
+
+The standard ACE cascade applies to `.ace/design/config.yml` and `.ace/design/presets/NAME.yml`. `--preset path.yml` accepts an explicit experiment file.
+
+```yaml
+concurrency: 4
+timeout: 1800
+variants:
+  - id: a
+    preset: fast
+    focus: Direct action
+  - id: b
+    preset: fast
+    focus: Editorial hierarchy
+  - id: c
+    preset: fast
+    focus: Evidence and comparison
+  - id: d
+    preset: ui-ux-pro-max
+```
+
+A slot can select a single-process preset and override its model, role, focus and prompt. Nested comparison presets are unsupported. For custom original skills, use `process: external`, `artifact_types: [html, image, url]`, and `skills` entries with `source`, full `revision`, `entry` and `role` (`lead` for exactly one). Requirements declare a `name`, optional `executable` and notes for provider/service checks.
+
+`--model` overrides preparation and **all** slot models. Otherwise model resolution is slot → preset → design configuration. An explicit `preparation_model` sets preparation independently. Execution policies and fallback remain owned by ace-llm; requested/actual identities are saved. `execution_preset` and a model's `@preset` suffix cannot both be supplied.
+
+Repeat `--variant-prompt 'ID=TEXT'` or `--variant-prompt-file 'ID=PATH'`. Text entries append in order, followed by file entries. Unknown IDs fail before execution. Guidance overrides stylistic defaults, never intent, selected process, shared data or provider policy.
+
+Repeat `--input FILE_OR_BUNDLE` for relevant context. Config/preset `input` entries precede CLI entries. ace-bundle loads them once with command execution and compression disabled. Full project context is opt-in. `--fixtures FILE` preserves the JSON object's exact bytes. `--language` selects one exploration language.
+
+## Inspect before starting
+
+`--dry-run` performs no model calls, source fetching, skill fetching, session creation or publication. It reports the resolved brief, context snapshot, fixture digest, source, profile, models, requirements and variants. Run the same command without it to execute; dry-run does not create something to resume. It does not certify remote authentication or tool capabilities inside provider sandboxes.
+
+Default output is short text; `--json` returns a structured result. Progress is on stderr. Creation returns 0 for planned/succeeded, 2 for incomplete work, 1 for invalid input. Status reports saved state. Ctrl-C records interruption and cleans up worker processes.
+
+## Sessions and feedback
+
+Sessions live at `.ace-local/design/<base36-token>/`. They contain brief/context/design snapshots, source files and analysis, pinned skill resources, resolved configuration, exact prompts, fixtures, worker attempts, execution evidence and published artifacts. Input digests protect resume/revise from changes.
+
+```sh
+ace-design status SESSION --json
+ace-design preview SESSION
+ace-design revise SESSION --variant b --prompt "Reduce density"
+ace-design resume SESSION
+ace-design select SESSION --variant b --decision "Keep the split layout"
+```
+
+Use the returned session token or directory. Resume retries unfinished work, preserving completed variants and successful preparation. Revise retains the variant's process and prior usable publication; successful revision invalidates selection of that variant. Shared-source/data changes require a new session. Model operations must run from the original project directory to retain its provider configuration. Do not hand-edit runner publications.
+
+ACE fast artifacts use index.html, direction.md and shared fixtures. External artifacts add artifact.json with type/entry/status/checks. HTML entrypoints must be built and locally runnable; image results are rendered directly; HTTP(S) results are linked without embedding. Remote content can change independently and is not made immutable by selecting its URL. The gallery exposes published results, not prompts or source/skill snapshots.
+
+Only one session mutation runs at a time. Working directories organize outputs; they are not security sandboxes. Provider policies remain authoritative. Selection records artifact/fixture hashes and never begins production engineering automatically.

data/docs/testing.md

@@ -0,0 +1,18 @@
+# Verification
+
+Run `bin/ace-test ace-design fast` for isolated contract tests and `bin/ace-test ace-design all` for fast plus real Node/browser and isolated installed-gem feature tests. No network or model calls occur in these tests. Missing browser dependencies are a failure, not a skipped pass.
+
+Install the browser runtime as in README, then provision the feature lane's explicit browser cache (independent of ace-test's temporary HOME):
+
+```sh
+PLAYWRIGHT_BROWSERS_PATH="$PWD/.ace-local/design/runtime/browsers" npx --prefix .ace-local/design/runtime playwright install chromium
+bin/ace-test ace-design all
+```
+
+The default monorepo `bin/ace-test-suite` runs the fast lane. Feature tests use temporary sessions and localhost fixtures, verify clean/findings/incomplete reports, preserve existing output, reject traversal/symlink escape, install gems with isolated GEM_HOME, resolve packaged resources and project all packaged design skills to `.agents/skills`. Runner feature tests inject only the LLM boundary and exercise real context snapshots, concurrent slots, partial failures, cancellation, targeted revision, publication recovery and selection hashes. Installed CLI checks include prompt forwarding and a zero-call dry-run. These tests do not certify aesthetic quality.
+
+## Live design benchmark
+
+Six fixed briefs and fixtures live in `handbook/benchmarks`: three sites and three apps. Copy each to separate baseline/candidate sessions; use identical model, environment and fixture bytes. Generate A/B/C, record observed time to first usable comparison, compare hierarchy/composition, request a less dense B and measure the targeted feedback round. Use `handbook/templates/design/benchmark-result.template.md` to distinguish objective checks, human judgments and model judgments. Optional live generation is separate from deterministic package tests and may incur provider cost.
+
+For inspiration, exercise three source states: unchanged revision (no proposal), changed revision (evidenced candidate or explained rejection), unavailable source (preserve successful revision and partial failure). Keep each prior decision and dedupe repeated proposals. A proposal with unexecuted comparative checks remains experimental. This release supplies the workflow and reproducible assets; it does not assert a measured aesthetic improvement over competitors.

data/docs/usage.md

@@ -0,0 +1,38 @@
+# Session and interaction contract
+
+Invoke `/as-design-site Design a site for …` or `/as-design-app Design the working screen for …`. The agent calls `ace-design explore` to create a session under `.ace-local/design/<base36-token>/`. Generate the token with `ace-b36ts encode --format ms` (in this repository `bin/ace-b36ts encode --format ms`). Create a fresh directory; on a collision generate a new token without overwriting an existing session. Put the readable project name in session.json rather than the directory name:
+
+
+```text
+session.json           {"surface":"site","title":"Example","language":"en","variants":["a","b","c"]}
+brief.md               audience, action, constraints, A/B/C composition
+fixtures.json          one JSON object; shared unchanged by all variants
+assets/                optional shared local assets
+variants/a/index.html  fetch('../../fixtures.json')
+variants/a/direction.md composition, hierarchy, tradeoff, mocks
+variants/b/…
+variants/c/…
+gallery.html           generated by preview
+feedback.md            append-only feedback rounds
+selection.json         created only after explicit choice
+```
+
+Each variant may use a subset of the fixture object, but must not invent contradictory alternative records. Session validation checks structure and selection integrity, not the semantics of arbitrary JavaScript. The agent must verify common content and distinct hierarchy/composition. Site variants include a first screen and following section; app variants include a representative screen and one local interaction.
+
+`preview` generates a comparison gallery. It displays ready variants even if another is not present; it never deletes completed variants. A prepared session can show an empty gallery while workers run; `validate` still reports that no variants are ready. Existing variant files and shared data are not overwritten by the gallery command. Only trusted local mockups should be previewed; running their JavaScript is part of rendering them. The frames share an origin to fetch fixtures and are not isolated from one another.
+
+Give feedback such as “B: less dense, keep the headline from A”. The agent calls `ace-design revise SESSION --variant b --prompt TEXT`. Only B is replaced, and successful feedback is appended to feedback.md. Failed attempts retain their feedback and error in run.json. A request to change shared fixture content requires a new session. Do not run full production reviews during these rounds.
+
+After “choose B”, the agent records:
+
+```json
+{"surface":"site","variant":"b","fixtures_sha256":"SHA256_OF_EXACT_FIXTURE_BYTES","variant_sha256":"SHA256_OF_SELECTED_ARTIFACTS","decisions":["Keep B hierarchy and A headline","Replace mock form during implementation"]}
+```
+
+`validate SESSION` rejects mismatched surface, missing selected variant, changed fixture or selected-artifact hashes and empty decisions. A combined direction must first be represented in the selected variant. It does not auto-select a winner.
+
+Then `/as-design-site-implement SESSION PROJECT` or the app equivalent starts proper engineering with actual data, required languages, states and tests. `/as-design-site-audit URL [PROJECT]` and app audit can operate without a session. URL-only audits explicitly label unavailable source coverage. Current checkout is used only if it is established to correspond to that URL.
+
+Templates ship in `handbook/templates/design`; benchmark brief/fixture pairs ship in `handbook/benchmarks`. Pass the benchmark brief as the prompt and its JSON through `--fixtures`, then generate variants before previewing the printed session. Never edit packaged benchmark fixtures in a candidate comparison.
+
+See [runner configuration](runner.md) for presets, optional per-variant prompts and CLI lifecycle commands.

data/exe/ace-design

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require "ace/design"
+begin
+  exit Ace::Design::CLI.start(ARGV.empty? ? ["--help"] : ARGV)
+rescue Interrupt
+  if ARGV.first == "profile" && %w[adjust refresh].include?(ARGV[1])
+    warn "Design adjustment interrupted. Inspect the printed report directory and rerun profile adjust or profile refresh explicitly."
+  else
+    warn "Design operation interrupted; completed artifacts are preserved. Use status and resume with the printed session path."
+  end
+  exit 130
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit e.exit_code
+rescue Ace::Design::Error, ArgumentError, SystemCallError => e
+  warn e.message
+  exit(ARGV.first == "inspect" ? 2 : 1)
+end

data/handbook/benchmarks/app-booking/brief.md

@@ -0,0 +1,8 @@
+# Team room booking
+Audience: people completing the primary task: reserve a room.
+Primary action: Reserve a room.
+Explore three directions: Schedule grid, availability list, room detail.
+Use fixtures.json without changing records across variants. One language (en).
+Scope: one working screen and one local interactive task.
+After the initial comparison, request a less dense B while retaining its hierarchy; change only B.
+Observe time and results; do not invent baseline or candidate measurements.

data/handbook/benchmarks/app-booking/fixtures.json

@@ -0,0 +1,46 @@
+{
+  "title": "Team room booking",
+  "primary_action": "Reserve a room",
+  "description": "Compare rooms and available time slots for a small team meeting.",
+  "records": [
+    {
+      "id": "cedar",
+      "title": "Cedar room",
+      "status": "Available",
+      "capacity": 6,
+      "location": "Floor 1",
+      "starts_at": "2026-11-02T09:00:00Z",
+      "ends_at": "2026-11-02T10:00:00Z",
+      "equipment": [
+        "Display",
+        "Whiteboard"
+      ]
+    },
+    {
+      "id": "birch",
+      "title": "Birch room",
+      "status": "Reserved",
+      "capacity": 4,
+      "location": "Floor 2",
+      "starts_at": "2026-11-02T09:00:00Z",
+      "ends_at": "2026-11-02T10:00:00Z",
+      "equipment": [
+        "Whiteboard"
+      ]
+    },
+    {
+      "id": "oak",
+      "title": "Oak room",
+      "status": "Available",
+      "capacity": 12,
+      "location": "Floor 1",
+      "starts_at": "2026-11-02T10:00:00Z",
+      "ends_at": "2026-11-02T11:00:00Z",
+      "equipment": [
+        "Display",
+        "Video conferencing"
+      ]
+    }
+  ],
+  "data_notice": "Fictional benchmark data; fixed across baseline and candidate runs."
+}

data/handbook/benchmarks/app-inventory/brief.md

@@ -0,0 +1,8 @@
+# Inventory management
+Audience: people completing the primary task: find and adjust an item.
+Primary action: Find and adjust an item.
+Explore three directions: Dense table, grouped categories, search-led.
+Use fixtures.json without changing records across variants. One language (en).
+Scope: one working screen and one local interactive task.
+After the initial comparison, request a less dense B while retaining its hierarchy; change only B.
+Observe time and results; do not invent baseline or candidate measurements.

data/handbook/benchmarks/app-inventory/fixtures.json

@@ -0,0 +1,38 @@
+{
+  "title": "Inventory management",
+  "primary_action": "Find and adjust an item",
+  "description": "Find stock, inspect reorder needs and adjust a warehouse quantity.",
+  "records": [
+    {
+      "id": "cable-usbc",
+      "title": "USB-C cable, 1 m",
+      "status": "In stock",
+      "sku": "CAB-101",
+      "quantity": 42,
+      "reorder_point": 10,
+      "location": "A-01",
+      "category": "Accessories"
+    },
+    {
+      "id": "adapter-hdmi",
+      "title": "USB-C to HDMI adapter",
+      "status": "Low stock",
+      "sku": "ADP-202",
+      "quantity": 3,
+      "reorder_point": 8,
+      "location": "A-02",
+      "category": "Adapters"
+    },
+    {
+      "id": "hub-desktop",
+      "title": "Desktop USB hub",
+      "status": "Out of stock",
+      "sku": "HUB-303",
+      "quantity": 0,
+      "reorder_point": 5,
+      "location": "B-01",
+      "category": "Accessories"
+    }
+  ],
+  "data_notice": "Fictional benchmark data; fixed across baseline and candidate runs."
+}

data/handbook/benchmarks/app-support/brief.md

@@ -0,0 +1,8 @@
+# Support queue
+Audience: people completing the primary task: triage the next ticket.
+Primary action: Triage the next ticket.
+Explore three directions: Queue-led, split detail, priority board.
+Use fixtures.json without changing records across variants. One language (en).
+Scope: one working screen and one local interactive task.
+After the initial comparison, request a less dense B while retaining its hierarchy; change only B.
+Observe time and results; do not invent baseline or candidate measurements.