@almadar/skills 1.1.3 → 1.2.1

package/dist/index.js

@@ -3,6 +3,7 @@ import { join } from 'path';
 import { generateBehaviorsDocs, getAllBehaviors, generateModulesDocs, getAllStdOperators } from '@almadar/std';
 import { OPERATORS, UI_SLOTS, PATTERN_TYPES, ViewTypeSchema } from '@almadar/core/types';
 import { getPatternPropsCompact, getPatternActionsRef, getAllPatternTypes } from '@almadar/patterns';
+import { BINDING_DOCS, CORE_BINDINGS } from '@almadar/core';
 
 // src/generators/utils.ts
 function formatFrontmatter(fm) {
@@ -204,7 +205,7 @@ Trait State Machine \u2192 render-ui \u2192 UI Component \u2192 User Action \u21
 | **One trait per slot** | Each slot (main, modal, drawer) owned by ONE trait |
 | **INIT renders UI** | Every trait needs INIT self-loop to render initial UI |
 | **One page per entity** | Use trait's render-ui for create/edit/view, not separate pages |
-| **form-section has onSubmit** | Connects form to trait events |
+| **form-section has submitEvent** | Connects form to trait events (NOT onSubmit!) |
 | **std/* are templates** | Guide LLM generation, not runtime code |
 
 ### Slot Ownership
@@ -215,7 +216,7 @@ Trait State Machine \u2192 render-ui \u2192 UI Component \u2192 User Action \u21
 \u2502 TaskManagement trait OWNS:                  \u2502
 \u2502   \u2022 main \u2192 entity-table, page-header        \u2502
 \u2502   \u2022 modal \u2192 form-section (create/edit)      \u2502
-\u2502   \u2022 drawer \u2192 entity-detail (view)           \u2502
+\u2502   \u2022 drawer \u2192 detail-panel (view)            \u2502
 \u2502                                             \u2502
 \u2502 NO other trait should render to these slots \u2502
 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518
@@ -273,6 +274,7 @@ function getCriticalErrors() {
 ### 1. INIT Transition Required (CRITICAL)
 
 Every trait MUST have an INIT self-loop transition. The runtime fires \`INIT\` when page loads.
+The INIT render-ui MUST be a **single composed stack**, not flat calls:
 
 \`\`\`json
 {
@@ -280,8 +282,19 @@ Every trait MUST have an INIT self-loop transition. The runtime fires \`INIT\` w
   "to": "Browsing",
   "event": "INIT",
   "effects": [
-    ["render-ui", "main", { "type": "page-header", ... }],
-    ["render-ui", "main", { "type": "entity-table", ... }]
+    ["render-ui", "main", {
+      "type": "stack", "direction": "vertical", "gap": "lg",
+      "children": [
+        { "type": "stack", "direction": "horizontal", "justify": "between", "align": "center",
+          "children": [
+            { "type": "typography", "variant": "h1", "text": "Title" },
+            { "type": "button", "label": "Create", "event": "CREATE", "variant": "primary" }
+          ]
+        },
+        { "type": "entity-table", "entity": "EntityName", "columns": ["..."], "searchable": true,
+          "itemActions": [{ "label": "View", "event": "VIEW" }] }
+      ]
+    }]
   ]
 }
 \`\`\`
@@ -377,10 +390,11 @@ WRONG: Two traits both render to "main" on page load
 CORRECT: ONE trait owns each slot
 \`\`\`
 
-### 9. Missing onSubmit in form-section
+### 9. Missing submitEvent in form-section
 \`\`\`
 WRONG: { "type": "form-section", "entity": "Task" }
-CORRECT: { "type": "form-section", "entity": "Task", "onSubmit": "SAVE" }
+ALSO WRONG: { "type": "form-section", "entity": "Task", "onSubmit": "SAVE" }
+CORRECT: { "type": "form-section", "entity": "Task", "submitEvent": "SAVE", "cancelEvent": "CANCEL" }
 \`\`\`
 
 ### 10. Duplicate Transitions (Same from+event)
@@ -404,7 +418,7 @@ CORRECT: { "pages": [{ "traits": [...] }] } - UI comes from render-ui effects
 ### 13. Using form-actions Pattern (DOES NOT EXIST!)
 \`\`\`
 WRONG: ["render-ui", "main", { "type": "form-actions", "actions": [...] }]
-CORRECT: Use form-section with onSubmit/onCancel props
+CORRECT: Use form-section with submitEvent/cancelEvent props
 \`\`\`
 Actions are INSIDE patterns, not separate patterns.
 
@@ -453,7 +467,7 @@ function getValidationHintsSection() {
 | ORB_P_MISSING_TRAITS | Add \`traits\` array to page with at least one trait ref |
 | ORB_E_INVALID_FIELD_TYPE | Use valid type: string, number, boolean, date, enum, relation. NOT entity names! |
 | ORB_INIT_MISSING | Add INIT self-loop transition with render-ui effects |
-| ORB_FORM_SUBMIT | Add onSubmit event name to form-section pattern |
+| ORB_FORM_SUBMIT | Add submitEvent and cancelEvent to form-section pattern |
 | ORB_DUPE_TRANS | Add guards to differentiate same-event transitions |
 | ORB_SLOT_CONTENTION | Merge traits or use different slots |
 | ORB_DUPE_PAGE_TRAITS | Remove duplicate trait references from page |
@@ -743,145 +757,461 @@ Orbitals communicate via events:
 - Add relatedLinks for navigation between related records
 `;
 }
+function getBindingsGuide() {
+  const lines = [
+    "## Valid Binding References",
+    "",
+    "Bindings reference runtime values using `@root.path` syntax:",
+    "",
+    "| Binding | Description | Example |",
+    "|---------|-------------|---------|"
+  ];
+  for (const [bindingKey, docs] of Object.entries(BINDING_DOCS)) {
+    const example = docs.examples[0] || `@${bindingKey}`;
+    lines.push(`| \`@${bindingKey}\` | ${docs.description} | \`${example}\` |`);
+  }
+  lines.push(
+    "",
+    "### Binding Rules",
+    "",
+    "- `@entity.field` - Access entity fields (e.g., `@entity.status`, `@entity.count`)",
+    "- `@payload.field` - Access event payload data (read-only)",
+    "- `@state` - Current state name (no path)",
+    "- `@now` - Current timestamp (no path)",
+    "- `@config.field` - Trait configuration values",
+    "",
+    "### Common Mistakes",
+    "",
+    "| \u274C Invalid | \u2705 Correct |",
+    "|------------|------------|",
+    '| `@count` | Use `stats` pattern or static text (e.g., `"Total Tasks"`) |',
+    "| `@count:status=pending` | Use filtered entity-table or static labels |",
+    "| `@entity.task.title` | `@entity.title` (entity type is implicit) |",
+    "| `@payload.field` in `set` effect | `@entity.field` (set modifies entity only) |",
+    ""
+  );
+  return lines.join("\n");
+}
+function getBindingsCompact() {
+  const validBindings = CORE_BINDINGS.map((b) => `@${b}`).join(", ");
+  return `Valid bindings: ${validBindings}`;
+}
+function getBindingContextRules() {
+  return `
+## Binding Context Rules
+
+| Context | Allowed Bindings | Notes |
+|---------|-----------------|-------|
+| Guards | @entity, @payload, @state, @now | Read-only conditions |
+| Effects | @entity, @payload, @state, @now | @entity can be modified via set |
+| Ticks | @entity, @state, @now | No payload (no event) |
+| Render-UI | @entity, @payload, @state, @config | Display values only |
+
+**Critical Rule:** The ".set" effect ONLY modifies @entity fields.
+`.trim();
+}
+
+// src/prompts/skill-sections/pattern-design-guide.ts
 function getRenderUIDesignGuide() {
-  return `## Render-UI Design Guide
+  return `## Render-UI Atomic Composition Guide (v5.0)
 
-### Syntax
-\`["render-ui", slot, { "type": pattern, ...props }]\`
-Clear slot: \`["render-ui", "modal", null]\`
+### The Five Rules of Sophisticated Composition (MANDATORY)
+
+Every render-ui effect MUST satisfy ALL five rules:
+
+| Rule | Requirement | Validation |
+|------|-------------|------------|
+| **1** | **Single Render-UI** per transition | One render-ui effect only |
+| **2** | **Three Atomic Levels** | Atoms (2+) + Molecules (1+) + Organisms (1+) |
+| **3** | **Layout Wrapper** | Root must be stack/box/container/grid |
+| **4** | **Theme Variables** | ALL visual props use CSS vars |
+| **5** | **Template Quality** | Match CrudTemplate/ListTemplate sophistication |
 
-### Slot Strategy
-| Slot | Use For | Composable? |
-|------|---------|-------------|
-| \`main\` | Primary content | **YES** \u2014 stack multiple render-ui calls |
-| \`modal\` | Forms (create/edit), confirmations | One at a time |
-| \`drawer\` | Detail views, quick edits | One at a time |
-| \`sidebar\` | Navigation, persistent filters | One at a time |
-| \`overlay\` | Confirmations, alerts | One at a time |
+---
 
-### Pattern Selection by Intent
-| Intent | Patterns | Key Props |
-|--------|----------|-----------|
-| List/browse data | \`entity-table\`, \`entity-cards\`, \`entity-list\` | columns, itemActions, searchable |
-| Show metrics/KPIs | \`stats\` | metrics: [{label, value, icon, trend}] |
-| Filter/search | \`filter-group\`, \`search-input\` | filters (from entity enum fields) |
-| Create/edit form | \`form-section\` | fields, submitEvent, cancelEvent |
-| View details | \`entity-detail\`, \`detail-panel\` | fields/fieldNames, actions |
-| Organize content | \`tabs\` | tabs: [{label, content}] |
-| Dashboard layout | \`dashboard-grid\` | columns (number) |
-| Charts | \`chart\` | chartType, data, xAxis, yAxis |
-| Progress | \`progress-bar\`, \`meter\` | value, max, label |
-| Timeline | \`timeline\` | items: [{date, title, description}] |
-| Page heading | \`page-header\` | title, subtitle, actions |
-| Confirmation | \`confirmation\` | title, message, onConfirm, onCancel |
-| Master/detail | \`master-detail\` | Split list + detail |
-| Cards grid | \`entity-cards\` | columns, itemActions, layout |
+### Rule 1: Single Render-UI Per Transition
 
-### Composition Recipes
+Each transition executes exactly ONE render-ui effect with composed children:
 
-**CRUD Browsing INIT** (most common \u2014 compose ALL of these in main slot):
 \`\`\`json
-["render-ui", "main", { "type": "page-header", "title": "Tasks", "subtitle": "Manage your tasks", "actions": [{ "label": "New Task", "event": "CREATE", "variant": "primary" }] }],
-["render-ui", "main", { "type": "stats", "entity": "Task", "metrics": [{ "label": "Total", "value": "@count", "icon": "clipboard" }, { "label": "Active", "value": "@count:status=active", "icon": "clock" }, { "label": "Done", "value": "@count:status=done", "icon": "check-circle" }] }],
-["render-ui", "main", { "type": "entity-table", "entity": "Task", "columns": ["title", "status", "createdAt"], "searchable": true, "itemActions": [{ "label": "View", "event": "VIEW" }, { "label": "Edit", "event": "EDIT" }, { "label": "Delete", "event": "DELETE" }] }]
-\`\`\`
+// \u2705 CORRECT: Single render-ui with composed children
+{
+  "from": "Browsing",
+  "to": "Browsing",
+  "event": "INIT",
+  "effects": [
+    ["render-ui", "main", {
+      "type": "stack",
+      "direction": "vertical",
+      "gap": "lg",
+      "children": [
+        { "type": "page-header", "title": "...", "actions": [...] },
+        { "type": "entity-table", "entity": "...", ... }
+      ]
+    }]
+  ]
+}
 
-**Dashboard INIT**:
+// \u274C WRONG: Multiple flat render-ui calls
+{
+  "effects": [
+    ["render-ui", "main", { "type": "page-header", ... }],
+    ["render-ui", "main", { "type": "entity-table", ... }]
+  ]
+}
 \`\`\`
-main: page-header \u2192 title + date range actions
-main: dashboard-grid \u2192 columns: 3
-main: stats \u2192 computed KPIs from entity counts
-main: chart \u2192 primary data visualization
-main: entity-cards \u2192 recent items (limit: 6)
+
+---
+
+### Rule 2: Three Atomic Levels Required
+
+Every composition MUST contain ALL three levels:
+
+#### Level 1: Atoms (Minimum 2 distinct types)
+
+| Type | Purpose | Example Usage |
+|------|---------|---------------|
+| \`typography\` | All text content | Headlines, labels, body text |
+| \`badge\` | Status indicators | Active, Pending, Completed |
+| \`button\` | User actions | Create, Edit, Delete |
+| \`avatar\` | User/entity images | Profile pictures |
+| \`icon\` | Decorative icons | Plus, Edit, Trash |
+| \`progress-bar\` | Progress indicators | Upload progress |
+| \`divider\` | Visual separation | Section dividers |
+
+#### Level 2: Molecules (Minimum 1)
+
+| Type | Purpose | Example Usage |
+|------|---------|---------------|
+| \`box\` | Visual containers | Stat cards, panels |
+| \`card\` | Content grouping | Feature cards |
+| \`modal\` | Dialog overlays | Create/edit forms |
+| \`drawer\` | Side panels | Detail views |
+| \`tabs\` | Content organization | Filter tabs |
+| \`alert\` | Notifications | Success/error messages |
+| \`accordion\` | Collapsible sections | FAQ, settings |
+
+#### Level 3: Organisms (Minimum 1 for data views)
+
+| Type | Purpose | Example Usage |
+|------|---------|---------------|
+| \`entity-table\` | Data tables | List views |
+| \`form-section\` | Forms | Create/edit |
+| \`detail-panel\` | Detail views | View record |
+| \`page-header\` | Page headers | Title + actions |
+| \`chart\` | Data visualization | Analytics |
+| \`timeline\` | Chronological events | Activity history |
+| \`stats\` | KPI metrics | Dashboard stats |
+
+---
+
+### Rule 3: Layout-First Structure
+
+Root element MUST be a layout primitive:
+
+\`\`\`json
+// \u2705 CORRECT: Layout wrappers
+{ "type": "stack", "direction": "vertical", "gap": "lg", "children": [...] }
+{ "type": "stack", "direction": "horizontal", "gap": "md", "children": [...] }
+{ "type": "box", "padding": "lg", "bg": "var(--color-card)", "children": [...] }
+{ "type": "container", "size": "xl", "padding": "lg", "children": [...] }
+{ "type": "grid", "cols": 3, "gap": "md", "children": [...] }
+
+// \u274C WRONG: No layout wrapper
+{ "type": "page-header", "title": "..." }
+{ "type": "entity-table", "entity": "..." }
 \`\`\`
 
-**Detail View (drawer)**:
+#### Layout Props Reference
+
+**Stack (VStack/HStack)**
+\`\`\`json
+{
+  "type": "stack",
+  "direction": "vertical" | "horizontal",
+  "gap": "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl",
+  "align": "start" | "center" | "end" | "stretch",
+  "justify": "start" | "center" | "end" | "between" | "around",
+  "wrap": true | false
+}
 \`\`\`
-drawer: entity-detail \u2192 all fields + [Edit, Delete] actions
-drawer: tabs \u2192 related collections (if entity has relation fields)
+
+**Box**
+\`\`\`json
+{
+  "type": "box",
+  "padding": "none" | "xs" | "sm" | "md" | "lg" | "xl",
+  "bg": "var(--color-card)" | "var(--color-muted)" | "var(--color-primary)",
+  "border": true | false,
+  "borderColor": "var(--color-border)",
+  "rounded": "var(--radius-none)" | "var(--radius-sm)" | "var(--radius-md)" | "var(--radius-lg)" | "var(--radius-xl)",
+  "shadow": "var(--shadow-none)" | "var(--shadow-sm)" | "var(--shadow-md)" | "var(--shadow-lg)"
+}
 \`\`\`
 
-**Wizard Flow**:
+**Container**
+\`\`\`json
+{
+  "type": "container",
+  "size": "sm" | "md" | "lg" | "xl" | "full",
+  "padding": "none" | "xs" | "sm" | "md" | "lg" | "xl"
+}
 \`\`\`
-main: wizard-progress \u2192 steps array + currentStep
-main: wizard-container \u2192 current step content
-main: wizard-navigation \u2192 Back/Next/Submit buttons
+
+**Grid**
+\`\`\`json
+{
+  "type": "grid",
+  "cols": 1 | 2 | 3 | 4 | 6 | 12 | { "sm": 1, "md": 2, "lg": 3 },
+  "gap": "none" | "xs" | "sm" | "md" | "lg" | "xl"
+}
 \`\`\`
 
-### Layout Composition (stack, box, grid)
+---
+
+### Rule 4: Theme Variable Enforcement
 
-Layout patterns wrap other patterns via \`children\` arrays for rich, structured views.
+ALL visual properties MUST use CSS theme variables:
 
-**VStack** (vertical stack): \`{ "type": "stack", "direction": "vertical", ... }\`
-**HStack** (horizontal stack): \`{ "type": "stack", "direction": "horizontal", ... }\`
-**Box** (styled container): \`{ "type": "box", ... }\`
+| Property | \u2705 CORRECT | \u274C WRONG |
+|----------|-----------|----------|
+| Colors | "var(--color-primary)" | "#3b82f6", "blue", "white" |
+| Backgrounds | "var(--color-card)" | "#ffffff", "white" |
+| Text colors | "var(--color-foreground)" | "#000000", "black" |
+| Spacing | "var(--spacing-lg)" | "16px", "1rem" |
+| Radius | "var(--radius-md)" | "8px", "0.5rem" |
+| Shadows | "var(--shadow-sm)" | "0 2px 4px rgba(0,0,0,0.1)" |
 
-#### Stack Props
-| Prop | Values | Default |
-|------|--------|---------|
-| \`direction\` | \`"vertical"\`, \`"horizontal"\` | \`"vertical"\` |
-| \`gap\` | \`"none"\`, \`"xs"\`, \`"sm"\`, \`"md"\`, \`"lg"\`, \`"xl"\` | \`"md"\` |
-| \`align\` | \`"start"\`, \`"center"\`, \`"end"\`, \`"stretch"\` | \`"stretch"\` |
-| \`justify\` | \`"start"\`, \`"center"\`, \`"end"\`, \`"between"\`, \`"around"\` | \`"start"\` |
-| \`wrap\` | \`true\`, \`false\` | \`false\` |
+---
+
+### Rule 5: Template-Quality Composition
+
+Match the sophistication of reference templates in \`packages/almadar-ui/components/templates/\`.
+
+#### CrudTemplate Structure
+\`\`\`
+Container (size: xl, padding: lg)
+  \u2514\u2500\u2500 VStack (gap: lg)
+      \u251C\u2500\u2500 PageHeader (title + actions)
+      \u251C\u2500\u2500 Alert (error state)
+      \u251C\u2500\u2500 EntityTable (searchable, sortable, actions)
+      \u2514\u2500\u2500 Modal (form-section for create/edit)
+\`\`\`
+
+#### ListTemplate Structure
+\`\`\`
+Container (size: md, padding: lg)
+  \u2514\u2500\u2500 VStack (gap: lg)
+      \u251C\u2500\u2500 Typography (h2 title)
+      \u251C\u2500\u2500 Input (search)
+      \u251C\u2500\u2500 HStack (filter buttons)
+      \u2514\u2500\u2500 VStack (list items)
+\`\`\`
+
+#### Dashboard Structure
+\`\`\`
+Container (size: full, padding: lg)
+  \u2514\u2500\u2500 Grid (cols: { sm: 1, md: 2, lg: 4 })
+      \u251C\u2500\u2500 Box (stat card 1)
+      \u251C\u2500\u2500 Box (stat card 2)
+      \u251C\u2500\u2500 Box (stat card 3)
+      \u2514\u2500\u2500 Box (stat card 4)
+\`\`\`
 
-#### Box Props
-| Prop | Values |
-|------|--------|
-| \`padding\` / \`paddingX\` / \`paddingY\` | \`"none"\`, \`"xs"\`, \`"sm"\`, \`"md"\`, \`"lg"\`, \`"xl"\` |
-| \`bg\` | \`"default"\`, \`"muted"\`, \`"card"\`, \`"primary"\`, \`"secondary"\`, \`"accent"\` |
-| \`border\` | \`true\`, \`false\` |
-| \`rounded\` | \`"none"\`, \`"sm"\`, \`"md"\`, \`"lg"\`, \`"full"\` |
-| \`shadow\` | \`"none"\`, \`"sm"\`, \`"md"\`, \`"lg"\` |
+#### Stats Cards - Static Text Only
 
-#### Grid Props
-| Prop | Values |
-|------|--------|
-| \`cols\` | \`1\`\u2013\`12\` or \`{ sm: 1, md: 2, lg: 3 }\` |
-| \`gap\` | \`"none"\`, \`"xs"\`, \`"sm"\`, \`"md"\`, \`"lg"\`, \`"xl"\` |
+For stats/overview sections, use **static text labels**, NOT computed bindings:
 
-#### Nesting Example \u2014 Page Header + Stats Row + Table
 \`\`\`json
-["render-ui", "main", {
-  "type": "stack", "direction": "vertical", "gap": "lg",
+// \u2705 CORRECT: Static text for labels
+{
+  "type": "box",
+  "padding": "md",
+  "bg": "var(--color-card)",
   "children": [
-    { "type": "stack", "direction": "horizontal", "justify": "between", "align": "center",
-      "children": [
-        { "type": "typography", "variant": "h1", "text": "Orders" },
-        { "type": "button", "label": "New Order", "event": "CREATE", "variant": "primary" }
-      ]
-    },
-    { "type": "stack", "direction": "horizontal", "gap": "md", "wrap": true,
-      "children": [
-        { "type": "box", "padding": "md", "bg": "card", "border": true, "rounded": "md",
-          "children": [{ "type": "stats", "metrics": [{ "label": "Total", "value": "@count" }] }]
-        },
-        { "type": "box", "padding": "md", "bg": "card", "border": true, "rounded": "md",
-          "children": [{ "type": "stats", "metrics": [{ "label": "Pending", "value": "@count:status=pending" }] }]
-        }
+    { "type": "typography", "variant": "caption", "text": "Total Tasks" },
+    { "type": "typography", "variant": "h2", "text": "--" }
+  ]
+}
+
+// \u2705 CORRECT: Using stats pattern with entity
+{
+  "type": "stats",
+  "entity": "Task",
+  "label": "Total Tasks"
+}
+
+// \u274C WRONG: Invented computed bindings
+{ "text": "@count" }
+{ "text": "@count:status=pending" }
+\`\`\`
+
+---
+
+### Validated Example: Task Management
+
+This example has been validated with \`npx @almadar/cli validate\`:
+
+\`\`\`json
+{
+  "name": "Taskly",
+  "version": "1.0.0",
+  "orbitals": [{
+    "name": "Task Management",
+    "entity": {
+      "name": "Task",
+      "collection": "tasks",
+      "fields": [
+        { "name": "title", "type": "string", "required": true },
+        { "name": "status", "type": "enum", "values": ["pending", "active", "done"] },
+        { "name": "priority", "type": "enum", "values": ["low", "medium", "high"] }
       ]
     },
-    { "type": "entity-table", "entity": "Order", "columns": ["customer", "total", "status"], "searchable": true }
-  ]
-}]
+    "traits": [{
+      "name": "TaskInteraction",
+      "category": "interaction",
+      "linkedEntity": "Task",
+      "emits": [{ "event": "INIT", "scope": "internal" }],
+      "stateMachine": {
+        "states": [
+          { "name": "Browsing", "isInitial": true },
+          { "name": "Creating" }
+        ],
+        "events": [
+          { "key": "INIT", "name": "Initialize" },
+          { "key": "CREATE", "name": "Create" },
+          { "key": "SAVE", "name": "Save", "payload": [{ "name": "data", "type": "object" }] },
+          { "key": "CANCEL", "name": "Cancel" }
+        ],
+        "transitions": [
+          {
+            "from": "Browsing",
+            "to": "Browsing",
+            "event": "INIT",
+            "effects": [
+              ["render-ui", "main", {
+                "type": "stack",
+                "direction": "vertical",
+                "gap": "lg",
+                "children": [
+                  {
+                    "type": "page-header",
+                    "title": "Task Management",
+                    "actions": [{ "label": "Create Task", "event": "CREATE", "variant": "primary" }]
+                  },
+                  {
+                    "type": "entity-table",
+                    "entity": "Task",
+                    "columns": ["title", "status", "priority"],
+                    "searchable": true,
+                    "itemActions": [
+                      { "label": "Edit", "event": "EDIT" },
+                      { "label": "Delete", "event": "DELETE" }
+                    ]
+                  }
+                ]
+              }]
+            ]
+          },
+          {
+            "from": "Browsing",
+            "to": "Creating",
+            "event": "CREATE",
+            "effects": [
+              ["render-ui", "modal", {
+                "type": "form-section",
+                "entity": "Task",
+                "fields": ["title", "status", "priority"],
+                "submitEvent": "SAVE",
+                "cancelEvent": "CANCEL"
+              }]
+            ]
+          },
+          {
+            "from": "Creating",
+            "to": "Browsing",
+            "event": "SAVE",
+            "effects": [
+              ["persist", "create", "Task", "@payload.data"],
+              ["render-ui", "modal", null],
+              ["emit", "INIT"]
+            ]
+          },
+          {
+            "from": "Creating",
+            "to": "Browsing",
+            "event": "CANCEL",
+            "effects": [
+              ["render-ui", "modal", null]
+            ]
+          }
+        ]
+      }
+    }],
+    "pages": [{
+      "name": "TasksPage",
+      "path": "/tasks",
+      "viewType": "list",
+      "isInitial": true,
+      "entity": "Task",
+      "traits": [{ "ref": "TaskInteraction" }]
+    }],
+    "emits": [],
+    "listens": []
+  }]
+}
+\`\`\`
+
+---
+
+${getBindingsGuide()}
+
+---
+
+### Critical Validation Rules
+
+| Element | Correct Format | Wrong Format | Error |
+|---------|----------------|--------------|-------|
+| **Events** | \`{ "key": "INIT", "name": "Init" }\` | \`"INIT"\` | ORB_T_EVT_INVALID_FORMAT |
+| **Emits** | \`[{ "event": "INIT", "scope": "internal" }}]\` | \`["INIT"]\` | ORB_T_UNDEFINED_TRAIT |
+| **Payload events** | \`{ "key": "SAVE", "payload": [...] }\` | No payload | ORB_BINDING_PAYLOAD_FIELD_UNDECLARED |
+| **Page traits** | \`{ "ref": "TraitName" }\` | With linkedEntity | ORB_P_INVALID_TRAIT_REF |
+| **Category** | \`"category": "interaction"\` | Missing | ORB_T_MISSING_CATEGORY |
+
+---
+
+### Composition Quality Checklist
+
+Before calling \`finish_task\`, verify:
+
+\`\`\`
+\u25A1 Single render-ui per transition
+\u25A1 Root element is layout (stack/box/container/grid)
+\u25A1 Contains 2+ atoms (typography, badge, button, etc.)
+\u25A1 Contains 1+ molecules (box, card, tabs, alert)
+\u25A1 Contains 1+ organisms (entity-table, form-section, page-header)
+\u25A1 Uses theme variables for ALL visual properties
+\u25A1 Has 3+ distinct sections (header, content, actions)
+\u25A1 Matches template quality from almadar-ui/components/templates/
+\u25A1 Passes npx @almadar/cli validate with zero errors
 \`\`\`
 
-#### When to Use Layout Patterns
-- **VStack**: Default page layout \u2014 stack header, content sections, tables vertically
-- **HStack**: Side-by-side elements \u2014 stat cards, action buttons, header with controls
-- **Box**: Visual grouping \u2014 cards, panels, highlighted sections with borders/backgrounds
-- **Grid**: Equal-width columns \u2014 dashboard cards, stat grids, gallery layouts
+---
+
+### BANNED Patterns
 
-> **Tip**: A single \`render-ui\` call with a top-level \`stack\` containing nested children produces a more cohesive layout than multiple flat \`render-ui\` calls to the same slot.
+| Wrong | Correct |
+|-------|---------|
+| Multiple flat render-ui calls | Single composed render-ui |
+| Root organism without layout | Layout wrapper required |
+| Hex colors | Theme CSS variables |
+| Pixel values | Theme spacing variables |
+| Events as strings \`"INIT"\` | Event objects \`{ "key": "INIT" }\` |
+| Emits as strings \`["INIT"]\` | Emit objects \`[{ "event": "INIT" }]\` |
+| \`onSubmit\` / \`onCancel\` | \`submitEvent\` / \`cancelEvent\` |
+| \`headerActions\` | \`actions\` |
 
-### Domain-Aware Pattern Selection
-| Domain | List Pattern | Extras |
-|--------|-------------|--------|
-| business/admin | \`entity-table\` (searchable) | \`stats\`, \`filter-group\` |
-| ecommerce | \`entity-cards\` | \`stats\` (revenue), \`chart\` |
-| content/CMS | \`entity-cards\` | \`tabs\`, \`media-gallery\` |
-| dashboard | \`dashboard-grid\` | \`stats\`, \`chart\`, \`meter\`, \`timeline\` |
-| workflow | \`entity-table\` | \`progress-bar\`, \`timeline\` |
+---
 
 ${getPatternPropsCompact()}
 
@@ -889,6 +1219,244 @@ ${getPatternActionsRef()}
 `;
 }
 
+// src/prompts/skill-sections/theme-guide.ts
+function getThemeGuide() {
+  return `## Theme Variable System (MANDATORY)
+
+All visual properties MUST use CSS theme variables. Never use hardcoded values.
+
+### \u274C BANNED: Hardcoded Values
+
+| Type | Wrong | Why |
+|------|-------|-----|
+| Hex colors | "#3b82f6", "#ffffff", "#000000" | Not themeable |
+| Named colors | "white", "black", "red", "blue" | Not themeable |
+| Pixel values | "16px", "8px", "24px" | Not scalable |
+| Rem values | "1rem", "0.5rem" | Inconsistent |
+| Arbitrary values | "0 2px 4px rgba(0,0,0,0.1)" | Not themeable |
+
+### \u2705 REQUIRED: Theme Variables
+
+### Color Variables
+
+| Variable | Usage | Example Context |
+|----------|-------|-----------------|
+| \`var(--color-foreground)\` | Primary text | Headlines, body text |
+| \`var(--color-muted-foreground)\` | Secondary text | Captions, labels, hints |
+| \`var(--color-background)\` | Page background | Main container bg |
+| \`var(--color-card)\` | Card backgrounds | Box containers, panels |
+| \`var(--color-muted)\` | Subtle sections | Alternating rows, disabled states |
+| \`var(--color-primary)\` | Primary actions | Main buttons, active states |
+| \`var(--color-primary-foreground)\` | Text on primary | Button labels |
+| \`var(--color-secondary)\` | Secondary actions | Secondary buttons |
+| \`var(--color-secondary-foreground)\` | Text on secondary | Secondary button labels |
+| \`var(--color-success)\` | Success states | Completed badges, success alerts |
+| \`var(--color-warning)\` | Warnings | Warning badges, alerts |
+| \`var(--color-destructive)\` | Errors, delete | Danger buttons, error states |
+| \`var(--color-border)\` | Borders, dividers | Card outlines, separators |
+| \`var(--color-input)\` | Input backgrounds | Form field backgrounds |
+| \`var(--color-ring)\` | Focus rings | Input focus states |
+
+### Spacing Variables
+
+| Variable | Value | Usage |
+|----------|-------|-------|
+| \`var(--spacing-xs)\` | 4px | Tight gaps, icon spacing |
+| \`var(--spacing-sm)\` | 8px | Small gaps, compact layouts |
+| \`var(--spacing-md)\` | 12px | Standard gaps |
+| \`var(--spacing-lg)\` | 16px | Large gaps, section padding |
+| \`var(--spacing-xl)\` | 24px | Extra large gaps |
+| \`var(--spacing-2xl)\` | 32px | Page-level spacing |
+| \`var(--spacing-3xl)\` | 48px | Major section spacing |
+| \`var(--spacing-4xl)\` | 64px | Hero section spacing |
+
+### Radius Variables
+
+| Variable | Value | Usage |
+|----------|-------|-------|
+| \`var(--radius-none)\` | 0px | Sharp corners |
+| \`var(--radius-sm)\` | 2px | Small elements, tags |
+| \`var(--radius-md)\` | 6px | Buttons, inputs, small cards |
+| \`var(--radius-lg)\` | 8px | Cards, panels, modals |
+| \`var(--radius-xl)\` | 12px | Large containers |
+| \`var(--radius-2xl)\` | 16px | Extra large containers |
+| \`var(--radius-full)\` | 9999px | Pills, avatars, badges |
+
+### Shadow Variables
+
+| Variable | Usage |
+|----------|-------|
+| \`var(--shadow-none)\` | Flat design, no elevation |
+| \`var(--shadow-sm)\` | Subtle elevation, cards |
+| \`var(--shadow-md)\` | Cards, dropdowns, popovers |
+| \`var(--shadow-lg)\` | Modals, dialogs |
+| \`var(--shadow-xl)\` | High elevation elements |
+| \`var(--shadow-2xl)\` | Maximum elevation |
+
+### Pattern-Specific Examples
+
+#### Box / Card Container
+\`\`\`json
+{
+  "type": "box",
+  "padding": "lg",
+  "bg": "var(--color-card)",
+  "border": true,
+  "borderColor": "var(--color-border)",
+  "rounded": "var(--radius-lg)",
+  "shadow": "var(--shadow-sm)"
+}
+\`\`\`
+
+#### Typography
+\`\`\`json
+// Page title
+{
+  "type": "typography",
+  "variant": "h1",
+  "text": "Page Title",
+  "color": "var(--color-foreground)"
+}
+
+// Secondary text
+{
+  "type": "typography",
+  "variant": "caption",
+  "text": "Label text",
+  "color": "var(--color-muted-foreground)"
+}
+
+// Success text
+{
+  "type": "typography",
+  "variant": "body",
+  "text": "Completed",
+  "color": "var(--color-success)"
+}
+\`\`\`
+
+#### Button (use variant, not manual colors)
+\`\`\`json
+// Primary action
+{
+  "type": "button",
+  "label": "Save",
+  "event": "SAVE",
+  "variant": "primary"
+}
+
+// Secondary action
+{
+  "type": "button",
+  "label": "Cancel",
+  "event": "CANCEL",
+  "variant": "secondary"
+}
+
+// Danger action
+{
+  "type": "button",
+  "label": "Delete",
+  "event": "DELETE",
+  "variant": "danger"
+}
+\`\`\`
+
+#### Badge (variant maps to semantic colors)
+\`\`\`json
+{
+  "type": "badge",
+  "text": "Active",
+  "variant": "primary"
+}
+
+{
+  "type": "badge",
+  "text": "Completed",
+  "variant": "success"
+}
+
+{
+  "type": "badge",
+  "text": "Pending",
+  "variant": "warning"
+}
+
+{
+  "type": "badge",
+  "text": "Error",
+  "variant": "danger"
+}
+\`\`\`
+
+#### Stack Layout
+\`\`\`json
+{
+  "type": "stack",
+  "direction": "vertical",
+  "gap": "lg",
+  "align": "stretch",
+  "justify": "start"
+}
+\`\`\`
+
+### Theme Validation Checklist
+
+Before calling \`finish_task\`, verify:
+
+- [ ] No hex colors (#fff, #000, #3b82f6, etc.)
+- [ ] No named colors (white, black, red, blue, etc.)
+- [ ] No pixel values (16px, 8px, 24px, etc.)
+- [ ] No rem values (1rem, 0.5rem, etc.)
+- [ ] All colors use var(--color-*)
+- [ ] All spacing uses var(--spacing-*)
+- [ ] All radius uses var(--radius-*)
+- [ ] All shadows use var(--shadow-*)
+
+### Auto-Correction Reference
+
+The system will auto-correct these common mistakes:
+
+| Wrong | Auto-Corrected To |
+|-------|-------------------|
+| "#fff" or "white" | "var(--color-background)" |
+| "#000" or "black" | "var(--color-foreground)" |
+| "#3b82f6" | "var(--color-primary)" |
+| "#10b981" | "var(--color-success)" |
+| "#f59e0b" | "var(--color-warning)" |
+| "#ef4444" | "var(--color-destructive)" |
+| "16px" | "var(--spacing-lg)" |
+| "8px" | "var(--spacing-sm)" |
+| "24px" | "var(--spacing-xl)" |
+| "8px" (radius) | "var(--radius-md)" |
+`;
+}
+function getBannedProps() {
+  return `## BANNED PROPS (NEVER USE)
+
+| Wrong Prop | Correct Prop | Pattern |
+|------------|--------------|---------|
+| \`onSubmit\` | \`submitEvent\` | form-section |
+| \`onCancel\` | \`cancelEvent\` | form-section |
+| \`headerActions\` | \`actions\` | detail-panel |
+| \`loading\` | \`isLoading\` | all patterns |
+| \`fieldNames\` | \`fields\` | detail-panel, form-section |
+| \`onConfirm\` | (use event transitions) | confirmation |
+| \`placement\` | (remove) | itemActions |
+| \`isDestructive\` | (use variant: "danger") | itemActions |
+
+### Banned Value Patterns
+
+| Wrong | Correct |
+|-------|---------|
+| Hex colors: "#3b82f6" | Theme vars: "var(--color-primary)" |
+| Named colors: "white", "red" | Theme vars: "var(--color-background)" |
+| Pixel values: "16px" | Theme vars: "var(--spacing-lg)" |
+| Events as strings: "INIT" | Event objects: { "key": "INIT", "name": "Init" } |
+| Emits as strings: ["INIT"] | Emit objects: [{ "event": "INIT", "scope": "internal" }] |
+`;
+}
+
 // src/prompts/skill-sections/custom-traits.ts
 function getCustomTraitSection() {
   return `## Custom Trait Guide
@@ -968,7 +1536,7 @@ Every \`interaction\` trait MUST have:
             "title": "In Review"
           }],
           ["render-ui", "main", {
-            "type": "entity-detail",
+            "type": "detail-panel",
             "entity": "Document",
             "fieldNames": ["title", "content"]
           }],
@@ -1004,7 +1572,7 @@ Every \`interaction\` trait MUST have:
             "title": "Published!"
           }],
           ["render-ui", "main", {
-            "type": "entity-detail",
+            "type": "detail-panel",
             "entity": "Document"
           }]
         ]
@@ -1148,7 +1716,7 @@ When traits need to communicate across orbitals, you MUST:
 | \`page-header\` | \`actions: [{label, event}]\` | Top-right buttons (New, Export) |
 | \`form-section\` | \`onSubmit\`, \`onCancel\` | Form submit/cancel buttons |
 | \`entity-table\` | \`itemActions: [{label, event}]\` | Row action buttons (Edit, Delete) |
-| \`entity-detail\` | \`headerActions: [{label, event}]\` | Detail view header buttons |
+| \`detail-panel\` | \`actions: [{label, event}]\` | Detail view header buttons |
 | \`confirmation\` | \`onConfirm\`, \`onCancel\` | Confirmation dialog buttons |
 `;
 }
@@ -1557,7 +2125,7 @@ function getCommonFixPatternsSection() {
 | \`entity-table\` | itemActions | \`"itemActions": [{ "label": "Edit", "event": "EDIT" }]\` |
 | \`form-section\` | onSubmit | \`"onSubmit": "SAVE"\` |
 | \`form-section\` | fields | \`"fields": ["field1", "field2"]\` |
-| \`entity-detail\` | fieldNames | \`"fieldNames": ["field1", "field2"]\` |
+| \`detail-panel\` | fields | \`"fields": ["field1", "field2"]\` |
 | \`page-header\` | actions | \`"actions": [{ "label": "New", "event": "CREATE" }]\` |`;
 }
 function getOverGenerationSection() {
@@ -2020,6 +2588,14 @@ ${getSExprQuickRef()}
 
 ${includeDesignGuide ? getRenderUIDesignGuide() : ""}
 
+${includeDesignGuide ? `---
+
+${getThemeGuide()}
+
+---
+
+${getBannedProps()}` : ""}
+
 ${stdSection}
 ---
 
@@ -2131,55 +2707,29 @@ finish_task({ appName: "App" })
 # Reads .orbitals/*.json \u2192 schema.json \u2192 orbital validate
 \`\`\`
 
-### Phase 4: DESIGN REFINEMENT (optional but recommended)
-
-After \`finish_task\` produces \`schema.json\`, enhance key transitions with \`design_transition\`.
-
-**When to use**: INIT transitions (they benefit most from rich composition \u2014 header + stats + content), and CREATE/VIEW transitions for polished forms and detail views.
-
-**Step-by-step:**
-
-1. Call \`design_transition\` for the transition:
-\`\`\`json
-{
-  "from": "Browsing", "to": "Browsing", "event": "INIT",
-  "slot": "main", "entityName": "Task",
-  "entityFields": [{"name": "title", "type": "string"}, {"name": "status", "type": "enum", "values": ["pending", "active", "done"]}],
-  "domainCategory": "business"
-}
-\`\`\`
-Returns: \`{ "success": true, "effects": [["render-ui", "main", {...}], ...] }\`
-
-2. Extract the orbital chunk:
-\`\`\`json
-{ "file": "schema.json", "type": "orbital", "name": "Task Management" }
-\`\`\`
-
-3. Edit the chunk file: replace render-ui effects in the target transition with the designed effects. **Keep all non-render-ui effects** (persist, emit, set) \u2014 only replace the render-ui tuples.
+### Phase 4: VERIFY COMPOSITION QUALITY
 
-4. Apply the chunk back:
-\`\`\`json
-{ "chunkId": "<id from extract_chunk>" }
-\`\`\`
+Before calling \`finish_task\`, verify each INIT transition:
 
-**Splicing rule**: For a transition with mixed effects like:
-\`\`\`json
-[["persist", "create", "Task", "@payload.data"], ["render-ui", "modal", null], ["emit", "INIT"]]
-\`\`\`
-Keep \`persist\` and \`emit\`, replace \`render-ui\` with the designed effects.
-For INIT transitions (render-ui only), replace all effects.
+1. **Uses a single \`render-ui\` call** with top-level \`stack\` and \`children\` \u2014 NOT flat sequential calls
+2. **Has 3+ composed sections**: header (HStack: title + action), metrics (HStack/Grid of Box cards), data (entity-table/entity-cards)
+3. **Uses domain-appropriate atoms**: \`badge\` for status, \`typography\` for labels/values, \`button\` for actions
+4. **Props are correct**: \`submitEvent\` not \`onSubmit\`, \`actions\` not \`headerActions\`, \`fields\` not \`fieldNames\`
 
-**Skip design_transition for**: SAVE, CANCEL, CONFIRM_DELETE transitions (they have persist/emit effects with simple slot-clearing \u2014 no UI to design).
+If any INIT transition is flat (just \`page-header\` + \`entity-table\`), redesign it as a composed VStack hierarchy before finishing.
 `;
 }
 function getMinimalExample() {
   return `---
 
-## Example: Task Manager
+## Example: Task Manager (Atomic Composition - VALIDATED)
+
+This example passes \`npx @almadar/cli validate\` with zero errors:
 
 \`\`\`json
 {
   "name": "Taskly",
+  "version": "1.0.0",
   "orbitals": [{
     "name": "Task Management",
     "entity": {
@@ -2194,40 +2744,51 @@ function getMinimalExample() {
       "name": "TaskInteraction",
       "category": "interaction",
       "linkedEntity": "Task",
+      "emits": [{ "event": "INIT", "scope": "internal" }],
       "stateMachine": {
         "states": [
           { "name": "Browsing", "isInitial": true },
-          { "name": "Creating" },
-          { "name": "Viewing" },
-          { "name": "Editing" },
-          { "name": "Deleting" }
+          { "name": "Creating" }
+        ],
+        "events": [
+          { "key": "INIT", "name": "Initialize" },
+          { "key": "CREATE", "name": "Create" },
+          { "key": "SAVE", "name": "Save", "payload": [{ "name": "data", "type": "object" }] },
+          { "key": "CANCEL", "name": "Cancel" }
         ],
-        "events": ["INIT", "CREATE", "VIEW", "EDIT", "DELETE", "SAVE", "CANCEL", "CONFIRM_DELETE"],
         "transitions": [
           {
             "from": "Browsing", "to": "Browsing", "event": "INIT",
             "effects": [
-              ["render-ui", "main", { "type": "page-header", "title": "Tasks", "subtitle": "Manage your tasks", "actions": [{ "label": "New Task", "event": "CREATE", "variant": "primary" }] }],
-              ["render-ui", "main", { "type": "stats", "entity": "Task", "metrics": [{ "label": "Total", "value": "@count", "icon": "clipboard" }, { "label": "Active", "value": "@count:status=active", "icon": "clock" }, { "label": "Done", "value": "@count:status=done", "icon": "check-circle" }] }],
-              ["render-ui", "main", { "type": "entity-table", "entity": "Task", "columns": ["title", "status"], "searchable": true, "itemActions": [{ "label": "View", "event": "VIEW" }, { "label": "Edit", "event": "EDIT" }, { "label": "Delete", "event": "DELETE" }] }]
+              ["render-ui", "main", {
+                "type": "stack", "direction": "vertical", "gap": "lg",
+                "children": [
+                  { "type": "stack", "direction": "horizontal", "justify": "between", "align": "center",
+                    "children": [
+                      { "type": "typography", "variant": "h1", "text": "Tasks" },
+                      { "type": "button", "label": "New Task", "event": "CREATE", "variant": "primary" }
+                    ]
+                  },
+                  { "type": "stack", "direction": "horizontal", "gap": "md", "wrap": true,
+                    "children": [
+                      { "type": "box", "padding": "md", "bg": "var(--color-card)", "border": true, "rounded": "var(--radius-md)",
+                        "children": [{ "type": "typography", "variant": "caption", "text": "Total" }, { "type": "typography", "variant": "h2", "text": "@count" }] },
+                      { "type": "box", "padding": "md", "bg": "var(--color-card)", "border": true, "rounded": "var(--radius-md)",
+                        "children": [{ "type": "typography", "variant": "caption", "text": "Active" }, { "type": "badge", "variant": "primary", "text": "@count:status=active" }] },
+                      { "type": "box", "padding": "md", "bg": "var(--color-card)", "border": true, "rounded": "var(--radius-md)",
+                        "children": [{ "type": "typography", "variant": "caption", "text": "Done" }, { "type": "badge", "variant": "success", "text": "@count:status=done" }] }
+                    ]
+                  },
+                  { "type": "entity-table", "entity": "Task", "columns": ["title", "status"], "searchable": true,
+                    "itemActions": [{ "label": "View", "event": "VIEW" }, { "label": "Edit", "event": "EDIT" }, { "label": "Delete", "event": "DELETE" }] }
+                ]
+              }]
             ]
           },
           {
             "from": "Browsing", "to": "Creating", "event": "CREATE",
             "effects": [["render-ui", "modal", { "type": "form-section", "entity": "Task", "fields": ["title", "status"], "submitEvent": "SAVE", "cancelEvent": "CANCEL" }]]
           },
-          {
-            "from": "Browsing", "to": "Viewing", "event": "VIEW",
-            "effects": [["render-ui", "drawer", { "type": "entity-detail", "entity": "Task", "actions": [{ "label": "Edit", "event": "EDIT" }, { "label": "Delete", "event": "DELETE", "variant": "danger" }] }]]
-          },
-          {
-            "from": "Browsing", "to": "Editing", "event": "EDIT",
-            "effects": [["render-ui", "modal", { "type": "form-section", "entity": "Task", "fields": ["title", "status"], "submitEvent": "SAVE", "cancelEvent": "CANCEL" }]]
-          },
-          {
-            "from": "Browsing", "to": "Deleting", "event": "DELETE",
-            "effects": [["render-ui", "overlay", { "type": "confirmation", "title": "Delete Task?", "message": "This action cannot be undone." }]]
-          },
           {
             "from": "Creating", "to": "Browsing", "event": "SAVE",
             "effects": [["persist", "create", "Task", "@payload.data"], ["render-ui", "modal", null], ["emit", "INIT"]]
@@ -2235,15 +2796,7 @@ function getMinimalExample() {
           {
             "from": "Creating", "to": "Browsing", "event": "CANCEL",
             "effects": [["render-ui", "modal", null]]
-          },
-          {
-            "from": "Viewing", "to": "Browsing", "event": "CANCEL",
-            "effects": [["render-ui", "drawer", null]]
-          },
-          {
-            "from": "Editing", "to": "Browsing", "event": "SAVE",
-            "effects": [["persist", "update", "Task", "@payload.data"], ["render-ui", "modal", null], ["emit", "INIT"]]
-          },
+          }
           {
             "from": "Editing", "to": "Browsing", "event": "CANCEL",
             "effects": [["render-ui", "modal", null]]
@@ -2259,24 +2812,35 @@ function getMinimalExample() {
         ]
       }
     }],
-    "pages": [{ "name": "TasksPage", "path": "/tasks", "traits": [{ "ref": "TaskInteraction" }] }]
+    "pages": [{
+      "name": "TasksPage",
+      "path": "/tasks",
+      "viewType": "list",
+      "isInitial": true,
+      "entity": "Task",
+      "traits": [{ "ref": "TaskInteraction" }]
+    }],
+    "emits": [],
+    "listens": []
   }]
 }
 \`\`\`
 
-**Key points**:
-- ONE page (TasksPage) not four (list/create/edit/view)
-- INIT transition composes **multiple patterns**: page-header + stats + entity-table
-- States are OBJECTS with \`isInitial\` flag
-- **Actions are INSIDE patterns (use unified props)**:
-  - \`page-header\` has \`actions: [{label, event, variant}]\`
-  - \`entity-table\` has \`itemActions: [{label, event}]\` and \`searchable: true\`
-  - \`form-section\` has \`submitEvent\` and \`cancelEvent\` (NOT onSubmit/onCancel!)
-  - \`entity-detail\` has \`actions\` (NOT headerActions!)
-  - \`confirmation\` emits action events
-  - \`stats\` has \`metrics: [{label, value, icon}]\`
-- **NEVER use**: \`onSubmit\`, \`onCancel\`, \`headerActions\`, \`loading\` (use \`isLoading\`)
-- NO separate "form-actions" pattern - it doesn't exist!
+**Key points \u2014 Atomic Composition**:
+- **INIT uses a SINGLE \`render-ui\` call** with a top-level \`stack\` containing composed \`children\`
+- **3 sections composed**: header (HStack: title + button), metrics (HStack of Box stat cards), data (entity-table)
+- **Atoms used**: \`typography\` (h1, h2, caption), \`badge\` (status indicators), \`button\` (actions)
+- **Layout used**: \`stack\` (vertical page, horizontal rows), \`box\` (stat cards)
+- **Organism used**: \`entity-table\` with searchable + itemActions
+- **Theme variables**: All colors use \`var(--color-*)\`, spacing uses \`var(--spacing-*)\`, radius uses \`var(--radius-*)\`
+
+**Validation Rules** (MANDATORY):
+- Events: \`{ "key": "INIT", "name": "Initialize" }\` \u2014 NOT \`"INIT"\`
+- Emits: \`[{ "event": "INIT", "scope": "internal" }]\` \u2014 NOT \`["INIT"]\`
+- Payload events MUST declare payload: \`{ "key": "SAVE", "payload": [{ "name": "data", "type": "object" }] }\`
+- Page traits: \`{ "ref": "TaskInteraction" }\` \u2014 NOT with linkedEntity
+- Props: \`submitEvent\` (not \`onSubmit\`), \`actions\` (not \`headerActions\`), \`fields\` (not \`fieldNames\`)
+- Theme: All visual properties use CSS variables
 `;
 }
 
@@ -2285,9 +2849,9 @@ function generateKflowOrbitalsSkill(compact = false) {
   const frontmatter = {
     name: "kflow-orbitals",
     description: "Generate KFlow schemas using the Orbitals composition model. Decomposes applications into atomic Orbital Units (Entity x Traits x Patterns) with structural caching for efficiency.",
-    allowedTools: ["Read", "Write", "Edit", "generate_orbital", "design_transition", "finish_task", "query_schema_structure", "extract_chunk", "apply_chunk"],
-    version: "4.1.0"
-    // v4.1: design refinement workflow with design_transition
+    allowedTools: ["Read", "Write", "Edit", "generate_orbital", "finish_task", "query_schema_structure", "extract_chunk", "apply_chunk"],
+    version: "5.0.0"
+    // v5.0: atomic composition (removed design_transition, single-pass design)
   };
   const content = generateLeanOrbitalSkill({
     includeExample: true,
@@ -2608,7 +3172,7 @@ Output the complete updated domain language text.
 2. **Follow naming conventions** - PascalCase for entities/pages, camelCase for fields
 3. **Include all required fields** - Every entity needs at least one field
 4. **Define page paths** - Use RESTful URL patterns
-5. **Match patterns to view types** - list\u2192entity-list, detail\u2192entity-detail, create/edit\u2192form-section
+5. **Match patterns to view types** - list\u2192entity-list/entity-table, detail\u2192detail-panel, create/edit\u2192form-section
 `.trim();
   return {
     name: "domain-language",
@@ -2616,353 +3180,6 @@ Output the complete updated domain language text.
     content
   };
 }
-function getMinimalTypeReference() {
-  return `
-## Orbital Schema Structure
-
-\`\`\`typescript
-interface OrbitalDefinition {
-  name: string;              // Entity name (PascalCase)
-  entity: Entity;            // Data model
-  traits: TraitRef[];        // State machines (names or definitions)
-  pages: Page[];             // Routes and views
-  emits?: string[];          // Events this orbital emits
-  listens?: EventListener[]; // Events this orbital listens to
-}
-\`\`\`
-
-### Entity Fields
-
-\`\`\`typescript
-{ name: "title", type: "string", required: true }
-{ name: "count", type: "number", default: 0 }
-{ name: "status", type: "enum", values: ["pending", "active", "done"] }
-{ name: "dueDate", type: "date" }
-\`\`\`
-
-### Trait State Machine
-
-\`\`\`typescript
-{
-  states: [{ name: "Idle", isInitial: true }, { name: "Active" }],
-  events: ["INIT", "ACTIVATE", "COMPLETE"],
-  transitions: [
-    { from: "Idle", to: "Active", event: "ACTIVATE",
-      guards: [["condition"]],
-      effects: [["action"]] }
-  ]
-}
-\`\`\`
-`.trim();
-}
-function getPatternTypesCompact() {
-  const patterns = getAllPatternTypes();
-  return `
-## Available Pattern Types
-
-${patterns.map((p) => `- \`${p}\``).join("\n")}
-
-${getPatternPropsCompact()}
-`.trim();
-}
-function getSExprQuickRef2() {
-  const operators = Object.keys(OPERATORS).slice(0, 15);
-  return `
-## S-Expression Quick Reference
-
-### Guard Expressions (Conditions)
-
-\`\`\`typescript
-["=", "@entity.status", "active"]        // Equality
-[">", "@entity.count", 0]                 // Greater than
-["and", ["cond1"], ["cond2"]]            // Logical AND
-["or", ["cond1"], ["cond2"]]             // Logical OR
-["not", ["condition"]]                    // Logical NOT
-\`\`\`
-
-### Effect Expressions (Actions)
-
-\`\`\`typescript
-["set", "@entity.field", value]          // Update field
-["emit", "EVENT_NAME", payload]          // Emit event
-["navigate", "/path"]                     // Navigate to route
-["render-ui", "main", { type, props }]   // Render pattern
-["persist", "create", "Entity", data]    // Database operation
-\`\`\`
-
-### Available Operators
-
-${operators.map((op) => `- \`${op}\``).join("\n")}
-`.trim();
-}
-function getRenderUIQuickRef2() {
-  const slots = UI_SLOTS;
-  return `
-## Render-UI Effect Reference
-
-### Syntax
-
-\`\`\`typescript
-["render-ui", slot, patternConfig | null]
-\`\`\`
-
-### UI Slots
-
-${slots.map((slot) => `- \`${slot}\``).join("\n")}
-
-### Example
-
-\`\`\`typescript
-["render-ui", "main", {
-  type: "entity-table",
-  entity: "Task",
-  columns: ["title", "status"],
-  itemActions: [{ label: "Edit", event: "EDIT" }]
-}]
-\`\`\`
-
-Clear slot: \`["render-ui", "modal", null]\`
-`.trim();
-}
-function getFieldTypesCompact() {
-  return `
-## Field Types
-
-| Type | Example | Notes |
-|------|---------|-------|
-| \`string\` | \`{ name: "title", type: "string" }\` | Text |
-| \`number\` | \`{ name: "count", type: "number" }\` | Integer or float |
-| \`boolean\` | \`{ name: "active", type: "boolean" }\` | true/false |
-| \`date\` | \`{ name: "birthday", type: "date" }\` | Date only |
-| \`timestamp\` | \`{ name: "createdAt", type: "timestamp" }\` | Date + time |
-| \`enum\` | \`{ name: "status", type: "enum", values: ["a", "b"] }\` | Fixed options |
-| \`array\` | \`{ name: "tags", type: "array", items: "string" }\` | List |
-| \`relation\` | \`{ name: "user", type: "relation", relation: { entity: "User", cardinality: "one" } }\` | Foreign key |
-
-### Field Properties
-
-- \`required: true\` - Must have value
-- \`default: value\` - Default value
-- \`unique: true\` - Must be unique
-`.trim();
-}
-
-// src/generators/kflow-design.ts
-function getTransitionContextGuide() {
-  return `## Transition Context
-
-You receive a single transition to design. Use these inputs to make UI decisions:
-
-### Input Fields
-| Field | What It Tells You |
-|-------|-------------------|
-| \`from\` | Current state (e.g., "Browsing", "Creating") |
-| \`to\` | Target state (e.g., "Browsing", "Viewing") |
-| \`event\` | What the user did (e.g., "INIT", "CREATE", "VIEW") |
-| \`currentSlot\` | Which slot to render into (\`main\`, \`modal\`, \`drawer\`) |
-| \`entity\` | Entity name + fields (drives column/field selection) |
-| \`designHints\` | Style + UX hints from decomposition |
-| \`domainContext\` | Category + vocabulary (drives pattern choice) |
-| \`existingEffects\` | Current render-ui effects (if enhancing) |
-
-### Decision Flow
-
-\`\`\`
-1. What EVENT is this?
-   \u251C\u2500 INIT \u2192 Compose full page layout (header + content + data)
-   \u251C\u2500 CREATE/EDIT \u2192 Form in modal or drawer
-   \u251C\u2500 VIEW \u2192 Detail in drawer or inline
-   \u251C\u2500 DELETE \u2192 Confirmation in overlay
-   \u2514\u2500 SAVE/CANCEL \u2192 Clear slot (return null)
-
-2. What SLOT?
-   \u251C\u2500 main \u2192 Compose multiple patterns (stack them)
-   \u251C\u2500 modal \u2192 Single form or confirmation
-   \u251C\u2500 drawer \u2192 Detail view or quick edit form
-   \u2514\u2500 overlay \u2192 Confirmation dialog
-
-3. What DOMAIN?
-   \u251C\u2500 business \u2192 entity-table + stats + filter-group
-   \u251C\u2500 dashboard \u2192 dashboard-grid + chart + stats
-   \u251C\u2500 ecommerce \u2192 entity-cards + stats (revenue)
-   \u251C\u2500 content \u2192 entity-cards + tabs + media
-   \u2514\u2500 workflow \u2192 timeline + progress-bar
-
-4. What ENTITY FIELDS suggest?
-   \u251C\u2500 enum fields \u2192 filter-group, badge columns
-   \u251C\u2500 date fields \u2192 timeline, date columns
-   \u251C\u2500 number fields \u2192 stats, chart, meter
-   \u251C\u2500 relation fields \u2192 tabs for related collections
-   \u2514\u2500 image/url fields \u2192 entity-cards (visual)
-\`\`\``;
-}
-function getLayoutCompositionGuide() {
-  return `## Layout Composition
-
-Use layout patterns to create structured, visually rich views.
-
-### Stack (VStack / HStack)
-\`{ "type": "stack", "direction": "vertical"|"horizontal", "gap": "sm"|"md"|"lg", "children": [...] }\`
-
-### Box (Styled Container)
-\`{ "type": "box", "padding": "md", "bg": "card", "border": true, "rounded": "md", "children": [...] }\`
-
-### Grid (Multi-Column)
-\`{ "type": "grid", "cols": 3, "gap": "md", "children": [...] }\`
-
-### Composition Patterns
-
-**Page Layout** \u2014 VStack wrapping all content:
-\`\`\`json
-["render-ui", "main", {
-  "type": "stack", "direction": "vertical", "gap": "lg",
-  "children": [
-    { "type": "page-header", "title": "...", "actions": [...] },
-    { "type": "stack", "direction": "horizontal", "gap": "md", "wrap": true,
-      "children": [
-        { "type": "box", "padding": "md", "bg": "card", "border": true, "rounded": "md",
-          "children": [{ "type": "stats", "metrics": [...] }] },
-        { "type": "box", "padding": "md", "bg": "card", "border": true, "rounded": "md",
-          "children": [{ "type": "stats", "metrics": [...] }] }
-      ]
-    },
-    { "type": "entity-table", "entity": "...", "columns": [...], "searchable": true }
-  ]
-}]
-\`\`\`
-
-**Dashboard Layout** \u2014 Grid of cards:
-\`\`\`json
-["render-ui", "main", {
-  "type": "stack", "direction": "vertical", "gap": "lg",
-  "children": [
-    { "type": "page-header", "title": "Dashboard" },
-    { "type": "grid", "cols": { "sm": 1, "md": 2, "lg": 3 }, "gap": "md",
-      "children": [
-        { "type": "box", "padding": "lg", "bg": "card", "border": true, "rounded": "md",
-          "children": [{ "type": "stats", "metrics": [...] }] },
-        { "type": "box", "padding": "lg", "bg": "card", "border": true, "rounded": "md",
-          "children": [{ "type": "chart", "chartType": "line", "data": [...] }] },
-        { "type": "box", "padding": "lg", "bg": "card", "border": true, "rounded": "md",
-          "children": [{ "type": "entity-cards", "entity": "...", "columns": 1 }] }
-      ]
-    }
-  ]
-}]
-\`\`\`
-
-**Detail Drawer** \u2014 Stacked sections:
-\`\`\`json
-["render-ui", "drawer", {
-  "type": "stack", "direction": "vertical", "gap": "md",
-  "children": [
-    { "type": "entity-detail", "entity": "...", "actions": [{ "label": "Edit", "event": "EDIT" }] },
-    { "type": "tabs", "tabs": [
-      { "label": "Related Items", "content": { "type": "entity-table", "entity": "..." } },
-      { "label": "Activity", "content": { "type": "timeline", "items": [...] } }
-    ]}
-  ]
-}]
-\`\`\`
-
-### When to Use Layout vs Flat
-- **Flat** (multiple render-ui calls): Simple pages, 2-3 patterns stacked vertically
-- **Nested** (single render-ui with layout): Complex pages, side-by-side elements, cards with backgrounds, dashboard grids`;
-}
-function getOutputFormatSection() {
-  return `## Output Format
-
-Return ONLY a JSON array of render-ui effect tuples. No explanation, no markdown.
-
-### Simple (multiple flat effects):
-\`\`\`json
-[
-  ["render-ui", "main", { "type": "page-header", "title": "...", "actions": [...] }],
-  ["render-ui", "main", { "type": "stats", "entity": "...", "metrics": [...] }],
-  ["render-ui", "main", { "type": "entity-table", "entity": "...", "columns": [...] }]
-]
-\`\`\`
-
-### Composed (single effect with layout nesting):
-\`\`\`json
-[
-  ["render-ui", "main", { "type": "stack", "direction": "vertical", "gap": "lg", "children": [...] }]
-]
-\`\`\`
-
-### Clear slot:
-\`\`\`json
-[
-  ["render-ui", "modal", null]
-]
-\`\`\`
-
-### Rules
-1. Return valid JSON array \u2014 nothing else
-2. Every effect must be \`["render-ui", slot, config]\`
-3. Use entity fields from the input for columns, form fields, stats
-4. Match domain vocabulary for labels (e.g., "Place Order" not "Create")
-5. Include \`itemActions\` on tables/cards with appropriate events
-6. Use \`searchable: true\` on tables for business domains
-7. For INIT transitions, ALWAYS compose multiple patterns (never just a table)
-8. For CREATE/EDIT, always include \`submitEvent\` and \`cancelEvent\` on form-section`;
-}
-function generateKflowDesignSkill() {
-  const frontmatter = {
-    name: "kflow-design",
-    description: "Design rich render-ui effects for orbital schema transitions. Focused on pattern selection, layout composition, and domain-aware UI authoring.",
-    allowedTools: ["Read", "Write", "Edit"],
-    version: "1.0.0"
-  };
-  const content = `# Render-UI Design Skill
-
-> Design rich, polished render-ui effects for orbital schema transitions.
-
-You are a UI design specialist for KFlow orbital schemas. Your job is to take a
-transition context (state, event, entity, domain) and produce the best possible
-render-ui effects using the full pattern catalog.
-
-**Your goal**: Every transition should produce UI that is visually rich, functionally
-complete, and domain-appropriate. Never default to just "entity-table" \u2014 compose
-layouts with headers, stats, filters, and appropriate patterns.
-
----
-
-${getTransitionContextGuide()}
-
----
-
-${getRenderUIDesignGuide()}
-
----
-
-${getLayoutCompositionGuide()}
-
----
-
-${getSExprQuickRef2()}
-
----
-
-${getCommonErrorsSection("top6")}
-
----
-
-${getOutputFormatSection()}
-`;
-  return {
-    name: "kflow-design",
-    frontmatter,
-    content
-  };
-}
-function getDesignSkillStats() {
-  const skill = generateKflowDesignSkill();
-  return {
-    lines: skill.content.split("\n").length,
-    chars: skill.content.length
-  };
-}
 
 // src/orbitals-skills-generators/lean/lean-orbital-generator.ts
 var LEAN_CORE_INSTRUCTIONS = `
@@ -3168,7 +3385,7 @@ The tools handle proper prompting, caching, and S-Expression syntax. Writing dir
     { "name": "TasksPage", "path": "/tasks", "viewType": "list", "isInitial": true }
   ],
   "traits": ["TaskManager"],
-  "patterns": ["page-header", "entity-table", "form-section", "entity-detail"]
+  "patterns": ["page-header", "entity-table", "form-section", "detail-panel"]
 }
 \`\`\`
 
@@ -3265,7 +3482,7 @@ TaskManager behavior:
       then ["render-ui", "modal", null]
 
     - From Browsing to Viewing on VIEW
-      then ["render-ui", "drawer", {"type": "entity-detail", "entity": "Task", "fieldNames": ["title", "description", "status", "priority", "dueDate"], "actions": [{"label": "Edit", "event": "EDIT"}, {"label": "Delete", "event": "DELETE", "variant": "danger"}]}]
+      then ["render-ui", "drawer", {"type": "detail-panel", "entity": "Task", "fields": ["title", "description", "status", "priority", "dueDate"], "actions": [{"label": "Edit", "event": "EDIT"}, {"label": "Delete", "event": "DELETE", "variant": "danger"}]}]
 
     - From Viewing to Editing on EDIT
       then ["render-ui", "drawer", null]
@@ -3559,10 +3776,139 @@ function generateAllBuilderSkills() {
       },
       content: generateLeanFixingSkill2()
     },
-    generateDomainLanguageSkill(),
-    generateKflowDesignSkill()
+    generateDomainLanguageSkill()
   ];
 }
+function getMinimalTypeReference() {
+  return `
+## Orbital Schema Structure
+
+\`\`\`typescript
+interface OrbitalDefinition {
+  name: string;              // Entity name (PascalCase)
+  entity: Entity;            // Data model
+  traits: TraitRef[];        // State machines (names or definitions)
+  pages: Page[];             // Routes and views
+  emits?: string[];          // Events this orbital emits
+  listens?: EventListener[]; // Events this orbital listens to
+}
+\`\`\`
+
+### Entity Fields
+
+\`\`\`typescript
+{ name: "title", type: "string", required: true }
+{ name: "count", type: "number", default: 0 }
+{ name: "status", type: "enum", values: ["pending", "active", "done"] }
+{ name: "dueDate", type: "date" }
+\`\`\`
+
+### Trait State Machine
+
+\`\`\`typescript
+{
+  states: [{ name: "Idle", isInitial: true }, { name: "Active" }],
+  events: ["INIT", "ACTIVATE", "COMPLETE"],
+  transitions: [
+    { from: "Idle", to: "Active", event: "ACTIVATE",
+      guards: [["condition"]],
+      effects: [["action"]] }
+  ]
+}
+\`\`\`
+`.trim();
+}
+function getPatternTypesCompact() {
+  const patterns = getAllPatternTypes();
+  return `
+## Available Pattern Types
+
+${patterns.map((p) => `- \`${p}\``).join("\n")}
+
+${getPatternPropsCompact()}
+`.trim();
+}
+function getSExprQuickRef2() {
+  const operators = Object.keys(OPERATORS).slice(0, 15);
+  return `
+## S-Expression Quick Reference
+
+### Guard Expressions (Conditions)
+
+\`\`\`typescript
+["=", "@entity.status", "active"]        // Equality
+[">", "@entity.count", 0]                 // Greater than
+["and", ["cond1"], ["cond2"]]            // Logical AND
+["or", ["cond1"], ["cond2"]]             // Logical OR
+["not", ["condition"]]                    // Logical NOT
+\`\`\`
+
+### Effect Expressions (Actions)
+
+\`\`\`typescript
+["set", "@entity.field", value]          // Update field
+["emit", "EVENT_NAME", payload]          // Emit event
+["navigate", "/path"]                     // Navigate to route
+["render-ui", "main", { type, props }]   // Render pattern
+["persist", "create", "Entity", data]    // Database operation
+\`\`\`
+
+### Available Operators
+
+${operators.map((op) => `- \`${op}\``).join("\n")}
+`.trim();
+}
+function getRenderUIQuickRef2() {
+  const slots = UI_SLOTS;
+  return `
+## Render-UI Effect Reference
+
+### Syntax
+
+\`\`\`typescript
+["render-ui", slot, patternConfig | null]
+\`\`\`
+
+### UI Slots
+
+${slots.map((slot) => `- \`${slot}\``).join("\n")}
+
+### Example
+
+\`\`\`typescript
+["render-ui", "main", {
+  type: "entity-table",
+  entity: "Task",
+  columns: ["title", "status"],
+  itemActions: [{ label: "Edit", event: "EDIT" }]
+}]
+\`\`\`
+
+Clear slot: \`["render-ui", "modal", null]\`
+`.trim();
+}
+function getFieldTypesCompact() {
+  return `
+## Field Types
+
+| Type | Example | Notes |
+|------|---------|-------|
+| \`string\` | \`{ name: "title", type: "string" }\` | Text |
+| \`number\` | \`{ name: "count", type: "number" }\` | Integer or float |
+| \`boolean\` | \`{ name: "active", type: "boolean" }\` | true/false |
+| \`date\` | \`{ name: "birthday", type: "date" }\` | Date only |
+| \`timestamp\` | \`{ name: "createdAt", type: "timestamp" }\` | Date + time |
+| \`enum\` | \`{ name: "status", type: "enum", values: ["a", "b"] }\` | Fixed options |
+| \`array\` | \`{ name: "tags", type: "array", items: "string" }\` | List |
+| \`relation\` | \`{ name: "user", type: "relation", relation: { entity: "User", cardinality: "one" } }\` | Foreign key |
+
+### Field Properties
+
+- \`required: true\` - Must have value
+- \`default: value\` - Default value
+- \`unique: true\` - Must be unique
+`.trim();
+}
 
 // src/prompts/generation-prompts.ts
 function getOrbitalDecompositionPrompt() {
@@ -3736,6 +4082,316 @@ Use with: \`uses: [{ from: "std/behaviors/crud", as: "CRUD" }]\`
 `;
 }
 
-export { formatFrontmatter, generateAllBuilderSkills, generateDomainLanguageSkill, generateKflowDesignSkill, generateKflowOrbitalFixingSkill, generateKflowOrbitalsSkill, generateLeanFixingSkill2 as generateLeanFixingSkill, generateLeanFixingSkill as generateLeanFixingSkillFull, generateLeanOrbitalSkill2 as generateLeanOrbitalSkill, generateLeanOrbitalSkill as generateLeanOrbitalSkillFull, getArchitectureSection, getAssetRefSection, getCommonErrorsSection, getCommonFixPatternsSection, getCompletionRulesSection, getConnectivityCompact, getContextUsageCompact, getContextUsageSection, getCustomTraitCompact, getCustomTraitSection, getDecompositionChecklist, getDecompositionCompact, getDecompositionSection, getDesignErrorsCompact, getDesignErrorsSection, getDesignSkillStats, getEfficiencySection, getFieldTypesCompact, getFixingWorkflowSection, getFlowPatternSection, getFullOrbitalPrompt, getGameAsOrbitalsSection, getGameEntityTemplatesSection, getGamePatternsSection, getGameTraitsSection, getGameTypesSection, getIconLibraryCompact, getIconLibrarySection, getKeyBehaviorsReference2 as getKeyBehaviorsReference, getMinimalTypeReference, getMultiFileSection, getOrbitalConnectivitySection, getOrbitalDecompositionPrompt, getOverGenerationSection, getPatternTypesCompact, getPortableOrbitalOutputSection, getRenderUIDesignGuide, getRenderUIQuickRef2 as getRenderUIQuickRef, getRequirementsDecomposePrompt, getRequirementsTraitPrompt, getSExprQuickRef2 as getSExprQuickRef, getSchemaUpdateCompact, getSchemaUpdateSection, getUsesImportCompact, getUsesImportSection, getValidationHintsSection, writeAllSkills, writeSkill };
+// src/evals/composition-quality.ts
+var EVAL_CASES = [
+  {
+    name: "task-management-basic",
+    description: "Generate a basic task management view with CRUD",
+    prompt: `Generate an Orbital schema for a task management app.
+    
+Entity: Task with fields: title (string, required), status (enum: pending/active/done), priority (enum: low/medium/high)
+
+Requirements:
+- List view with search and actions (view, edit, delete)
+- Modal form for creating tasks
+- Use atomic composition with stack layouts
+- Include stats/overview section showing counts`,
+    expectedPatterns: ["stack", "page-header", "entity-table", "form-section", "box", "typography", "badge", "button"],
+    minScore: 70,
+    domain: "general"
+  },
+  {
+    name: "patient-portal-dashboard",
+    description: "Generate a healthcare patient portal dashboard",
+    prompt: `Generate an Orbital schema for a healthcare patient portal.
+
+Entities:
+- Patient: name, dateOfBirth, medicalRecordNumber, insuranceStatus
+- Appointment: date, time, doctor, status, notes
+
+Requirements:
+- Dashboard with patient statistics (total, active, critical)
+- Patient list with filters by status
+- Appointment scheduling view
+- Use healthcare-appropriate layouts (calm, organized)
+- Include tabs for different views`,
+    expectedPatterns: ["stack", "grid", "page-header", "entity-table", "tabs", "badge", "card", "stats"],
+    minScore: 75,
+    domain: "healthcare"
+  },
+  {
+    name: "ecommerce-product-catalog",
+    description: "Generate an e-commerce product catalog",
+    prompt: `Generate an Orbital schema for an e-commerce product catalog.
+
+Entities:
+- Product: name, price, category, stockLevel, rating, imageUrl
+- Category: name, description
+
+Requirements:
+- Product grid with cards (use grid layout)
+- Filters by category and price range
+- Product detail view with image
+- Shopping cart indicator
+- Use product-appropriate layouts (visual, appealing)`,
+    expectedPatterns: ["stack", "grid", "entity-cards", "filter-group", "badge", "card", "image"],
+    minScore: 75,
+    domain: "ecommerce"
+  },
+  {
+    name: "project-management-kanban",
+    description: "Generate a project management kanban board",
+    prompt: `Generate an Orbital schema for a project management kanban board.
+
+Entities:
+- Project: name, status, deadline, progress, owner
+- Task: title, status (todo/in-progress/done), assignee, priority, dueDate
+
+Requirements:
+- Kanban board with columns for each status
+- Task cards with drag-drop feel (visual design)
+- Project overview with progress bars
+- Team member avatars
+- Due date indicators`,
+    expectedPatterns: ["stack", "grid", "card", "progress-bar", "avatar", "badge", "page-header"],
+    minScore: 80,
+    domain: "project-management"
+  },
+  {
+    name: "analytics-dashboard",
+    description: "Generate an analytics dashboard with charts",
+    prompt: `Generate an Orbital schema for an analytics dashboard.
+
+Entities:
+- Metric: name, value, change, trend
+- Report: title, date, type, status
+
+Requirements:
+- Stats cards with trend indicators (up/down)
+- Chart visualization area
+- Recent reports list
+- Date range selector
+- Professional, data-dense layout`,
+    expectedPatterns: ["stack", "grid", "stats", "chart", "entity-table", "badge", "card"],
+    minScore: 75,
+    domain: "general"
+  }
+];
+function analyzeComposition(schema) {
+  const metrics = {
+    renderUICount: 0,
+    atomTypes: [],
+    moleculeTypes: [],
+    organismTypes: [],
+    layoutRoot: null,
+    nestingDepth: 0,
+    sectionCount: 0,
+    themeVariableUsage: 0,
+    hardcodedValues: []
+  };
+  for (const orbital of schema.orbitals) {
+    for (const trait of orbital.traits) {
+      const t = trait;
+      if (!t.stateMachine?.transitions) continue;
+      for (const transition of t.stateMachine.transitions) {
+        if (!transition.effects) continue;
+        for (const effect of transition.effects) {
+          if (!Array.isArray(effect)) continue;
+          if (effect[0] !== "render-ui") continue;
+          metrics.renderUICount++;
+          const pattern = effect[2];
+          if (pattern && typeof pattern === "object") {
+            analyzePattern(pattern, metrics, 0);
+          }
+        }
+      }
+    }
+  }
+  const totalValues = metrics.atomTypes.length + metrics.moleculeTypes.length + metrics.organismTypes.length;
+  if (totalValues > 0) {
+    metrics.themeVariableUsage = 100 - metrics.hardcodedValues.length / totalValues * 100;
+  }
+  return metrics;
+}
+function analyzePattern(pattern, metrics, depth) {
+  if (!pattern || typeof pattern !== "object") return;
+  metrics.nestingDepth = Math.max(metrics.nestingDepth, depth);
+  if (depth === 0 && ["stack", "box", "container", "grid"].includes(pattern.type)) {
+    metrics.layoutRoot = pattern.type;
+  }
+  const atomTypes = ["typography", "badge", "button", "avatar", "icon", "progress-bar", "divider"];
+  const moleculeTypes = ["card", "modal", "drawer", "tabs", "alert", "accordion", "box"];
+  const organismTypes = ["entity-table", "form-section", "detail-panel", "page-header", "chart", "timeline", "stats"];
+  if (atomTypes.includes(pattern.type) && !metrics.atomTypes.includes(pattern.type)) {
+    metrics.atomTypes.push(pattern.type);
+  }
+  if (moleculeTypes.includes(pattern.type) && !metrics.moleculeTypes.includes(pattern.type)) {
+    metrics.moleculeTypes.push(pattern.type);
+  }
+  if (organismTypes.includes(pattern.type) && !metrics.organismTypes.includes(pattern.type)) {
+    metrics.organismTypes.push(pattern.type);
+  }
+  for (const [key, value] of Object.entries(pattern)) {
+    if (typeof value === "string") {
+      if (value.startsWith("#") || /^\d+px$/.test(value) || ["white", "black", "red", "blue"].includes(value.toLowerCase())) {
+        metrics.hardcodedValues.push(`${key}: ${value}`);
+      }
+    }
+  }
+  if (depth === 1 && pattern.type) {
+    metrics.sectionCount++;
+  }
+  if (pattern.children && Array.isArray(pattern.children)) {
+    for (const child of pattern.children) {
+      analyzePattern(child, metrics, depth + 1);
+    }
+  }
+}
+function scoreStructure(metrics, schema) {
+  let score = 0;
+  const transitions = countTransitions(schema);
+  if (metrics.renderUICount <= transitions) {
+    score += 5;
+  }
+  if (metrics.layoutRoot) {
+    score += 5;
+  }
+  if (metrics.nestingDepth >= 3) {
+    score += 5;
+  } else if (metrics.nestingDepth >= 2) {
+    score += 3;
+  }
+  score += 5;
+  if (hasClosedCircuit(schema)) {
+    score += 5;
+  }
+  return Math.min(25, score);
+}
+function scoreComposition(metrics) {
+  let score = 0;
+  if (metrics.atomTypes.length >= 4) {
+    score += 10;
+  } else if (metrics.atomTypes.length === 3) {
+    score += 7;
+  } else if (metrics.atomTypes.length === 2) {
+    score += 5;
+  }
+  if (metrics.moleculeTypes.length >= 3) {
+    score += 7;
+  } else if (metrics.moleculeTypes.length === 2) {
+    score += 5;
+  } else if (metrics.moleculeTypes.length === 1) {
+    score += 3;
+  }
+  if (metrics.organismTypes.length >= 2) {
+    score += 8;
+  } else if (metrics.organismTypes.length === 1) {
+    score += 5;
+  }
+  return Math.min(25, score);
+}
+function scoreTheme(metrics) {
+  let score = 0;
+  if (metrics.themeVariableUsage >= 95) {
+    score += 15;
+  } else if (metrics.themeVariableUsage >= 85) {
+    score += 10;
+  } else if (metrics.themeVariableUsage >= 75) {
+    score += 5;
+  }
+  const hasNoHardcodedColors = !metrics.hardcodedValues.some((v) => v.includes("#") || ["white", "black"].some((c) => v.toLowerCase().includes(c)));
+  if (hasNoHardcodedColors) {
+    score += 5;
+  }
+  const hasNoHardcodedSpacing = !metrics.hardcodedValues.some((v) => /\d+px/.test(v));
+  if (hasNoHardcodedSpacing) {
+    score += 5;
+  }
+  return Math.min(25, score);
+}
+function scoreQuality(metrics, testCase) {
+  let score = 0;
+  if (metrics.sectionCount >= 4) {
+    score += 8;
+  } else if (metrics.sectionCount === 3) {
+    score += 6;
+  } else if (metrics.sectionCount === 2) {
+    score += 4;
+  }
+  const expectedPresent = testCase.expectedPatterns.filter(
+    (p) => metrics.atomTypes.includes(p) || metrics.moleculeTypes.includes(p) || metrics.organismTypes.includes(p)
+  ).length;
+  score += expectedPresent / testCase.expectedPatterns.length * 8;
+  score += 5;
+  score += 4;
+  return Math.min(25, score);
+}
+function calculateTotalScore(schema, testCase, validationErrors) {
+  const metrics = analyzeComposition(schema);
+  const breakdown = {
+    structure: scoreStructure(metrics, schema),
+    composition: scoreComposition(metrics),
+    theme: scoreTheme(metrics),
+    quality: scoreQuality(metrics, testCase)
+  };
+  if (validationErrors.length > 0) {
+    breakdown.structure = Math.max(0, breakdown.structure - validationErrors.length * 2);
+  }
+  const total = breakdown.structure + breakdown.composition + breakdown.theme + breakdown.quality;
+  return {
+    score: Math.min(100, Math.round(total)),
+    breakdown
+  };
+}
+function countTransitions(schema) {
+  let count = 0;
+  for (const orbital of schema.orbitals) {
+    for (const trait of orbital.traits) {
+      const t = trait;
+      if (t.stateMachine?.transitions) {
+        count += t.stateMachine.transitions.length;
+      }
+    }
+  }
+  return count;
+}
+function hasClosedCircuit(schema) {
+  for (const orbital of schema.orbitals) {
+    for (const trait of orbital.traits) {
+      const t = trait;
+      if (!t.stateMachine) continue;
+      const states = new Set((t.stateMachine.states || []).map((s) => s.name));
+      const incomingStates = /* @__PURE__ */ new Set();
+      const outgoingStates = /* @__PURE__ */ new Set();
+      for (const transition of t.stateMachine.transitions || []) {
+        incomingStates.add(transition.to);
+        outgoingStates.add(transition.from);
+      }
+      for (const state of states) {
+        const stateObj = (t.stateMachine.states || []).find((s) => s.name === state);
+        if (!stateObj?.isInitial && !incomingStates.has(state)) {
+          return false;
+        }
+      }
+    }
+  }
+  return true;
+}
+function generateComparisonMatrix(comparisons) {
+  let markdown = "# Composition Quality Provider Comparison\n\n";
+  markdown += "| Provider | Average Score | task-mgmt | patient | ecommerce | kanban | analytics |\n";
+  markdown += "|----------|---------------|-----------|---------|-----------|--------|-----------|\n";
+  for (const comp of comparisons) {
+    const scores = EVAL_CASES.map((tc) => {
+      const result = comp.cases.find((c) => c.caseName === tc.name);
+      return result ? `${result.score}${result.passed ? "\u2713" : ""}` : "N/A";
+    });
+    markdown += `| ${comp.provider} | ${comp.averageScore} | ${scores.join(" | ")} |
+`;
+  }
+  return markdown;
+}
+
+export { EVAL_CASES, analyzeComposition, calculateTotalScore, formatFrontmatter, generateAllBuilderSkills, generateComparisonMatrix, generateDomainLanguageSkill, generateKflowOrbitalFixingSkill, generateKflowOrbitalsSkill, generateLeanFixingSkill2 as generateLeanFixingSkill, generateLeanFixingSkill as generateLeanFixingSkillFull, generateLeanOrbitalSkill2 as generateLeanOrbitalSkill, generateLeanOrbitalSkill as generateLeanOrbitalSkillFull, getArchitectureSection, getAssetRefSection, getBannedProps, getBindingContextRules, getBindingsCompact, getBindingsGuide, getCommonErrorsSection, getCommonFixPatternsSection, getCompletionRulesSection, getConnectivityCompact, getContextUsageCompact, getContextUsageSection, getCustomTraitCompact, getCustomTraitSection, getDecompositionChecklist, getDecompositionCompact, getDecompositionSection, getDesignErrorsCompact, getDesignErrorsSection, getEfficiencySection, getFieldTypesCompact, getFixingWorkflowSection, getFlowPatternSection, getFullOrbitalPrompt, getGameAsOrbitalsSection, getGameEntityTemplatesSection, getGamePatternsSection, getGameTraitsSection, getGameTypesSection, getIconLibraryCompact, getIconLibrarySection, getKeyBehaviorsReference2 as getKeyBehaviorsReference, getMinimalTypeReference, getMultiFileSection, getOrbitalConnectivitySection, getOrbitalDecompositionPrompt, getOverGenerationSection, getPatternTypesCompact, getPortableOrbitalOutputSection, getRenderUIDesignGuide, getRenderUIQuickRef2 as getRenderUIQuickRef, getRequirementsDecomposePrompt, getRequirementsTraitPrompt, getSExprQuickRef2 as getSExprQuickRef, getSchemaUpdateCompact, getSchemaUpdateSection, getThemeGuide, getUsesImportCompact, getUsesImportSection, getValidationHintsSection, writeAllSkills, writeSkill };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map