@utopia-studio-design/design-system-cli 0.8.1 → 0.8.3

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.

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

@@ -0,0 +1,111 @@
+# Complete UX source migration ledger
+
+Status: **IN PROGRESS — broad representative coverage, not full source-interaction parity.**
+
+Pinned source: `The-Utopia-Studio/mentix-design` at `6b4b2770d04e42cc2e5453c3d80e35c282b3438f`.
+Remote HEAD was checked against this revision on 2026-09-13.
+
+## What is actually done
+
+- Source inventory: 66 page definitions + shared/system helpers = 85 entries.
+- 104 indexed screenshot states, plus pages omitted from that screenshot index.
+- 218 exact named function fragments available as bounded, internal MCP evidence.
+- 59 source-backed examples on individual pages, with 188 selectable states. These represent 65 of 66 source page definitions; the original `/auth` reference index is superseded by the catalogue.
+- 20 independent Ceramic parts available to composition discovery. Fields, record tables, checklists, ratings, measures, trends and media stages extend the existing account, activity, directory and delivery parts.
+- Catalogue and individual `#/templates/patterns/:id` routes replace the stacked one-pager. Legacy example-query links remain usable.
+- The invented review and workspace examples are retired from UI/MCP discovery.
+
+"Source indexed" means readable reference code, not a semantic implementation or a production service.
+
+## Remaining parity work
+
+1. Replace remaining generic record/dashboard fixtures with source-specific columns, filters and decision states. A page mapping alone does not establish this parity.
+2. Preserve the finer onboarding interactions: credential matrices, document previews, per-item checks, orientation completion and plan comparison. Current drafts and progress are local examples, not cross-page persistence.
+3. Complete scheduling detail variations. Upcoming, pending and completed tabs now select distinct matching records; booking, feedback and assessment exercise key validations but not every original branch.
+4. Expand profile defaults, settings variants and original public-page sections. Current forms and content pages are representative compositions.
+5. Session-expiry modal remains unported; existing recovery is inline. Shared application/portal shells intentionally are not copied into the library.
+6. Compare each source fragment with its representative port before marking it complete. Live authentication, storage, payments, media and provider integration remain host responsibilities, not required side effects of gallery demos.
+
+Each port must preserve actual source interaction intent, expose useful pieces independently, replace brand-specific policies/data, map to registered Ceramic semantics, and prove the rendered consumer. Never fill a missing preview with a made-up screen or original screenshot labeled as themed.
+
+## Per-page ledger
+
+| Source page | Source-pattern ID | Gallery implementation |
+| --- | --- | --- |
+| `/auth` | `account-auth` | Reference index; replaced by the UX catalogue, not duplicated as a product flow |
+| `/forgot-password` | `account-forgot-password` | `password-recovery-01` — representative port; 4 selectable states |
+| `/invite` | `account-invite` | `invitation-01` — representative port; 4 selectable states |
+| `/locked` | `account-locked` | `account-protection-01` — representative port; 4 selectable states |
+| `/login` | `account-login` | `login-01` — representative port; 4 selectable states |
+| `/mfa` | `account-mfa` | `two-factor-01` — representative port; 4 selectable states |
+| `/onboarding/credentials` | `account-onboarding-credentials` | `credentials-01` — representative port; 5 selectable states |
+| `/onboarding/legal` | `account-onboarding-legal` | `agreements-01` — representative port; 5 selectable states |
+| `/onboarding/orientation` | `account-onboarding-orientation` | `orientation-01` — representative port; 3 selectable states; `plan-selection-01` — representative port; 3 selectable states |
+| `/onboarding` | `account-onboarding` | `setup-progress-01` — representative port; 4 selectable states |
+| `/onboarding/profile` | `account-onboarding-profile` | `profile-setup-01` — representative port; 5 selectable states |
+| `/reset-password` | `account-reset-password` | `password-reset-01` — representative port; 4 selectable states |
+| `/session-expired` | `account-session-expired` | `session-recovery-01` — representative port; 4 selectable states |
+| `/signup` | `account-signup` | `signup-01` — representative port; 3 selectable states |
+| `/verify-email` | `account-verify-email` | `verify-email-01` — representative port; 3 selectable states |
+| `/welcome` | `account-welcome` | `welcome-01` — representative port; 2 selectable states |
+| `/admin/analytics` | `admin-analytics` | `analytics-01` — representative port; 2 selectable states |
+| `/admin/audit` | `admin-audit` | `audit-log-01` — representative port; 3 selectable states |
+| `/admin/broadcasts/new` | `admin-broadcasts-new` | `broadcast-schedule-01` — representative port; 3 selectable states |
+| `/admin/broadcasts` | `admin-broadcasts` | `broadcast-management-01` — representative port; 3 selectable states |
+| `/admin/closures` | `admin-closures` | `closure-queue-01` — representative port; 3 selectable states |
+| `/admin/devices` | `admin-devices` | `device-monitoring-01` — representative port; 3 selectable states |
+| `/admin/escalations` | `admin-escalations` | `matching-escalations-01` — representative port; 3 selectable states |
+| `/admin/incidents` | `admin-incidents` | `incident-tracking-01` — representative port; 3 selectable states |
+| `/admin/onboarding/[id]` | `admin-onboarding-detail` | `verification-checklist-01` — representative port; 3 selectable states |
+| `/admin/onboarding` | `admin-onboarding` | `verification-queue-01` — representative port; 3 selectable states |
+| `/admin/payments` | `admin-payments` | `payment-cycle-01` — representative port; 3 selectable states |
+| `/admin/providers` | `admin-providers` | `provider-connections-01` — representative port; 3 selectable states |
+| `/admin/settings` | `admin-settings` | `account-settings-01` — representative port; 6 selectable states |
+| `/admin/subscriptions/[id]/allocate` | `admin-subscriptions-detail-allocate` | `credit-allocation-01` — representative port; 3 selectable states |
+| `/admin/subscriptions/[id]` | `admin-subscriptions-detail` | `subscription-detail-01` — representative port; 3 selectable states |
+| `/admin/subscriptions/new` | `admin-subscriptions-new` | `subscription-create-01` — representative port; 3 selectable states |
+| `/admin/subscriptions` | `admin-subscriptions` | `subscriptions-01` — representative port; 3 selectable states |
+| `/admin/transactions` | `admin-transactions` | `credit-transactions-01` — representative port; 3 selectable states |
+| `/marketing/blog` | `marketing-blog` | `article-library-01` — representative port; 2 selectable states |
+| `/marketing/contact` | `marketing-contact` | `contact-form-01` — representative port; 3 selectable states |
+| `/marketing` | `marketing` | `product-introduction-01` — representative port; 1 selectable states |
+| `/portal/mentor/messages` | `portal-mentor-messages` | `conversation-list-01` — representative port; 2 selectable states |
+| `/portal/mentor` | `portal-mentor` | `expert-overview-01` — representative port; 2 selectable states |
+| `/portal/mentor/profile` | `portal-mentor-profile` | `profile-editing-01` — representative port; 4 selectable states |
+| `/portal/mentor/requests/[id]` | `portal-mentor-requests-detail` | `request-decision-01` — representative port; 3 selectable states |
+| `/portal/mentor/sessions/[id]/assess` | `portal-mentor-sessions-detail-assess` | `structured-assessment-01` — representative port; 2 selectable states |
+| `/portal/mentor/settings` | `portal-mentor-settings` | `account-settings-01` — representative port; 6 selectable states |
+| `/portal/sessions/[id]/live` | `portal-sessions-detail-live` | `live-session-01` — representative port; 3 selectable states |
+| `/portal/sponsor/billing` | `portal-sponsor-billing` | `invoices-01` — representative port; 3 selectable states |
+| `/portal/sponsor` | `portal-sponsor` | `subscription-detail-01` — representative port; 3 selectable states |
+| `/portal/sponsor/profile` | `portal-sponsor-profile` | `profile-editing-01` — representative port; 4 selectable states |
+| `/portal/sponsor/sessions` | `portal-sponsor-sessions` | `session-list-01` — representative port; 3 selectable states |
+| `/portal/sponsor/settings` | `portal-sponsor-settings` | `account-settings-01` — representative port; 6 selectable states |
+| `/portal/sponsor/trainees` | `portal-sponsor-trainees` | `team-allocations-01` — representative port; 3 selectable states |
+| `/portal/trainee/competency` | `portal-trainee-competency` | `skill-progression-01` — representative port; 2 selectable states |
+| `/portal/trainee/credits` | `portal-trainee-credits` | `credit-balance-01` — representative port; 3 selectable states |
+| `/portal/trainee/mentors` | `portal-trainee-mentors` | `people-directory-01` — representative port; 3 selectable states |
+| `/portal/trainee/messages` | `portal-trainee-messages` | `conversation-list-01` — representative port; 2 selectable states |
+| `/portal/trainee/notifications` | `portal-trainee-notifications` | `notifications-01` — representative port; 4 selectable states |
+| `/portal/trainee` | `portal-trainee` | `personal-overview-01` — representative port; 3 selectable states |
+| `/portal/trainee/profile` | `portal-trainee-profile` | `profile-editing-01` — representative port; 4 selectable states |
+| `/portal/trainee/request` | `portal-trainee-request` | `booking-request-01` — representative port; 5 selectable states |
+| `/portal/trainee/sessions/[id]/feedback` | `portal-trainee-sessions-detail-feedback` | `session-feedback-01` — representative port; 2 selectable states |
+| `/portal/trainee/sessions/[id]` | `portal-trainee-sessions-detail` | `session-detail-01` — representative port; 3 selectable states |
+| `/portal/trainee/sessions/[id]/precheck` | `portal-trainee-sessions-detail-precheck` | `connectivity-check-01` — representative port; 3 selectable states |
+| `/portal/trainee/sessions` | `portal-trainee-sessions` | `session-list-01` — representative port; 3 selectable states |
+| `/portal/trainee/settings/notifications` | `portal-trainee-settings-notifications` | `notification-preferences-01` — representative port; 2 selectable states |
+| `/portal/trainee/settings` | `portal-trainee-settings` | `account-settings-01` — representative port; 6 selectable states |
+| `/portal/tv/[id]` | `portal-tv-detail` | `broadcast-viewer-01` — representative port; 3 selectable states |
+| `/portal/tv` | `portal-tv` | `media-library-01` — representative port; 3 selectable states |
+
+## Evidence and boundaries
+
+- Exact source functions and hashes: `docs/design-system/ux-source-evidence/` (internal, never customer attribution).
+- Source registry: `packages/design-system/src/manifests/ux-source-inventory.json`.
+- CLI source read-only tools: list_ux_source_patterns, find_ux_source_patterns, get_ux_source_part.
+- Public gallery only renders entries registered in ux-examples.json.
+- No accounts, messages, uploads, payments, media permission, security changes, commits, deployment or npm publishing occurred.
+- Source token mappings are adaptation guidance requiring slot-level decisions, not a global string replacement or proof of theme compliance.
+- Browser QA: all 59 routes and 188 exposed states across the existing 8-theme matrix; desktop/mobile Chromium, 959px and Arabic/360px. Validation, file-type rejection, allocation limits, verification prerequisites, assessment gating, record lifecycle and local media/chat behavior have targeted tests. This is not a pixel/interaction parity check of every upstream fragment.
+- Rams quick_review blocked by account review quota; no score exists.

