@utopia-studio-design/design-system-cli 0.7.1 → 0.8.0

package/data/docs/ceramic-release-2026-09-06.md

@@ -9,3 +9,5 @@ Development validation: Vitest 13 files / 79 tests passed; CLI generation and MC
 Rams quick_review was attempted but the workspace review credits were exhausted. The pre-commit review_files attempt failed at the provider transport; no score was obtained.
 
 This release does not mark independent QA reports closed. Server Designer Agent activation remains disabled under the existing production configuration.
+
+Published: `@utopia-studio-design/design-system@0.9.1` and `@utopia-studio-design/design-system-cli@0.7.1`. CLI 0.7.0 was superseded immediately after the public-tarball check detected an omitted standalone runtime. The 0.7.1 package bundles that runtime directly. All nine public template generation commands, route/page counts and documented tokens pass. The Chat Workspace consumer installs exclusively from npm and builds successfully. Merge integration auth/footer checks: 8 passed.

package/data/docs/create-a-brandbook.md

@@ -0,0 +1,79 @@
+# Create a Brandbook
+
+Create the brandbook before authoring a Ceramic theme. The brandbook turns a brief, optional logo, references, and existing imagery into one governed `BRAND.md`. That file becomes the input for semantic color, typography, imagery, motion, Marketing, and Solution decisions in the design system.
+
+## Connect the GitHub skill
+
+Connect Ceramic MCP first. Then call `get_brandbook_skill`. The response identifies the canonical GitHub repository, approved branch, pinned revision, and `SKILL.md` path. Resolve that exact source before starting the workflow. Private repository access uses the active GitHub account; do not place access tokens in prompts or project files.
+
+```text
+get_brandbook_skill {}
+```
+
+```bash
+git clone --branch main https://github.com/The-Utopia-Studio/Ceramic-Brandbook.git
+```
+
+The source of truth is `skills/ceramic-brandbook/SKILL.md` in that repository. The MCP response pins a reviewed commit so an agent does not silently use a different workflow.
+
+## Prepare the direction session
+
+Call `prepare_brandbook_run` with a brand name and useful brief. A logo is optional. Include the audience, offer, character, constraints, existing assets, required locales, and intended Marketing or Solution uses when they are known.
+
+```json
+{
+  "name": "prepare_brandbook_run",
+  "arguments": {
+    "brandName": "Your brand",
+    "brief": "Audience, offer, character, constraints, and desired outcome"
+  }
+}
+```
+
+This call prepares work; it does not generate, save, or publish a release.
+
+## Present A, B, and C
+
+Before producing a final brandbook, present exactly three materially different directions labeled A, B, and C. Each direction must compare:
+
+- positioning and verbal character;
+- Latin and Arabic typography;
+- semantic color architecture;
+- photographic subject, light, composition, and treatment;
+- Ceramic motion personality;
+- Marketing expression and example assets;
+- Solution or product expression and example applications;
+- fit, risk, and tradeoff.
+
+The user chooses one direction. Refine it with the user until its palette, type, imagery, motion, and application choices are clear. Do not build or save the final brandbook before this refinement is complete.
+
+## Produce one `BRAND.md`
+
+The approved brandbook has one editorial source:
+
+```text
+BRAND.md
+assets/manifest.json
+assets/generated/
+validation.json
+```
+
+`BRAND.md` must define strategy, voice, logo rules, semantic color roles, Latin and Arabic type, layout, photography, motion, Marketing, Solution, accessibility, and implementation guidance. English and Arabic must have equal content coverage, visual hierarchy, and usable LTR/RTL behavior unless the user explicitly changes the locale scope.
+
+Use the active chat's native image generator by default. Record the provider, prompt or operation, source assets, and generated output in the asset manifest. Provider choice stays outside the brand contract so the same workflow can run in ChatGPT, another capable client, or a named external provider.
+
+For Solution, choose one to three applications from phone, desktop, and environment according to the brand and available assets. Generate a dedicated scene for every photographic desktop or environment mockup. Place the resulting mockups directly on the semantic brand canvas without generic backing panels, white or translucent plates, or explanatory text over the image.
+
+## Validate and hand off
+
+Validate the source and built release, then save the versioned bundle in the brand's Brand Room. The approved `BRAND.md` becomes the only brandbook input to **Create a Theme**. The theme maps its decisions to Ceramic semantic roles; it does not reinterpret the chosen direction.
+
+Release checks:
+
+- GitHub repository, branch, revision, and skill path are recorded.
+- The selected A/B/C direction and refinement decision are recorded.
+- English and Arabic content and visuals have parity.
+- Image provenance and rights metadata are present.
+- Marketing and Solution applications reflect the selected direction.
+- Brandbook validation passes before theme authoring begins.
+

