@utopia-studio-design/design-system-cli 0.6.2 → 0.7.0

package/data/docs/foundations.md

@@ -2,6 +2,33 @@
 
 Foundations define the semantic contract for humans, AI agents, themes, and reusable components. Components consume roles. Themes map those roles to visual primitives. The design-system app renders these pages at `/docs/foundations/*`.
 
+## Non-negotiable premises
+
+1. **Everything is semantic.** Every visible element must express its meaning, role, state, hierarchy, and layout intent through a registered token, component, `data-slot`, state attribute, or composition pattern.
+2. **Pages only compose.** Pages own content, routing, data binding, and orchestration. They do not own CSS, raw visual primitives, or theme decisions.
+3. **Visual ownership flows in one direction.** Semantic tokens → components and registered patterns → page composition. Themes map those roles to brand expression without changing their meaning.
+4. **A missing semantic role is a contract gap.** Do not patch the page. Extend the design-system contract, document it, register it, and then consume it.
+5. **Product surfaces are not marketing pages.** In tools, rooms, consoles, setup flows, and agent workspaces, names identify the current object rather than acting as campaign headlines. Keep them within the product heading scale. Remove decorative kickers, readiness slogans, oversized editorial type, and promotional prose unless they communicate a real state or action.
+
+Interactive elements follow the same ownership rule. Actions use the registered `Button`, `IconButton`, or selection-control pattern. A navigation CTA keeps an anchor or router link as its single semantic root and receives Button behavior through `Button asChild`. Pages must not style a raw `<a>` or `<button>` with local CSS to imitate a design-system control.
+
+The static gate `npm run audit:semantic-pages` rejects CSS files and CSS imports under `src/pages/`. Registered patterns may own CSS, but their consumers must use token roles. `npm run audit:workspace-setup` enforces that rule for workspace setup, including its external identity token and registered responsive breakpoints.
+
+Registered workflow compositions include `brand-room-empty-start` and `designer-agent-workbench`. A new Brand Room keeps compact identity, empty-state truth, first action, and setup sequence in one surface without turning the brand name or empty-state copy into a marketing hero. The designer workbench keeps journey, conversation, and created artifacts in one hierarchy; future stages never appear in the artifact register as if they already exist. Agent activity appears inside the conversation as a truthful projection of durable queued, running, checkpointed, approved, completed, or failed server events. It never claims a file read, edit, command, provider call, or external write that did not occur. Durable generated results resolve in the context/output rail. Their CSS and breakpoint contracts live in `src/patterns/`, while pages supply localized content and state only.
+
+Teams building assistant, support, or collaborative chat products use the
+[Ceramic chat service methodology](./chat-service-methodology.md). Managed chat
+workspaces resolve scrolling, live-edge following, compact tool disclosure,
+composer behavior, output separation, localization, and QA through the shared
+Chat contract rather than page-local implementations.
+
+## Ceramic Brand Identity Contract
+
+- `/brand/ceramic-logo.svg` is the canonical Ceramic logo for every product, documentation, authentication, navigation, loading, promotional, and agent-selection surface.
+- Preserve the wordmark's aspect ratio and Brick Red artwork. Scale the registered asset; do not redraw, recolor, crop, or substitute a symbol, monogram, generic icon, or generated mark.
+- Decorative repetitions use `alt=""` or `aria-hidden="true"`. A logo that identifies its surface uses the accessible name `Ceramic`.
+- Retired Ceramic symbols may remain as archival source files, but they are not approved interface assets and must not be referenced by production UI.
+
 ## Foundation Pages
 
 - `All Tokens`: complete semantic contract and required roles.
@@ -16,10 +43,13 @@ Foundations define the semantic contract for humans, AI agents, themes, and reus
 
 ## Token Contract
 
