@almadar/skills 1.2.2 → 1.3.0

package/dist/index.d.ts

@@ -181,6 +181,12 @@ interface LeanSkillOptions {
  * the larger ~49K variant used by legacy callers.
  */
 declare function generateLeanOrbitalSkill(options?: LeanSkillOptions): string;
+/**
+ * Get subagent system prompt for orbital generation.
+ * This is used by the orbital generator subagent in @almadar/agent.
+ * Provides focused guidance on generating complete orbitals with entities.
+ */
+declare function getSubagentSystemPrompt(): string;
 
 /**
  * Lean Fixing Skill Generator
@@ -419,6 +425,8 @@ declare function getIconLibraryCompact(): string;
  * Get the fixing workflow section.
  */
 declare function getFixingWorkflowSection(): string;
+/**
+
 /**
  * Get common fix patterns section.
  */
@@ -660,4 +668,4 @@ interface ProviderComparison {
  */
 declare function generateComparisonMatrix(comparisons: ProviderComparison[]): string;
 
-export { type CompositionMetrics, EVAL_CASES, type EvalCase, type EvalResult, type GeneratedSkill, type ProviderComparison, type ScoreBreakdown, type SkillFrontmatter, analyzeComposition, calculateTotalScore, formatFrontmatter, generateAllBuilderSkills, generateComparisonMatrix, generateDomainLanguageSkill, generateKflowOrbitalFixingSkill, generateKflowOrbitalsSkill, generateLeanFixingSkill$1 as generateLeanFixingSkill, generateLeanFixingSkill as generateLeanFixingSkillFull, generateLeanOrbitalSkill$1 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, getKeyBehaviorsReference, getMinimalTypeReference, getMultiFileSection, getOrbitalConnectivitySection, getOrbitalDecompositionPrompt, getOverGenerationSection, getPatternTypesCompact, getPortableOrbitalOutputSection, getRenderUIDesignGuide, getRenderUIQuickRef, getRequirementsDecomposePrompt, getRequirementsTraitPrompt, getSExprQuickRef, getSchemaUpdateCompact, getSchemaUpdateSection, getThemeGuide, getUsesImportCompact, getUsesImportSection, getValidationHintsSection, writeAllSkills, writeSkill };
+export { type CompositionMetrics, EVAL_CASES, type EvalCase, type EvalResult, type GeneratedSkill, type ProviderComparison, type ScoreBreakdown, type SkillFrontmatter, analyzeComposition, calculateTotalScore, formatFrontmatter, generateAllBuilderSkills, generateComparisonMatrix, generateDomainLanguageSkill, generateKflowOrbitalFixingSkill, generateKflowOrbitalsSkill, generateLeanFixingSkill$1 as generateLeanFixingSkill, generateLeanFixingSkill as generateLeanFixingSkillFull, generateLeanOrbitalSkill$1 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, getKeyBehaviorsReference, getMinimalTypeReference, getMultiFileSection, getOrbitalConnectivitySection, getOrbitalDecompositionPrompt, getOverGenerationSection, getPatternTypesCompact, getPortableOrbitalOutputSection, getRenderUIDesignGuide, getRenderUIQuickRef, getRequirementsDecomposePrompt, getRequirementsTraitPrompt, getSExprQuickRef, getSchemaUpdateCompact, getSchemaUpdateSection, getSubagentSystemPrompt, getThemeGuide, getUsesImportCompact, getUsesImportSection, getValidationHintsSection, writeAllSkills, writeSkill };

package/dist/index.js

@@ -497,7 +497,28 @@ function getDecompositionSection() {
 ### 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** - do NOT split CRUD operations into separate orbitals
+- **CRITICAL: Create exactly ONE orbital per entity**
+- **CRITICAL: If the prompt mentions N entities, create N orbitals** (e.g., "Product, Category, Order" \u2192 3 orbitals)
+- **CRITICAL: EVERY orbital MUST have an entity field** - no exceptions
+- **NEVER** collapse multiple entities into a single dashboard orbital
+
+**Entity Field is REQUIRED in every orbital:**
+\`\`\`json
+{
+  "name": "Product Management",
+  "entity": {          // \u2190 REQUIRED: Every orbital needs this
+    "name": "Product",
+    "collection": "products",
+    "fields": [...]
+  },
+  "traits": [...],
+  "pages": [...]
+}
+\`\`\`
+
+**Common mistake to avoid:**
+- \u274C WRONG: Creating an orbital with no entity field
+- \u2705 CORRECT: Every orbital has its entity defined inline
 
 ### Step 2: Select Interaction Model
 | Domain | Create | View | Edit | Delete |
@@ -596,6 +617,9 @@ function getDecompositionCompact() {
 - What are the core data objects?
 - persistent (DB), runtime (memory), or singleton (config)?
 - **CRITICAL: Create exactly ONE orbital per entity**
+- **CRITICAL: If the prompt mentions N entities, create N orbitals** (e.g., "Product, Category, Order" \u2192 3 orbitals)
+- **CRITICAL: EVERY orbital MUST have an entity field**
+- **NEVER** collapse multiple entities into a single dashboard orbital
 
 ### Step 2: Select Interaction Model
 | Domain | Create | View | Edit | Delete |
@@ -2061,34 +2085,113 @@ function getIconLibraryCompact() {
 function getFixingWorkflowSection() {
   return `## Fixing Workflow
 
+### Understanding Validation Errors
+
+Validation output format:
+\`\`\`
+\u274C [ERROR_CODE] path.to.error: Description
+   \u{1F4A1} Fix hint
+\`\`\`
+
+**The path tells you exactly where to edit.**
+
+| Error Path | What to Edit |
+|------------|--------------|
+| \`orbitals[0].entity.fields\` | Add/modify entity fields |
+| \`orbitals[0].traits[0].stateMachine.transitions[1]\` | Add/modify transition |
+| \`orbitals[0].traits[0].stateMachine.states\` | Add state or mark isTerminal |
+| \`...effects[0][2].children[1].children[0].children[1].text\` | Fix binding in render-ui |
+
 ### Step 1: Validate and Analyze
 
 \`\`\`
 validate_schema()
 \`\`\`
 
-Group errors by orbital component:
+**CRITICAL: Before fixing, you MUST understand the full scope of errors.**
+
+Parse and categorize all errors:
 - **Entity errors**: Field types, relations, collection names
 - **Trait errors**: State machine, events, transitions
 - **Page errors**: Missing traits, invalid references
 - **Pattern errors**: Missing required fields in render-ui
 
-### Step 2: Apply Batched Fixes
+**Count errors by orbital and severity.**
+
+### Step 2: Create Fix Plan
+
+**BEFORE making any edits, write out your fix plan:**
+
+\`\`\`
+## Fix Plan
+
+### Summary
+- Total errors: X (Y critical, Z warnings)
+- Affected orbitals: [list]
+- Estimated complexity: simple|medium|complex
+
+### Execution Order
+1. **Fix [ID]**: [Description] -> [Target location]
+2. **Fix [ID]**: [Description] -> [Target location]
+3. ...
+
+### Dependencies
+- Fix X must happen before Fix Y
+- Group A fixes can be batched
+\`\`\`
+
+**Planning Rules:**
+- Group related fixes (same orbital, same component)
+- Identify dependencies (entity fields before bindings)
+- Prioritize critical errors first
+- Estimate if fix is simple (1 edit) or needs multiple steps
+
+### Step 3: Execute Fixes
 
-Fix ALL errors of the same type in one edit. Priority order:
+**Execute your plan systematically:**
 
-1. **Entity fixes** (field types, enums, relations)
-2. **State machine fixes** (initial state, orphan states)
-3. **Transition fixes** (missing INIT, unreachable states)
-4. **Pattern fixes** (missing props in render-ui effects)
+For each fix in your plan:
+1. **Apply the fix** using Edit tool
+2. **Verify the fix** - check the specific error is resolved
+3. **Track progress** - note which fixes are done
 
-### Step 3: Re-validate
+**Execution Order (Priority):**
+1. **Entity structure fixes** (add missing entity, fields, persistence)
+2. **Event/state fixes** (add missing events, states, transitions)
+3. **Effect fixes** (render-ui effects, bindings)
+4. **Pattern property fixes** (missing columns, fields, actions)
+5. **Minor syntax fixes** (enum values, type corrections)
+
+**Batching Strategy:**
+- Fix ALL errors of the same type in one orbital per edit
+- If errors span multiple orbitals, create separate edits
+- Document what each edit fixes
+
+### Step 4: Re-validate and Verify
 
 \`\`\`
 validate_schema()
 \`\`\`
 
-**STOP when "valid": true** - do not add more tasks or re-verify.`;
+**After each batch of fixes, re-validate to confirm progress.**
+
+Compare results with your plan:
+- Expected errors resolved
+- New errors appeared (unintended side effects)
+- Errors still present (fix did not work)
+
+**If new errors appear:**
+1. Analyze the new error
+2. Update your fix plan
+3. Continue execution
+
+### Step 5: Final Summary
+
+**Call finish_task with:**
+- Summary of what was fixed
+- Number of edits made
+- Any warnings or notes
+`;
 }
 function getCommonFixPatternsSection() {
   return `## Common Fix Patterns
@@ -2126,7 +2229,49 @@ function getCommonFixPatternsSection() {
 | \`form-section\` | onSubmit | \`"onSubmit": "SAVE"\` |
 | \`form-section\` | fields | \`"fields": ["field1", "field2"]\` |
 | \`detail-panel\` | fields | \`"fields": ["field1", "field2"]\` |
-| \`page-header\` | actions | \`"actions": [{ "label": "New", "event": "CREATE" }]\` |`;
+| \`page-header\` | actions | \`"actions": [{ "label": "New", "event": "CREATE" }]\` |
+
+### Binding Format Fixes (CRITICAL)
+
+Validator error: \`ORB_BINDING_INVALID_FORMAT\` - "Invalid binding format: '@count:status=pending'"
+Suggestion: "Use @root.field.nested format" means \`@entity.fieldName\`, NOT literal "root".
+
+**Common Invalid Patterns from Validator:**
+| Invalid Binding | Validator Message | Fix |
+|-----------------|-------------------|-----|
+| \`@count\` | Invalid binding format | Remove OR use \`@entity.count\` with computed field |
+| \`@count:status=pending\` | Invalid binding format | \`@entity.pendingCount\` + add computed field |
+| \`@count:status=active\` | Invalid binding format | \`@entity.activeCount\` + add computed field |
+| \`@count:status=done\` | Invalid binding format | \`@entity.doneCount\` + add computed field |
+
+**Step-by-Step Fix Process:**
+
+Given error: \`ORB_BINDING_INVALID_FORMAT\` at path \`orbitals[0].traits[0]...children[1].text\`
+
+1. **Extract orbital index** from path (e.g., \`orbitals[0]\` -> index 0)
+2. **Find the invalid binding** (e.g., \`"@count:status=pending"\`)
+3. **Add computed fields** to orbital's entity:
+\`\`\`json
+// In orbitals[0].entity.fields array, ADD:
+{ "name": "pendingCount", "type": "number", "default": 0 },
+{ "name": "activeCount", "type": "number", "default": 0 },
+{ "name": "doneCount", "type": "number", "default": 0 }
+\`\`\`
+4. **Replace ALL invalid bindings** in render-ui:
+\`\`\`json
+// BEFORE:
+{ "type": "badge", "text": "@count:status=pending", "variant": "warning" }
+// AFTER:
+{ "type": "badge", "text": "@entity.pendingCount", "variant": "warning" }
+\`\`\`
+
+**Validator Error Code Reference:**
+| Code | Meaning | Action |
+|------|---------|--------|
+| \`ORB_BINDING_INVALID_FORMAT\` | Binding syntax wrong | Use \`@entity.field\` format |
+| \`ORB_BINDING_UNKNOWN_ROOT\` | Wrong root prefix | Use \`@entity\`, \`@payload\`, \`@state\`, \`@now\` |
+| \`ORB_BINDING_INVALID_PATH\` | Field doesn't exist | Add field to entity OR correct name |
+| \`ORB_BINDING_STATE_NO_PATH\` | \`@state\` needs no path | Use \`@state\` alone, not \`@state.field\` |`;
 }
 function getOverGenerationSection() {
   return `## Over-Generation Detection
@@ -2156,16 +2301,57 @@ The trait's render-ui effects handle all UI (modals for create/edit, drawers for
 function getEfficiencySection() {
   return `## Efficiency Guidelines
 
-Target: **30-50 tool calls** for most fixes.
+Target: **3-5 tool calls** for most fixes.
+
+### For Small Schemas (< 15KB)
+
+\`\`\`
+Step 1: Read schema.orb (1 call)
+Step 2: Edit to fix ALL errors at once (1 call)
+Step 3: Validate if needed (1 call)
+Total: 3 tool calls
+\`\`\`
+
+### For Large Schemas (> 15KB) - MANDATORY CHUNKING
+
+**\u26A0\uFE0F WARNING: For schemas larger than 15KB, you MUST use chunking tools.**
+
+Direct edit_file on large schemas will fail or consume excessive tokens. ALWAYS use this workflow:
+
+\`\`\`
+MANDATORY Step 1: query_schema_structure("schema.orb")
+                   \u2192 Check totalSize field
+
+MANDATORY Step 2: extract_chunk({
+                     file: "schema.orb",
+                     type: "orbital", 
+                     name: "TargetOrbitalName"
+                   })
+                   \u2192 Returns: { chunkId: "abc123", chunkFile: ".chunks/chunk-abc123.json" }
+
+MANDATORY Step 3: edit_file({
+                     path: ".chunks/chunk-abc123.json",
+                     old_string: ...,
+                     new_string: ...
+                   })
+
+MANDATORY Step 4: apply_chunk({ chunkId: "abc123" })
+                   \u2192 Merges back to schema.orb
+\`\`\`
+
+**NEVER** use Read/Edit directly on schema files > 15KB. **ALWAYS** use chunking.
 
 **DO:**
-- Batch related changes (read once, edit all, write once)
-- Fix all same-type errors together
-- Run validation once after all changes
+- **Target 3 tool calls** for simple fixes (read \u2192 edit \u2192 done)
+- Fix ONLY what the user asked for (don't over-fix)
+- Batch related changes in ONE edit
+- Use chunking for schemas > 15KB
 
 **DON'T:**
+- Fix errors the user didn't ask about
+- Add missing transitions/states unless explicitly requested
 - Read schema multiple times without changes
-- Make one small change per tool call
+- Make multiple small edits - do ONE comprehensive edit
 - Re-verify after validation passes
 - Create documentation files`;
 }
@@ -2678,7 +2864,46 @@ If the user specifies validation constraints, add S-expression guards on transit
 ### 4. ONE Orbital Per Entity
 Do NOT create multiple orbitals for the same entity. All CRUD operations belong in ONE orbital.
 
-**Missing context fields = validation warnings. Missing guards = unenforced business rules!**`;
+### 5. Entity Field is REQUIRED (CRITICAL)
+Every orbital MUST have an entity field. No exceptions.
+
+\`\`\`json
+{
+  "name": "Product Management",
+  "entity": {          // \u2190 REQUIRED
+    "name": "Product",
+    "collection": "products",
+    "fields": [...]
+  },
+  "traits": [...],
+  "pages": [...]
+}
+\`\`\`
+
+**Verify before calling finish_task:**
+- [ ] Each orbital has an "entity" field
+- [ ] Each entity has a "name" and "collection"
+- [ ] Each entity has "fields" array
+
+**Missing entity field = INVALID orbital!**
+
+**Fixing Entity Errors:**
+If validation shows errors like "Missing entity" or "No fields":
+1. Read the orbital file from .orbitals/ directory
+2. Add the missing entity field:
+\`\`\`json
+"entity": {
+  "name": "Product",
+  "collection": "products",
+  "fields": [
+    { "name": "name", "type": "string", "required": true },
+    { "name": "price", "type": "number" }
+  ]
+}
+\`\`\`
+3. Save the file and re-validate
+
+**DO NOT call finish_task until ALL orbitals have entities!**`;
 }
 function getToolWorkflowSection() {
   return `---
@@ -2699,8 +2924,28 @@ generate_orbital({ orbital: {...}, orbitalIndex: 1, totalOrbitals: N })
 
 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:
+### Phase 3: VALIDATE (CRITICAL)
+After generating ALL orbitals, validate BEFORE calling finish_task:
+
+\`\`\`
+validate_schema()
+\`\`\`
+
+**If validation shows errors:**
+1. Read the error path (e.g., orbitals[0].entity)
+2. Fix the issue in the orbital file
+3. Re-run validate_schema()
+
+**Common errors to fix:**
+- ORB_E_MISSING_NAME \u2192 Add entity name
+- ORB_E_NO_FIELDS \u2192 Add entity fields  
+- Missing entity field \u2192 Add entity object with name and fields
+
+**CRITICAL: Check EACH orbital file in .orbitals/ directory:**
+Use Read tool to check each orbital file has entity field.
+
+### Phase 4: COMBINE
+Call \`finish_task\` to auto-combine:
 
 \`\`\`
 finish_task({ appName: "App" })
@@ -2841,6 +3086,203 @@ This example passes \`npx @almadar/cli validate\` with zero errors:
 - 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
+
+---
+
+## Example: E-commerce with Multiple Orbitals (3 Entities)
+
+For an app with Product, Category, and Order:
+
+\`\`\`json
+{
+  "name": "EcommerceAdmin",
+  "version": "1.0.0",
+  "orbitals": [
+    {
+      "name": "Product Management",
+      "entity": {
+        "name": "Product",
+        "collection": "products",
+        "fields": [
+          { "name": "name", "type": "string", "required": true },
+          { "name": "price", "type": "number", "required": true },
+          { "name": "stock", "type": "number", "default": 0 }
+        ]
+      },
+      "traits": [{ "name": "ProductInteraction", "category": "interaction", "linkedEntity": "Product" }],
+      "pages": [{ "name": "ProductsPage", "path": "/products", "traits": [{ "ref": "ProductInteraction" }] }]
+    },
+    {
+      "name": "Category Management",
+      "entity": {
+        "name": "Category",
+        "collection": "categories",
+        "fields": [
+          { "name": "name", "type": "string", "required": true },
+          { "name": "slug", "type": "string", "required": true }
+        ]
+      },
+      "traits": [{ "name": "CategoryInteraction", "category": "interaction", "linkedEntity": "Category" }],
+      "pages": [{ "name": "CategoriesPage", "path": "/categories", "traits": [{ "ref": "CategoryInteraction" }] }]
+    },
+    {
+      "name": "Order Management",
+      "entity": {
+        "name": "Order",
+        "collection": "orders",
+        "fields": [
+          { "name": "orderNumber", "type": "string", "required": true },
+          { "name": "totalAmount", "type": "number", "required": true },
+          { "name": "status", "type": "enum", "values": ["pending", "processing", "shipped", "delivered"] }
+        ]
+      },
+      "traits": [{ "name": "OrderInteraction", "category": "interaction", "linkedEntity": "Order" }],
+      "pages": [{ "name": "OrdersPage", "path": "/orders", "traits": [{ "ref": "OrderInteraction" }] }]
+    }
+  ]
+}
+\`\`\`
+
+**Key Points for Multi-Orbital Apps:**
+- Each orbital has its own entity field (REQUIRED)
+- Each entity has its own collection name
+- Each orbital has its own page
+- Call \`generate_orbital\` 3 times (once per orbital)
+`;
+}
+function getSubagentSystemPrompt() {
+  return `# Orbital Generation Subagent
+
+You are a specialized subagent that generates complete FullOrbitalUnit definitions.
+Your task is to expand a lightweight orbital input into a full orbital with entity, traits, state machines, and pages.
+
+## Core Formula
+Orbital Unit = Entity \xD7 Traits \xD7 Patterns
+
+## REQUIRED Output Structure
+
+Every orbital MUST have this exact structure:
+
+\`\`\`json
+{
+  "name": "OrbitalName",
+  "entity": {                    // \u2190 CRITICAL: REQUIRED FIELD
+    "name": "EntityName",
+    "collection": "entitynames",  // Plural lowercase
+    "persistence": "persistent",  // or "runtime" or "singleton"
+    "fields": [
+      { "name": "fieldName", "type": "string|number|boolean|enum|timestamp|array|object|relation", "required": true }
+    ]
+  },
+  "traits": [
+    {
+      "name": "TraitName",
+      "category": "interaction",
+      "linkedEntity": "EntityName",
+      "stateMachine": {
+        "states": [
+          { "name": "Browsing", "isInitial": true },
+          { "name": "Creating" },
+          { "name": "Editing" }
+        ],
+        "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": [
+                  // header, metrics, data table
+                ]
+              }]
+            ]
+          }
+        ]
+      }
+    }
+  ],
+  "pages": [
+    {
+      "name": "PageName",
+      "path": "/path",
+      "viewType": "list",
+      "traits": [{ "ref": "TraitName" }]
+    }
+  ],
+  "domainContext": {
+    "request": "...",
+    "category": "business",
+    "vocabulary": { "item": "...", "create": "..." }
+  },
+  "design": {
+    "style": "modern",
+    "uxHints": { "flowPattern": "crud-cycle", "listPattern": "entity-table" }
+  }
+}
+\`\`\`
+
+## CRITICAL RULES
+
+1. **ENTITY FIELD IS REQUIRED**: Every orbital MUST have an "entity" field at the top level
+2. **Entity Name**: Must match the orbital's primary entity
+3. **Collection**: Plural lowercase version of entity name (e.g., "products" for Product)
+4. **Fields**: At minimum, include id, name, and relevant fields from input
+
+## Common Mistakes to Avoid
+
+- \u274C WRONG: Missing entity field at orbital level
+- \u274C WRONG: Only linkedEntity in trait, no orbital.entity
+- \u274C WRONG: Empty fields array
+- \u2705 CORRECT: Full entity object with name, collection, persistence, fields
+
+## Field Types
+
+| Type | Use For | Example |
+|------|---------|---------|
+| string | Text, names | { "name": "title", "type": "string", "required": true } |
+| number | Prices, counts | { "name": "price", "type": "number" } |
+| enum | Status, categories | { "name": "status", "type": "enum", "values": ["pending", "active"] } |
+| timestamp | Dates, times | { "name": "createdAt", "type": "timestamp", "default": "@now" } |
+| relation | Links to other entities | { "name": "categoryId", "type": "relation", "relation": { "entity": "Category" } } |
+
+## State Machine Patterns
+
+**CRUD Pattern:**
+- States: Browsing (isInitial), Creating, Editing, Viewing
+- Events: INIT, CREATE, EDIT, VIEW, SAVE, CANCEL, DELETE
+- INIT effect: render-ui with stack containing header, metrics, entity-table
+
+**Transitions:**
+- Browsing \u2192 Creating: on CREATE
+- Creating \u2192 Browsing: on SAVE or CANCEL
+- Browsing \u2192 Editing: on EDIT
+- Editing \u2192 Browsing: on SAVE or CANCEL
+
+## Effects Reference
+
+| Effect | Syntax | Purpose |
+|--------|--------|---------|
+| render-ui | ["render-ui", "main", { ... }] | Render UI pattern |
+| render-ui | ["render-ui", "modal", { ... }] | Render modal |
+| persist | ["persist", "create", "Entity", "@payload.data"] | Save to DB |
+| set | ["set", "@entity.field", value] | Update field |
+| emit | ["emit", "EVENT", payload] | Emit event |
+| navigate | ["navigate", "/path"] | Navigate |
+
+## Output Requirements
+
+Return ONLY valid JSON. No markdown, no explanations.
+The JSON must be a complete FullOrbitalUnit with all required fields.
 `;
 }
 
@@ -2971,7 +3413,7 @@ function generateKflowOrbitalFixingSkill() {
   const frontmatter = {
     name: metadata.name,
     description: metadata.description,
-    allowedTools: ["Read", "Edit", "Bash"],
+    allowedTools: ["Read", "Edit", "Bash", "query_schema_structure", "extract_chunk", "apply_chunk"],
     version: metadata.version
   };
   const content = generateLeanFixingSkill({
@@ -3980,14 +4422,34 @@ ${getCommonErrorsSection()}
 
 Return ONLY valid JSON matching the FullOrbitalUnit structure. No markdown, no explanations.
 
+**CRITICAL: The entity field is REQUIRED at the orbital level:**
+
 \`\`\`json
 {
-  "name": "EntityName",
-  "entity": { ... },
+  "name": "Product Management",
+  "entity": {          // \u2190 REQUIRED: Must have this field
+    "name": "Product",
+    "collection": "products",
+    "persistence": "persistent",
+    "fields": [
+      { "name": "name", "type": "string", "required": true },
+      { "name": "price", "type": "number" }
+    ]
+  },
   "traits": [ ... ],
   "pages": [ ... ]
 }
 \`\`\`
+
+**Validation Rules:**
+- MUST include "entity" field at orbital level (NOT just linkedEntity in traits)
+- entity.name must match the orbital's primary entity
+- entity.collection must be plural lowercase (e.g., "products", not "Product")
+- entity.fields must have at least one field
+
+**Common Mistake:**
+- \u274C WRONG: Only putting entity reference in trait.linkedEntity
+- \u2705 CORRECT: Full entity object in orbital.entity field
 `.trim();
 }
 function getRequirementsDecomposePrompt() {
@@ -4392,6 +4854,6 @@ function generateComparisonMatrix(comparisons) {
   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 };
+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, getSubagentSystemPrompt, getThemeGuide, getUsesImportCompact, getUsesImportSection, getValidationHintsSection, writeAllSkills, writeSkill };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map