package/data/docs/dextrum-document-family.md

@@ -0,0 +1,47 @@
+# Dextrum: v2 product theme and 07 Sep document ruling
+
+## Ownership and precedence
+
+Product surfaces use Ceramic's Dextrum v2 two-mode contract: neutral charcoal Dark (default) and cool-neutral Light. Documents, decks and one-pagers follow the frozen 07 Sep 2026 document rulings until superseded. HTML is a delivery format; an HTML presentation retains the document ruling and its animation/accessibility requirements. Animated HTML remains the default output. PPTX/PDF require an explicit request.
+
+The owner-supplied exemplar is `2026-09-07_dextrum_onepager-totalenergies-tier1-v1_1.pptx`. Its slide XML confirms light blue `#C9E0F5` strips and steel-blue `#5B87AD` bands. Client-specific text and logos in that file are not reusable brand-kit content. The file is not redistributed with the package.
+
+## Shared document-family contract
+
+Core registers `venture-document` and these opt-in composition slots. Every venture may map the same semantic roles through its theme, without adopting Dextrum colors.
+
+| Slot | Dextrum document treatment |
+| --- | --- |
+| `.uds-document-strip` | Light blue `#C9E0F5`, ink `#192B39` text |
+| `.uds-document-eyebrow` | Ocean Blue `#3E8ECC` accent |
+| `.uds-document-chip` | White background, ink text |
+| `.uds-document-band` | Steel blue `#5B87AD`, white text |
+| `.uds-document-logo-container` | Separate white rounded container; existing surface radius and spacing tokens |
+
+Use `--document-*` roles registered in `theme-dextrum.json` and mapped in `dextrum.css`. These roles are independent of product light/dark mode. The rounded geometry uses the existing surface contract; no exact numeric corner radius was specified in the owner's ruling.
+
+`logo-on-band` is approved for both identity marks on document bands. Keep each transparent logo unchanged inside its separate white rounded container. Do not recolor, distort or bake a background into an SVG. Generic no-backing guidance continues to reject unregistered treatments on product surfaces; it must not reject this explicitly approved document treatment.
+
+## Identity custody
+
+Canonical source: owner-supplied `dextrum-jamal-brand-kit.zip`, not a recreated repository mark. BLUE v2, TEAL BLUE, GREY and BLUE v2 with tagline are mirrored byte for byte:
+
+- Web: `public/brand/dextrum/{blue-v2,teal,grey,tagline-blue-v2}.svg`
+- npm: `src/themes/assets/dextrum/` in the design-system package
+- `public/brand/dextrum-logo.svg` mirrors BLUE v2 exactly.
+- `ceramic.assets.json` beside the variants records source filenames and SHA-256 hashes.
+
+The original asset repository remains available for photography. Its identity guidance cannot override these owner-supplied canonical SVGs.
+
+## Retired v1 data
+
+The kit's 01 Sep `dextrum-design-language.md` uses historical `#192B39`/`#2F3F4C` structural surfaces. It is not the v2 product-token authority. `theme-dextrum.json` and `dextrum.css` already contained two modes; the stale `themes.json` summary still exposed v1 values. The summary now derives its default values from the v2 dark mapping, while the docs expose both modes and the document roles. `#192B39` remains legitimate brand ink in light mode and documents; it is not the product's dark canvas.
+
+## Validation (09 Sep 2026)
+
+- 28 targeted tests passed: v2 registry parity, docs token discovery, canonical SVG hashes, and localized presentation boundaries.
+- Design-system and app builds passed; semantic page ownership audit passed.
+- Chromium computed styles confirmed product backgrounds switch between `#F7F7F5` and `#0E1215` while document strips remain `#C9E0F5`, bands `#5B87AD`, and logo containers white.
+- npm pack dry-run includes all four canonical SVGs; CLI data regenerated from source.
+- Rams quick_review was requested but unavailable because the workspace's 30 review credits were exhausted.
+- This source update has not yet been published to npm or deployed to the production site.

package/data/docs/guide.md