-- Use semantic roles such as `--background`, `--foreground`, `--primary`, `--secondary`, `--surface`, `--surface-elevated`, `--border`, `--ring`, `--radius-control`, `--radius-surface`, `--font-sans`, `--font-arabic-body`, and `--font-arabic-display`.
+- Use semantic roles such as `--background`, `--foreground`, `--primary`, `--secondary`, `--surface`, `--surface-elevated`, `--border`, `--ring`, `--radius-control`, `--radius-surface`, `--font-sans`, `--font-size-page-title`, `--line-height-page-title`, `--font-arabic-body`, and `--font-arabic-display`.
+- Dense product tools use the workspace role family: `--font-size-workspace-title`, `--font-size-workspace-body`, `--font-size-workspace-label`, `--line-height-workspace-body`, `--workspace-row-min-block-size`, `--workspace-panel-padding`, `--workspace-content-max-inline-size`, `--workspace-composer-min-block-size`, and `--workspace-context-rail-min-inline-size`. Agent consoles, editors, and operations workspaces consume these roles instead of introducing page-local type or spacing scales. `ChatLayout density="compact"` opts a persistent workspace conversation into the same contract without changing standalone chat defaults; generated work uses the context-rail minimum so preview, status, and review actions do not compete for space.
 - Do not hardcode Utopia Default primitives such as Brick Red, Special Black, TWK Lausanne, or IBM Plex Sans Arabic inside reusable components.
 - Use logical CSS properties: `padding-inline`, `margin-inline`, `border-inline`, `inset-inline`, `block-size`, and `inline-size`.
 - Use start/end API names instead of left/right names.
+- Reusable layout widths consume container roles such as `--container-narrow`, `--container-compact`, `--container-standard`, and `--container-wide`.
+- CSS media queries cannot interpolate custom properties. Pattern breakpoint literals therefore live in an adjacent `*.contract.json` registry and must pass the pattern audit; an unregistered breakpoint is a contract violation.
 
 ## Color Contract
 
@@ -63,7 +93,7 @@ Arabic display sizing should follow the Latin display scale at about 95%, rather
 - Controls consume `--radius-control`.
 - Cards, dialogs, popovers, and other framed surfaces consume `--radius-surface`.
 - Avatars, pills, and circular affordances may consume a round role when present.
-- Control dimensions use size roles such as `--size-control-sm`, `--size-control-md`, and `--size-control-lg`.
+- In published 0.8.2, Button dimensions use `--button-height-sm`, `--button-height`, and `--button-height-lg`; inputs use `--input-height`. Prefer the registered component size API.
 - Borders use semantic width/style roles such as `--border-width-hairline`, `--border-width-focus`, and `--border-style-default`.
 - Utopia Default can be square. Future themes may be rounded without component rewrites.
 
@@ -74,12 +104,14 @@ Arabic display sizing should follow the Latin display scale at about 95%, rather
 - Runtime recipes use four engine-neutral intents: `feedback`, `page`, `surface`, and `layout`.
 - Components consume `--motion-duration-*` and `--motion-ease-*` roles rather than hardcoded milliseconds or easing curves.
 - `MotionProvider` sets the theme profile and runtime adapter for a subtree. Motion-aware components expose `motion?: boolean` for a local override.
+- Ceramic React applications use the Framer Motion adapter by default for layout reflow, shared-layout, drag, and gesture transitions. These transitions still consume the active semantic recipe from `MotionProvider`; application code must not introduce private timing or easing values.
+- CSS transitions remain appropriate for local hover, focus, color, and other state-only micro-interactions. The design-system core stays engine-neutral so non-React consumers can use the built-in WAAPI adapter.
 - `MotionProvider asChild` applies that policy to exactly one semantic subtree root without adding a wrapper. The consumer root must accept `className`, `style`, `data-*`, and its children.
 - `motion={false}` and `prefers-reduced-motion: reduce` disable decorative movement while preserving state changes and accessibility.
 - Directional motion follows logical inline start/end and mirrors in RTL when direction carries meaning.
 - Icon motion follows the action: a bell swings from its top, download moves downward, and copy snaps once. Do not apply a generic bounce.
 - `utopia-default` uses the `ceremonial` profile, `dextrum` uses `swift`, and both `barrier-intelligence` and `renacore` use `precise`.
