@almadar/skills 2.1.0 → 2.4.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, isInlineTrait as isInlineTrait$1 } from '@almadar/core/types';
-import { getPatternPropsCompact, getPatternActionsRef, getAllPatternTypes } from '@almadar/patterns';
+import { getPatternPropsCompact, getPatternActionsRef, getOrbAllowedPatternsCompact, getAllPatternTypes } from '@almadar/patterns';
 import { BINDING_DOCS, CORE_BINDINGS, isInlineTrait } from '@almadar/core';
 import { generateDomainLanguageReference } from '@almadar/core/domain-language';
 
@@ -1369,6 +1369,190 @@ ${getPatternPropsCompact()}
 ${getPatternActionsRef()}
 `;
 }
+function getOrbRenderUIGuide() {
+  const patternsRef = getOrbAllowedPatternsCompact();
+  return `## .orb Render-UI Composition Guide
+
+### Golden Behavior Pattern
+
+Every render-ui tree in .orb follows the same structure observed across all 107 golden behaviors:
+
+\`\`\`
+stack (vertical, gap: lg)            \u2190 root wrapper, ALWAYS
+  \u251C\u2500\u2500 stack (horizontal)             \u2190 header row (icon + title + actions)
+  \u2502     \u251C\u2500\u2500 icon
+  \u2502     \u251C\u2500\u2500 typography (h2/h3)
+  \u2502     \u2514\u2500\u2500 button (primary action)
+  \u251C\u2500\u2500 divider                        \u2190 visual separation
+  \u251C\u2500\u2500 stat-display / badge row       \u2190 optional summary stats
+  \u2514\u2500\u2500 data-list / data-grid          \u2190 main content
+        OR form-section              \u2190 for create/edit states
+\`\`\`
+
+The most-used patterns (by frequency across all behaviors):
+1. \`stack\` (2820) - ALL layout
+2. \`typography\` (1332) - ALL text
+3. \`divider\` (803) - section separation
+4. \`icon\` (796) - decorative/semantic icons
+5. \`button\` (782) - ALL actions
+6. \`badge\` (697) - status indicators
+7. \`stat-display\` (691) - metric cards
+8. \`data-list\` (178) - list views
+9. \`progress-bar\` (131) - progress indicators
+10. \`card\` (108) - content grouping
+
+---
+
+### Composition Rules
+
+| Rule | Requirement |
+|------|-------------|
+| **1** | Root element MUST be \`stack\` (vertical) or \`box\` |
+| **2** | Use ONLY atoms, molecules, and allowed exceptions (see pattern list below) |
+| **3** | Single \`render-ui\` per transition (compose children, never multiple flat calls) |
+| **4** | ALL visual props use CSS theme variables (no hex colors, no pixels) |
+| **5** | Every action button's \`event\` must match a state machine event key |
+
+**Allowed exceptions** (entity-aware but standard in .orb):
+\`data-list\`, \`data-grid\`, \`search-input\`, \`form-section\`, \`meter\`
+
+**BANNED from .orb render-ui** (organisms, resolved by compiler/runtime):
+\`entity-table\`, \`entity-list\`, \`entity-cards\`, \`page-header\`, \`detail-panel\`,
+\`stats\`, \`dashboard-grid\`, \`header\`, \`sidebar\`, \`navigation\`, \`master-detail\`
+
+---
+
+### Layout Reference
+
+**Stack** (use for ALL layout):
+\`\`\`json
+{
+  "type": "stack",
+  "direction": "vertical" | "horizontal",
+  "gap": "xs" | "sm" | "md" | "lg" | "xl",
+  "align": "start" | "center" | "end" | "stretch",
+  "justify": "start" | "center" | "end" | "between"
+}
+\`\`\`
+
+**Box** (styled container):
+\`\`\`json
+{
+  "type": "box",
+  "padding": "sm" | "md" | "lg",
+  "bg": "var(--color-card)",
+  "border": true,
+  "borderColor": "var(--color-border)",
+  "rounded": "var(--radius-md)",
+  "shadow": "var(--shadow-sm)"
+}
+\`\`\`
+
+---
+
+### Theme Variables (MANDATORY)
+
+| Property | Use | Never |
+|----------|-----|-------|
+| Colors | \`var(--color-primary)\` | \`#3b82f6\` |
+| Backgrounds | \`var(--color-card)\` | \`white\` |
+| Text | \`var(--color-foreground)\` | \`black\` |
+| Muted text | \`var(--color-muted-foreground)\` | \`gray\` |
+| Borders | \`var(--color-border)\` | \`#e5e7eb\` |
+| Radius | \`var(--radius-md)\` | \`8px\` |
+| Shadows | \`var(--shadow-sm)\` | \`0 2px 4px...\` |
+
+---
+
+### Example: Browsing State (from golden behaviors)
+
+\`\`\`json
+["render-ui", "main", {
+  "type": "stack", "direction": "vertical", "gap": "lg",
+  "children": [
+    {
+      "type": "stack", "direction": "horizontal", "gap": "md",
+      "justify": "between", "align": "center",
+      "children": [
+        {
+          "type": "stack", "direction": "horizontal", "gap": "sm", "align": "center",
+          "children": [
+            { "type": "icon", "name": "list", "size": "lg" },
+            { "type": "typography", "variant": "h2", "content": "Items" }
+          ]
+        },
+        { "type": "button", "label": "Create", "event": "CREATE", "variant": "primary" }
+      ]
+    },
+    { "type": "divider" },
+    {
+      "type": "stack", "direction": "horizontal", "gap": "md",
+      "children": [
+        { "type": "stat-display", "label": "Total", "value": "@entity.total", "icon": "package" },
+        { "type": "stat-display", "label": "Price", "value": "@entity.price", "icon": "dollar-sign" }
+      ]
+    },
+    {
+      "type": "data-list", "entity": "Item",
+      "emptyIcon": "inbox",
+      "itemActions": [
+        { "label": "Edit", "event": "EDIT" },
+        { "label": "Delete", "event": "DELETE", "variant": "danger" }
+      ]
+    }
+  ]
+}]
+\`\`\`
+
+### Example: Modal Form (from golden behaviors)
+
+\`\`\`json
+["render-ui", "modal", {
+  "type": "stack", "direction": "vertical", "gap": "md",
+  "children": [
+    {
+      "type": "stack", "direction": "horizontal", "gap": "sm", "align": "center",
+      "children": [
+        { "type": "icon", "name": "plus-circle", "size": "md" },
+        { "type": "typography", "variant": "h3", "content": "Create Item" }
+      ]
+    },
+    { "type": "divider" },
+    {
+      "type": "form-section", "entity": "Item",
+      "mode": "create",
+      "submitEvent": "SAVE",
+      "cancelEvent": "CANCEL"
+    }
+  ]
+}]
+\`\`\`
+
+---
+
+${getBindingsGuide()}
+
+---
+
+### Available Patterns (derived from registry)
+
+${patternsRef}
+
+---
+
+### BANNED Patterns
+
+| Wrong | Correct |
+|-------|---------|
+| \`entity-table\` | \`data-list\` or \`data-grid\` |
+| \`page-header\` | \`stack\` with \`icon\` + \`typography\` + \`button\` |
+| \`detail-panel\` | \`stack\` with field \`typography\` rows |
+| \`stats\` | \`stat-display\` atoms in a \`stack\` |
+| Multiple flat render-ui calls | Single composed render-ui |
+| Hex colors / pixels | Theme CSS variables |
+| \`onSubmit\` / \`onCancel\` | \`submitEvent\` / \`cancelEvent\` |
+`;
+}
 
 // src/prompts/skill-sections/theme-guide.ts
 function getThemeGuide() {
@@ -4076,6 +4260,647 @@ When answering:
   };
 }
 