@@ -6,6 +6,8 @@ Guide pages are the operating layer of Ceramic. They define how humans and AI ag
 
 - `Getting Started`: installation, theme CSS, first component, examples, CLI discovery, Arabic-friendly entrypoint.
 - `What's New`: release notes for package, manifest, theme, and docs changes.
+- `Connect MCP`: connect a supported agent to Ceramic's machine-readable contracts.
+- `Create a Brandbook`: resolve the reviewed GitHub skill, compare A/B/C directions, refine one with the user, and produce the single `BRAND.md` input for theme authoring.
 - `Create a Theme`: scaffold a theme, define brand primitives, map Ceramic semantic roles, document visual policy, and verify compatibility.
 - `Use Templates`: discover a reviewed starter, inspect its contract, copy it with a theme, connect product-owned data, and validate the standalone result.
 - `Arabic Friendly`: RTL-first layout, Arabic typography, mixed-script resilience, localization readiness, and icon/motion mirroring.

package/data/docs/presentation-asset-repository.md

@@ -51,3 +51,8 @@ assets when relevant. It does not force imagery into data or evidence slides,
 repeat one image as decoration, or mix an asset into a theme that is not listed.
 The final handoff records the repository path, commit SHA, crop or
 transformation, credit, license, and slide numbers for every used asset.
+
+
+## Venture document rulings
+
+Product surfaces remain Ceramic-owned. Documents, decks and one-pagers follow their venture’s approved document ruling; an HTML delivery format does not erase that boundary. Dextrum uses the [07 Sep document family](dextrum-document-family.md), including registered white rounded logo-on-band containers. Canonical transparent SVG variants are mirrored in `public/brand/dextrum/` and the design-system package. Preserve the requested output format.

package/data/docs/ui-parts-qa.md