-- WAAPI is built in. Motion for React, Anime.js, and GSAP are optional peer adapters, so unused engines do not need to ship with an application.
+- WAAPI is built in. Framer Motion is the default React adapter; Anime.js and GSAP remain optional peer adapters, so unused engines do not need to ship with an application.
 
 ```tsx
 import { getMotionThemeProfile, MotionProvider } from '@utopia-studio-design/design-system/Motion'
@@ -121,8 +153,9 @@ The engine-neutral registry is published as `manifests/motion-profiles.json`. It
 
 - Core owns icon slots, icon-only controls, labels, and accessibility.
 - Theme manifests own icon philosophy and icon style.
-- Use `lucide-react` as the default shadcn/ui icon baseline for examples and previews.
-- Use `PhosphorIcon` when a product selects the Phosphor family. Import individual
+- Existing core components may keep their documented Lucide defaults, but theme-facing examples must follow the active theme policy.
+- `utopia-default` and `utopia-cloudblur` select Phosphor Icons for interface actions and navigation.
+- Use `PhosphorIcon` on those themed surfaces. Import individual
   `*Icon` exports from `@phosphor-icons/react` so bundlers can tree-shake unused icons.
 - `PhosphorIcon` uses `currentColor` and `--icon-size-xs|sm|md`; do not pass raw
   color or pixel sizes.
@@ -149,9 +182,10 @@ export function IconExamples() {
 }
 ```
 
-Phosphor is an additional supported family, not a silent replacement for
-Lucide-based component internals. Breadcrumb separators and existing Ceramic
-navigation defaults keep their documented icon contracts.
+Selecting Phosphor at the theme layer does not silently rewrite Lucide-based
+component internals. Compose Phosphor through the documented icon slots;
+Breadcrumb separators and existing Ceramic navigation defaults keep their
+documented contracts until their icon slot is explicitly supplied.
 
 ## Illustration Contract
 
@@ -201,3 +235,7 @@ All Tokens and the Arabic Friendly page must include or link to these RTL previe
 - Side navigation
 
 Individual Foundation pages should show a compact Arabic / RTL check instead of repeating the full product mockups.
+
+## Scrolling without scrollbar chrome
+
+Ceramic preserves native overflow scrolling while hiding scrollbar chrome globally, on both axes and during hover/focus. Do not use `scrollbar-width: thin`, reveal-on-hover scrollbars, or disable scrolling to hide a bar. Horizontal tabs must remain reachable through keyboard navigation and touch/trackpad scrolling. This contract is registered as `scroll-without-chrome` in the patterns manifest.

package/data/docs/guide.md

@@ -6,14 +6,13 @@ 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.
-- `Quick Start with AI`: dense setup workflow for AI coding tools.
-- `Working with AI`: how manifests, docs, and examples stay machine-readable.
-- `Principles`: semantic-first, shadcn-founded, theme-extensible, Arabic-friendly, AI-readable rules.
-- `Theme System`: required semantic roles, Utopia Default as first theme, and future theme boundaries.
+- `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.
-- `Styling Components`: safe component styling through semantic tokens and app-layer className.
-- `Styling Library Interop`: Tailwind, plain CSS, CSS modules, and CSS-in-JS bridges through Ceramic CSS variables.
-- `Migration Guide`: safe migration from app-local UI or raw shadcn usage into `packages/design-system`.
+- `Token System`: an architecture overview connecting theme-owned Token Values to selected Semantic Tokens and Ceramic components, followed by focused color, type, spacing, shape, motion, and elevation guidance.
+- `Icons`: supported icon libraries, accessibility, and mirroring rules.
+- `Illustrations`: intentional media usage and text-first localization rules.
+- `Packages & CLI`: package entrypoints, CLI discovery, and the shadcn/ui foundation.
 
 ## Guide Contract
 
@@ -89,8 +88,9 @@ import {
 
 ## Phosphor Icon Composition
 
-Phosphor is an optional supported icon family. It does not replace Lucide-based
-defaults inside existing Ceramic components.
+Phosphor is the selected icon family for The Utopia Studio and Utopia Cloudblur.
+It is composed through Ceramic icon slots and does not silently replace
+Lucide-based defaults inside existing components.
 
 ```tsx
 import { GearIcon } from '@phosphor-icons/react'

package/data/docs/handover-billing-aiden.md