package/data/docs/ux-pattern-publish-2026-09-13.md

@@ -0,0 +1,31 @@
+# UX pattern package and website release — 2026-09-13
+
+Built on current production commit b04761f, incorporating UX-only commit
+077596e and retaining existing Brandbook MCP discovery and preparation tools.
+
+Published packages: design-system 0.11.0 and design-system-cli 0.8.0.
+Includes 59 runnable UX examples, 20 semantic parts, 16 adaptation recipes,
+and an evidence inventory of 85 entries / 218 fragments. Evidence entries
+are not a claim that all original interactions have been implemented.
+
+Validation: package/app builds, bundle budgets, CLI/MCP and standalone bundle
+checks, semantic page ownership, and 38 desktop/mobile Chromium tests passed.
+An initial browser run overlapped package rebuilding; the isolated rerun passed
+all 38. Downloaded public npm tarballs verified all 59 examples, UX and existing
+Brandbook MCP calls, plus all nine template commands and documented tokens.
+The website release snapshot was generated from those public tarballs.
+
+Rams quick_review and review_files were both requested, but the workspace
+allowance was exhausted. No Rams score is claimed.
+
+Production authentication/backend environment settings are preserved. This
+release does not deploy Convex or include unrelated local room/auth changes.
+
+## Concurrent release reconciliation
+
+A separate Brandbook task published CLI 0.8.1 during this release without the
+UX APIs. CLI 0.8.2 combines both releases: all UX APIs and source bundles,
+Brandbook validation, and version-pinned generated MCP launch configuration.
+CLI tests passed again; public 0.8.2 tarball verification covers UX discovery,
+Brandbook tool retention and validation, all 59 examples, and nine templates.
+Final versions: design-system 0.11.0, design-system-cli 0.8.2.