@@ -0,0 +1,172 @@
+# Optional semantic UI parts — QA
+
+## Workflow expansion — 2026-09-13
+
+**PASS WITH RISKS for representative local coverage; full source migration remains IN PROGRESS.**
+
+- 59 dedicated examples, 188 selectable states, 20 independent parts. 65 product source pages have representative mappings; `/auth` is the reference index replaced by the catalogue. No complete upstream portal shell is copied.
+- 38 desktop/mobile Chromium checks passed: catalogue/navigation/reload, every route at 1440/959/390px without the application sidebar, all states across 8 themes at 959px, Arabic mobile, original account interactions, new form validation, file format rejection, conditional matching, localized plan values, allocation limits, prerequisites and assessment submission gates, record lifecycle/CSV, session tabs, separate file/chat state, local conversation/media behavior and code-file selection.
+- TypeScript, `audit:semantic-pages`, and `test:cli` passed. CLI verifies theme resolution, standalone code dependencies, candidate discovery/composition, MCP protocol, source hashes and bounded fragment retrieval. Source coverage assertions do not assert interaction parity.
+- Visually inspected Korean credit allocation in the real application (1440×1000) and Arabic profile setup fixture (390×900). No horizontal spill or docs sidebar in these views. Native file chooser text follows browser locale, not app locale.
+- Fixed missing standalone dependency references, accessible select/feedback names, status-tab mapping, and an attachment filename leaking into the chat draft. Shared workflow semantics own all added presentation; pages do not import CSS.
+- `design-system-ux-qa` guided the rendered-consumer checks and separation of tested coverage from source parity. Rams quick_review was attempted again after final UI fixes but the workspace has exhausted its 30-credit allowance; no Rams score/review was obtained.
+- Not verified: WebKit/Firefox, real signed-in account-specific chrome, full source visual/interaction parity, real upload/storage/auth/provider/media/payment services. Original detailed credential matrices, per-item verification, plan comparisons, some record/dashboard-specific actions, profile defaults and public content sections remain reduced examples. See `ux-pattern-migration.md`.
+- Nothing was committed, published, pushed or deployed. Generated CLI data was synchronized locally.
+
+The sections below retain earlier checkpoints, not the current example counts.
+
+## Sidebar regression remediation — 2026-09-13
+
+PASS WITH RISKS. The previous fixture-heavy coverage missed a P2 application
+shell regression: `/templates/patterns/:id` rendered TemplatesPage but
+getActiveAreaId returned a nested string, so getSidebarArea fell back to docs.
+The real-app area assertion failed before the fix. Detail routes now resolve
+the templates area and template pages do not mount app-sidebar at any width.
+No CSS override or unrelated page changes were needed.
+
+22 Chromium checks passed after the fix, including all 12 real-app detail routes
+at 1440/959/390px, catalogue, reload, Arabic detail, equal shell/main widths and
+retained documentation navigation. TypeScript and semantic page ownership passed.
+Rams review was attempted but quota-blocked. Authenticated session-specific
+chrome and WebKit/Firefox were not exercised; route classification is independent
+of auth. This narrow fix does not alter the incomplete source migration scope.
+
+## Current evidence — individual pages, 2026-09-13
+
+**PASS WITH RISKS for this local change.** Catalogue → one dedicated pattern
+page replaces the stacked one-pager, following the latest user clarification.
+There are now 12 source-backed examples, 41 selectable states and 13 independent
+parts. The full source migration is still incomplete.
+
+- Observed: real app catalogue, search, dedicated route, reload and back/forward;
+  no simultaneous full-page previews. Legacy example-query links show one example.
+- Added invitation acceptance/code/expiry, session recovery, people directory,
+  conversation list, notification inbox and delivery preferences. Source portal
+  shells are not copied. ActivityList, DirectoryCards and ChannelPreferences are
+  independently available to MCP composition discovery.
+- 20 Chromium desktop/mobile tests passed. Behavioral checks cover invitation
+  validation/accept/decline, session reauth/cancel, directory filter/sort/detail,
+  read status, archive empty state and channel restrictions/save/reset, alongside
+  existing account interactions. All 41 selectable states render in 8 themes at
+  959px. New pages also render at Arabic/RTL 360px; full-width preview at 1440px.
+- Fixed native directory select accessible names after a failing interaction
+  test. Removed a generic search keyword that incorrectly selected people cards
+  for unrelated dashboard searches. Retained visible focus on interactive links;
+  route-focused headings do not draw a full-width control outline.
+- TypeScript, semantic page ownership, CLI contracts, source hash coverage and
+  standalone MCP bundles passed. Earlier brandbooks type errors did not recur;
+  no edits were made to that service in this change.
+- Browser artifacts: `pattern-catalogue-ko.png`, `people-page-ko.png`,
+  `preferences-ar.png` in the corresponding `test-results/ui-pattern-library-*`
+  directories. Korean catalogue/detail and Arabic preferences were inspected.
+- Rams quick_review was attempted; quota exhausted, no external review score.
+- Deliberate boundaries: session recovery is inline, not the source fixed modal;
+  no countdown navigation. Invitation strength uses sample host rules. Directory
+  and message destinations are local handoff previews, not a full booking/chat
+  backend. No actual mail, auth, preferences or membership mutations occur.
+- Untested: WebKit/Firefox, screen-reader application testing, real service
+  callbacks, custom unregistered themes and source-only pages. These examples
+  are not a claim of complete branch-for-branch upstream parity or npm release.
+
+## Historical first account batch — superseded
+
+**PASS WITH RISKS for the first account port batch. Full requested migration is
+INCOMPLETE.** The older two-example report below is historical, not current scope.
+
+- Imported the complete pinned source inventory: 66 page definitions, 85 entries
+  including shared/system helpers, 104 indexed states and 218 exact function
+  fragments. Source hash checks and remote HEAD match the pinned revision.
+- Fixed static-route precedence and indexed settings pages absent from screenshots.
+- Local MCP supports full source discovery and bounded fragment reads, with
+  user/room theme then Cloudblur, source-only status, required semantic adaptation
+  and no automatic whole-portal import. Composition discovery includes source
+  candidates without asking the user to choose patterns.
+- Removed invented review/workspace examples from public/MCP discovery. Gallery
+  now contains six source-backed account examples with 22 selectable states.
+- Source differences are deliberate: no original branding, sample medical
+  identities, compliance/trial promises, mock navigation/localStorage auth or
+  automatic account side effects. No QR placeholder is presented as a real key.
+- Added password visibility/rules, code entry and provider selection as independent
+  registered parts. Code cells and feedback surfaces have bounded semantic radii.
+- 12 Chromium desktop/mobile tests passed: roles, opt-in separation, form
+  validation, password visibility, link-login, resend cooldown, email edit, code
+  paste/arrows/recovery, independent gallery state/code/viewport/copy, all 22
+  exposed states × 8 themes at 959px, full-width 1440px and Arabic at 360px.
+- CLI contracts, standalone MCP bundles and semantic-page ownership passed.
+  TypeScript passed during the first batch check, but the final whole-workspace
+  rerun is blocked by TS7022/TS7006 in `src/services/brandbooks.ts:29-30`, outside
+  this change. That file was not edited here. Source tests validate every function
+  fragment and Korean intent discovery.
+- Rams quick_review was attempted but blocked by review quota; no score exists.
+- Untested: Safari/Firefox, actual auth/provider/email backends, custom unregistered
+  themes, all source-only page interactions as rendered Ceramic ports. State
+  renderability is not full behavioral equivalence to every source branch.
+- No deployment, npm publication, commit or production mutation occurred.
+
+Remaining work is tracked per source page in `ux-pattern-migration.md`.
+
+## Historical gallery-only review — superseded
+
+Verdict: PASS WITH RISKS (local implementation, not a release)
+
+## Scope
+
+Single-example regression repaired: both registered examples render together,
+with independent per-article controls. Navigation does not unmount other
+examples; search alone filters. The gallery count reflects two implemented
+examples, NOT completion of the original source-pattern migration. Desktop and
+mobile regression includes simultaneous rendering, vertical order, input state
+retention across navigation, and independent Code/Preview/viewport controls.
+
+Presentation follows the user's block-gallery screenshot: horizontal navigation,
+compact Preview/Code and viewport/reset/install/AI toolbar above a full-width
+example. No documentation sidebar or oversized hero. Usage guidance is collapsed
+by default. Tests assert full preview width, absence of the old sidebar/install
+section, tablet sizing, copy fallback and mobile containment. Rams quick review
+was attempted again; credits remain exhausted.
+
+The human-facing library now lists UX patterns with two contextual page
+examples: signup and request review. The unrequested workspace-creation example
+was withdrawn from the UI and MCP registry. Preview/code, actual
+dependency files, base npm installation and optional AI handoff replace the
+previous seven isolated cards. Seven independent parts remain the AI building
+blocks: choices, validated input, filters, review list, existing KPIGrid,
+progress steps and outcome notice. No required customer assembly flow,
+source branding, source screenshots or role-specific portal categories appear
+in the library. The former screen-copy approach is retired; 101 original source
+screens remain internal references, not claimed migrations.
+
+The agent optionally discovers parts from the product goal, checks fit and
+retrieves actual exports/dependencies through MCP. No user selection is required.
+No match produces `no-pattern-needed`. User/room theme takes precedence; absence
+falls back to Cloudblur. Unknown explicit themes fail instead of rebranding.
+
+## Evidence
+
+- `tests/e2e/ui-pattern-library.spec.ts`: desktop and mobile Chromium, Korean/
+  English/Arabic, list/search, no source branding, local signup validation and
+  completion, shared filters/review rows, empty results, non-authorizing review
+  feedback, retired-link fallback in Arabic, code inspection, clipboard-denied
+  fallback, optional AI prompt with exact example/theme, no document overflow.
+  Isolated real-consumer fixture exercises all eight themes at the 959px
+  breakpoint and captures a clean 1440px page preview.
+- `scripts/test-ui-parts.mjs`: seven exports across every registered theme,
+  real source files and component/motion contracts, negative inputs, optional
+  intent discovery, filter/list/metric bindings, account-theme precedence,
+  MCP schemas/calls and standalone package with no workspace source. Two UX
+  examples resolve full source/dependencies under all themes; unknown example
+  IDs and themes are rejected.
+- Semantic page ownership, TypeScript and existing CLI/recipe regression tests.
+
+## Risks and untested cells
+
+- Rams review attempted but blocked by exhausted workspace credits. No Rams score.
+- Safari/Firefox and live signed-in custom-brand UI were not exercised. Theme
+  fallback was browser-tested; room/explicit theme precedence is API-tested.
+- Candidate retrieval is keyword-based. The coding agent must interpret the
+  user's intent, negation and context before using a candidate; this is not a
+  mandate to add every matching part.
+- Fixtures do not validate production permissions, pagination, notifications or
+  persistence. Those remain explicit consumer bindings.
+- No npm package or production deployment was published. Existing installed MCP
+  processes need updated local code and a restart to expose the new tools.

