@almadar/skills 1.0.12 → 1.1.0

package/dist/index.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'fs';
 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, getPatternsGroupedByCategory } from '@almadar/patterns';
+import { getPatternPropsCompact, getPatternActionsRef, getAllPatternTypes } from '@almadar/patterns';
 
 // src/generators/utils.ts
 function formatFrontmatter(fm) {
@@ -46,24 +46,6 @@ Writing ${skills.length} skills to ${baseDir}...`);
   console.log(`
 \u2713 Generated ${skills.length} skills`);
 }
-function getMinimalTypeReference() {
-  const patternsByCategory = getPatternsGroupedByCategory();
-  const categories = Object.keys(patternsByCategory);
-  return `## Type Reference
-
-### Pattern Types
-${categories.map((cat) => `- **${cat}**: ${patternsByCategory[cat].slice(0, 5).join(", ")}...`).join("\n")}
-
-Total: ${PATTERN_TYPES.length} patterns
-
-### Operators
-Use S-expressions for guards and effects. See std library for full list.
-
-**Math**: \`+\`, \`-\`, \`*\`, \`/\`, \`>\`, \`<\`, \`>=\`, \`<=\`, \`=\`, \`!=\`
-**Logic**: \`and\`, \`or\`, \`not\`
-**Effects**: \`set\`, \`++\`, \`--\`, \`persist\`, \`fetch\`, \`emit\`, \`render-ui\`
-`;
-}
 function getSExprQuickRef() {
   return `## S-Expression Syntax
 
@@ -134,20 +116,27 @@ ${mod.operators.map((op) => `- **${op.name}**: ${op.description}`).join("\n")}
 }
 function getStdBehaviorsWithStateMachines() {
   const behaviors = getAllBehaviors();
-  const nonGameBehaviors = behaviors.filter(
-    (b) => !b.category?.includes("game") && b.stateMachine
-  );
+  const nonGameBehaviors = behaviors.filter((b) => {
+    const traits = b.orbitals?.[0]?.traits ?? [];
+    const hasGameCategory = traits.some((t) => t.category?.includes("game"));
+    const hasStateMachine = traits.some((t) => t.stateMachine);
+    return !hasGameCategory && hasStateMachine;
+  });
   return `## Standard Behaviors
 
-${nonGameBehaviors.map((behavior) => `### ${behavior.name}
+${nonGameBehaviors.map((behavior) => {
+    const trait = (behavior.orbitals?.[0]?.traits ?? []).find((t) => t.stateMachine);
+    const sm = trait?.stateMachine;
+    return `### ${behavior.name}
 
-**States**: ${behavior.stateMachine.states.map((s) => s.name).join(", ")}
-**Events**: ${behavior.stateMachine.events.join(", ")}
+**States**: ${sm?.states?.map((s) => s.name).join(", ") ?? "N/A"}
+**Events**: ${sm?.events?.join(", ") ?? "N/A"}
 
 \`\`\`json
 ${JSON.stringify(behavior, null, 2)}
 \`\`\`
-`).join("\n\n")}
+`;
+  }).join("\n\n")}
 `;
 }
 function getKeyBehaviorsReference() {
@@ -273,35 +262,23 @@ function getValidViewTypes() {
   const validTypes = ViewTypeSchema.options;
   return validTypes.map((t) => `\`${t}\``).join(", ");
 }
-function getCommonErrorsSection() {
+function getCommonErrorsSection(level = "full") {
+  const critical = getCriticalErrors();
+  if (level === "top6") return critical;
+  return critical + getEdgeCaseErrors();
+}
+function getCriticalErrors() {
   return `## Critical Rules
 
-### NEVER Use @payload in set Effects (CRITICAL)
-
-The \`set\` effect modifies entity state. **@payload is READ-ONLY** - it contains event data.
-
-\`\`\`json
-// WRONG - @payload is read-only!
-["set", "@payload.data.createdAt", "@now"]
-["set", "@payload.data.status", "active"]
-
-// CORRECT - Use @entity to modify state
-["set", "@entity.createdAt", "@now"]
-["set", "@entity.status", "active"]
-\`\`\`
-
-**Rule:** \`set\` target MUST start with \`@entity\`, never \`@payload\`.
-
-### INIT Transition Required (CRITICAL)
+### 1. INIT Transition Required (CRITICAL)
 
 Every trait MUST have an INIT self-loop transition. The runtime fires \`INIT\` when page loads.
 
 \`\`\`json
-// REQUIRED in EVERY trait:
 {
   "from": "Browsing",
   "to": "Browsing",
-  "event": "INIT",  // \u2190 Runtime fires this on page load
+  "event": "INIT",
   "effects": [
     ["render-ui", "main", { "type": "page-header", ... }],
     ["render-ui", "main", { "type": "entity-table", ... }]
@@ -311,43 +288,40 @@ Every trait MUST have an INIT self-loop transition. The runtime fires \`INIT\` w
 
 Without INIT: Page loads blank, nothing renders, no UI appears.
 
-### Valid Patterns ONLY (CRITICAL)
+### 2. NEVER Use @payload in set Effects
 
-**DO NOT invent custom patterns!** Only these patterns exist:
+The \`set\` effect modifies entity state. **@payload is READ-ONLY**.
 
-${getPatternCategories()}
+\`\`\`json
+// WRONG
+["set", "@payload.data.status", "active"]
 
-**NEVER use**: \`onboarding-welcome\`, \`category-selector\`, \`assessment-question\`, etc. - these DO NOT exist!
+// CORRECT
+["set", "@entity.status", "active"]
+\`\`\`
+
+**Rule:** \`set\` target MUST start with \`@entity\`, never \`@payload\`.
 
-### Valid viewType Values
+### 3. Valid Patterns ONLY
 
-Pages must use valid viewType values: ${getValidViewTypes()}
+**DO NOT invent custom patterns!** Only these patterns exist:
 
-Invalid values like \`form\`, \`wizard\`, \`onboarding\` will cause validation errors.
+${getPatternCategories()}
 
-${getPatternPropsCompact()}
+**NEVER use**: \`onboarding-welcome\`, \`category-selector\`, \`assessment-question\`, etc.
 
-${getPatternActionsRef()}
+Valid viewType values: ${getValidViewTypes()}
 
-### Page Structure Required (CRITICAL)
+### 4. Page Structure Required
 
 Every page MUST have \`path\` and \`traits\` properties:
 
 \`\`\`json
-// WRONG - missing path and traits:
 {
   "pages": [{
     "name": "TasksPage",
-    "entity": "Task"  // \u274C Missing path and traits!
-  }]
-}
-
-// CORRECT - complete page definition:
-{
-  "pages": [{
-    "name": "TasksPage",
-    "path": "/tasks",           // \u2190 REQUIRED: starts with /
-    "traits": [{ "ref": "TaskManagement" }]  // \u2190 REQUIRED: trait-driven UI
+    "path": "/tasks",
+    "traits": [{ "ref": "TaskManagement" }]
   }]
 }
 \`\`\`
@@ -355,232 +329,119 @@ Every page MUST have \`path\` and \`traits\` properties:
 Without \`path\`: Validation error \`ORB_P_MISSING_PATH\`
 Without \`traits\`: Validation error \`ORB_P_MISSING_TRAITS\`
 
-### Valid Field Types ONLY (CRITICAL)
+### 5. Valid Field Types ONLY
 
 Field types MUST be one of: \`string\`, \`number\`, \`boolean\`, \`date\`, \`timestamp\`, \`datetime\`, \`array\`, \`object\`, \`enum\`, \`relation\`
 
 \`\`\`json
 // WRONG - using entity name as type:
-{ "name": "author", "type": "User" }           // \u274C "User" is not a valid type!
-{ "name": "post", "type": "BlogPost" }         // \u274C Invalid!
+{ "name": "author", "type": "User" }
 
-// CORRECT - use relation type with entity reference:
+// CORRECT - use relation type:
 { "name": "author", "type": "relation", "relation": { "entity": "User", "cardinality": "one" } }
-{ "name": "post", "type": "relation", "relation": { "entity": "BlogPost", "cardinality": "one" } }
-
-// CORRECT for arrays of primitives:
-{ "name": "tags", "type": "array", "items": { "type": "string" } }
-
-// CORRECT for enums:
-{ "name": "status", "type": "enum", "values": ["pending", "active", "done"] }
 \`\`\`
 
-### Event Listeners Structure
+### 6. Modal State Machine Pattern
 
-Event listeners go INSIDE traits, not at orbital level:
+When a transition opens a modal/drawer, the target state MUST have CLOSE and CANCEL transitions:
 
 \`\`\`json
-// WRONG - at orbital level:
-{
-  "name": "Task Management",
-  "listens": ["SOME_EVENT"]  // \u274C Wrong location, wrong format
-}
-
-// CORRECT - inside trait:
-{
-  "traits": [{
-    "name": "TaskInteraction",
-    "listens": [
-      { "event": "USER_UPDATED", "handler": "REFRESH_LIST" }  // \u2705 Object format
-    ]
-  }]
-}
+{ "from": "Browsing", "to": "Creating", "event": "CREATE",
+  "effects": [["render-ui", "modal", { "type": "form-section", "cancelEvent": "CANCEL", ... }]] },
+{ "from": "Creating", "to": "Browsing", "event": "CANCEL",
+  "effects": [["render-ui", "modal", null]] },
+{ "from": "Creating", "to": "Browsing", "event": "CLOSE",
+  "effects": [["render-ui", "modal", null]] },
+{ "from": "Creating", "to": "Browsing", "event": "SAVE",
+  "effects": [["persist", "create", "Entity", "@payload.data"], ["render-ui", "modal", null], ["emit", "INIT"]] }
 \`\`\`
 
+**CLOSE** = user clicks outside modal/presses Escape. **CANCEL** = form cancel button. Both needed.
+`;
+}
+function getEdgeCaseErrors() {
+  return `
 ---
 
-## Common Errors (AVOID)
-
-### 1. Missing INIT Transition
-\`\`\`
-WRONG: No INIT transition \u2192 Page loads blank
-CORRECT: { "from": "browsing", "to": "browsing", "event": "INIT", "effects": [...render-ui...] }
-\`\`\`
+## Additional Errors (Edge Cases)
 
-### 2. Over-Generating Pages
+### 7. Over-Generating Pages
 \`\`\`
 WRONG: TaskListPage, TaskCreatePage, TaskEditPage, TaskViewPage (4 pages!)
 CORRECT: TasksPage with EntityManagement trait (1 page)
 \`\`\`
 
-### 3. Duplicate Slot Rendering
+### 8. Duplicate Slot Rendering
 \`\`\`
 WRONG: Two traits both render to "main" on page load
 CORRECT: ONE trait owns each slot
 \`\`\`
 
-### 4. Missing onSubmit in form-section
+### 9. Missing onSubmit in form-section
 \`\`\`
 WRONG: { "type": "form-section", "entity": "Task" }
 CORRECT: { "type": "form-section", "entity": "Task", "onSubmit": "SAVE" }
 \`\`\`
 
-### 5. Duplicate Transitions (Same from+event)
+### 10. Duplicate Transitions (Same from+event)
 \`\`\`
 WRONG: Two transitions with same "from" and "event" without guards
 CORRECT: Use GUARDS to differentiate transitions
 \`\`\`
 
-### 6. Using "render" Instead of "render-ui"
+### 11. Using "render" Instead of "render-ui"
 \`\`\`
 WRONG: ["render", "main", {...}]
 CORRECT: ["render-ui", "main", {...}]
 \`\`\`
 
-### 7. Generating Sections Array (Legacy)
+### 12. Generating Sections Array (Legacy)
 \`\`\`
 WRONG: { "pages": [{ "sections": [...] }] }
 CORRECT: { "pages": [{ "traits": [...] }] } - UI comes from render-ui effects
 \`\`\`
 
-### 8. Using form-actions Pattern (DOES NOT EXIST!)
+### 13. Using form-actions Pattern (DOES NOT EXIST!)
 \`\`\`
 WRONG: ["render-ui", "main", { "type": "form-actions", "actions": [...] }]
-CORRECT: Use form-section with onSubmit/onCancel props:
-         { "type": "form-section", "entity": "Task", "fields": [...], "onSubmit": "SAVE", "onCancel": "CANCEL" }
+CORRECT: Use form-section with onSubmit/onCancel props
 \`\`\`
-Actions are INSIDE patterns, not separate patterns. The form-section pattern includes submit/cancel buttons.
+Actions are INSIDE patterns, not separate patterns.
 
-### 9. Forgetting itemActions in entity-table
+### 14. Forgetting itemActions in entity-table
 \`\`\`
-WRONG: { "type": "entity-table", "entity": "Task" }  // No row actions
-CORRECT: { "type": "entity-table", "entity": "Task", "itemActions": [{"label": "Edit", "event": "EDIT"}, {"label": "Delete", "event": "DELETE"}] }
+WRONG: { "type": "entity-table", "entity": "Task" }
+CORRECT: { "type": "entity-table", "entity": "Task", "itemActions": [{"label": "Edit", "event": "EDIT"}] }
 \`\`\`
 
-### 10. Duplicate Trait Names Across Orbitals
+### 15. Duplicate Trait Names Across Orbitals
 \`\`\`
 WRONG: UserOrbital uses "EntityManagement", TaskOrbital uses "EntityManagement"
 CORRECT: UserOrbital uses "UserManagement", TaskOrbital uses "TaskManagement"
 \`\`\`
 Each trait name MUST be unique. Pattern: \`{Entity}{Purpose}\`
 
-### 11. Using @payload in set Effect
-\`\`\`
-WRONG: ["set", "@payload.acceptedAt", "@now"]  // @payload is read-only!
-CORRECT: ["set", "@entity.acceptedAt", "@now"]  // set modifies entity state
-\`\`\`
-\`set\` effect MUST use \`@entity.field\` binding. \`@payload\` is read-only event data.
-
-### 12. Hallucinated itemAction Properties
+### 16. Hallucinated itemAction Properties
 \`\`\`
-WRONG: { "label": "View", "event": "VIEW", "condition": "@entity.status === 'active'" }
-CORRECT: { "label": "View", "event": "VIEW", "showWhen": ["=", "@entity.status", "active"] }
+WRONG: { "label": "View", "event": "VIEW", "condition": "..." }
+CORRECT: { "label": "View", "event": "VIEW" }
 \`\`\`
 Valid itemAction props: \`label\`, \`event\`, \`navigatesTo\`, \`placement\`, \`variant\`, \`showWhen\`
-Note: \`showWhen\` is defined but NOT yet implemented - actions always visible.
-
-### 14. Missing Page Path
-\`\`\`
-WRONG: { "pages": [{ "name": "TasksPage", "entity": "Task" }] }
-CORRECT: { "pages": [{ "name": "TasksPage", "path": "/tasks", "traits": [...] }] }
-\`\`\`
 
-### 15. Using Entity Name as Field Type
-\`\`\`
-WRONG: { "name": "author", "type": "User" }
-CORRECT: { "name": "author", "type": "relation", "relation": { "entity": "User", "cardinality": "one" } }
-\`\`\`
-
-### 16. Missing Traits Array on Page
-\`\`\`
-WRONG: { "pages": [{ "name": "TasksPage", "path": "/tasks" }] }
-CORRECT: { "pages": [{ "name": "TasksPage", "path": "/tasks", "traits": [{ "ref": "TaskManagement" }] }] }
-\`\`\`
-
-### 13. Modal State Machine Pattern (CRITICAL)
-
-When a transition opens a modal (renders to \`modal\` or \`drawer\` slot), the target state MUST have:
-1. A **CLOSE** transition to clear the modal and return to browsing state
-2. A **CANCEL** transition (for forms with cancel buttons)
-3. The CLOSE/CANCEL effects MUST include \`["render-ui", "modal", null]\` to clear the slot
-
-\`\`\`json
-// WRONG - Modal opens but no way to close it!
-{
-  "from": "browsing", "to": "creating", "event": "CREATE",
-  "effects": [["render-ui", "modal", { "type": "form-section", ... }]]
-}
-// No CLOSE or CANCEL transition from "creating" \u2192 Page gets stuck!
-
-// CORRECT - Full modal open/close cycle:
-{
-  "from": "browsing", "to": "creating", "event": "CREATE",
-  "effects": [["render-ui", "modal", { "type": "form-section", "cancelEvent": "CANCEL", ... }]]
-},
-{
-  "from": "creating", "to": "browsing", "event": "CANCEL",
-  "effects": [["render-ui", "modal", null]]
-},
-{
-  "from": "creating", "to": "browsing", "event": "CLOSE",
-  "effects": [["render-ui", "modal", null]]
-},
-{
-  "from": "creating", "to": "browsing", "event": "SAVE",
-  "effects": [
-    ["persist", "create", "Entity", "@payload.data"],
-    ["render-ui", "modal", null],  // \u2190 IMPORTANT: Clear modal on save too!
-    ["fetch", "Entity", {}]
-  ]
-}
-\`\`\`
-
-**Why CLOSE is needed:** The UI sends \`CLOSE\` when user clicks outside the modal or presses Escape.
-**Why CANCEL is needed:** Forms emit \`CANCEL\` when user clicks the Cancel button.
-**Both are needed** for complete modal behavior. Without them, the modal cannot be dismissed and reopened.
-
-### 14. Wrong Filtering Pattern (Use Query Singleton)
-\`\`\`
-WRONG: Individual filter buttons with manual FILTER events
-       { "type": "button", "label": "Active", "action": "FILTER", "data": { "status": "active" } }
-
-CORRECT: Use Query Singleton entity + filter-group pattern:
-\`\`\`
-
-**Query Singleton Pattern for Filtering:**
-
-1. Define a singleton entity to hold filter state:
-\`\`\`json
-{
-  "name": "TaskQuery",
-  "entity": {
-    "name": "TaskQuery",
-    "singleton": true,
-    "runtime": true,
-    "fields": [
-      { "name": "status", "type": "string" },
-      { "name": "search", "type": "string" }
-    ]
-  }
-}
-\`\`\`
-
-2. Use \`set\` effects to update filter state:
+### 17. Event Listeners Structure
+Event listeners go INSIDE traits, not at orbital level:
 \`\`\`json
-{
-  "from": "Browsing", "to": "Browsing", "event": "FILTER",
-  "effects": [["set", "@TaskQuery.status", "@payload.status"]]
-}
+"traits": [{ "name": "TaskInteraction",
+  "listens": [{ "event": "USER_UPDATED", "handler": "REFRESH_LIST" }] }]
 \`\`\`
 
-3. Reference query in patterns:
+### 18. Wrong Filtering Pattern (Use Query Singleton)
+Use a singleton entity for filter state + \`query\` prop on entity-table:
 \`\`\`json
-["render-ui", "main", {
-  "type": "entity-table",
-  "entity": "Task",
-  "query": "@TaskQuery"
-}]
+{ "name": "TaskQuery", "entity": { "name": "TaskQuery", "singleton": true, "runtime": true,
+    "fields": [{ "name": "status", "type": "string" }, { "name": "search", "type": "string" }] } }
 \`\`\`
+Reference: \`["render-ui", "main", { "type": "entity-table", "entity": "Task", "query": "@TaskQuery" }]\`
 `;
 }
 function getValidationHintsSection() {
@@ -699,6 +560,78 @@ function getDecompositionChecklist() {
 - [ ] emits/listens defined for cross-orbital events
 `;
 }
+function getDecompositionCompact() {
+  return `## Orbital Decomposition Protocol
+
+### Step 0: Classify Domain
+| Domain | Keywords | Key Traits |
+|--------|----------|------------|
+| business | manage, track, workflow | EntityManagement, SearchAndFilter |
+| game | play, score, level | Physics2D, Health, GameState |
+| form | wizard, onboarding | Wizard, FormSubmission |
+| dashboard | metrics, KPI | EntityManagement |
+| content | blog, CMS | none (page navigation) |
+
+### Step 1: Identify Entities (ONE Orbital Per Entity)
+- What are the core data objects?
+- persistent (DB), runtime (memory), or singleton (config)?
+- **CRITICAL: Create exactly ONE orbital per entity**
+
+### Step 2: Select Interaction Model
+| Domain | Create | View | Edit | Delete |
+|--------|--------|------|------|--------|
+| business | modal | drawer | modal | confirm |
+| game | none | none | none | none |
+| form | wizard | drawer | page | confirm |
+
+### Step 3: Choose Traits
+- Business: EntityManagement (handles CRUD via render-ui)
+- Game: Physics2D, Health, Score, Collision
+- Form: Wizard (multi-step) or FormSubmission (single)
+
+### Step 4: Define State Machine
+\`\`\`
+states: Identify user-facing modes (browsing, creating, editing, viewing)
+events: Identify user actions (INIT, CREATE, VIEW, EDIT, SAVE, CLOSE)
+transitions: Map (from, event) \u2192 (to, effects)
+\`\`\`
+
+### Step 5: Add INIT Transition (CRITICAL)
+Every trait MUST have an INIT self-loop with render-ui effects. Without INIT, the page loads blank!
+
+### Step 6: Define Pages
+- ONE page per entity (business) or workflow (form)
+- Attach traits to pages via \`traits\` array
+- Add \`"guard"\` (singular) S-expressions on SAVE transitions for business rules
+`;
+}
+function getConnectivityCompact() {
+  return `## Orbital Connectivity
+
+For multi-entity apps, connect orbitals:
+
+\`\`\`json
+{
+  "entity": {
+    "fields": [
+      { "name": "customerId", "type": "relation", "relation": { "entity": "Customer", "cardinality": "one" } }
+    ]
+  },
+  "emits": ["ORDER_COMPLETED"],
+  "listens": [{ "event": "MENU_ITEM_UNAVAILABLE", "triggers": "DISABLE_ITEM" }],
+  "design": {
+    "uxHints": {
+      "relatedLinks": [{ "relation": "customerId", "label": "View Customer", "targetView": "detail" }]
+    }
+  }
+}
+\`\`\`
+
+- **relation fields**: Link entities (Order \u2192 Customer)
+- **emits/listens**: Cross-orbital event communication
+- **relatedLinks**: Navigation between related records
+`;
+}
 function getFlowPatternSection() {
   return `## Flow Pattern Selection
 
@@ -804,6 +737,151 @@ Orbitals communicate via events:
 - Add relatedLinks for navigation between related records
 `;
 }
+function getRenderUIDesignGuide() {
+  return `## Render-UI Design Guide
+
+### Syntax
+\`["render-ui", slot, { "type": pattern, ...props }]\`
+Clear slot: \`["render-ui", "modal", null]\`
+
+### 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 |
+
+### Composition Recipes
+
+**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" }] }]
+\`\`\`
+
+**Dashboard INIT**:
+\`\`\`
+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)
+\`\`\`
+
+**Detail View (drawer)**:
+\`\`\`
+drawer: entity-detail \u2192 all fields + [Edit, Delete] actions
+drawer: tabs \u2192 related collections (if entity has relation fields)
+\`\`\`
+
+**Wizard Flow**:
+\`\`\`
+main: wizard-progress \u2192 steps array + currentStep
+main: wizard-container \u2192 current step content
+main: wizard-navigation \u2192 Back/Next/Submit buttons
+\`\`\`
+
+### Layout Composition (stack, box, grid)
+
+Layout patterns wrap other patterns via \`children\` arrays for rich, structured views.
+
+**VStack** (vertical stack): \`{ "type": "stack", "direction": "vertical", ... }\`
+**HStack** (horizontal stack): \`{ "type": "stack", "direction": "horizontal", ... }\`
+**Box** (styled container): \`{ "type": "box", ... }\`
+
+#### 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\` |
+
+#### 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"\` |
+
+#### Grid Props
+| Prop | Values |
+|------|--------|
+| \`cols\` | \`1\`\u2013\`12\` or \`{ sm: 1, md: 2, lg: 3 }\` |
+| \`gap\` | \`"none"\`, \`"xs"\`, \`"sm"\`, \`"md"\`, \`"lg"\`, \`"xl"\` |
+
+#### Nesting Example \u2014 Page Header + Stats Row + Table
+\`\`\`json
+["render-ui", "main", {
+  "type": "stack", "direction": "vertical", "gap": "lg",
+  "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": "entity-table", "entity": "Order", "columns": ["customer", "total", "status"], "searchable": true }
+  ]
+}]
+\`\`\`
+
+#### 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
+
+> **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.
+
+### Domain-Aware Pattern Selection
+| Domain | List Pattern | Extras |
+|--------|-------------|--------|
+| business/admin | \`entity-table\` (searchable) | \`stats\`, \`filter-group\` |
+| e-commerce | \`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()}
+
+${getPatternActionsRef()}
+`;
+}
 
 // src/prompts/skill-sections/custom-traits.ts
 function getCustomTraitSection() {
@@ -1889,13 +1967,16 @@ function generateLeanOrbitalSkill(options = {}) {
   const {
     includeExample = true,
     includeToolWorkflow = true,
-    includeStdLibrary = true,
+    includeStdLibrary = false,
     stdLibraryFull = false,
-    includeStdStateMachines = true,
-    includeSchemaUpdates = true
+    includeStdStateMachines = false,
+    includeSchemaUpdates = false,
+    includeCustomTraits = false,
+    errorLevel = "top6",
+    includeDesignGuide = true
   } = options;
   let stdSection = "";
-  if (includeStdLibrary) {
+  if (includeStdLibrary || includeStdStateMachines) {
     if (includeStdStateMachines) {
       stdSection = `---
 
@@ -1917,6 +1998,8 @@ ${getStdMinimalReference()}
 `;
     }
   }
+  const decompositionSection = includeStdStateMachines || includeCustomTraits ? getDecompositionSection() : getDecompositionCompact();
+  const connectivitySection = includeStdStateMachines || includeCustomTraits ? getOrbitalConnectivitySection() : getConnectivityCompact();
   return `# Orbital Generation Skill
 
 > Generate Orbital applications using Orbital Units: Entity \xD7 Traits \xD7 Patterns
@@ -1925,15 +2008,11 @@ ${getArchitectureSection()}
 
 ---
 
-${getMinimalTypeReference()}
-
----
-
 ${getSExprQuickRef()}
 
 ---
 
-${getRenderUIQuickRef()}
+${includeDesignGuide ? getRenderUIDesignGuide() : ""}
 
 ${stdSection}
 ---
@@ -1942,7 +2021,7 @@ ${getFlowPatternSection()}
 
 ---
 
-${getDecompositionSection()}
+${decompositionSection}
 
 ---
 
@@ -1950,7 +2029,7 @@ ${getPortableOrbitalOutputSection()}
 
 ---
 
-${getOrbitalConnectivitySection()}
+${connectivitySection}
 
 ---
 
@@ -1958,12 +2037,12 @@ ${getContextUsageCompact()}
 
 ---
 
-${getCommonErrorsSection()}
+${getCommonErrorsSection(errorLevel)}
 
----
+${includeCustomTraits ? `---
 
 ${getCustomTraitSection()}
-
+` : ""}
 ${includeToolWorkflow ? getToolWorkflowSection() : ""}
 
 ${includeSchemaUpdates ? `---
@@ -2024,17 +2103,67 @@ function getToolWorkflowSection() {
 
 ## Tool Workflow
 
-1. **DECOMPOSE**: Break requirements into OrbitalUnits
-2. **GENERATE**: Call \`generate_orbital\` for each orbital
-3. **COMBINE**: Call \`construct_combined_schema\` (FINAL STEP)
+### Phase 1: DECOMPOSE
+Break requirements into OrbitalUnits (pure reasoning, no tools).
+
+### Phase 2: GENERATE
+Call \`generate_orbital\` for each orbital:
 
 \`\`\`
 generate_orbital({ orbital: {...}, orbitalIndex: 0, totalOrbitals: N })
 generate_orbital({ orbital: {...}, orbitalIndex: 1, totalOrbitals: N })
 ...
-construct_combined_schema({ name: "App", description: "..." })
-# STOP HERE - job is done
 \`\`\`
+
+Each orbital is written to \`.orbitals/<name>.json\` with ALL effects (render-ui, persist, emit, set, etc.).
+
+### Phase 3: COMBINE
+Call \`finish_task\` to auto-combine and validate:
+
+\`\`\`
+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.
+
+4. Apply the chunk back:
+\`\`\`json
+{ "chunkId": "<id from extract_chunk>" }
+\`\`\`
+
+**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.
+
+**Skip design_transition for**: SAVE, CANCEL, CONFIRM_DELETE transitions (they have persist/emit effects with simple slot-clearing \u2014 no UI to design).
 `;
 }
 function getMinimalExample() {
@@ -2072,8 +2201,9 @@ function getMinimalExample() {
           {
             "from": "Browsing", "to": "Browsing", "event": "INIT",
             "effects": [
-              ["render-ui", "main", { "type": "page-header", "title": "Tasks", "actions": [{ "label": "New Task", "event": "CREATE", "variant": "primary" }] }],
-              ["render-ui", "main", { "type": "entity-table", "entity": "Task", "columns": ["title", "status"], "itemActions": [{ "label": "View", "event": "VIEW" }, { "label": "Edit", "event": "EDIT" }, { "label": "Delete", "event": "DELETE" }] }]
+              ["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" }] }]
             ]
           },
           {
@@ -2130,14 +2260,15 @@ function getMinimalExample() {
 
 **Key points**:
 - ONE page (TasksPage) not four (list/create/edit/view)
-- INIT transition renders initial UI (page-header + entity-table)
+- 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}]\`
+  - \`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!
 `;
@@ -2148,15 +2279,18 @@ 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"],
-    version: "3.1.0"
-    // Bumped version for compact option
+    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
   };
   const content = generateLeanOrbitalSkill({
     includeExample: true,
     includeToolWorkflow: true,
-    includeStdStateMachines: !compact
-    // Full std/* examples (21K chars)
+    includeStdStateMachines: false,
+    includeSchemaUpdates: false,
+    includeCustomTraits: false,
+    errorLevel: "top6",
+    includeDesignGuide: true
   });
   return {
     name: "kflow-orbitals",
@@ -2201,10 +2335,6 @@ ${getArchitectureSection()}
 
 ---
 
-${getMinimalTypeReference()}
-
----
-
 ${getSExprQuickRef()}
 
 ---
@@ -2225,7 +2355,11 @@ ${getOverGenerationSection()}` : ""}
 
 ---
 
-${getCommonErrorsSection()}
+${getCommonErrorsSection("full")}
+
+---
+
+${getCustomTraitSection()}
 
 ${includeSchemaUpdates ? `---
 
@@ -2476,9 +2610,356 @@ Output the complete updated domain language text.
     content
   };
 }
+function getMinimalTypeReference() {
+  return `
+## Orbital Schema Structure
 
-// src/orbitals-skills-generators/lean/lean-orbital-generator.ts
-var LEAN_CORE_INSTRUCTIONS = `
+\`\`\`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 e-commerce \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 = `
 ## Core Instructions
 
 Generate orbital schemas using **Domain Language** - a natural, readable format.
@@ -3072,139 +3553,10 @@ function generateAllBuilderSkills() {
       },
       content: generateLeanFixingSkill2()
     },
-    generateDomainLanguageSkill()
+    generateDomainLanguageSkill(),
+    generateKflowDesignSkill()
   ];
 }
-function getMinimalTypeReference2() {
-  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() {
@@ -3244,7 +3596,7 @@ ${getArchitectureSection()}
 
 ---
 
-${getMinimalTypeReference2()}
+${getMinimalTypeReference()}
 
 ---
 
@@ -3378,6 +3730,6 @@ Use with: \`uses: [{ from: "std/behaviors/crud", as: "CRUD" }]\`
 `;
 }
 
-export { formatFrontmatter, generateAllBuilderSkills, generateDomainLanguageSkill, generateKflowOrbitalFixingSkill, generateKflowOrbitalsSkill, generateLeanFixingSkill2 as generateLeanFixingSkill, generateLeanFixingSkill as generateLeanFixingSkillFull, generateLeanOrbitalSkill2 as generateLeanOrbitalSkill, generateLeanOrbitalSkill as generateLeanOrbitalSkillFull, getArchitectureSection, getAssetRefSection, getCommonErrorsSection, getCommonFixPatternsSection, getCompletionRulesSection, getContextUsageCompact, getContextUsageSection, getCustomTraitCompact, getCustomTraitSection, getDecompositionChecklist, getDecompositionSection, getDesignErrorsCompact, getDesignErrorsSection, getEfficiencySection, getFieldTypesCompact, getFixingWorkflowSection, getFlowPatternSection, getFullOrbitalPrompt, getGameAsOrbitalsSection, getGameEntityTemplatesSection, getGamePatternsSection, getGameTraitsSection, getGameTypesSection, getIconLibraryCompact, getIconLibrarySection, getKeyBehaviorsReference2 as getKeyBehaviorsReference, getMinimalTypeReference2 as getMinimalTypeReference, getMultiFileSection, getOrbitalConnectivitySection, getOrbitalDecompositionPrompt, getOverGenerationSection, getPatternTypesCompact, getPortableOrbitalOutputSection, getRenderUIQuickRef2 as getRenderUIQuickRef, getRequirementsDecomposePrompt, getRequirementsTraitPrompt, getSExprQuickRef2 as getSExprQuickRef, getSchemaUpdateCompact, getSchemaUpdateSection, getUsesImportCompact, getUsesImportSection, getValidationHintsSection, writeAllSkills, writeSkill };
+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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map