@almadar/agent 1.6.1 → 1.6.2

package/dist/tools/index.js

@@ -5,7 +5,7 @@ import { exec, spawn, execSync } from 'child_process';
 import * as path from 'path';
 import path__default from 'path';
 import { promisify } from 'util';
-import * as fs4 from 'fs/promises';
+import * as fs5 from 'fs/promises';
 import { isStructuredOutputAvailable, getStructuredOutputClient, LLMClient } from '@almadar/llm';
 import * as domain_language_star from '@almadar/core/domain-language';
 import * as fs3 from 'fs';
@@ -585,12 +585,12 @@ ${output}`);
       description: `Execute a shell command in the workspace directory.
 
 IMPORTANT: You are restricted to your workspace directory. Use RELATIVE paths only:
-- ./schema.json (NOT /schema.json or absolute paths)
+- ./schema.orb (NOT /schema.orb or absolute paths)
 - ./app (NOT /app or absolute paths)
 
 Examples:
-- orbital validate ./schema.json --json
-- npx kflow compile ./schema.json -o ./app --verify
+- orbital validate ./schema.orb --json
+- npx kflow compile ./schema.orb -o ./app --verify
 - cd ./app && npm install
 
 Commands using absolute paths outside your workspace will be blocked.`,
@@ -604,7 +604,7 @@ Commands using absolute paths outside your workspace will be blocked.`,
 var execAsync = promisify(exec);
 var MAX_VALIDATION_ATTEMPTS = 5;
 function createValidateSchemaTool(workDir) {
-  const schemaPath = path.join(workDir, "schema.json");
+  const schemaPath = path.join(workDir, "schema.orb");
   let validationAttempts = 0;
   return tool(
     async () => {
@@ -620,7 +620,7 @@ function createValidateSchemaTool(workDir) {
       }
       try {
         try {
-          await fs4.access(schemaPath);
+          await fs5.access(schemaPath);
         } catch {
           return JSON.stringify({
             success: false,
@@ -629,7 +629,7 @@ function createValidateSchemaTool(workDir) {
             errors: [{
               code: "FILE_NOT_FOUND",
               path: "",
-              message: "File not found: schema.json. Create it first with write_file."
+              message: "File not found: schema.orb. Create it first with write_file."
             }]
           });
         }
@@ -690,7 +690,7 @@ function createValidateSchemaTool(workDir) {
     },
     {
       name: "validate_schema",
-      description: `Validate the schema.json file in the workspace.
+      description: `Validate the schema.orb file in the workspace.
 
 Runs validation using \`npx @almadar/cli validate --json\`.
 
@@ -1285,14 +1285,14 @@ function checkCompositionQuality(schema) {
 async function collectOrbitalsFromDir(workDir) {
   const orbitalsDir = path.join(workDir, ".orbitals");
   try {
-    const dirStat = await fs4.stat(orbitalsDir);
+    const dirStat = await fs5.stat(orbitalsDir);
     if (!dirStat.isDirectory()) {
       return [];
     }
   } catch {
     return [];
   }
-  const files = await fs4.readdir(orbitalsDir);
+  const files = await fs5.readdir(orbitalsDir);
   const jsonFiles = files.filter((f) => f.endsWith(".json"));
   if (jsonFiles.length === 0) {
     return [];
@@ -1300,7 +1300,7 @@ async function collectOrbitalsFromDir(workDir) {
   const orbitals = [];
   for (const file of jsonFiles) {
     try {
-      const content = await fs4.readFile(path.join(orbitalsDir, file), "utf-8");
+      const content = await fs5.readFile(path.join(orbitalsDir, file), "utf-8");
       orbitals.push(JSON.parse(content));
     } catch {
     }
@@ -1354,7 +1354,7 @@ function createFinishTaskTool(workDir) {
         } else {
           const domainPath = path.join(workDir, "domain.txt");
           try {
-            const domainText = await fs4.readFile(domainPath, "utf-8");
+            const domainText = await fs5.readFile(domainPath, "utf-8");
             if (domainText.trim()) {
               source = "domain";
               const appName = input.summary?.match(/Generated \d+ orbitals?:?\s*(.+)/)?.[1] || "Application";
@@ -1387,8 +1387,8 @@ function createFinishTaskTool(workDir) {
           compositionWarnings = checkCompositionQuality(combinedSchema);
         }
         if (combinedSchema) {
-          const schemaPath = path.join(workDir, "schema.json");
-          await fs4.writeFile(schemaPath, JSON.stringify(combinedSchema, null, 2));
+          const schemaPath = path.join(workDir, "schema.orb");
+          await fs5.writeFile(schemaPath, JSON.stringify(combinedSchema, null, 2));
           validationResult = await validateSchemaWithCLI(schemaPath);
         }
       }
@@ -1409,25 +1409,16 @@ function createFinishTaskTool(workDir) {
           propCorrections: propCorrections || 0,
           compositionWarnings: compositionWarnings || []
         },
-        schemaPath: combinedSchema ? path.join(workDir, "schema.json") : input.schemaPath,
+        schemaPath: combinedSchema ? path.join(workDir, "schema.orb") : input.schemaPath,
         nextAction: "NONE - Task is complete. Output a brief success message to the user."
       };
     },
     {
       name: "finish_task",
-      description: `Signal that the orbital generation workflow is COMPLETE.
-
-\u26A0\uFE0F IMPORTANT: After calling this tool, STOP. Do not make any more tool calls.
-
-WHAT IT DOES:
-1. Automatically collects orbitals from .orbitals/ directory
-2. Combines them into a single OrbitalSchema
-3. Validates the combined schema
-4. Writes schema.json to workspace
-5. Returns success with stats`,
+      description: `Complete workflow: collect orbitals from .orbitals/, combine into schema, validate, write schema.orb. STOP after calling.`,
       schema: z.object({
-        summary: z.string().describe("Brief summary of what was accomplished"),
-        schemaPath: z.string().optional().describe("Path to the combined schema file if already written")
+        summary: z.string().describe("What was accomplished"),
+        schemaPath: z.string().optional().describe("Schema file path if already written")
       })
     }
   );
@@ -1441,7 +1432,7 @@ function generateFingerprint(spec) {
     entity: spec.entity,
     pages: spec.pages,
     traits: spec.traits.sort(),
-    patterns: spec.patterns.sort(),
+    patterns: spec.patterns?.sort() || [],
     emits: spec.emits?.sort() || [],
     listens: spec.listens?.map((l) => `${l.event}:${l.triggers}`).sort() || []
   });
@@ -1578,7 +1569,7 @@ ${relations}` : ""}
 ${pagesInfo}
 
 **Behaviors**: ${spec.traits.join(", ")}
-**UI Patterns**: ${spec.patterns.join(", ")}
+**UI Patterns**: ${spec.patterns?.join(", ") || "auto-detect from traits"}
 ${emitsInfo}
 ${listensInfo}
 
@@ -1610,7 +1601,7 @@ var GenerateOrbitalDomainSchema = z.object({
       isInitial: z.boolean().optional()
     })),
     traits: z.array(z.string()),
-    patterns: z.array(z.string()),
+    patterns: z.array(z.string()).optional(),
     domainContext: z.object({
       request: z.string(),
       requestFragment: z.string().optional(),
@@ -1756,7 +1747,7 @@ function createGenerateOrbitalDomainTool(options = {}) {
           cached: false,
           domainWritten: true,
           usage,
-          domainText
+          domainLength: domainText.length
         });
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -2131,6 +2122,88 @@ ${sections.join("\n\n")}
 `;
 }
 
+// src/evals/utils/compact-orbital.ts
+function compactField(f) {
+  let desc = `${f.name}:${f.type}`;
+  if (f.required) desc += "*";
+  if (f.values) desc += `(${f.values.length})`;
+  if (f.relation) desc += `\u2192${f.relation.entity}`;
+  return desc;
+}
+function getStateName(state) {
+  return typeof state === "string" ? state : state.name;
+}
+function getTraitRef(ref) {
+  return typeof ref === "string" ? ref : ref.ref;
+}
+function compactOrbital(orbital) {
+  const lines = [];
+  lines.push(`orbital: ${orbital.name}`);
+  if (orbital.entity) {
+    const e = orbital.entity;
+    const fieldSummary = e.fields?.map(compactField).join(", ") || "none";
+    const collection = e.collection ? ` (${e.collection})` : "";
+    lines.push(`  entity: ${e.name}${collection} [${fieldSummary}] ${e.fields?.length || 0} fields`);
+  }
+  if (orbital.traits) {
+    for (const trait of orbital.traits) {
+      const sm = trait.stateMachine;
+      if (sm) {
+        const stateNames = sm.states?.map(getStateName) || [];
+        const stateList = stateNames.join("\u2192");
+        const stateCount = stateNames.length;
+        const eventCount = sm.events?.length || 0;
+        const transCount = sm.transitions?.length || 0;
+        lines.push(`  trait: ${trait.name} [${stateList}] ${stateCount} states, ${eventCount} events, ${transCount} transitions`);
+      } else {
+        lines.push(`  trait: ${trait.name}`);
+      }
+    }
+  }
+  if (orbital.pages) {
+    for (const page of orbital.pages) {
+      const traitRefs = page.traits?.map(getTraitRef).join(", ") || "none";
+      lines.push(`  page: ${page.path} \u2192 ${traitRefs}`);
+    }
+  }
+  if (orbital.emits?.length) {
+    lines.push(`  emits: ${orbital.emits.join(", ")}`);
+  }
+  if (orbital.listens?.length) {
+    lines.push(`  listens: ${orbital.listens.map((l) => `${l.event} \u2192 ${l.triggers}`).join(", ")}`);
+  }
+  return lines.join("\n");
+}
+function compactSchema(schema) {
+  const lines = [];
+  if (schema.name) {
+    lines.push(`schema: ${schema.name} v${schema.version || "1.0.0"}`);
+  }
+  const orbitals = schema.orbitals || [];
+  lines.push(`orbitals: ${orbitals.length}`);
+  for (const orbital of orbitals) {
+    lines.push(compactOrbital(orbital));
+  }
+  return lines.join("\n");
+}
+function compactOrbitalResult(result) {
+  if (!result.orbital) {
+    return JSON.stringify({ success: false, error: "Generation failed" });
+  }
+  const orbital = result.orbital;
+  const summary = compactOrbital(orbital);
+  const validationLine = result.validation ? result.validation.valid ? "  validation: valid" : `  validation: INVALID (${result.validation.errors?.map((e) => e.message).join("; ") || "unknown errors"})` : "";
+  const usageLine = result.usage ? `  tokens: ${result.usage.totalTokens || 0}` : "";
+  const compactLines = [
+    `success: true`,
+    `fingerprint: ${result.fingerprint || "none"}`,
+    summary,
+    validationLine,
+    usageLine
+  ].filter(Boolean);
+  return compactLines.join("\n");
+}
+
 // src/tools/orbital-subagent.ts
 function getEntityName3(entity) {
   if (isEntityReference(entity)) {
@@ -2152,8 +2225,8 @@ var OrbitalInputSchema = z.object({
         })
       )
     }),
-    traits: z.array(z.string()),
-    patterns: z.array(z.string()),
+    traits: z.array(z.string()).default([]),
+    patterns: z.array(z.string()).optional(),
     pages: z.array(
       z.object({
         name: z.string(),
@@ -2340,7 +2413,16 @@ function createOrbitalSubagentTool(options = {}) {
             });
           }
         }
-        return JSON.stringify({
+        if (options.workDir && finalOrbital) {
+          const orbitalsDir = path.join(options.workDir, ".orbitals");
+          fs3.mkdirSync(orbitalsDir, { recursive: true });
+          const safeFileName = orbitalUnit.name.replace(/[^a-zA-Z0-9_-]/g, "_");
+          fs3.writeFileSync(
+            path.join(orbitalsDir, `${safeFileName}.json`),
+            JSON.stringify(finalOrbital, null, 2)
+          );
+        }
+        return compactOrbitalResult({
           success: true,
           orbital: finalOrbital,
           fingerprint: result.fingerprint,
@@ -2362,15 +2444,19 @@ function createOrbitalSubagentTool(options = {}) {
     },
     {
       name: "generate_orbital",
-      description: `Generate a full orbital schema from an OrbitalUnit.
+      description: `Generate ONE orbital schema from a single OrbitalUnit.
 
 Spawns a subagent to expand a lightweight OrbitalUnit into a complete
 FullOrbitalUnit with all sections, layouts, and configurations.
 
+IMPORTANT: This tool generates exactly ONE orbital per call. Each orbital
+must have exactly ONE entity. For multi-entity apps, call this tool
+SEPARATELY for each orbital (e.g., 4 entities = 4 calls).
+
 USAGE:
-1. Decompose user request into OrbitalUnits
-2. For each orbital, call generate_orbital with embedded context
-3. Collect results and merge into final schema`,
+1. Decompose user request into OrbitalUnits (one per entity)
+2. Call generate_orbital ONCE PER ORBITAL \u2014 do NOT batch multiple orbitals
+3. After all orbitals are generated, call finish_task`,
       schema: OrbitalInputSchema
     }
   );
@@ -3399,27 +3485,27 @@ var CombineSchemaInputSchema = z.object({
   validate: z.boolean().optional().default(true)
 });
 async function autoCollectOrbitals(workDir) {
-  const fs7 = await import('fs');
-  const path8 = await import('path');
-  const orbitalsDir = path8.join(workDir, ".orbitals");
-  if (!fs7.existsSync(orbitalsDir)) {
-    const files2 = fs7.readdirSync(workDir).filter(
+  const fs9 = await import('fs');
+  const path10 = await import('path');
+  const orbitalsDir = path10.join(workDir, ".orbitals");
+  if (!fs9.existsSync(orbitalsDir)) {
+    const files2 = fs9.readdirSync(workDir).filter(
       (f) => f.endsWith(".json") && (f.startsWith("orbital-") || f.includes("orbital"))
     );
     if (files2.length === 0) {
       throw new Error("No orbitals found. Generate orbitals first using generate_orbital, or provide them directly.");
     }
     return files2.map((f) => {
-      const content = fs7.readFileSync(path8.join(workDir, f), "utf-8");
+      const content = fs9.readFileSync(path10.join(workDir, f), "utf-8");
       return JSON.parse(content);
     });
   }
-  const files = fs7.readdirSync(orbitalsDir).filter((f) => f.endsWith(".json"));
+  const files = fs9.readdirSync(orbitalsDir).filter((f) => f.endsWith(".json"));
   if (files.length === 0) {
     throw new Error("No orbitals found in .orbitals/ directory.");
   }
   return files.map((f) => {
-    const content = fs7.readFileSync(path8.join(orbitalsDir, f), "utf-8");
+    const content = fs9.readFileSync(path10.join(orbitalsDir, f), "utf-8");
     return JSON.parse(content);
   });
 }
@@ -3521,7 +3607,7 @@ var CHUNKS_DIR = ".chunks";
 async function ensureChunksDir(workspaceDir) {
   const chunksPath = path.join(workspaceDir, CHUNKS_DIR);
   try {
-    await fs4.mkdir(chunksPath, { recursive: true });
+    await fs5.mkdir(chunksPath, { recursive: true });
   } catch {
   }
   return chunksPath;
@@ -3545,7 +3631,7 @@ function createQuerySchemaStructureTool(workDir) {
     async ({ file }) => {
       const filePath = path.isAbsolute(file) ? file : path.join(workDir, file);
       try {
-        const content = await fs4.readFile(filePath, "utf-8");
+        const content = await fs5.readFile(filePath, "utf-8");
         const schema = JSON.parse(content);
         const stats = fs3.statSync(filePath);
         const structure = {
@@ -3574,7 +3660,7 @@ function createQuerySchemaStructureTool(workDir) {
 
 USE THIS FIRST before extracting chunks to understand what orbitals and traits exist.`,
       schema: z.object({
-        file: z.string().describe('Path to schema file (e.g., "schema.json")')
+        file: z.string().describe('Path to schema file (e.g., "schema.orb")')
       })
     }
   );
@@ -3584,7 +3670,7 @@ function createExtractChunkTool(workDir) {
     async ({ file, type, name, parentOrbital, includeTraits = true }) => {
       const filePath = path.isAbsolute(file) ? file : path.join(workDir, file);
       try {
-        const content = await fs4.readFile(filePath, "utf-8");
+        const content = await fs5.readFile(filePath, "utf-8");
         const schema = JSON.parse(content);
         const chunkId = randomUUID().slice(0, 8);
         const chunksDir = await ensureChunksDir(workDir);
@@ -3635,7 +3721,7 @@ function createExtractChunkTool(workDir) {
           chunkData.inlineTrait = orbital.traits[inlineTraitIndex];
         }
         const chunkContent = JSON.stringify(chunkData, null, 2);
-        await fs4.writeFile(chunkFile, chunkContent);
+        await fs5.writeFile(chunkFile, chunkContent);
         const relativeChunkFile = path.relative(workDir, chunkFile);
         return JSON.stringify({
           success: true,
@@ -3673,14 +3759,14 @@ function createApplyChunkTool(workDir) {
       const chunkFilePath = path.join(workDir, CHUNKS_DIR, chunkFileName);
       try {
         try {
-          await fs4.access(chunkFilePath);
+          await fs5.access(chunkFilePath);
         } catch {
           return JSON.stringify({ error: `Chunk file not found: ${chunkFileName}.` });
         }
-        const chunkContent = await fs4.readFile(chunkFilePath, "utf-8");
+        const chunkContent = await fs5.readFile(chunkFilePath, "utf-8");
         const chunkData = JSON.parse(chunkContent);
         const { meta } = chunkData;
-        const schemaContent = await fs4.readFile(meta.sourceFile, "utf-8");
+        const schemaContent = await fs5.readFile(meta.sourceFile, "utf-8");
         const schema = JSON.parse(schemaContent);
         if (meta.type === "orbital" && chunkData.orbital) {
           schema.orbitals[meta.orbitalIndex] = chunkData.orbital;
@@ -3711,8 +3797,8 @@ function createApplyChunkTool(workDir) {
           }
         }
         const output = JSON.stringify(schema, null, 2);
-        await fs4.writeFile(meta.sourceFile, output);
-        await fs4.unlink(chunkFilePath);
+        await fs5.writeFile(meta.sourceFile, output);
+        await fs5.unlink(chunkFilePath);
         return JSON.stringify({
           success: true,
           message: `Changes merged into ${path.basename(meta.sourceFile)}`,
@@ -4075,12 +4161,70 @@ function quickComplexityCheck(prompt) {
     estimatedOrbitals: estimatedCounts[estimate.estimatedLevel]
   };
 }
+function categorizeError(error) {
+  const message = error.message?.toLowerCase() || "";
+  const code = error.code?.toLowerCase() || "";
+  if (message.includes("binding") || code.includes("binding")) {
+    return "binding";
+  }
+  if (message.includes("state") || code.includes("state")) {
+    return "state-machine";
+  }
+  if (message.includes("required") || message.includes("missing")) {
+    return "schema";
+  }
+  return "other";
+}
+function getErrorSpecificGuidance(errors) {
+  const types = new Set(errors.map(categorizeError));
+  const guidance = [];
+  if (types.has("binding")) {
+    guidance.push(`
+## BINDING ERROR FIXES
+
+Invalid bindings detected. Fix these patterns:
+
+\u274C INVALID:
+- "@count" - missing entity reference
+- "@count:status=active" - wrong syntax
+- "@entity" - missing field
+
+\u2705 VALID:
+- "@entity.count" - entity field reference
+- "@entity.status" - enum field reference  
+- "@payload.data" - payload reference
+- "@state.current" - state reference
+
+Replace invalid bindings with proper entity.field references.`);
+  }
+  if (types.has("state-machine")) {
+    guidance.push(`
+## STATE MACHINE FIXES
+
+Check for:
+- Unreachable states (no incoming transitions)
+- Missing transitions for events
+- Invalid state names
+
+Ensure every state (except initial) has at least one incoming transition.`);
+  }
+  if (types.has("schema")) {
+    guidance.push(`
+## SCHEMA FIXES
+
+Check for:
+- Required fields (name, type for entity fields)
+- Missing entity definitions
+- Invalid type values`);
+  }
+  return guidance.join("\n");
+}
 async function createFixPlan(schema, errors, config) {
   const planStart = Date.now();
   const criticalErrors = errors.filter(
-    (e) => e.code?.includes("ENTITY") || e.code?.includes("REQUIRED") || e.code?.includes("JSON")
+    (e) => e.severity === "error" || e.code?.includes("ENTITY") || e.code?.includes("REQUIRED")
   );
-  const warningErrors = errors.filter((e) => !criticalErrors.includes(e));
+  const warningErrors = errors.filter((e) => e.severity === "warning");
   const orbitalErrors = /* @__PURE__ */ new Map();
   errors.forEach((error, index) => {
     let pathStr;
@@ -4106,6 +4250,8 @@ async function createFixPlan(schema, errors, config) {
     const orbital = schema.orbitals[orbitalIndex];
     if (orbital) {
       affectedOrbitals.push(orbital.name);
+      const stepErrors = errorIndices.map((i) => errors[i]);
+      const errorType = categorizeError(stepErrors[0]);
       const midPoint = Math.ceil(errorIndices.length / 2);
       const batches = [
         errorIndices.slice(0, midPoint),
@@ -4118,7 +4264,8 @@ async function createFixPlan(schema, errors, config) {
           orbitalIndex,
           errorIndices: batch,
           provider: batchIndex === 0 ? "deepseek" : "qwen",
-          dependencies: []
+          dependencies: [],
+          errorType
         });
       });
     }
@@ -4143,13 +4290,14 @@ async function createFixPlan(schema, errors, config) {
     console.log(`[Fixing] Plan created in ${Date.now() - planStart}ms`);
     console.log(`[Fixing] Strategy: ${parallelizationStrategy}`);
     console.log(`[Fixing] Steps: ${executionOrder.length}`);
+    console.log(`[Fixing] Error types: ${[...new Set(executionOrder.map((s) => s.errorType))].join(", ")}`);
   }
   return plan;
 }
 async function executeFixStep(schema, step, errors, config) {
   const orbital = schema.orbitals[step.orbitalIndex];
   if (!orbital) {
-    return { success: false, updatedOrbital: null };
+    return { success: false, updatedOrbital: null, fixed: false };
   }
   const client = step.provider === "deepseek" ? new LLMClient({
     provider: "deepseek",
@@ -4159,58 +4307,30 @@ async function executeFixStep(schema, step, errors, config) {
     model: "qwen/qwen3.5-397b-a17b"
   });
   const stepErrors = step.errorIndices.map((i) => errors[i]);
-  const skillContent = config.skillContent || "";
-  const hasBindingErrors = stepErrors.some(
-    (e) => e.message?.toLowerCase().includes("binding") || e.code?.toLowerCase().includes("binding")
-  );
-  const bindingGuidance = hasBindingErrors ? `
-## BINDING ERROR FIXES
-
-Common binding mistakes and fixes:
-
-\u274C INVALID:
-- "@count" \u2192 missing entity reference
-- "@status" \u2192 missing entity reference
-- "@count:status=active" \u2192 wrong syntax
-
-\u2705 VALID (from skill):
-- "@entity.count" - entity field reference
-- "@entity.status" - enum field reference  
-- "@payload.data" - event payload data
-- "@state" - current state name
-- "@now" - current timestamp
-
-Replace bare field names like "@count" with proper entity references like "@entity.count".
-` : "";
-  const systemPrompt = `${skillContent}
-
-${bindingGuidance}
-
-## FIXING INSTRUCTIONS
-
-You are fixing validation errors in an OrbitalSchema orbital.
-
-Rules:
-1. Preserve ALL valid content - only fix the reported errors
-2. Return the COMPLETE orbital with entity, traits, and pages
-3. Ensure entity has: name, collection, and fields array
-4. Use valid binding formats: @entity.field, @payload.field, @state
+  const errorGuidance = getErrorSpecificGuidance(stepErrors);
+  const skillContext = config.skillContent || "";
+  const systemPrompt = `You are an expert at fixing OrbitalSchema validation errors.
+${skillContext ? "\n" + skillContext.slice(0, 2e3) + "\n" : ""}
+${errorGuidance}
+
+CRITICAL RULES:
+1. Preserve ALL valid content - only fix the errors
+2. Return the COMPLETE orbital with all fields (entity, traits, pages)
+3. Ensure the entity field is present with proper name, collection, and fields
+4. Use valid binding formats: @entity.field, @payload.field, @state.field
 
 Return ONLY the fixed orbital as valid JSON.`;
-  const userPrompt = `Fix these validation errors in orbital "${orbital.name}":
+  const userPrompt = `Fix these errors in orbital "${orbital.name}":
 
-ERRORS:
-${stepErrors.map((e) => {
-    const path8 = Array.isArray(e.path) ? e.path.join(".") : e.path;
-    return `- Path: ${path8}
+ERRORS TO FIX:
+${stepErrors.map((e) => `- Path: ${Array.isArray(e.path) ? e.path.join(".") : e.path}
   Code: ${e.code}
-  Message: ${e.message}`;
-  }).join("\n")}
+  Message: ${e.message}`).join("\n")}
 
 CURRENT ORBITAL (JSON):
 ${JSON.stringify(orbital, null, 2)}
 
-Return the COMPLETE fixed orbital as JSON with all fields (entity, traits, pages).`;
+Return the COMPLETE fixed orbital as JSON. Include all fields (entity, traits, pages).`;
   try {
     const result = await client.call({
       systemPrompt,
@@ -4218,14 +4338,27 @@ Return the COMPLETE fixed orbital as JSON with all fields (entity, traits, pages
       maxTokens: 8192,
       skipSchemaValidation: true
     });
+    const fixedOrbital = result;
+    const hasEntity = fixedOrbital.entity && typeof fixedOrbital.entity === "object";
+    const hasName = typeof fixedOrbital.name === "string";
+    const hasTraits = Array.isArray(fixedOrbital.traits);
+    const isValid = Boolean(hasEntity && hasName && hasTraits);
+    if (!isValid && config.verbose) {
+      console.log(`[Fixing] Fix validation failed: entity=${hasEntity}, name=${hasName}, traits=${hasTraits}`);
+    }
     return {
-      success: true,
-      updatedOrbital: result
+      success: isValid,
+      updatedOrbital: result,
+      fixed: isValid
     };
   } catch (error) {
+    if (config.verbose) {
+      console.log(`[Fixing] Fix execution failed: ${error instanceof Error ? error.message : "Unknown"}`);
+    }
     return {
       success: false,
-      updatedOrbital: null
+      updatedOrbital: null,
+      fixed: false
     };
   }
 }
@@ -4243,22 +4376,22 @@ async function executeFixPlan(schema, plan, errors, config) {
       Promise.all(qwenSteps.map((step) => executeFixStep(schema, step, errors, config)))
     ]);
     deepseekSteps.forEach((step, i) => {
-      if (deepseekResults[i].success) {
+      if (deepseekResults[i].success && deepseekResults[i].fixed) {
         updatedSchema.orbitals[step.orbitalIndex] = deepseekResults[i].updatedOrbital;
       }
     });
     qwenSteps.forEach((step, i) => {
-      if (qwenResults[i].success) {
+      if (qwenResults[i].success && qwenResults[i].fixed) {
         updatedSchema.orbitals[step.orbitalIndex] = qwenResults[i].updatedOrbital;
       }
     });
   } else {
     for (const step of plan.executionOrder) {
       if (config.verbose) {
-        console.log(`[Fixing] Executing: ${step.description}`);
+        console.log(`[Fixing] Executing: ${step.description} (${step.errorType})`);
       }
       const result = await executeFixStep(schema, step, errors, config);
-      if (result.success) {
+      if (result.success && result.fixed) {
         updatedSchema.orbitals[step.orbitalIndex] = result.updatedOrbital;
       }
     }
@@ -4303,10 +4436,10 @@ function validateSchema(schema) {
     }
   }
 }
-async function orchestrateFixing(schema, config = {}) {
+async function orchestrateFixingV2(schema, config = {}) {
   const totalStart = Date.now();
   if (config.verbose) {
-    console.log("[Fixing] Starting Plan-Then-Execute fixing workflow");
+    console.log("[Fixing V2] Starting enhanced Plan-Then-Execute fixing workflow");
   }
   const initialValidation = validateSchema(schema);
   if (initialValidation.valid) {
@@ -4329,6 +4462,12 @@ async function orchestrateFixing(schema, config = {}) {
       }
     };
   }
+  if (config.verbose) {
+    console.log(`[Fixing V2] Found ${initialValidation.errors.length} errors to fix`);
+    initialValidation.errors.forEach((e) => {
+      console.log(`  - ${e.code}: ${e.message}`);
+    });
+  }
   const planStart = Date.now();
   const plan = await createFixPlan(schema, initialValidation.errors, config);
   const planMs = Date.now() - planStart;
@@ -4336,17 +4475,21 @@ async function orchestrateFixing(schema, config = {}) {
   let fixedSchema = await executeFixPlan(schema, plan, initialValidation.errors, config);
   const executeMs = Date.now() - executeStart;
   const verifyStart = Date.now();
-  const finalValidation = validateSchema(fixedSchema);
+  let finalValidation = validateSchema(fixedSchema);
   const verifyMs = Date.now() - verifyStart;
   let retries = 0;
   const maxRetries = config.maxRetries || 2;
   while (!finalValidation.valid && retries < maxRetries) {
     if (config.verbose) {
-      console.log(`[Fixing] Retrying (${retries + 1}/${maxRetries})...`);
+      console.log(`[Fixing V2] Retrying (${retries + 1}/${maxRetries})...`);
+      console.log(`[Fixing V2] Remaining errors: ${finalValidation.errors.length}`);
     }
     const retryPlan = await createFixPlan(fixedSchema, finalValidation.errors, config);
     fixedSchema = await executeFixPlan(fixedSchema, retryPlan, finalValidation.errors, config);
     const retryValidation = validateSchema(fixedSchema);
+    if (config.verbose) {
+      console.log(`[Fixing V2] After retry: ${retryValidation.errors.length} errors remaining`);
+    }
     if (retryValidation.valid || retryValidation.errors.length < finalValidation.errors.length) {
       finalValidation.errors = retryValidation.errors;
       finalValidation.valid = retryValidation.valid;
@@ -4355,11 +4498,11 @@ async function orchestrateFixing(schema, config = {}) {
   }
   const totalMs = Date.now() - totalStart;
   if (config.verbose) {
-    console.log("[Fixing] === Summary ===");
-    console.log(`[Fixing] Plan: ${planMs}ms, Execute: ${executeMs}ms, Verify: ${verifyMs}ms`);
-    console.log(`[Fixing] Total: ${totalMs}ms`);
-    console.log(`[Fixing] Errors: ${initialValidation.errors.length} \u2192 ${finalValidation.errors.length}`);
-    console.log(`[Fixing] Success: ${finalValidation.valid ? "YES" : "PARTIAL"}`);
+    console.log("[Fixing V2] === Summary ===");
+    console.log(`[Fixing V2] Plan: ${planMs}ms, Execute: ${executeMs}ms, Verify: ${verifyMs}ms`);
+    console.log(`[Fixing V2] Total: ${totalMs}ms`);
+    console.log(`[Fixing V2] Errors: ${initialValidation.errors.length} \u2192 ${finalValidation.errors.length}`);
+    console.log(`[Fixing V2] Success: ${finalValidation.valid ? "YES" : "PARTIAL"}`);
   }
   return {
     success: finalValidation.valid,
@@ -4406,9 +4549,25 @@ function createOrchestratedGenerationTool(options) {
           version: "1.0.0",
           orbitals: result.orbitals
         };
+        if (options.workDir) {
+          const schemaPath = path.join(options.workDir, "schema.orb");
+          fs3.writeFileSync(schemaPath, JSON.stringify(schema, null, 2));
+          const orbitalsDir = path.join(options.workDir, ".orbitals");
+          fs3.mkdirSync(orbitalsDir, { recursive: true });
+          for (const orbital of result.orbitals) {
+            const name = ("name" in orbital ? String(orbital.name) : "unknown").replace(/[^a-zA-Z0-9_-]/g, "_");
+            fs3.writeFileSync(
+              path.join(orbitalsDir, `${name}.json`),
+              JSON.stringify(orbital, null, 2)
+            );
+          }
+        }
+        const summary = compactSchema(schema);
         return {
           success: true,
-          schema,
+          summary,
+          orbitalCount: result.orbitals.length,
+          schemaPath: options.workDir ? path.join(options.workDir, "schema.orb") : void 0,
           complexity: result.complexity,
           provider: result.provider,
           timing: result.timing
@@ -4426,16 +4585,9 @@ function createOrchestratedGenerationTool(options) {
     },
     {
       name: "generate_schema_orchestrated",
-      description: `Generate an OrbitalSchema using complexity-based provider routing.
-
-This tool automatically selects the best generation strategy:
-- Simple (1 orbital) \u2192 Fast single-provider generation
-- Medium (2-3 orbitals) \u2192 Efficient single-provider generation  
-- Complex (4+ orbitals) \u2192 Parallel multi-provider generation
-
-The tool handles decomposition, provider selection, and result combination automatically.`,
+      description: `Generate an OrbitalSchema with automatic complexity-based provider routing.`,
       schema: z.object({
-        prompt: z.string().describe("User prompt describing the application to generate")
+        prompt: z.string().describe("App description prompt")
       })
     }
   );
@@ -4530,7 +4682,7 @@ function createOrchestratedFixingTool(options) {
         console.log(`[OrchestratedFixing] Found ${initialValidation.errors.length} errors to fix`);
       }
       try {
-        const result = await orchestrateFixing(typedSchema, {
+        const result = await orchestrateFixingV2(typedSchema, {
           maxRetries,
           verbose,
           skillContent