+// src/generators/orb.ts
+function generateOrbSkill() {
+  const frontmatter = {
+    name: "orb",
+    description: "Generate .orb programs using molecule-first composition. Atoms + molecules only, no organisms.",
+    allowedTools: ["Read", "Write", "Edit", "generate_orbital", "generate_schema_orchestrated", "finish_task", "query_schema_structure", "extract_chunk", "apply_chunk"],
+    version: "1.0.0"
+  };
+  const content = generateOrbSkillContent();
+  return {
+    name: "orb",
+    frontmatter,
+    content
+  };
+}
+function generateOrbSkillContent() {
+  return `# Orb Generation Skill (Molecule-First)
+
+> Generate .orb programs using Orbital Units: Entity x Traits x Patterns
+> Pattern vocabulary: atoms + molecules only. No organisms.
+
+${getArchitectureSection()}
+
+---
+
+${getSExprQuickRef()}
+
+---
+
+${getMoleculeFirstDesignGuide()}
+
+---
+
+${getThemeGuide()}
+
+---
+
+${getBannedProps()}
+
+---
+
+${getFlowPatternSection()}
+
+---
+
+${getDecompositionCompact()}
+
+---
+
+${getPortableOrbitalOutputSection()}
+
+---
+
+${getConnectivityCompact()}
+
+---
+
+${getContextUsageCompact()}
+
+---
+
+${getCommonErrorsSection("top6")}
+
+${getToolWorkflowSection2()}
+
+${getCriticalOutputRequirements2()}
+
+${getMoleculeFirstExample()}
+`;
+}
+function getMoleculeFirstDesignGuide() {
+  return `## Render-UI Molecule-First Design Guide
+
+### The Five Rules of Composition (MANDATORY)
+
+| Rule | Requirement |
+|------|-------------|
+| **1** | **Single Render-UI** per transition |
+| **2** | **Two Levels**: Atoms (2+) + Molecules (1+) |
+| **3** | **Layout Wrapper**: Root must be \`stack\`, \`card\`, \`box\`, or \`simple-grid\` |
+| **4** | **Theme Variables**: ALL visual props use CSS vars |
+| **5** | **Composable**: Build from small pieces, never use rigid organisms |
+
+---
+
+### Pattern Vocabulary
+
+These are the ONLY patterns you may use. They are derived from 104 production behaviors across 18 domains.
+
+#### Atoms (Basic UI Elements)
+
+| Pattern | Purpose | Key Props |
+|---------|---------|-----------|
+| \`typography\` | All text content | \`variant\` (h1-h6, body, caption), \`text\`, \`color\` |
+| \`button\` | User actions | \`label\`, \`event\`, \`variant\` (primary, secondary, ghost, destructive) |
+| \`icon\` | Lucide icons | \`name\`, \`size\`, \`color\` |
+| \`badge\` | Status indicators | \`text\`, \`variant\` (primary, success, warning, error) |
+| \`divider\` | Visual separation | \`orientation\` |
+| \`avatar\` | User/entity images | \`src\`, \`name\`, \`size\` |
+| \`progress-bar\` | Progress indicators | \`value\`, \`max\`, \`label\` |
+| \`status-dot\` | Status indicator dots | \`status\`, \`label\` |
+| \`star-rating\` | Rating display | \`value\`, \`max\` |
+
+#### Layout Molecules
+
+| Pattern | Purpose | Key Props |
+|---------|---------|-----------|
+| \`stack\` | Flex layout (V/H) | \`direction\` (vertical/horizontal), \`gap\`, \`align\`, \`justify\`, \`wrap\` |
+| \`card\` | Content grouping | \`padding\`, \`border\`, \`rounded\`, \`shadow\`, \`children\` |
+| \`box\` | Visual container | \`padding\`, \`bg\`, \`border\`, \`rounded\`, \`shadow\`, \`children\` |
+| \`simple-grid\` | Grid layout | \`cols\`, \`gap\`, \`children\` |
+
+#### Data Molecules
+
+| Pattern | Purpose | Key Props |
+|---------|---------|-----------|
+| \`data-grid\` | Tabular data display | \`entity\`, \`fields\`, \`itemActions\`, \`cols\`, \`gap\` |
+| \`data-list\` | Vertical list display | \`entity\`, \`fields\`, \`itemActions\` |
+| \`form-section\` | Form input groups | \`entity\`, \`fields\`, \`submitEvent\`, \`cancelEvent\` |
+| \`search-input\` | Search fields | \`placeholder\`, \`event\` |
+| \`filter-group\` | Filter controls | \`filters\`, \`event\` |
+| \`tabs\` | Tabbed content | \`tabs\`, \`activeTab\` |
+
+#### Metric/Chart Molecules
+
+| Pattern | Purpose | Key Props |
+|---------|---------|-----------|
+| \`stat-display\` | Single KPI display | \`label\`, \`value\`, \`icon\` |
+| \`stats\` | Multiple stat cards | \`entity\`, \`items\` |
+| \`stat-badge\` | Stat with badge | \`label\`, \`value\`, \`variant\` |
+| \`meter\` | Metric gauge | \`value\`, \`max\`, \`label\` |
+| \`line-chart\` | Line chart | \`entity\`, \`xField\`, \`yField\` |
+| \`chart\` | Generic chart | \`entity\`, \`type\`, \`fields\` |
+| \`trend-indicator\` | Trend up/down | \`value\`, \`direction\` |
+| \`score-display\` | Score/count | \`value\`, \`label\` |
+
+#### State Molecules
+
+| Pattern | Purpose | Key Props |
+|---------|---------|-----------|
+| \`empty-state\` | No data fallback | \`title\`, \`description\`, \`icon\` |
+| \`loading-state\` | Loading spinner | \`message\` |
+
+#### Form Molecules
+
+| Pattern | Purpose | Key Props |
+|---------|---------|-----------|
+| \`textarea\` | Multi-line input | \`placeholder\`, \`rows\` |
+| \`range-slider\` | Range input | \`min\`, \`max\`, \`step\`, \`value\` |
+| \`upload-drop-zone\` | File upload | \`accept\`, \`maxSize\` |
+| \`calendar-grid\` | Date picker grid | \`selectedDate\`, \`event\` |
+
+#### Navigation Molecules
+
+| Pattern | Purpose | Key Props |
+|---------|---------|-----------|
+| \`wizard-progress\` | Multi-step progress | \`steps\`, \`currentStep\` |
+| \`wizard-navigation\` | Step navigation | \`steps\`, \`currentStep\` |
+| \`action-buttons\` | Action button group | \`actions\` |
+
+#### Specialty Molecules
+
+| Pattern | Purpose | Key Props |
+|---------|---------|-----------|
+| \`lightbox\` | Image/media viewer | \`src\`, \`alt\` |
+| \`map-view\` | Map display | \`center\`, \`zoom\`, \`markers\` |
+| \`health-bar\` | Health/HP bar | \`value\`, \`max\` |
+| \`d-pad\` | Directional pad | \`events\` |
+| \`combat-log\` | Event log | \`entries\` |
+| \`dialogue-box\` | Dialogue/chat | \`speaker\`, \`text\` |
+
+#### Game Canvas Molecules
+
+| Pattern | Purpose | Key Props |
+|---------|---------|-----------|
+| \`isometric-canvas\` | 3D isometric canvas | \`tiles\`, \`units\` |
+| \`platformer-canvas\` | 2D platformer | \`entities\`, \`viewport\` |
+| \`simulation-canvas\` | Simulation display | \`entities\`, \`viewport\` |
+| \`canvas-effect\` | Canvas visual effects | \`effect\`, \`duration\` |
+| \`game-hud\` | Game HUD overlay | \`stats\`, \`actions\` |
+| \`game-menu\` | Game menu | \`items\` |
+| \`game-over-screen\` | End screen | \`score\`, \`message\` |
+| \`inventory-panel\` | Inventory display | \`items\`, \`slots\` |
+
+---
+
+### BANNED Patterns (NEVER USE)
+
+These organism-level patterns are deprecated. Use the molecule equivalents:
+
+| Banned Pattern | Use Instead |
+|---------------|-------------|
+| \`entity-table\` | \`data-grid\` with \`entity\`, \`fields\`, \`itemActions\` |
+| \`entity-list\` | \`data-list\` with \`entity\`, \`fields\`, \`itemActions\` |
+| \`entity-cards\` | \`data-grid\` with \`cols: 3\`, or compose with \`card\` children in a \`simple-grid\` |
+| \`page-header\` | Compose with \`stack\` (horizontal) + \`typography\` (h1) + \`button\` |
+| \`detail-panel\` | Compose with \`stack\` (vertical) + \`typography\` + \`badge\` + \`divider\` |
+| \`timeline\` | Compose with \`data-list\` or \`stack\` + timestamp items |
+| \`crud-template\` | Compose from \`data-grid\` + \`form-section\` + layout molecules |
+| \`list-template\` | Compose from \`data-list\` + \`search-input\` + layout molecules |
+| \`detail-template\` | Compose from \`stack\` + \`typography\` + \`badge\` + \`button\` |
+
+---
+
+### Layout-First Structure (Rule 3)
+
+Root element MUST be a layout molecule:
+
+\`\`\`json
+{ "type": "stack", "direction": "vertical", "gap": "lg", "children": [...] }
+{ "type": "stack", "direction": "horizontal", "gap": "md", "children": [...] }
+{ "type": "box", "padding": "lg", "bg": "var(--color-card)", "children": [...] }
+{ "type": "simple-grid", "cols": 3, "gap": "md", "children": [...] }
+\`\`\`
+
+#### 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
+}
+\`\`\`
+
+**Box**
+\`\`\`json
+{
+  "type": "box",
+  "padding": "none" | "xs" | "sm" | "md" | "lg" | "xl",
+  "bg": "var(--color-card)" | "var(--color-muted)" | "var(--color-primary)",
+  "border": true | false,
+  "rounded": "var(--radius-md)" | "var(--radius-lg)",
+  "shadow": "var(--shadow-sm)" | "var(--shadow-md)"
+}
+\`\`\`
+
+---
+
+### Composition Pattern: Header Row
+
+Instead of \`page-header\`, compose with atoms:
+
+\`\`\`json
+{
+  "type": "stack", "direction": "horizontal", "justify": "between", "align": "center",
+  "children": [
+    { "type": "typography", "variant": "h1", "text": "Tasks" },
+    { "type": "button", "label": "New Task", "event": "CREATE", "variant": "primary", "icon": "plus" }
+  ]
+}
+\`\`\`
+
+### Composition Pattern: Stat Cards
+
+\`\`\`json
+{
+  "type": "stack", "direction": "horizontal", "gap": "md", "wrap": true,
+  "children": [
+    { "type": "stat-display", "label": "Total", "value": "--", "icon": "list" },
+    { "type": "stat-display", "label": "Active", "value": "--", "icon": "activity" },
+    { "type": "stat-display", "label": "Done", "value": "--", "icon": "check-circle" }
+  ]
+}
+\`\`\`
+
+### Composition Pattern: Data View with Actions
+
+\`\`\`json
+{
+  "type": "data-grid", "entity": "Task", "fields": ["title", "status", "priority"],
+  "itemActions": [
+    { "event": "VIEW", "label": "View" },
+    { "event": "EDIT", "label": "Edit" },
+    { "event": "DELETE", "label": "Delete" }
+  ]
+}
+\`\`\`
+
+---
+
+### 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:
+
+\`\`\`
+[] Single render-ui per transition
+[] Root element is layout (stack/box/simple-grid)
+[] Contains 2+ atoms (typography, badge, button, icon)
+[] Contains 1+ data molecules (data-grid, data-list, form-section, stats)
+[] NO organism patterns (entity-table, entity-list, page-header, etc.)
+[] Uses theme variables for ALL visual properties
+[] Matches production quality from standard behaviors
+[] Passes orbital validate with zero errors and zero warnings
+\`\`\`
+
+---
+
+### BANNED Patterns (Additional)
+
+| 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\` |
+| \`entity-table\` | \`data-grid\` |
+| \`entity-list\` | \`data-list\` |
+| \`page-header\` | \`stack\` + \`typography\` + \`button\` |
+
+---
+
+${getBindingsGuide()}
+`;
+}
+function getToolWorkflowSection2() {
+  return `---
+
+## Tool Workflow
+
+### Phase 1: DECOMPOSE
+Break requirements into OrbitalUnits (pure reasoning, no tools).
+
+### Phase 2: GENERATE
+
+**Option A: Orchestrated Generation (RECOMMENDED for 3+ orbitals)**
+Use \`generate_schema_orchestrated\` for automatic complexity-based routing:
+
+\`\`\`
+generate_schema_orchestrated({ prompt: "Full app description with all entities and features" })
+\`\`\`
+
+**Option B: Per-Orbital Generation (for simple cases or fine-grained control)**
+Call \`generate_orbital\` for each orbital:
+
+\`\`\`
+generate_orbital({ orbital: {...}, orbitalIndex: 0, totalOrbitals: N })
+\`\`\`
+
+### Phase 3: COMBINE
+Call \`finish_task\` to auto-combine orbitals into schema.orb:
+
+\`\`\`
+finish_task({ appName: "App" })
+\`\`\`
+
+### Phase 4: VALIDATE (CRITICAL)
+After combining, validate the schema:
+
+\`\`\`
+validate_schema()
+\`\`\`
+
+### Phase 5: VERIFY COMPOSITION QUALITY
+
+Before calling \`finish_task\`, verify each INIT transition:
+
+1. **Uses a single \`render-ui\` call** with top-level \`stack\` and \`children\`
+2. **Has 3+ composed sections**: header (HStack: title + action), metrics (stat-display/stats), data (data-grid/data-list)
+3. **Uses domain-appropriate atoms**: \`badge\` for status, \`typography\` for labels/values, \`button\` for actions
+4. **NO organisms**: Never \`entity-table\`, \`entity-list\`, \`page-header\`, \`detail-panel\`
+5. **Props are correct**: \`submitEvent\` not \`onSubmit\`, \`fields\` not \`fieldNames\`
+`;
+}
+function getCriticalOutputRequirements2() {
+  return `---
+
+## CRITICAL: Output Requirements
+
+Every orbital MUST include:
+
+### 1. domainContext (REQUIRED)
+\`\`\`json
+"domainContext": {
+  "request": "<original user request>",
+  "requestFragment": "<what part produced THIS orbital>",
+  "category": "business",
+  "vocabulary": { "item": "Task", "create": "Add", "delete": "Remove" }
+}
+\`\`\`
+
+### 2. design (REQUIRED)
+\`\`\`json
+"design": {
+  "style": "modern",
+  "uxHints": {
+    "flowPattern": "crud-cycle",
+    "listPattern": "data-grid",
+    "formPattern": "modal"
+  }
+}
+\`\`\`
+
+### 3. Business Rule Guards on SAVE (when rules exist)
+If the user specifies validation constraints, add S-expression guards:
+\`\`\`json
+{
+  "from": "Creating", "to": "Browsing", "event": "SAVE",
+  "guard": ["<=", "@payload.data.score", 100],
+  "effects": [["persist", "create", "Entry", "@payload.data"], ...]
+}
+\`\`\`
+
+### 4. ONE Orbital Per Entity
+
+### 5. Entity Field is REQUIRED (CRITICAL)
+Every orbital MUST have an entity field. No exceptions.`;
+}
+function getMoleculeFirstExample() {
+  return `---
+
+## Example: Task Manager (Molecule-First - VALIDATED)
+
+This example passes \`orbital validate\` with zero errors and zero warnings.
+Uses only atoms and molecules. No organisms.
+
+\`\`\`json
+{
+  "name": "Taskly",
+  "version": "1.0.0",
+  "orbitals": [{
+    "name": "Task Management",
+    "entity": {
+      "name": "Task",
+      "collection": "tasks",
+      "fields": [
+        { "name": "title", "type": "string", "required": true },
+        { "name": "description", "type": "string" },
+        { "name": "status", "type": "enum", "values": ["todo", "in-progress", "done"] },
+        { "name": "priority", "type": "enum", "values": ["low", "medium", "high"] }
+      ]
+    },
+    "traits": [{
+      "name": "TaskInteraction",
+      "category": "interaction",
+      "linkedEntity": "Task",
+      "emits": [{ "event": "INIT", "scope": "internal" }],
+      "stateMachine": {
+        "states": [
+          { "name": "Browsing", "isInitial": true },
+          { "name": "Creating" },
+          { "name": "Editing" },
+          { "name": "Viewing" }
+        ],
+        "events": [
+          { "key": "INIT", "name": "Initialize" },
+          { "key": "CREATE", "name": "Create" },
+          { "key": "VIEW", "name": "View", "payload": [{ "name": "id", "type": "string" }] },
+          { "key": "EDIT", "name": "Edit", "payload": [{ "name": "id", "type": "string" }] },
+          { "key": "DELETE", "name": "Delete", "payload": [{ "name": "id", "type": "string" }] },
+          { "key": "SAVE", "name": "Save", "payload": [{ "name": "data", "type": "object" }] },
+          { "key": "CANCEL", "name": "Cancel" },
+          { "key": "CLOSE", "name": "Close" }
+        ],
+        "transitions": [
+          {
+            "from": "Browsing", "to": "Browsing", "event": "INIT",
+            "effects": [
+              ["fetch", "Task"],
+              ["render-ui", "main", {
+                "type": "stack", "direction": "vertical", "gap": "lg",
+                "children": [
+                  {
+                    "type": "stack", "direction": "horizontal", "justify": "between", "align": "center",
+                    "children": [
+                      { "type": "typography", "variant": "h1", "text": "Task Management" },
+                      { "type": "button", "label": "New Task", "event": "CREATE", "variant": "primary", "icon": "plus" }
+                    ]
+                  },
+                  {
+                    "type": "stack", "direction": "horizontal", "gap": "md", "wrap": true,
+                    "children": [
+                      { "type": "stat-display", "label": "Total Tasks", "value": "--", "icon": "list" },
+                      { "type": "stat-display", "label": "In Progress", "value": "--", "icon": "clock" },
+                      { "type": "stat-display", "label": "Completed", "value": "--", "icon": "check-circle" }
+                    ]
+                  },
+                  {
+                    "type": "search-input", "placeholder": "Search tasks..."
+                  },
+                  {
+                    "type": "data-grid", "entity": "Task",
+                    "fields": ["title", "status", "priority"],
+                    "itemActions": [
+                      { "event": "VIEW", "label": "View" },
+                      { "event": "EDIT", "label": "Edit" },
+                      { "event": "DELETE", "label": "Delete" }
+                    ]
+                  }
+                ]
+              }]
+            ]
+          },
+          {
+            "from": "Browsing", "to": "Creating", "event": "CREATE",
+            "effects": [
+              ["render-ui", "modal", {
+                "type": "form-section", "entity": "Task",
+                "fields": ["title", "description", "status", "priority"],
+                "submitEvent": "SAVE", "cancelEvent": "CANCEL"
+              }]
+            ]
+          },
+          {
+            "from": "Browsing", "to": "Viewing", "event": "VIEW",
+            "effects": [
+              ["fetch", "Task", "@payload.id"],
+              ["render-ui", "modal", {
+                "type": "stack", "direction": "vertical", "gap": "md",
+                "children": [
+                  { "type": "typography", "variant": "h2", "text": "@entity.title" },
+                  { "type": "badge", "text": "@entity.status", "variant": "primary" },
+                  { "type": "badge", "text": "@entity.priority", "variant": "secondary" },
+                  { "type": "divider" },
+                  { "type": "typography", "variant": "body", "text": "@entity.description" },
+                  { "type": "stack", "direction": "horizontal", "gap": "sm", "justify": "end",
+                    "children": [
+                      { "type": "button", "label": "Edit", "event": "EDIT", "variant": "secondary" },
+                      { "type": "button", "label": "Close", "event": "CLOSE", "variant": "ghost" }
+                    ]
+                  }
+                ]
+              }]
+            ]
+          },
+          {
+            "from": "Browsing", "to": "Editing", "event": "EDIT",
+            "effects": [
+              ["fetch", "Task", "@payload.id"],
+              ["render-ui", "modal", {
+                "type": "form-section", "entity": "Task",
+                "fields": ["title", "description", "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": "Editing", "to": "Browsing", "event": "SAVE",
+            "effects": [
+              ["persist", "update", "Task", "@entity.id", "@payload.data"],
+              ["render-ui", "modal", null],
+              ["emit", "INIT"]
+            ]
+          },
+          {
+            "from": "Creating", "to": "Browsing", "event": "CANCEL",
+            "effects": [["render-ui", "modal", null]]
+          },
+          {
+            "from": "Creating", "to": "Browsing", "event": "CLOSE",
+            "effects": [["render-ui", "modal", null]]
+          },
+          {
+            "from": "Editing", "to": "Browsing", "event": "CANCEL",
+            "effects": [["render-ui", "modal", null]]
+          },
+          {
+            "from": "Editing", "to": "Browsing", "event": "CLOSE",
+            "effects": [["render-ui", "modal", null]]
+          },
+          {
+            "from": "Viewing", "to": "Browsing", "event": "CLOSE",
+            "effects": [["render-ui", "modal", null]]
+          },
+          {
+            "from": "Viewing", "to": "Browsing", "event": "CANCEL",
+            "effects": [["render-ui", "modal", null]]
+          },
+          {
+            "from": "Viewing", "to": "Editing", "event": "EDIT",
+            "effects": [
+              ["render-ui", "modal", {
+                "type": "form-section", "entity": "Task",
+                "fields": ["title", "description", "status", "priority"],
+                "submitEvent": "SAVE", "cancelEvent": "CANCEL"
+              }]
+            ]
+          },
+          {
+            "from": "Browsing", "to": "Browsing", "event": "DELETE",
+            "effects": [
+              ["persist", "delete", "Task", "@payload.id"],
+              ["emit", "INIT"]
+            ]
+          }
+        ]
+      }
+    }],
+    "pages": [{
+      "name": "TasksPage",
+      "path": "/tasks",
+      "viewType": "list",
+      "isInitial": true,
+      "entity": "Task",
+      "traits": [{ "ref": "TaskInteraction" }]
+    }],
+    "emits": [],
+    "listens": []
+  }]
+}
+\`\`\`
+
+**Key points (molecule-first composition):**
+- **Header**: \`stack\` (horizontal) + \`typography\` (h1) + \`button\` (composed, NOT \`page-header\`)
+- **Stats**: \`stat-display\` molecules in a horizontal \`stack\` (NOT \`stats\` organism)
+- **Search**: \`search-input\` molecule
+- **Data**: \`data-grid\` with \`entity\`, \`fields\`, \`itemActions\` (NOT \`entity-table\`)
+- **Detail view**: \`stack\` + \`typography\` + \`badge\` + \`divider\` (NOT \`detail-panel\`)
+- **Forms**: \`form-section\` with \`submitEvent\`/\`cancelEvent\`
+- **Theme**: All visual props use CSS variables
+`;
+}
+
 // src/orbitals-skills-generators/lean/lean-orbital-generator.ts
 var LEAN_CORE_INSTRUCTIONS = `
 ## Core Instructions
@@ -4651,6 +5476,7 @@ Example workflow:
 // src/generators/index.ts
 function generateAllBuilderSkills() {
   return [
+    generateOrbSkill(),
     generateKflowOrbitalsSkill(),
     generateKflowOrbitalFixingSkill(),
     {
@@ -5306,6 +6132,6 @@ function generateComparisonMatrix(comparisons) {
   return markdown;
 }
 
-export { EVAL_CASES, analyzeComposition, calculateTotalScore, formatFrontmatter, generateAllBuilderSkills, generateAlmadarAssistantSkill, 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, getSubagentSystemPrompt, getThemeGuide, getUsesImportCompact, getUsesImportSection, getValidationHintsSection, writeAllSkills, writeSkill };
+export { EVAL_CASES, analyzeComposition, calculateTotalScore, formatFrontmatter, generateAllBuilderSkills, generateAlmadarAssistantSkill, generateComparisonMatrix, generateDomainLanguageSkill, generateKflowOrbitalFixingSkill, generateKflowOrbitalsSkill, generateLeanFixingSkill2 as generateLeanFixingSkill, generateLeanFixingSkill as generateLeanFixingSkillFull, generateLeanOrbitalSkill2 as generateLeanOrbitalSkill, generateLeanOrbitalSkill as generateLeanOrbitalSkillFull, generateOrbSkill, 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, getOrbRenderUIGuide, getOrbitalConnectivitySection, getOrbitalDecompositionPrompt, getOverGenerationSection, getPatternTypesCompact, getPortableOrbitalOutputSection, getRenderUIDesignGuide, getRenderUIQuickRef2 as getRenderUIQuickRef, getRequirementsDecomposePrompt, getRequirementsTraitPrompt, getSExprQuickRef2 as getSExprQuickRef, getSchemaUpdateCompact, getSchemaUpdateSection, getSubagentSystemPrompt, getThemeGuide, getUsesImportCompact, getUsesImportSection, getValidationHintsSection, writeAllSkills, writeSkill };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map