package/data/docs/ux-pattern-release-2026-09-13.md

@@ -0,0 +1,26 @@
+# UX-only production merge
+
+Scope: 59 representative UX examples, 188 selectable states, 20 independent
+semantic parts, catalogue/detail routing, source inventory, CLI/MCP discovery
+and adaptation logic. Based on `origin/main` e669f43; no local room/auth/billing,
+Convex, environment, domain, dependency or unrelated brand changes are included.
+
+PASS WITH RISKS: clean npm installation, design-system build, app production
+build, bundle budgets, CLI/MCP/standalone tests, semantic page ownership, and
+38 desktop/mobile Chromium tests passed in the isolated release worktree.
+Detailed interaction parity remains incomplete as recorded in the migration ledger.
+No npm release is part of this merge; existing npm versions are unchanged.
+
+Bounded input geometry is applied only inside UX examples. The shared token
+definitions do not restyle existing room consumers. Current membership guards
+are preserved for catalogue and nested detail routes.
+
+Rams quick_review and pre-commit review_files were requested but the workspace
+review quota is exhausted, so no score was obtained. Its one partial warning
+about the pre-existing presentation thumbnail does not reproduce from the
+stylesheet: its parent reserves 16/10 aspect ratio and the image fills that area.
+No baseline or guard was weakened. Browser-engine parity and live authenticated
+account-specific chrome remain untested. npm reported existing dependency audit
+findings (24 total, including 3 high); dependency files are unchanged.
+
+Room validation is a separate local task; production room code is unchanged.