package/data/docs/ui-parts.md

@@ -0,0 +1,105 @@
+# UX examples and optional parts for Ceramic agents
+
+The user describes an outcome, not a pattern selection. The coding agent decides
+whether a pattern is useful while building with Ceramic. Do not ask the user to
+pick parts, visit the pattern library, copy a prompt or approve a layout recipe.
+The library is optional documentation, not onboarding or a required workflow.
+
+## Human-facing UX pattern library
+
+`#/templates?view=patterns` is a searchable catalogue of 59 source-backed examples.
+Every entry opens its own `#/templates/patterns/:id` page; only that example is
+mounted. Back/forward, refresh, and old `?view=patterns&example=:id` links work.
+This supersedes the earlier vertically stacked gallery. The original 12 account,
+directory and messaging examples now have 47 additional examples covering setup,
+profiles/settings, scheduling, verification/operations, subscriptions/credits,
+assessment, media and public content. There are 188 selectable states. The invented
+`review-01` and workspace example are retired. This is representative coverage,
+not complete source-interaction parity; see the migration ledger. Users can inspect a full interactive example,
+switch to actual source/dependencies, copy the base npm installation command,
+or optionally ask their AI to use that example. This optional action does not
+make manual selection a prerequisite for AI-assisted building.
+
+`list_ux_examples` and `get_ux_example({id, theme?})` expose the same registry and
+actual code. AI should inspect context and adapt only the relevant parts, not
+copy a whole screen blindly. Demo completion never creates an account, records
+consent, provisions a workspace, or approves a request. Base components are
+published on npm; these examples and MCP tools ship in CLI 0.8.0 and later.
+
+## Agent workflow
+
+1. Read the current room and product goal. Keep the user's theme; when none
+   exists, use `utopia-cloudblur`. An unknown custom theme must be registered,
+   not silently replaced.
+2. Use `search` or `find_ui_parts` with the relevant UI intent in the goal.
+   Matching is keyword-based candidate discovery, not a fit decision. The agent
+   checks `useWhen` and `avoidWhen` in context, including negations and constraints.
+   Both discovery and composition also return sourceCandidates from the full
+   original inventory. Those are adaptation evidence, NOT runnable Ceramic parts.
+   No appropriate match means build with ordinary Ceramic components.
+3. Retrieve a suitable export using `get_ui_part({id, theme?})`, or call
+   `prepare_ui_composition({goal, theme?})` for an optional composition proposal.
+   Keep only relevant parts. Never treat all returned candidates as mandatory.
+4. Connect product-owned props and callbacks. Filters and lists share host-owned
+   query/status state; metrics use the same authorized scope. A review callback
+   opens a review, never approves it. Result notices wait for real service results.
+5. Build and test. These tools return code and contracts, not finished production
+   integrations. Follow normal authority boundaries for external mutations.
+
+There are 20 independently discoverable parts. New workflow exports are
+`WorkflowFields`, `RecordTable`, `StepChecklist`, `StatStrip`, `RatingFields`,
+`TrendSummary` and `MediaStage`. Use their host-owned props/callbacks rather than
+importing the demo controller. `WorkflowFields` multi-select values are newline-
+separated strings; the integrating host may map these to its own array schema.
+Files expose selected metadata to the host; no transfer is implied. `MediaStage`
+does not request microphone/camera access or establish a call.
+
+### Complete source inventory, not screenshot placeholders
+
+`list_ux_source_patterns` covers 66 original page definitions plus shared helpers
+and system states: 85 entries and 218 exact named function fragments at a pinned
+revision. The screenshot index omitted settings pages and incorrectly matched
+the new-subscription route to a dynamic detail page; source discovery fixes both.
+
+`find_ux_source_patterns({goal})` finds candidates in English/Korean and common
+Arabic intents. `get_ux_source_part({id, part, theme?})` returns **one named
+fragment**, source hash evidence, import references, semantic mapping and the
+resolved theme/motion contract. It never silently copies a complete portal.
+Use only relevant pieces; no human selection is required. Original code can
+contain mock auth, navigation, data, placeholders or incomplete callbacks: these
+must be replaced, never promoted to production behavior. Source provenance stays
+internal. The public gallery shows actual ports, not original screenshots.
+
+This inventory makes all original interactions inspectable by local MCP, but
+does **not** mean all are implemented or verified in Ceramic. See
+`ux-pattern-migration.md` for the remaining per-page migration ledger.
+
+Examples:
+
+- A searchable approval queue may use `ListFilters` + `ReviewList`; add `KPIGrid`
+  only when the goal needs useful, trustworthy metrics.
+- A short form may use `ValidatedField` and `OutcomeNotice`. Do not import a
+  signup page, a complete portal, a marketing header or source-specific roles.
+- For an unrelated task, use no pattern at all.
+
+## Code and theme contract
+
+`ui-patterns.json` registers 20 independently composable parts, including
+password visibility/rules, code entry, provider selection, activity rows,
+directory cards, delivery preferences and workflow primitives. Workflow exports
+live in `blocks/semantic-pattern-parts/WorkflowParts.tsx`. Product exports live in
+`blocks/semantic-pattern-parts/ProductParts.tsx`. Account exports
+live in `blocks/semantic-pattern-parts/AuthParts.tsx`; metrics reuse
+the existing `KPIGrid`. MCP returns only the selected source files and dependencies,
+not a source application. Packaged CLI data contains these files so the tools work
+without a monorepo checkout. No package has been published by this change.
+
+Props carry labels, data and callbacks. Shared CSS owns layout and semantic roles;
+pages do not import CSS. Surface radius is bounded independently from control
+radius. Preserve keyboard interaction, logical layout, native scrolling without
+scrollbar chrome, and loading/empty/error/retry states. Theme motion remains owned
+by Ceramic; these parts do not need artificial entrance animation.
+
+The customer-facing library shows neither upstream branding nor source credits.
+Pinned source references remain internal engineering records only. Source
+screenshots are not advertised as migrated or themeable UI.