@@ -0,0 +1,132 @@
+# Handover: Ceramic billing (Clerk + Convex + Polar)
+
+**Branch:** `feature/kp-work`
+**For:** Aiden
+**Site:** https://design.utopia-studio.co
+**Status:** Backend deployed; frontend env on Vercel is the main remaining step.
+
+---
+
+## What this PR adds
+
+- **Product layers:** `src/domain/`, `src/services/`, slim `src/utopia-os.tsx`, `convex/` billing backend
+- **Pricing page:** `#/pricing` (Polar checkout via Convex actions)
+- **Theme gating:** premium themes respect entitlements when `VITE_CERAMIC_BILLING_ENABLED=true`
+- **Docs:** `product-architecture.md`, `billing-setup.md`, architecture diagram
+
+Billing is **off by default** until Vercel env vars are set.
+
+---
+
+## Infrastructure (already configured)
+
+### Convex — team `thestudio`, project `ceramic-design-system`
+
+| | Dev | Prod |
+|---|-----|------|
+| Deployment | `nautical-goldfish-225` | `mellow-fox-829` |
+| Cloud URL | https://nautical-goldfish-225.convex.cloud | https://mellow-fox-829.convex.cloud |
+| Webhook URL | https://nautical-goldfish-225.convex.site/polar/webhook | https://mellow-fox-829.convex.site/polar/webhook |
+| Dashboard | [dev](https://dashboard.convex.dev/d/nautical-goldfish-225) | [prod](https://dashboard.convex.dev/d/mellow-fox-829) |
+
+Convex env vars are set on **both** deployments: Clerk issuer, Polar token/org/webhook secrets, `FRONTEND_URL`, `POLAR_SERVER=sandbox`.
+Secrets live in the Convex dashboard only — not in git.
+
+### Clerk — StudioOS app
+
+- Instance: `included-seahorse-61`
+- Issuer: `https://included-seahorse-61.clerk.accounts.dev`
+- JWT template: **`convex`** (required)
+- Publishable key → Vercel/local `VITE_UTOPIA_OS_CLERK_PUBLISHABLE_KEY` (ask Karan or Clerk dashboard)
+
+### Polar — org `the-utopia-studio`
+
+- Product ID (catalogue): `8ce88721-cb75-414b-9238-a8400a470d9e`
+- Checkout uses **price IDs**, not product IDs — copy a price ID from Polar → Products → ⋮ → copy price id for the `/pricing` grid
+- Webhooks registered for prod + dev Convex URLs (subscription.* events)
+
+---
+
+## Your checklist
+
+### 1. Vercel (production — design.utopia-studio.co)
+
+Set **Production** environment variables:
+
+```env
+VITE_UTOPIA_OS_CONVEX_URL=https://mellow-fox-829.convex.cloud
+VITE_UTOPIA_OS_CLERK_PUBLISHABLE_KEY=<StudioOS pk_test from Clerk>
+VITE_CERAMIC_BILLING_ENABLED=true
+VITE_UTOPIA_OS_FELLOW_ENABLED=false
+```
+
+Redeploy after saving.
+
+### 2. Clerk allowed origins
+
+StudioOS app → add:
+
+- `https://design.utopia-studio.co`
+- `http://localhost:5173`
+
+### 3. Local dev
+
+```sh
+git checkout feature/kp-work
+npm install
+cp .env.example .env.local   # then add keys (see billing-setup.md)
+npx convex dev               # optional; functions already deployed
+npm run dev
+```
+
+`.env.local` is gitignored. Karan has a working local copy with dev Convex + Clerk key.
+
+### 4. Smoke test
+
+1. Open https://design.utopia-studio.co (after Vercel env + redeploy)
+2. Sign in (Clerk)
+3. Go to `#/pricing` — plans should load from Polar
+4. Test checkout (sandbox) — success URL returns to `#/onboarding-v2?checkout=success` on the origin that opened checkout
+5. Confirm subscription row in Convex dashboard → Data → `subscriptions`
+6. Premium theme unlock on `#/themes` for subscribed user
+
+### 5. Polar products
+
+If pricing page is empty, confirm the product has **active prices** in Polar sandbox and that Convex `POLAR_ACCESS_TOKEN` has product read scope.
+
+---
+
+## Key files
+
+| Area | Path |
+|------|------|
+| Convex schema | `convex/schema.ts` |
+| Polar + webhooks | `convex/subscriptions.ts`, `convex/http.ts` |
+| Entitlements query | `convex/entitlements.ts` |
+| Domain rules | `src/domain/entitlements.ts` |
+| Client wiring | `src/services/utopia-os-client.ts`, `src/utopia-os.tsx` |
+| Pricing UI | `src/pages/PricingPage.tsx` |
+| Setup guide | `docs/design-system/billing-setup.md` |
+
+---
+
+## Known limitations / follow-ups
+
+- **Fellow / brand room:** still on Daedalus Convex — keep `VITE_UTOPIA_OS_FELLOW_ENABLED=false` on Ceramic-only deployments
+- **Polar sandbox:** `POLAR_SERVER=sandbox` on both Convex envs until go-live
+- **Team plan:** schema supports `team`; Clerk org gating not wired yet
+- **Rotate secrets:** Polar OAT and webhook secrets were shared in chat during setup — rotate in Polar if concerned
+
+---
+
+## MCP connectors (optional)
+
+Project `.cursor/mcp.json`: Convex (stdio), Clerk, Vercel. Install OAuth in Cursor Settings → MCP if agents need dashboard access.
+
+---
+
+## Questions
+
+- Karan for Clerk publishable key and Vercel project access
+- Convex dashboard for data/webhook logs
+- Polar dashboard for products and webhook delivery logs

package/data/docs/logo-maker-methodology.md

@@ -0,0 +1,109 @@
+# Ceramic Logo Maker methodology
+
+Logo Maker helps a person without design training make an informed identity
+decision. It does not declare that a logo is good because a model prefers it.
+It presents a recommendation, tests the generated artifact against shared and
+brand-specific criteria, shows visual evidence, and leaves approval to a human.
+
+## What “good” means
+
+A good logo passes two different kinds of judgment.
+
+### Universal quality gates
+
+These gates apply to every logo direction:
+
+1. **Small-size legibility** — the defining shape remains identifiable at 16px
+   and 24px without relying on fine detail.
+2. **One-color integrity** — the mark survives as one flat color for engraving,
+   embossing, photocopying, and restricted production.
+3. **Positive and reverse contrast** — approved light- and dark-surface versions
+   retain the same silhouette and visual weight.
+4. **Silhouette and spacing** — the outer contour, counters, negative space,
+   and clear space remain intentional rather than collapsing into noise.
+5. **Lockup versatility** — the registered wordmark, symbol, and compact badge
+   formats remain related and usable in their declared contexts.
+6. **Distinctiveness** — the concept has one ownable visual idea and is not
+   interchangeable with a generic category mark.
+7. **Reference independence** — selected third-party logos inform comparison
+   only; artwork, proprietary letterforms, and distinctive constructions are
+   never copied or morphed.
+8. **Production readiness** — the approved result can be redrawn as clean vector
+   geometry without gradients, effects, or detail that the brief did not require.
+
+Passing these gates does not prove trademark availability. Similarity review is
+design evidence, not legal clearance.
+
+### Brand-specific fit
+
+The agent evaluates each concept against the durable Discovery brief:
+
+- what the brand must communicate;
+- what it must never become;
+- the primary audience and usage context;
+- the selected logo structure and references;
+- the intended values and the visible feature that expresses each value; and
+- explicit constraints, such as scripts, markets, colors, or production media.
+
+A technically clean logo can still be the wrong logo when it contradicts this
+brief. Brand fit must therefore remain separate from universal craft quality.
+
+## Required response structure
+
+The durable assistant response remains Markdown and uses this order:
+
+1. `Recommended direction` — one decisive proposal with concrete construction.
+2. `Suggested palette` — named colors and `#RRGGBB` values when relevant.
+3. `Values expressed through the mark` — value-to-visible-evidence mappings.
+4. `Logo quality check` — evidence for every applicable quality gate.
+5. `Decisions needed` — no more than two unresolved choices.
+6. `Next step` — one action the user can understand without design knowledge.
+
+Do not return an unstructured wall of text or a single unexplained score.
+
+## Logo Quality Check presentation
+
+Each generated variant receives the same compact evidence board:
+
+| Check | Result | Required evidence |
+| --- | --- | --- |
+| Small-size test | Pass / Review / Fail | 16px and 24px render |
+| One-color test | Pass / Review / Fail | black or approved primary-color render |
+| Reverse test | Pass / Review / Fail | light-on-dark render |
+| Brief alignment | Strong / Partial / Weak | cited brief statement and visible response |
+| Distinctiveness | Strong / Review / Weak | defining feature and nearest-category risk |
+| Production fit | Ready / Review / Blocked | intended favicon, header, print, or badge context |
+
+The board shows evidence before judgment. A total score may summarize the board,
+but it never replaces failed checks, caveats, or comparison views. Approval stays
+disabled while a blocking check has no evidence.
+
+## Visual proof sheet
+
+Logo Maker should generate or derive these synchronized views from the actual
+selected artifact:
+
+- primary full-color lockup;
+- one-color mark;
+- reverse mark on a dark surface;
+- 16px and 24px small-size samples;
+- square and circular badge crops when the chosen structure supports them; and
+- one realistic target context such as product chrome, a web header, or print.
+
+These are evaluations of one artifact version, not separately invented logos.
+The Artifact register owns the visual files, variants, version, and approval.
+Interpretation, evidence, and unresolved decisions remain in the conversation.
+
+## Browser and MCP parity
+
+The browser and MCP both read `manifests/logo-skills.json`. The manifest exposes
+the shared quality gates, while this document defines how to interpret and show
+their evidence. An MCP client follows the same sequence:
+
+`get_room_context` → `list_logo_skills` → `prepare_logo_maker_run` → generate
+variant and proof sheet → return structured quality evidence → human review →
+checkpoint the approved artifact.
+
+Neither surface may claim that a gate passed without evaluating the generated
+artifact. A prepared prompt is not a completed quality check, and model output is
+not approval.

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

@@ -0,0 +1,53 @@
+# Presentation asset repository
+
+Keep presentation imagery in a dedicated GitHub repository. The repository is
+read-only input for presentation generation and must contain
+`ceramic.assets.json` at its root. The generator pins the commit SHA, reads the
+manifest, and uses only assets whose theme, locale, placement, aspect ratio,
+license, and usage policy match the deck.
+
+Do not add application code, install scripts, credentials, private customer
+data, or unlicensed media. Presentation tooling must never execute repository
+scripts or infer missing rights metadata.
+
+## Repository layout
+
+```text
+brand-presentation-assets/
+├── ceramic.assets.json
+├── logos/
+├── photography/
+├── illustrations/
+└── textures/
+```
+
+## Manifest example
+
+```json
+{
+  "$schema": "https://utopia-studio.co/schemas/ceramic-presentation-assets.schema.json",
+  "schemaVersion": "1.0.0",
+  "assets": [
+    {
+      "id": "studio-collaboration-01",
+      "kind": "photography",
+      "src": "photography/studio-collaboration-01.webp",
+      "alt": "A multidisciplinary team reviewing a prototype",
+      "usage": "Use for collaboration and delivery narratives; do not use as product evidence.",
+      "themes": ["utopia-default", "utopia-cloudblur"],
+      "locales": ["*"],
+      "placements": ["section-divider", "image-led", "closing"],
+      "aspectRatios": ["16:9", "3:2"],
+      "focalPoint": { "x": 0.62, "y": 0.45 },
+      "license": "Owned by The Utopia Studio",
+      "credit": "The Utopia Studio"
+    }
+  ]
+}
+```
+
+For a 12–15 slide deck, the prompt selects two to four distinct editorial
+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.

package/data/docs/product-architecture.md

@@ -0,0 +1,42 @@
+# Ceramic product architecture
+
+How the repo is layered so we can ship subscriptions without mixing product logic into the design-system packages.
+
+## Layers
+
+| Layer | Location | Owns |
+|-------|----------|------|
+| **Packages** | `packages/*` | Publishable npm artifacts (components, CLI, Clerk wrappers). No billing tables. |
+| **Domain** | `src/domain/` | Pure rules: theme access, plan tiers, entitlement checks. No React, no fetch. |
+| **Services** | `src/services/` | Convex function refs and other reusable mechanics. |
+| **Providers** | `src/utopia-os.tsx` | Orchestration: Clerk session, Convex queries, React context. |
+| **Control plane** | `convex/` | Auth-backed queries, Polar checkout, subscription webhooks. |
+| **Patterns** | `src/patterns/` | Registered semantic composition styling shared by pages; never imported by an individual page. |
+| **Pages** | `src/pages/` | Content, routing, data binding, and semantic composition only. No page-owned CSS or raw visual policy. |
+
+**Rule (from Studio Product Framework):** pages decide *when* to gate; domain decides *whether* access is allowed; Convex stores *what* the user bought.
+
+## Semantic UI ownership
+
+The UI dependency direction is fixed:
+
+```text
+semantic tokens → components / registered patterns → pages
+```
+
+- A page may select components, pass semantic variants, bind product state, and arrange registered patterns.
+- A page may not import CSS, create a page stylesheet, hardcode brand primitives, or invent a local visual variant.
+- `src/styles.css` is the application entrypoint that loads registered patterns. A page never loads pattern CSS itself.
+- If the system cannot express a required interface decision, treat that as a missing design-system contract and repair the component, pattern, manifest, or token layer first.
+- `npm run audit:semantic-pages` enforces the page boundary in local and release checks.
+
+## Convex deployments
+
+- **Ceramic `convex/`** (this repo) — subscriptions, `users`, webhooks. Point `VITE_UTOPIA_OS_CONVEX_URL` here for billing launch.
+- **Daedalus** (optional sibling) — legacy fellow/brand-room functions (`profiles:*`, `fellowDesign:*`). Still used when that deployment URL is set and billing is off.
+
+When billing is enabled, the same Convex URL must include `convex/entitlements.ts` and `convex/subscriptions.ts` from this repo.
+
+## Going live checklist
+
+See [billing-setup.md](./billing-setup.md).

package/data/docs/quick-start-ai.md

@@ -98,7 +98,6 @@ npx utopia-ds template --list --json
 npx utopia-ds template template-saas-solution-homepage --copy ./saas-solution-website
 npx utopia-ds template template-saas-solution-homepage --theme dextrum --copy ./dextrum-website
 npx utopia-ds theme utopia-default --json
-npx utopia-ds theme create nova
 npx utopia-ds docs arabic-friendly --dense
 npx utopia-ds doctor --json
 ```
@@ -161,15 +160,16 @@ messages, or raw stacks.
 
 ## Create A Theme
 
-Run this from the Ceramic Design System workspace:
+Theme creation changes the Design System source catalog; it is not available from a consumer project. Clone or open the Ceramic Design System repository, install its dependencies, and run these commands from the repository root:
 
 ```sh
-npx utopia-ds theme create nova
+npm install
+npm run ds -- theme create your-theme-name
 npm run sync-data --workspace @utopia-studio-design/design-system-cli
 npm run ds -- doctor
 ```
 
-The command creates `nova.css`, `theme-nova.json`, and registers the theme in `themes.json`. The scaffold includes dark, light, Arabic typography, shape, and semantic motion contracts. Replace its placeholder brand primitives before publishing it.
+Replace `your-theme-name` with the lowercase kebab-case ID you want for the theme. The command creates `<your-theme-name>.css`, `theme-<your-theme-name>.json`, and registers the theme in `themes.json`. The scaffold includes dark, light, Arabic typography, shape, and semantic motion contracts. Replace its placeholder brand primitives before publishing it.
 
 ## Core And Theme Boundary
 

package/data/docs/shadcn-conversion.md

@@ -31,5 +31,5 @@ Use the dense CLI output to pick the Utopia package import. If a component still
 - shadcn setup: `components.json`
 - Utopia catalog: `packages/design-system/src/manifests/catalog.json`
 - Component contracts: `packages/design-system/src/manifests/components.json`
-- Safe conversion wrappers: `packages/design-system/src/components/ShadcnPrimitives.tsx`
+- Safe conversion wrappers: `packages/design-system/src/components/Primitives.tsx`
 - Core semantic styling: `packages/design-system/src/core.css`

package/data/docs/sidebar-placement.md

@@ -0,0 +1,56 @@
+# Sidebar placement
+
+Ceramic treats sidebar placement as a logical layout preference. Pass `start` or `end` to `SidebarProvider`; do not convert the value to `left` or `right` before rendering or persistence.
+
+```tsx
+import {
+  Sidebar,
+  SidebarInset,
+  SidebarProvider,
+} from '@utopia-studio-design/design-system/Sidebar'
+
+export function WorkspaceShell({
+  direction,
+  placement = 'start',
+}: {
+  direction: 'ltr' | 'rtl'
+  placement?: 'start' | 'end'
+}) {
+  return (
+    <div dir={direction} className="workspace-shell">
+      <SidebarProvider placement={placement}>
+        <Sidebar>{/* localized navigation */}</Sidebar>
+        <SidebarInset>{/* workspace content */}</SidebarInset>
+      </SidebarProvider>
+    </div>
+  )
+}
+```
+
+The four supported mappings are:
+
+| Direction | `start` | `end` |
+| --- | --- | --- |
+| `ltr` | Physical left | Physical right |
+| `rtl` | Physical right | Physical left |
+
+Each combination uses the same semantic API:
+
+```tsx
+<div dir="ltr"><SidebarProvider placement="start">{/* left navigation */}</SidebarProvider></div>
+<div dir="ltr"><SidebarProvider placement="end">{/* right navigation */}</SidebarProvider></div>
+<div dir="rtl"><SidebarProvider placement="start">{/* right navigation */}</SidebarProvider></div>
+<div dir="rtl"><SidebarProvider placement="end">{/* left navigation */}</SidebarProvider></div>
+```
+
+`placement` defaults to `start`. Keep the semantic value in user settings so changing locale does not silently change intent. Sidebar, inset, rail, active indicator, collapsed tooltip, trigger icon, overlay, and mobile off-canvas motion all consume the same provider value.
+
+For mobile shells, render `SidebarBlockType1Trigger` in the app top bar as well as using `SidebarBlockType1`. The external trigger remains reachable while the drawer is closed. Supply every visible and accessible label from the product localization layer.
+
+When a product has a secondary workspace-tools panel, derive it as the opposite logical side:
+
+```ts
+const toolsPlacement = navigationPlacement === 'start' ? 'end' : 'start'
+```
+
+Load the persisted placement before revealing the shell, or inject it into the initial render. This avoids a hydration flash from the default `start` placement to the stored value.

package/data/docs/theme-authoring.md

@@ -4,11 +4,14 @@ Themes are token-contract and visual-policy implementations.
 
 ## Scaffold A Theme
 
+Clone or open the Ceramic Design System repository, install its dependencies, and run the authoring command from the repository root:
+
 ```sh
-npx utopia-ds theme create nova
+npm install
+npm run ds -- theme create your-theme-name
 ```
 
-Run the command from the Design System workspace. It writes the theme CSS and policy manifest and registers the theme in the catalog. Theme IDs use lowercase kebab-case. The generated colors and typography are safe placeholders, not a finished brand direction.
+`theme create` is not a consumer-project command. Replace `your-theme-name` with the lowercase kebab-case ID you want for the theme, such as `acme-dark`. The command writes the theme CSS and policy manifest into `packages/design-system` and registers the theme in the source catalog. The generated colors and typography are safe placeholders, not a finished brand direction.
 
 ## Required Read Order
 
@@ -37,7 +40,7 @@ A theme maps primitives to semantic roles and declares its own visual policy:
 
 Theme CSS owns both `[data-theme="<id>"]` and `[data-theme="<id>"][data-color-mode="light"]`. Templates set theme and color-mode attributes but must not remap brand primitives themselves.
 
-Utopia Default is strict about Brick Red, Special Black, TWK Lausanne, square geometry, and dot/bar icons. Those are not global design-system rules.
+Utopia Default is strict about Brick Red, Special Black, TWK Lausanne, square geometry, and its Phosphor icon policy. Those are not global design-system rules.
 
 ## Motion Profile