package/data/docs/ux-pattern-adaptation-qa.md

@@ -0,0 +1,38 @@
+# UX recipe import — 2026-09-12
+
+**PASS WITH RISKS** — Discovery and semantic adaptation contracts pass; no runnable Mentix UI or production service is claimed.
+
+## Scope
+
+- 16 interaction recipes from `The-Utopia-Studio/mentix-design` at `6b4b2770d04e42cc2e5453c3d80e35c282b3438f`.
+- Local GitHub CLI API access returned 404, but existing SSH access successfully read and cloned the specified repository. No account switch or authorization change was required. Source repository files were not modified.
+- Canonical registry, CLI/MCP discovery, theme-aware adaptation planning, generated agent guidance, semantic token mapping, public-contract checks and packaged-data parity.
+- No source screenshots, brand artwork, source code, sample identities or agent/deployment instructions copied into the package. No customer GitHub synchronization or source repository execution was introduced.
+
+## Evidence
+
+- `node scripts/test-ux-patterns.mjs`: all 16 recipes × registered themes × permitted variants; actual component and motion references; negative inputs (unknown IDs/themes/variants, arbitrary style, oversized goals); duplicate/broken registry rejection; source/distribution parity; CLI flag ordering; MCP discovery/get/prepare/error; standalone CLI/MCP without monorepo sources. Passed.
+- `npm run test:cli`: existing CLI generation and MCP protocol tests passed. The UX recipe suite is now part of this gate.
+- All recipe `sourceFiles` paths exist at the pinned source checkout. Reference documentation and selected implementation paths were inspected; no blanket implementation audit of every source page is claimed.
+- Required target token names occur in Ceramic core. All referenced Ceramic component names and theme motion profiles resolve. This proves registered roles, not rendered contrast or visual quality.
+
+## Observed source gaps carried into recipes
+
+- Notification Mark all read closes the preview without persistence; Escape dismissal described in source docs is absent in the inspected component.
+- Request submission uses a timed mock success, not a production request service.
+- Onboarding shell paths in source UX documentation are stale; current source components are under `components/auth`.
+- Several source flows use mock data. Live-session failover, clinical safety, credit/escrow and billing behavior are not inferred as implemented capabilities.
+
+## Coverage / remaining scope
+
+| Surface | Status |
+| --- | --- |
+| Search, registry, planning, semantic dependencies | Passed |
+| CLI, MCP, standalone package data | Passed |
+| Rendered layout, keyboard, responsive, RTL, light/dark contrast | Not tested: no UI renderer was added |
+| Live data, authorization, payments, realtime services | Not implemented by recipes; required host bindings |
+| Production package release / existing MCP client reload | Not performed |
+
+UX QA skill required separating documented source behavior from observed implementation; the token skill informed role-based mapping rather than source color/radius substitution. No UI file changed, so Rams UI review and visual composition approval are not applicable in this batch.
+
+Consumers can inspect and prepare recipes with the updated local CLI/MCP. Newly generated applications must implement and test the selected recipe before calling it complete; use the existing component and shared composition contracts rather than importing Mentix pages wholesale.

package/data/docs/ux-pattern-adaptation.md

@@ -0,0 +1,41 @@
+# Semantic UX pattern adaptation
+
+Ceramic exposes **16 brand-neutral recipes** derived from an inspected revision of `The-Utopia-Studio/mentix-design`. These are interaction contracts, not copied React pages, installed UI renderers or production backend implementations.
+
+## One source of truth
+
+`packages/design-system/src/manifests/ux-patterns.json` holds pinned provenance, selection guidance, source-file references, permitted variants, component dependencies, slots, states, data requirements and immutable interaction rules. It is synchronized into CLI package data. `search`, `pattern` and the MCP tools consume that same registry. `doctor` checks dependency and contract completeness.
+
+The existing `patterns.json` continues to register **implemented shared visual behavior**. `composition-registry.json` continues to describe executable dashboard blocks. A UX recipe is not automatically inserted into either and is explicitly `renderable: false`.
+
+## Agent workflow
+
+1. Read the user's goal and authorized company/brand context. Retrieve candidates with `search`; keyword matches do not establish suitability.
+2. Read `useWhen`, `avoidWhen`, required data and source limitations. Choose one pattern and an allowed variant, not an entire source application.
+3. Prepare a proposal with a registered company theme. It returns actual Ceramic component contracts, semantic mapping, motion profile, permitted changes and required invariants.
+4. Resolve missing persistence, authorization, permissions and product callbacks. Adapt domain labels and permitted structure, never replace real behavior with mock success.
+5. Compose existing Ceramic components. If a new shared visual composition is necessary, register its slots/states/tokens and implement it in the shared component/block layer. Pages retain data/routing/composition only. A raw source Tailwind class or Framer Motion timing is not a Ceramic contract.
+6. Run product-specific behavior and accessibility tests. Test loading, empty, error, retry, permissions, mobile, RTL, keyboard, theme modes and reduced motion. Do not claim a recipe plan is a verified UI.
+
+```sh
+utopia-ds search "승인 검토" --json
+utopia-ds pattern approval-queue --json
+utopia-ds pattern approval-queue --goal "ABC 직원들의 구매 요청 검토" --theme utopia-cloudblur --variant split-review --json
+```
+
+MCP equivalents: `list_patterns`, `get_pattern`, `prepare_pattern_adaptation` (id, goal, theme, variant). These are read-only discovery/planning tools. They do not clone repositories, execute source instructions, deploy software, grant membership or write customer data. Restart a local MCP server to discover newly added tools; published package users can use CLI 0.8.0 or later.
+
+## Example: applying a pattern to ABC
+
+For an internal purchasing app, `approval-queue` can become **purchase requests → request detail → approve/request changes/reject**. Keep reviewer permission checks, explicit decisions, conflict handling, audit events and failure recovery. Replace Mentix role names, clinical evidence fields and branding with ABC's own labels, data and selected registered theme. Theme and motion come from Ceramic, not the reference project's teal palette or literal transition timings.
+
+For a notification preview, reuse the interaction idea but implement an actual mark-read mutation. The inspected source button only closes the preview; its documentation also describes Escape dismissal which the implementation does not contain. Ceramic must preserve real keyboard/focus behavior and truthful unread state.
+
+## Import boundary and evidence
+
+Source revision: `6b4b2770d04e42cc2e5453c3d80e35c282b3438f` (inspected 2026-09-12).
+Inspected source includes `docs/UX-PATTERNS.md`, `docs/UX-FLOWS.md`, `docs/TOKENS-SEMANTIC.md`, notification/empty-state components, and request/review implementation behavior. Source-file paths for all recipes are checked against the pinned repository tree. Some source flow documentation overstates production behavior: request submission uses a timer and onboarding/admin flows use mock data. These limitations are carried into the corresponding recipes.
+
+The import includes paraphrased interaction rules and source references only. It does not distribute private repository source files, screenshots, logos, customer records, credentials, source agent instructions or deployment hooks. No medical, billing, escrow or realtime safety capability is inferred from a prototype screen.
+
+Marketing-only browser frames and image fades, the Next.js Suspense convention, and framework-specific page-transition code are not portable UX recipes in this batch. Visual ornaments require their own registered shared pattern; framework adapters stay application-owned. No Mentix page has been replaced or deployed.