@eigenpal/cli 0.14.3 → 0.15.1

package/dist/cli.js

@@ -52713,10 +52713,11 @@ function compileTypedScript(opts) {
     });
   }
   const actualParamNames = actualParams;
-  if (actualParamNames.length !== expectedParams.length || actualParamNames.some((n, i) => n !== expectedParams[i])) {
+  const parametersMismatch = opts.kind === "evaluator" ? actualParamNames.length !== expectedParams.length || actualParamNames.some((name, index) => name !== expectedParams[index]) : actualParamNames.length !== expectedParams.length || new Set(actualParamNames).size !== actualParamNames.length || actualParamNames.some((name) => !expectedParams.includes(name));
+  if (parametersMismatch) {
     return failWith({
       kind: "wrong-shape",
-      message: `Parameter list must be \`(${expectedParams.join(", ")})\` in this order (got \`(${actualParamNames.join(", ")})\`).`,
+      message: opts.kind === "evaluator" ? `Parameter list must be \`(${expectedParams.join(", ")})\` in this order (got \`(${actualParamNames.join(", ")})\`).` : `Parameter names must match the configured inputs \`(${expectedParams.join(", ")})\`; their order does not matter (got \`(${actualParamNames.join(", ")})\`).`,
       line: fn.loc?.start.line,
       column: fn.loc?.start.column
     });
@@ -53482,8 +53483,8 @@ var init_step_configs = __esm(() => {
   }).superRefine(refineJsonToXlsxLayout);
   TransformJsonToXlsxOutputSchema = JsonToXlsxOutputSchema;
   TransformScriptConfigSchema = object({
-    inputs: record(string2(), string2()).optional().describe("Named inputs mapped from template expressions. Keys become the function parameter list in declaration order: `inputs: { items, taxRate }` ⇒ `function script(items: …, taxRate: …): R { … }`."),
-    function: string2().min(1).max(SCRIPT_FN_MAX_BYTES, `script function is too long (max ${(SCRIPT_FN_MAX_BYTES / 1000).toFixed(0)}k characters)`).describe("TypeScript function declaration. Must be `function script(args): R { … }` where the parameter list equals `Object.keys(inputs)` in order and `R` is a return type annotation. The annotation IS this step's output schema."),
+    inputs: record(string2(), string2()).optional().describe("Named inputs mapped from template expressions. Keys become function parameters; parameter order is independent of YAML/JSON key order: `inputs: { items, taxRate }` accepts `function script(taxRate: …, items: …): R { … }`."),
+    function: string2().min(1).max(SCRIPT_FN_MAX_BYTES, `script function is too long (max ${(SCRIPT_FN_MAX_BYTES / 1000).toFixed(0)}k characters)`).describe("TypeScript function declaration. Must be `function script(args): R { … }` where parameter names exactly match the configured input keys in any order and `R` is a return type annotation. The annotation IS this step's output schema."),
     timeout: number2().positive().default(5000).optional().describe("Max execution time in milliseconds (default: 5000)"),
     memoryLimit: number2().positive().default(10 * 1024 * 1024).optional().describe("Max memory in bytes (default: 10MB)")
   }).superRefine((cfg, ctx) => {
@@ -53863,7 +53864,7 @@ var init_step_configs = __esm(() => {
       type: "transform.script",
       category: "transform",
       name: "Script",
-      description: "Execute a TypeScript function in a QuickJS sandbox. Input keys become the function's parameter list, in declaration order, and the required `: R` return-type annotation IS this step's output schema: `inputs: { items, taxRate }` ⇒ `function script(items: …, taxRate: …): R { … }`.",
+      description: "Execute a TypeScript function in a QuickJS sandbox. Input keys become function parameters in any order, and the required `: R` return-type annotation IS this step's output schema: `inputs: { items, taxRate }` accepts `function script(taxRate: …, items: …): R { … }`.",
       configSchema: TransformScriptConfigSchema,
       outputSchema: TransformScriptOutputSchema,
       configInWith: true
@@ -54027,36 +54028,36 @@ var init_workflow = __esm(() => {
   init_retry();
   init_steps();
   WORKFLOW_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]*$/;
-  WorkflowNameSchema = string2().min(1).max(64).regex(WORKFLOW_NAME_PATTERN, 'Workflow name must start with a lowercase letter or digit and contain only lowercase letters, digits, "_" or "-".');
+  WorkflowNameSchema = string2().min(1).max(64).regex(WORKFLOW_NAME_PATTERN, 'Workflow name must start with a lowercase letter or digit and contain only lowercase letters, digits, "_" or "-".').describe("URL-safe workflow slug: 1-64 lowercase letters, digits, underscores, or hyphens; must start with a letter or digit.");
   WorkflowInputPropertySchema = lazy(() => object({
-    name: string2().min(1).regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "Property names must start with a letter or underscore and contain only letters, numbers, and underscores"),
-    type: string2(),
-    description: string2().optional(),
-    required: boolean2().optional(),
-    values: array(string2()).optional(),
+    name: string2().min(1).regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "Property names must start with a letter or underscore and contain only letters, numbers, and underscores").describe("JSON object key, addressable in templates with dot notation."),
+    type: string2().describe("One of string, enum, number, integer, boolean, array, or object."),
+    description: string2().optional().describe("Human-readable field meaning."),
+    required: boolean2().optional().describe("Whether this property must be present; defaults to true when omitted."),
+    values: array(string2()).optional().describe("Allowed strings when type is enum."),
     items: object({
-      type: string2(),
-      values: array(string2()).optional(),
-      properties: array(WorkflowInputPropertySchema).optional()
-    }).optional(),
-    properties: array(WorkflowInputPropertySchema).optional()
+      type: string2().describe("Array element type: string, enum, number, integer, boolean, or object."),
+      values: array(string2()).optional().describe("Allowed strings when items.type is enum."),
+      properties: array(WorkflowInputPropertySchema).optional().describe("Recursive object fields when items.type is object.")
+    }).optional().describe("Element definition when type is array."),
+    properties: array(WorkflowInputPropertySchema).optional().describe("Recursive fields when type is object.")
   }));
   WorkflowInputDefSchema = object({
-    name: string2().min(1),
-    type: string2(),
-    description: string2().optional(),
-    required: boolean2().default(true),
-    default: unknown().optional(),
-    values: array(string2()).optional(),
+    name: string2().min(1).describe("Top-level input name used as `input.<name>` in template expressions."),
+    type: string2().describe("One of string, enum, number, integer, boolean, array, object, or file."),
+    description: string2().optional().describe("Human-readable input meaning shown to callers."),
+    required: boolean2().default(true).describe("Whether callers must provide this input."),
+    default: unknown().optional().describe("Value used when an optional input is omitted."),
+    values: array(string2()).optional().describe("Closed set of allowed strings when type is enum."),
     items: object({
-      type: string2(),
-      values: array(string2()).optional(),
-      properties: array(WorkflowInputPropertySchema).optional()
-    }).optional(),
-    properties: array(WorkflowInputPropertySchema).optional(),
-    source: string2().min(1).optional(),
-    mimeType: string2().min(1).optional(),
-    extension: string2().min(1).optional()
+      type: string2().describe("Array element type: string, enum, number, integer, boolean, object, or file."),
+      values: array(string2()).optional().describe("Closed set of allowed strings when items.type is enum."),
+      properties: array(WorkflowInputPropertySchema).optional().describe("Recursive fields when items.type is object.")
+    }).optional().describe("Element definition when type is array."),
+    properties: array(WorkflowInputPropertySchema).optional().describe("Recursive field definitions when type is object."),
+    source: string2().min(1).optional().describe("Registered external file resolver for single-tenant string-id file inputs, for example gpfs; valid only with type file."),
+    mimeType: string2().min(1).optional().describe("MIME hint such as application/pdf for a sourced file; mutually exclusive with extension."),
+    extension: string2().min(1).optional().describe("Extension hint such as pdf for a sourced file; mutually exclusive with mimeType.")
   }).superRefine((def, ctx) => {
     if (def.properties && def.type !== "object") {
       ctx.addIssue({
@@ -54115,20 +54116,20 @@ var init_workflow = __esm(() => {
     }
   });
   ManualTriggerMethodSchema = object({
-    type: literal("manual"),
-    enabled: boolean2().optional(),
-    inputSchema: JsonSchemaSchema.optional()
+    type: literal("manual").describe("Dashboard/manual run trigger."),
+    enabled: boolean2().optional().describe("Set false to disable dashboard runs; manual triggering is enabled by default."),
+    inputSchema: JsonSchemaSchema.optional().describe("Optional JSON Schema for trigger input.")
   });
   ApiTriggerMethodSchema = object({
-    type: literal("api"),
-    inputSchema: JsonSchemaSchema.optional()
+    type: literal("api").describe("Public API run trigger."),
+    inputSchema: JsonSchemaSchema.optional().describe("Optional JSON Schema for API input.")
   });
   EmailTriggerMethodSchema = object({
-    type: literal("email"),
+    type: literal("email").describe("Inbound email trigger."),
     whitelist: object({
-      domains: array(string2()).optional(),
-      emails: array(string2()).optional()
-    }).optional()
+      domains: array(string2()).optional().describe("Allowed sender domains."),
+      emails: array(string2()).optional().describe("Allowed exact sender email addresses.")
+    }).optional().describe("Optional sender allowlist by exact email address or domain.")
   });
   TriggerMethodSchema = discriminatedUnion("type", [
     ManualTriggerMethodSchema,
@@ -54137,23 +54138,23 @@ var init_workflow = __esm(() => {
   ]);
   TriggerMethodsSchema = array(TriggerMethodSchema).default([{ type: "manual" }]);
   WorkflowSettingsSchema = object({
-    timeout: number2().positive().optional(),
-    retry: WorkflowRetryPolicySchema.optional(),
+    timeout: number2().positive().optional().describe("Default step timeout in milliseconds."),
+    retry: WorkflowRetryPolicySchema.optional().describe("Default durable retry policy for steps."),
     retries: number2().int().min(0).optional(),
     retryDelay: number2().positive().optional()
   }).strict();
   WorkflowDefinitionSchema = object({
     name: WorkflowNameSchema,
-    kind: _enum(["workflow"]).default("workflow").optional(),
-    version: string2().default("1.0.0"),
-    description: string2().optional(),
-    enabled: boolean2().default(true),
-    triggerMethods: array(TriggerMethodSchema).default([{ type: "manual" }]),
-    inputs: array(WorkflowInputDefSchema).optional(),
-    steps: array(StepSchema),
-    output: union([record(string2(), string2()), string2()]).optional(),
-    settings: WorkflowSettingsSchema.optional(),
-    defaultModel: string2().optional()
+    kind: _enum(["workflow"]).default("workflow").optional().describe("Deprecated compatibility discriminator; omit for new workflows."),
+    version: string2().default("1.0.0").describe("Author-provided semantic version label stored with the definition."),
+    description: string2().optional().describe("Human-readable purpose of the workflow."),
+    enabled: boolean2().default(true).describe("Whether the workflow may be run."),
+    triggerMethods: array(TriggerMethodSchema).default([{ type: "manual" }]).describe("Ways this workflow can be invoked: manual, api, or email."),
+    inputs: array(WorkflowInputDefSchema).optional().describe("Top-level inputs available under `input` in template expressions."),
+    steps: array(StepSchema).describe("Ordered workflow steps; names must be unique."),
+    output: union([record(string2(), string2()), string2()]).optional().describe("Final output as named field-to-template mappings or one passthrough template expression."),
+    settings: WorkflowSettingsSchema.optional().describe("Workflow-wide timeout and retry defaults."),
+    defaultModel: string2().optional().describe("Default configured LLM provider id used by AI steps when the step does not select one.")
   });
   StoredWorkflowDefinitionSchema = object({
     id: string2(),
@@ -54251,6 +54252,23 @@ var init_file_source = __esm(() => {
 });
 
 // ../types/src/eval/compare-output.ts
+function tokenizeEvalPath(path) {
+  if (!path || path === "$")
+    return [];
+  return path.match(/[^.[\]]+|\[\]|\[\d+\]/g) ?? [];
+}
+function evalPathTokenMatches(pattern, candidate) {
+  return pattern === candidate || pattern === "[]" && /^\[\d+\]$/.test(candidate);
+}
+function evalPathIsDescendant(descendant, ancestor) {
+  if (descendant === ancestor)
+    return false;
+  if (ancestor === "$" || ancestor === "")
+    return descendant !== "$" && descendant !== "";
+  const ancestorTokens = tokenizeEvalPath(ancestor);
+  const descendantTokens = tokenizeEvalPath(descendant);
+  return descendantTokens.length > ancestorTokens.length && ancestorTokens.every((token, index) => evalPathTokenMatches(token, descendantTokens[index] ?? ""));
+}
 var MAX_UNORDERED_ARRAY_ITEMS = 1000, MAX_UNORDERED_PAIR_COMPARISONS = 1e6, MAX_UNORDERED_COMPARISON_OPERATIONS = 2000000;
 var init_compare_output = () => {};
 
@@ -54259,13 +54277,13 @@ var DATASET_NAME_PATTERN, DatasetNameSchema, DatasetMetaSchema, DatasetImportMod
 var init_dataset_archive = __esm(() => {
   init_zod();
   DATASET_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]*$/;
-  DatasetNameSchema = string2().min(1).max(128).regex(DATASET_NAME_PATTERN, "name must be lowercase kebab/snake-case");
+  DatasetNameSchema = string2().min(1).max(128).regex(DATASET_NAME_PATTERN, "name must be lowercase kebab/snake-case").describe("Example folder name: 1-128 lowercase letters, digits, hyphens, or underscores; must start with a letter or digit.");
   DatasetMetaSchema = object({
-    rowOrder: number2().int().min(0).optional(),
-    annotation: string2().max(2000).optional(),
-    overrides: record(string2(), unknown()).optional()
+    rowOrder: number2().int().min(0).optional().describe("Non-negative display order hint for this example."),
+    annotation: string2().max(2000).optional().describe("Free-form example note, limited to 2000 characters."),
+    overrides: record(string2(), unknown()).optional().describe('Per-step output overrides as `{ "steps": { "<stepName>": <outputObject> } }`; overridden steps are skipped or partially merged during evaluation.')
   });
-  DatasetImportModeSchema = _enum(["append", "replace"]);
+  DatasetImportModeSchema = _enum(["append", "replace"]).describe("append keeps existing examples; replace removes them before import.");
   DatasetImportRequestSchema = object({
     mode: DatasetImportModeSchema
   });
@@ -54292,7 +54310,8 @@ var init_dataset_archive = __esm(() => {
     label: string2().nullable(),
     weight: number2(),
     createdAt: string2().datetime({ offset: true }),
-    error: string2().nullable()
+    error: string2().nullable(),
+    details: unknown().nullable().optional().describe("Evaluator-specific structured details. Exact-diff includes mismatches with path, expected, and actual values.")
   });
   EvalResultsExportJsonSchema = object({
     workflowId: string2().min(1),
@@ -54308,7 +54327,7 @@ var init_evaluator_config = __esm(() => {
   init_ai_client();
   init_typed_script();
   init_compare_output();
-  EvaluatorTypeSchema = _enum(["exact-diff", "llm-judge", "custom-script"]);
+  EvaluatorTypeSchema = _enum(["exact-diff", "llm-judge", "custom-script"]).describe("Evaluator implementation selected by each evaluators.yaml entry.");
   ScoreInUnitInterval = number2().min(0, { message: "score must be >= 0" }).max(1, { message: "score must be <= 1" });
   LEGACY_EXACT_DIFF_COMPARISON_KEYS = [
     "paths",
@@ -54337,12 +54356,24 @@ var init_evaluator_config = __esm(() => {
     }
   });
   ExactDiffPathRuleSchema = object({
+    ignore: literal(true).optional().describe("Exclude this path and every descendant from comparison. Cannot be combined with other settings on the same rule."),
     order: _enum(["ordered", "unordered"]).optional().describe(`Array matching mode at this path. Independent of \`items\`. Set on the array path (\`lineItems\`), not the item path (\`lineItems[]\`). \`unordered\` matches distinct items in any order. Arrays stay ordered when omitted. Unordered matching is limited to ${MAX_UNORDERED_ARRAY_ITEMS} items, ${MAX_UNORDERED_PAIR_COMPARISONS} candidate pairs, and ${MAX_UNORDERED_COMPARISON_OPERATIONS} recursive operations per comparison.`),
     items: ExactDiffArrayItemsSchema.optional().describe("How expected and actual array items relate. Set on the array path (`lineItems`), not the item path (`lineItems[]`). Independent of `order`. Ordered arrays use positional prefix matching: `at-least` (default) requires expected to match actual from index 0 and allows trailing actual extras; `at-most` requires actual to match expected from index 0 and allows trailing expected extras; `exactly` is equal-cardinality positional comparison. Unordered arrays match distinct items in any order: `at-least` requires every expected item and allows extra actual items (including extras with missing or duplicate identities); `at-most` requires every actual item and allows missing expected items (every actual item being checked needs a valid unique identity); `exactly` is a bijection (both sides need valid unique identities)."),
     matchBy: ExactDiffMatchBySchema.optional().describe("Identity fields for unordered arrays of objects. Requires `order: unordered` on the same rule. Set on the array path (`lineItems`), not the item path (`lineItems[]`). A relative path (`sku`) or unique paths (`[country, sku]`) inside each item. Pairs expected and actual objects by exact identity, then diffs the paired objects with inherited nested rules. Identity type and value must both match: numeric `10` differs from string `'10'`; no coercion or numeric tolerance. Omitted = structural matching. Applies only at the array path where it is set and is not inherited by descendants. Nested object fields are allowed; array indexes, commas, and wildcards are not. Empty or comma-only values are rejected; composite paths must be unique."),
     allowExtraFields: boolean2().optional().describe("When false, extra actual keys at this object fail the diff. When omitted, extra keys are allowed. Applies only to objects."),
     numericTolerance: number2().min(0).optional().describe("Maximum absolute difference for numeric leaves at or under this path. Omitted = inherit, then historical relative epsilon. Explicit `0` is exact.")
   }).strict().superRefine((rule, ctx) => {
+    if (rule.ignore === true) {
+      const otherFields = Object.keys(rule).filter((field) => field !== "ignore");
+      if (otherFields.length > 0) {
+        ctx.addIssue({
+          code: ZodIssueCode.custom,
+          path: ["ignore"],
+          message: "`ignore: true` cannot be combined with other settings on the same rule"
+        });
+      }
+      return;
+    }
     if (rule.matchBy === undefined)
       return;
     if (rule.order !== "unordered") {
@@ -54354,7 +54385,7 @@ var init_evaluator_config = __esm(() => {
     }
   });
   ExactDiffConfigSchema = object({
-    rules: record(string2(), ExactDiffPathRuleSchema).optional().describe("Per-path comparison rules. Keys select compared paths (`$` = full output). More-specific keys inherit then override parent rules. `{}` selects a path using inherited platform defaults. Do not mix with legacy `paths`, `unorderedPaths`, `numericTolerance`, or `allowExtraFields`."),
+    rules: record(string2(), ExactDiffPathRuleSchema).optional().describe("Per-path comparison rules. Non-ignored keys select compared paths (`$` = full output); an ignore-only map means full output minus those paths. More-specific keys inherit then override parent rules. `{}` selects a path using inherited platform defaults; `{ ignore: true }` excludes it. Do not mix with legacy `paths`, `unorderedPaths`, `numericTolerance`, or `allowExtraFields`."),
     numericTolerance: number2().min(0).optional().describe("Legacy global numeric tolerance (absolute). When omitted, comparison uses historical relative epsilon. Prefer `rules.<path>.numericTolerance`. Accepted only when `rules` is omitted."),
     allowExtraFields: boolean2().optional().describe("Legacy global extra-field/extra-item flag. Prefer `rules.<path>.allowExtraFields` and `rules.<path>.items`. `true` normalizes to object extras allowed and array `items: at-least`; `false` normalizes to object extras rejected and array `items: exactly`. Accepted only when `rules` is omitted."),
     passThreshold: ScoreInUnitInterval.optional().describe(LEGACY_EVALUATOR_THRESHOLD_DESCRIPTION),
@@ -54406,6 +54437,19 @@ var init_evaluator_config = __esm(() => {
         });
       }
     }
+    const ignoredPaths = Object.entries(config.rules ?? {}).filter(([, rule]) => rule.ignore === true).map(([path]) => path);
+    for (const [path, rule] of Object.entries(config.rules ?? {})) {
+      if (rule.ignore === true)
+        continue;
+      const ignoredAncestor = ignoredPaths.find((ignoredPath) => ignoredPath !== path && evalPathIsDescendant(path, ignoredPath));
+      if (ignoredAncestor) {
+        ctx.addIssue({
+          code: ZodIssueCode.custom,
+          path: ["rules", path],
+          message: `cannot select \`${path}\` because ignored ancestor \`${ignoredAncestor}\` removes it before comparison`
+        });
+      }
+    }
   }).default({});
   JudgeModeSchema = _enum(["continuous", "discrete"]);
   LabelsRecord = record(string2().min(1), ScoreInUnitInterval);
@@ -54460,16 +54504,22 @@ var init_evaluator_config = __esm(() => {
     weight: number2().min(0).default(1).describe("Relative importance in the weighted mean. The overall score is Σ(weightᵢ × scoreᵢ) / Σweight. Set to 0 to score-only without affecting overall.")
   });
   EvaluatorConfigSchema = discriminatedUnion("type", [
-    EvaluatorBaseEntrySchema.extend({ type: literal("exact-diff"), config: ExactDiffConfigSchema }),
-    EvaluatorBaseEntrySchema.extend({ type: literal("llm-judge"), config: LlmJudgeConfigSchema }),
     EvaluatorBaseEntrySchema.extend({
-      type: literal("custom-script"),
-      config: CustomScriptConfigSchema
+      type: literal("exact-diff").describe("Deterministic structured-output comparison."),
+      config: ExactDiffConfigSchema.describe("Configuration for exact-diff.")
+    }),
+    EvaluatorBaseEntrySchema.extend({
+      type: literal("llm-judge").describe("Model-graded semantic comparison."),
+      config: LlmJudgeConfigSchema.describe("Configuration for llm-judge.")
+    }),
+    EvaluatorBaseEntrySchema.extend({
+      type: literal("custom-script").describe("Typed deterministic scoring script."),
+      config: CustomScriptConfigSchema.describe("Configuration for custom-script.")
     })
   ]);
   EvalConfigYamlSchema = object({
-    evaluators: array(EvaluatorConfigSchema).default([]),
-    passThreshold: ScoreInUnitInterval.optional()
+    evaluators: array(EvaluatorConfigSchema).default([]).describe("Evaluator entries run after each experiment execution."),
+    passThreshold: ScoreInUnitInterval.optional().describe("Workflow-level pass threshold for the weighted mean score. When omitted, legacy evaluator thresholds are combined for compatibility, otherwise the platform default is 0.7.")
   });
   EvaluatorResultSchema = object({
     score: ScoreInUnitInterval.nullable(),
@@ -184044,7 +184094,7 @@ function getAlignmentSize(text, tabWidth, startIndex = 0) {
   }
   return size;
 }
-function isObject2(object) {
+function isObject3(object) {
   return object !== null && typeof object === "object";
 }
 function skip(characters) {
@@ -196834,7 +196884,7 @@ ${codeblock}`, options8);
   get_string_width_default2 = getStringWidth2;
   get_alignment_size_default = getAlignmentSize;
   ast_path_default = AstPath;
-  is_object_default = isObject2;
+  is_object_default = isObject3;
   skipWhitespace = skip(/\s/u);
   skipSpaces = skip(" \t");
   skipToLineEnd = skip(",; \t");
@@ -205318,7 +205368,7 @@ import { fileURLToPath as fileURLToPath8 } from "url";
 // package.json
 var package_default = {
   name: "@eigenpal/cli",
-  version: "0.14.3",
+  version: "0.15.1",
   description: "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   keywords: [
     "eigenpal",
@@ -205357,15 +205407,18 @@ var package_default = {
   },
   scripts: {
     dev: "bun src/cli.ts",
-    build: "bun run generate:skill && bun build src/cli.ts --outdir dist --target node --format esm && rm -rf dist/templates dist/skill && cp -R src/templates dist/templates && cp -R src/skill dist/skill",
-    generate: "bun run generate:cli-docs && bun run generate:skill",
-    "generate:check": "bun run generate:cli-docs:check && bun run generate:skill:check",
+    build: "bun run generate:skill && bun build src/cli.ts --outdir dist --target node --format esm && rm -rf dist/templates dist/skill && cp -R src/templates dist/templates && cp -R src/skill dist/skill && cp src/docs-bundle.json dist/docs-bundle.json",
+    generate: "bun run generate:cli-docs && bun run generate:skill && bun run generate:docs",
+    "generate:check": "bun run generate:cli-docs:check && bun run generate:skill:check && bun run generate:docs:check && bun test scripts/docs-bundle-completeness.test.ts",
+    "generate:docs": "bun scripts/generate-docs-bundle.ts",
+    "generate:docs:check": "bun scripts/generate-docs-bundle.ts --check",
     "generate:skill": "bun scripts/generate-skill-reference.ts",
     "generate:skill:check": "bun scripts/generate-skill-reference.ts --check",
     "generate:cli-docs": "bun scripts/generate-cli-docs.ts",
     "generate:cli-docs:check": "bun scripts/generate-cli-docs.ts --check",
     "generate:logo": "bun scripts/render-logo-ascii.ts --cells 20",
     lint: "eslint src/",
+    test: "bun test src/ scripts/",
     typecheck: "tsc --noEmit"
   },
   dependencies: {
@@ -205873,13 +205926,20 @@ function table(rows, columns) {
 `);
 }
 function addJsonFlag(cmd) {
-  return cmd.option("--json", "Output the raw server response as JSON");
+  return cmd.option("--json", "Emit machine-readable JSON on stdout");
 }
 function withBaseUrl(cmd) {
   return cmd.option("--base-url <url>", "Server base URL");
 }
 function intArg(value) {
-  return Number.parseInt(value, 10);
+  if (!/^-?\d+$/.test(value)) {
+    throw new InvalidArgumentError2("Expected a whole number");
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) {
+    throw new InvalidArgumentError2("Expected a safe whole number");
+  }
+  return parsed;
 }
 function withPagination(cmd, defaultLimit = 50) {
   return cmd.option("--limit <n>", "Page size", intArg, defaultLimit).option("--offset <n>", "Page offset", intArg, 0);
@@ -205911,15 +205971,15 @@ function renderListResult(raw, columns, opts = {}) {
   if (opts.json) {
     console.log(JSON.stringify(raw, null, 2));
     if (rows.length > 0)
-      writeRecordCountHint(rows.length, total, label);
+      writeRecordCountHint(rows.length, total, label, false);
     return;
   }
   console.log(table(rows, columns));
   if (rows.length > 0)
     writeRecordCountHint(rows.length, total, label);
 }
-function writeRecordCountHint(shown, total, label) {
-  process.stderr.write(`${import_picocolors.default.dim(`${shown}${total > shown ? ` of ${total}` : ""} ${label}${total === 1 ? "" : "s"} · use --json for the raw payload`)}
+function writeRecordCountHint(shown, total, label, suggestJson = true) {
+  process.stderr.write(`${import_picocolors.default.dim(`${shown}${total > shown ? ` of ${total}` : ""} ${label}${total === 1 ? "" : "s"}${suggestJson ? " · use --json for machine-readable output" : ""}`)}
 `);
 }
 
@@ -208792,16 +208852,18 @@ async function writeBase64File(file, contentBase64) {
   await fs.mkdir(path6.dirname(file), { recursive: true });
   await fs.writeFile(file, Buffer.from(contentBase64, "base64"));
 }
-async function pollRun(client, executionId, interval, maxWait) {
+async function pollRun(client, executionId, interval, maxWait, json = false) {
   const started = Date.now();
   const base = `/v1/runs/${encodeURIComponent(executionId)}`;
   for (;; ) {
-    const payload = await client.get(base);
+    const payload = await client.get(`${base}?expand=execution`);
     const status = payload.execution?.status;
     if (payload.finished || isTerminalExecutionStatus(status)) {
       return await client.get(`${base}?expand=usage,execution`);
     }
     if (Date.now() - started > maxWait * 1000) {
+      if (json)
+        printJson(payload);
       process.stderr.write(`Timed out waiting for run ${executionId}
 `);
       process.exit(2);
@@ -208809,13 +208871,27 @@ async function pollRun(client, executionId, interval, maxWait) {
     await new Promise((resolve) => setTimeout(resolve, interval * 1000));
   }
 }
-async function pollExperiment(client, automationId, batchId, interval, maxWait) {
+async function pollExperiment(client, automationId, batchId, interval, maxWait, json = false) {
   const started = Date.now();
+  let notFoundRetries = 0;
+  let lastPayload;
   for (;; ) {
-    const payload = await client.get(`/v1/automations/${encodeURIComponent(automationId)}/experiments/${encodeURIComponent(batchId)}`);
+    let payload;
+    try {
+      payload = await client.get(`/v1/automations/${encodeURIComponent(automationId)}/experiments/${encodeURIComponent(batchId)}`);
+      lastPayload = payload;
+    } catch (error) {
+      if (!(error instanceof ApiError) || error.status !== 404 || notFoundRetries >= 2)
+        throw error;
+      notFoundRetries++;
+      await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+      continue;
+    }
     if (payload.status === "completed")
       return payload;
     if (Date.now() - started > maxWait * 1000) {
+      if (json)
+        printJson(lastPayload ?? { batchId, status: "pending" });
       process.stderr.write(`Timed out waiting for experiment ${batchId}
 `);
       process.exit(2);
@@ -208835,7 +208911,7 @@ function renderRunPayload(payload, opts) {
 function setExitCodeForFailedTerminalRun(payload) {
   const run = payload;
   const status = run?.execution?.status;
-  if (status === "failed" || status === "cancelled" || run?.finished === true && run?.error) {
+  if (status === "failed" || status === "cancelled" || status === "rejected" || run?.finished === true && run?.error) {
     process.exitCode = 1;
   }
 }
@@ -209489,6 +209565,89 @@ function dotenvQuote(value) {
 // src/commands/agents/experiments.ts
 import { promises as fs5 } from "node:fs";
 
+// src/lib/json-select.ts
+function selectJsonValue(value, path) {
+  const tokens = parseJsonSelectPath(path);
+  let values = [value];
+  let usedWildcard = false;
+  for (const token of tokens) {
+    const next = [];
+    for (const current of values) {
+      if (token === "*") {
+        usedWildcard = true;
+        if (Array.isArray(current))
+          next.push(...current);
+        continue;
+      }
+      if (typeof token === "number") {
+        if (Array.isArray(current) && token < current.length)
+          next.push(current[token]);
+        continue;
+      }
+      if (current && typeof current === "object" && !Array.isArray(current)) {
+        const object = current;
+        if (Object.hasOwn(object, token))
+          next.push(object[token]);
+      }
+    }
+    values = next;
+  }
+  if (values.length === 0) {
+    throw new Error(`--select path "${path}" did not match the JSON payload`);
+  }
+  return usedWildcard ? values : values[0];
+}
+function parseJsonSelectPath(path) {
+  const trimmed = path.trim();
+  if (trimmed.startsWith("$") && trimmed !== "$" && !trimmed.startsWith("$.") && !trimmed.startsWith("$[")) {
+    throw invalidPath(path);
+  }
+  const source = trimmed.replace(/^\$(?:\.)?/, "");
+  if (!source)
+    return [];
+  const tokens = [];
+  let cursor = 0;
+  while (cursor < source.length) {
+    if (source[cursor] === ".") {
+      if (cursor === 0 || cursor === source.length - 1 || source[cursor - 1] === "." || source[cursor + 1] === "." || source[cursor + 1] === "[") {
+        throw invalidPath(path);
+      }
+      cursor++;
+      continue;
+    }
+    if (source[cursor] === "[") {
+      if (cursor > 0 && source[cursor - 1] === ".")
+        throw invalidPath(path);
+      const close = source.indexOf("]", cursor + 1);
+      if (close === -1)
+        throw invalidPath(path);
+      const inner = source.slice(cursor + 1, close);
+      if (inner === "" || inner === "*")
+        tokens.push("*");
+      else if (/^(0|[1-9]\d*)$/.test(inner))
+        tokens.push(Number(inner));
+      else
+        throw invalidPath(path);
+      cursor = close + 1;
+      if (cursor < source.length && source[cursor] !== "." && source[cursor] !== "[") {
+        throw invalidPath(path);
+      }
+      continue;
+    }
+    if (cursor > 0 && source[cursor - 1] !== ".")
+      throw invalidPath(path);
+    const match = /^[A-Za-z_$][A-Za-z0-9_$-]*/.exec(source.slice(cursor));
+    if (!match)
+      throw invalidPath(path);
+    tokens.push(match[0]);
+    cursor += match[0].length;
+  }
+  return tokens;
+}
+function invalidPath(path) {
+  return new Error(`Invalid --select path "${path}". Use dot keys, numeric indexes, or [] wildcards (for example output.subjects[].name).`);
+}
+
 // src/commands/workflow/experiment-compare.ts
 function normalizeCompareSort(value) {
   switch (value) {
@@ -209571,6 +209730,90 @@ function buildBatchDiff(args) {
     }
   };
 }
+function buildExperimentOutputDiff(args) {
+  const a = new Map(args.rowsA.map((row) => [exampleLabelOf(row), row]));
+  const b = new Map(args.rowsB.map((row) => [exampleLabelOf(row), row]));
+  const shared = [...a.keys()].filter((example) => b.has(example)).sort();
+  const rows = shared.map((example) => {
+    const rowA = a.get(example);
+    const rowB = b.get(example);
+    const comparable = rowA.status === "completed" && rowB.status === "completed" && rowA.output !== undefined && rowB.output !== undefined;
+    if (!comparable) {
+      return {
+        example,
+        executionA: rowA.executionId,
+        executionB: rowB.executionId,
+        status: "incomparable",
+        differences: [
+          {
+            path: "$",
+            type: "incomparable",
+            expected: { status: rowA.status, error: rowA.error },
+            actual: { status: rowB.status, error: rowB.error }
+          }
+        ]
+      };
+    }
+    const differences = diffOutputJson(rowA.output, rowB.output);
+    return {
+      example,
+      executionA: rowA.executionId,
+      executionB: rowB.executionId,
+      status: differences.length === 0 ? "identical" : "changed",
+      differences
+    };
+  });
+  return {
+    batchA: args.batchIdA,
+    batchB: args.batchIdB,
+    rows,
+    summary: {
+      sharedExamples: shared.length,
+      identical: rows.filter((row) => row.status === "identical").length,
+      changed: rows.filter((row) => row.status === "changed").length,
+      incomparable: rows.filter((row) => row.status === "incomparable").length,
+      onlyInA: [...a.keys()].filter((example) => !b.has(example)).sort(),
+      onlyInB: [...b.keys()].filter((example) => !a.has(example)).sort()
+    }
+  };
+}
+function diffOutputJson(expected, actual, path = "$", limit = 200) {
+  if (Object.is(expected, actual))
+    return [];
+  if (Array.isArray(expected) && Array.isArray(actual)) {
+    const differences = [];
+    for (let index = 0;index < Math.max(expected.length, actual.length); index++) {
+      if (differences.length >= limit)
+        break;
+      const child = `${path}[${index}]`;
+      if (index >= expected.length) {
+        differences.push({ path: child, type: "extra", actual: actual[index] });
+      } else if (index >= actual.length) {
+        differences.push({ path: child, type: "missing", expected: expected[index] });
+      } else {
+        differences.push(...diffOutputJson(expected[index], actual[index], child, limit - differences.length));
+      }
+    }
+    return differences;
+  }
+  if (isObject2(expected) && isObject2(actual)) {
+    const differences = [];
+    for (const key of new Set([...Object.keys(expected), ...Object.keys(actual)])) {
+      if (differences.length >= limit)
+        break;
+      const child = path === "$" ? `$.${key}` : `${path}.${key}`;
+      if (!Object.hasOwn(expected, key)) {
+        differences.push({ path: child, type: "extra", actual: actual[key] });
+      } else if (!Object.hasOwn(actual, key)) {
+        differences.push({ path: child, type: "missing", expected: expected[key] });
+      } else {
+        differences.push(...diffOutputJson(expected[key], actual[key], child, limit - differences.length));
+      }
+    }
+    return differences;
+  }
+  return [{ path, type: "changed", expected, actual }];
+}
 function aggregateByEvaluator(rows) {
   const buckets = new Map;
   for (const r of rows) {
@@ -209755,6 +209998,33 @@ function renderBatchDiffHuman(diff) {
   process.stderr.write(`${ui.dim("mean Δ:")} ${meanDeltaText}   ` + `${ui.dim("examples shared:")} ${diff.summary.sharedExamples}   ` + `${ui.dim("only in A:")} ${diff.summary.onlyInA.length}   ` + `${ui.dim("only in B:")} ${diff.summary.onlyInB.length}
 `);
 }
+function renderExperimentOutputDiffHuman(diff) {
+  process.stderr.write(`${ui.dim("A =")} ${ui.bold(diff.batchA)}   ${ui.dim("B =")} ${ui.bold(diff.batchB)}
+
+`);
+  const visible = diff.rows.flatMap((row) => row.differences.map((difference) => ({
+    example: row.example,
+    path: difference.path,
+    type: difference.type,
+    expected: compactValue(difference.expected),
+    actual: compactValue(difference.actual)
+  })));
+  if (visible.length > 0) {
+    console.log(table(visible, [
+      { key: "example", header: "example" },
+      { key: "path", header: "path" },
+      { key: "type", header: "change" },
+      { key: "expected", header: "A" },
+      { key: "actual", header: "B" }
+    ]));
+  } else {
+    process.stderr.write(`${ui.dim("No actual-output differences in shared examples.")}
+`);
+  }
+  process.stderr.write(`
+${ui.dim("shared:")} ${diff.summary.sharedExamples}  ` + `${ui.ok(`identical: ${diff.summary.identical}`)}  ` + `${ui.warn(`changed: ${diff.summary.changed}`)}  ` + `${ui.warn(`incomparable: ${diff.summary.incomparable}`)}  ` + `${ui.dim("only in A:")} ${diff.summary.onlyInA.length}  ` + `${ui.dim("only in B:")} ${diff.summary.onlyInB.length}
+`);
+}
 async function fetchEvalResults(client, experimentId) {
   const ref = await client.get(`/v1/experiments/${encodeURIComponent(experimentId)}`);
   const raw = await client.get(`/v1/automations/${encodeURIComponent(ref.automationId)}/experiments/${encodeURIComponent(experimentId)}/export`, { format: "json" });
@@ -209763,6 +210033,214 @@ async function fetchEvalResults(client, experimentId) {
   }
   return raw;
 }
+async function fetchExperimentOutputs(client, experimentId) {
+  const ref = await client.get(`/v1/experiments/${encodeURIComponent(experimentId)}`);
+  const detail = await client.get(`/v1/automations/${encodeURIComponent(ref.automationId)}/experiments/${encodeURIComponent(experimentId)}`);
+  const runs = detail.runs ?? [];
+  const rows = await mapWithConcurrency(runs, 6, async (run) => {
+    const payload = await client.get(`/v1/runs/${encodeURIComponent(run.id)}`);
+    return {
+      executionId: run.id,
+      exampleId: run.exampleId ?? null,
+      exampleName: run.exampleName ?? null,
+      status: payload.execution?.status ?? payload.status ?? payload.result?.status ?? null,
+      error: payload.error ?? payload.execution?.error ?? payload.result?.error ?? null,
+      output: payload.output !== undefined ? payload.output : payload.result?.output
+    };
+  });
+  return { automationId: ref.automationId, rows };
+}
+function isObject2(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function compactValue(value) {
+  if (value === undefined)
+    return "—";
+  const rendered = JSON.stringify(value);
+  if (rendered === undefined)
+    return String(value);
+  return rendered.length > 80 ? `${rendered.slice(0, 77)}…` : rendered;
+}
+async function mapWithConcurrency(values, concurrency, fn) {
+  const results = new Array(values.length);
+  let cursor = 0;
+  await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+    while (cursor < values.length) {
+      const index = cursor++;
+      results[index] = await fn(values[index]);
+    }
+  }));
+  return results;
+}
+
+// src/commands/workflow/experiment-results.ts
+function experimentRowsFromDetail(detail) {
+  const namesByRun = new Map((detail.runs ?? []).map((run) => [run.id, run.exampleName]));
+  return Object.entries(detail.resultsByRun ?? {}).flatMap(([executionId, rows]) => rows.map((row) => ({
+    ...row,
+    executionId,
+    exampleName: namesByRun.get(executionId) ?? null,
+    score: numberOrNull(row.score),
+    weight: numberOrNull(row.weight) ?? 1
+  })));
+}
+function analyzeExperimentResults(args) {
+  let rows = args.evaluator ? args.rows.filter((row) => row.evaluatorName === args.evaluator) : [...args.rows];
+  if (args.failedOnly) {
+    rows = rows.filter((row) => row.error != null || row.passed === false);
+  }
+  const includedExecutionIds = new Set(rows.map((row) => row.executionId));
+  const runs = args.evaluator || args.failedOnly ? args.runs.filter((run) => includedExecutionIds.has(run.id)) : args.runs;
+  const rowsByRun = groupBy(rows, (row) => row.executionId);
+  const counts = { total: runs.length, passed: 0, failed: 0, errors: 0 };
+  const runScores = [];
+  const usePersistedAggregate = !args.evaluator && !args.failedOnly;
+  for (const run of runs) {
+    const runRows = rowsByRun.get(run.id) ?? [];
+    if (usePersistedAggregate && run.evalPassed != null) {
+      if (["failed", "cancelled", "rejected"].includes(run.status) && run.evalPassed !== true) {
+        counts.errors++;
+      } else if (run.evalPassed) {
+        counts.passed++;
+      } else {
+        counts.failed++;
+      }
+      if (typeof run.evalScore === "number")
+        runScores.push(run.evalScore);
+      continue;
+    }
+    if (["failed", "cancelled", "rejected"].includes(run.status) || runRows.length === 0 || runRows.some((row) => row.error != null)) {
+      counts.errors++;
+      continue;
+    }
+    if (runRows.some((row) => row.passed === false))
+      counts.failed++;
+    else
+      counts.passed++;
+    const score = weightedAverage(runRows);
+    if (score != null)
+      runScores.push(score);
+  }
+  const byEvaluator = [...groupBy(rows, (row) => row.evaluatorName)].map(([evaluator, evaluatorRows]) => ({
+    evaluator,
+    total: evaluatorRows.length,
+    passed: evaluatorRows.filter((row) => row.error == null && row.passed === true).length,
+    failed: evaluatorRows.filter((row) => row.error == null && row.passed === false).length,
+    errors: evaluatorRows.filter((row) => row.error != null).length,
+    averageScore: average(evaluatorRows.flatMap((row) => typeof row.score === "number" ? [row.score] : []))
+  }));
+  byEvaluator.sort((a, b) => a.evaluator.localeCompare(b.evaluator));
+  return {
+    summary: {
+      ...counts,
+      averageScore: average(runScores),
+      byEvaluator
+    },
+    discrepancies: flattenDiscrepancies(rows),
+    results: rows
+  };
+}
+function flattenDiscrepancies(rows) {
+  const discrepancies = [];
+  for (const row of rows) {
+    const details = objectOrNull(row.details);
+    const mismatches = Array.isArray(details?.mismatches) ? details.mismatches : [];
+    for (const mismatch of mismatches) {
+      const item = objectOrNull(mismatch);
+      if (!item || typeof item.path !== "string")
+        continue;
+      discrepancies.push({
+        example: row.exampleName || row.executionId,
+        executionId: row.executionId,
+        evaluator: row.evaluatorName,
+        path: item.path,
+        expected: item.expected,
+        actual: item.actual
+      });
+    }
+  }
+  return discrepancies;
+}
+function renderExperimentResultsSummary(analysis) {
+  const summary = analysis.summary;
+  process.stderr.write(`${ui.bold("Experiment results")}  total=${summary.total}  ${ui.ok(`passed=${summary.passed}`)}  ` + `${ui.warn(`failed=${summary.failed}`)}  errors=${summary.errors}  ` + `average=${formatScore2(summary.averageScore)}
+`);
+  if (summary.byEvaluator.length > 0) {
+    console.log(table(summary.byEvaluator, [
+      { key: "evaluator", header: "evaluator" },
+      { key: "total", header: "total", align: "right" },
+      { key: "passed", header: "pass", align: "right" },
+      { key: "failed", header: "fail", align: "right" },
+      { key: "errors", header: "error", align: "right" },
+      {
+        key: "averageScore",
+        header: "average",
+        align: "right",
+        format: (value) => formatScore2(value)
+      }
+    ]));
+  }
+  if (analysis.discrepancies.length > 0) {
+    process.stderr.write(`
+${ui.bold("Discrepancies")}
+`);
+    console.log(table(analysis.discrepancies, [
+      { key: "example", header: "example" },
+      { key: "evaluator", header: "evaluator" },
+      { key: "path", header: "path" },
+      { key: "expected", header: "expected", format: compactJson },
+      { key: "actual", header: "actual", format: compactJson }
+    ]));
+  }
+}
+function weightedAverage(rows) {
+  let total = 0;
+  let weight = 0;
+  for (const row of rows) {
+    if (typeof row.score !== "number")
+      continue;
+    const rowWeight = Number.isFinite(row.weight) ? row.weight : 1;
+    total += row.score * rowWeight;
+    weight += rowWeight;
+  }
+  return weight > 0 ? total / weight : null;
+}
+function average(values) {
+  return values.length > 0 ? values.reduce((sum, value) => sum + value, 0) / values.length : null;
+}
+function numberOrNull(value) {
+  if (typeof value === "number")
+    return Number.isFinite(value) ? value : null;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+function groupBy(values, key) {
+  const groups = new Map;
+  for (const value of values) {
+    const name = key(value);
+    const existing = groups.get(name);
+    if (existing)
+      existing.push(value);
+    else
+      groups.set(name, [value]);
+  }
+  return groups;
+}
+function objectOrNull(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function formatScore2(value) {
+  return value == null ? "—" : value.toFixed(3);
+}
+function compactJson(value) {
+  const rendered = JSON.stringify(value);
+  if (rendered === undefined)
+    return "undefined";
+  return rendered.length > 80 ? `${rendered.slice(0, 77)}…` : rendered;
+}
 
 // src/commands/agents/experiments.ts
 function registerExperimentCommands(agent) {
@@ -209770,11 +210248,11 @@ function registerExperimentCommands(agent) {
     process.stderr.write("`eigenpal agents experiment` requires a subcommand. Run `eigenpal agents experiment --help`.\n");
     process.exit(2);
   });
-  addJsonFlag(withBaseUrl(experiment.command("run <agent-id-or-slug>"))).description("Start an experiment over dataset examples.").option("--example-id <id>", "Run one dataset example").option("--wait", "Poll until the experiment reaches a terminal status").option("--interval <seconds>", "Polling interval in seconds", intArg, 2).action(action(runExperiment));
-  addJsonFlag(withBaseUrl(experiment.command("status <agent-id-or-slug> <batch-id>"))).description("Get experiment status.").option("--watch", "Poll until complete").option("--interval <seconds>", "Polling interval in seconds", intArg, 2).option("--max-wait <seconds>", "Maximum wait before exit code 2", intArg, 1800).option("--include <parts>", "Reserved for future detailed parts").action(action(experimentStatus));
-  withBaseUrl(experiment.command("results <agent-id-or-slug> [batch-id]")).description("Print experiment results as JSON or CSV.").requiredOption("--format <csv|json>", "Output format", parseResultsFormat).option("--out <path>", "Write output to file").action(action(experimentResults));
+  addJsonFlag(withBaseUrl(experiment.command("run <agent-id-or-slug>"))).description("Start an experiment over dataset examples.").option("--example-id <id>", "Run one dataset example").option("--wait", "Poll until the experiment reaches a terminal status").option("--interval <seconds>", "Polling interval in seconds", intArg, 2).option("--max-wait <seconds>", "Maximum wait before exit code 2", intArg, 1800).action(action(runExperiment));
+  addJsonFlag(withBaseUrl(experiment.command("status <agent-id-or-slug> <batch-id>"))).description("Get experiment status.").option("--watch", "Poll until complete").option("--interval <seconds>", "Polling interval in seconds", intArg, 2).option("--max-wait <seconds>", "Maximum wait before exit code 2", intArg, 1800).action(action(experimentStatus));
+  addJsonFlag(withBaseUrl(experiment.command("results <agent-id-or-slug> [batch-id]"))).description("Print experiment results as JSON or CSV.").option("--format <csv|json>", "Output format (default json)", parseResultsFormat, "json").option("--out <path>", "Write output to file").option("--summary", "Show total/pass/fail/error counts, average score, and evaluator rollups").option("--failed-only", "Keep only failed or errored evaluator results").option("--evaluator <name>", "Keep only results from this evaluator").option("--select <path>", "Print only a nested JSON value (for example summary.byEvaluator or discrepancies[].path)").action(action(experimentResults));
   addJsonFlag(withPagination(withBaseUrl(experiment.command("list <agent-id-or-slug>")), 50)).description("List experiments.").option("--batch-id <id>", "Filter to one batch id").action(action(listExperiments));
-  addJsonFlag(withBaseUrl(experiment.command("compare <batch-id-a> <batch-id-b>"))).description("Diff eval scores between two experiment batches.").option("--sort <abs-delta-desc|delta-asc|delta-desc|name>", "Row sort order (default: biggest movers first)", "abs-delta-desc").option("--regression-threshold <n>", "Δ below this is flagged as a regression (default 0.05)", Number.parseFloat, 0.05).action(action(compareExperiments));
+  addJsonFlag(withBaseUrl(experiment.command("compare <batch-id-a> <batch-id-b>"))).description("Compare evaluator scores or actual outputs between two experiment batches.").option("--outputs", "Compare actual run outputs instead of evaluator scores").option("--sort <abs-delta-desc|delta-asc|delta-desc|name>", "Row sort order (default: biggest movers first)", "abs-delta-desc").option("--regression-threshold <n>", "Δ below this is flagged as a regression (default 0.05)", Number.parseFloat, 0.05).action(action(compareExperiments));
   addJsonFlag(withBaseUrl(experiment.command("cancel <agent-id-or-slug> <batch-id>"))).description("Cancel every active execution in an experiment.").option("--yes", "Skip confirmation (required in CI / agent terminals without a TTY)").action(action(cancelExperiment));
 }
 async function runExperiment(agentId, opts) {
@@ -209784,26 +210262,73 @@ async function runExperiment(agentId, opts) {
     ...opts.exampleId ? { examples: [opts.exampleId] } : {}
   });
   const experimentId = payload.id ?? payload.batchId;
+  if (opts.wait && !experimentId) {
+    throw new Error("Experiment start response did not include a batch id; cannot honor --wait");
+  }
   if (opts.wait && experimentId) {
-    payload = await pollExperiment(client, automationId, experimentId, opts.interval, 1800);
+    payload = await pollExperiment(client, automationId, experimentId, opts.interval, opts.maxWait, opts.json);
+  }
+  const stablePayload = {
+    ...payload,
+    batchId: experimentId,
+    total: payload.runCount ?? payload.total
+  };
+  renderGeneric(stablePayload, opts, `${opts.wait ? "Completed" : "Started"} experiment ${experimentId ?? ""}`);
+  const failedCount = payload.failedCount;
+  if (opts.wait && typeof failedCount === "number" && failedCount > 0) {
+    process.exitCode = 1;
   }
-  renderGeneric(payload, opts, `Started experiment ${experimentId ?? ""}`);
 }
 async function experimentStatus(agentId, batchId, opts) {
   const client = buildClient(opts);
   const automationId = agentAutomationId(agentId);
-  const payload = opts.watch ? await pollExperiment(client, automationId, batchId, opts.interval, opts.maxWait) : await client.get(`/v1/automations/${encodeURIComponent(automationId)}/experiments/${encodeURIComponent(batchId)}`);
+  const payload = opts.watch ? await pollExperiment(client, automationId, batchId, opts.interval, opts.maxWait, opts.json) : await client.get(`/v1/automations/${encodeURIComponent(automationId)}/experiments/${encodeURIComponent(batchId)}`);
   renderGeneric(payload, opts, `Experiment ${batchId}`);
+  if (opts.watch) {
+    const counts = payload;
+    if ([counts.failedCount, counts.cancelledCount, counts.rejectedCount].some((count) => typeof count === "number" && count > 0)) {
+      process.exitCode = 1;
+    }
+  }
 }
 async function experimentResults(agentId, batchId, opts) {
   const client = buildClient(opts);
   const automationId = agentAutomationId(agentId);
+  if (opts.json && opts.format !== "json") {
+    throw new Error("--json cannot be combined with --format csv");
+  }
   const selected = batchId ?? String((await client.get(`/v1/automations/${encodeURIComponent(automationId)}/experiments`, {
     limit: "1",
     offset: "0"
   })).data?.[0]?.id ?? "");
   if (!selected)
     throw new Error("No experiment batch found");
+  const analyze = opts.summary || opts.failedOnly || opts.evaluator !== undefined || opts.select !== undefined;
+  if (analyze) {
+    if (opts.format !== "json")
+      throw new Error("Experiment analysis options require --format json");
+    const detail = await client.get(`/v1/automations/${encodeURIComponent(automationId)}/experiments/${encodeURIComponent(selected)}`);
+    const analysis = analyzeExperimentResults({
+      rows: experimentRowsFromDetail(detail),
+      runs: detail.runs ?? [],
+      evaluator: opts.evaluator,
+      failedOnly: opts.failedOnly
+    });
+    const output = opts.select ? selectJsonValue(analysis, opts.select) : analysis;
+    if (opts.summary && !opts.json && !opts.out && !opts.select) {
+      renderExperimentResultsSummary(analysis);
+      return;
+    }
+    const content = `${JSON.stringify(output, null, 2)}
+`;
+    if (opts.out) {
+      await fs5.writeFile(opts.out, content);
+      success(`Wrote ${opts.out}`);
+    } else {
+      process.stdout.write(content);
+    }
+    return;
+  }
   const payload = await client.get(`/v1/automations/${encodeURIComponent(automationId)}/experiments/${encodeURIComponent(selected)}`);
   const content = opts.format === "json" ? JSON.stringify(payload, null, 2) : toCsv(payload.runs, ["id", "status", "exampleId"]);
   if (opts.out) {
@@ -209836,6 +210361,25 @@ async function compareExperiments(batchIdA, batchIdB, opts) {
     throw new Error("--regression-threshold must be a non-negative number");
   }
   const client = buildClient(opts);
+  if (opts.outputs) {
+    const [outputsA, outputsB] = await Promise.all([
+      fetchExperimentOutputs(client, batchIdA),
+      fetchExperimentOutputs(client, batchIdB)
+    ]);
+    if (outputsA.automationId !== outputsB.automationId) {
+      throw new Error("Experiment batches must belong to the same automation");
+    }
+    const diff = buildExperimentOutputDiff({
+      batchIdA,
+      batchIdB,
+      rowsA: outputsA.rows,
+      rowsB: outputsB.rows
+    });
+    if (opts.json)
+      return printJson(diff);
+    renderExperimentOutputDiffHuman(diff);
+    return;
+  }
   const [rowsA, rowsB] = await Promise.all([
     fetchEvalResults(client, batchIdA),
     fetchEvalResults(client, batchIdB)
@@ -209884,6 +210428,9 @@ async function listAgentFiles(agentId, opts) {
   console.log(table((payload.files ?? []).map((name) => ({ name })), [{ key: "name", header: "PATH" }]));
 }
 async function getAgentFile(agentId, remotePath, opts) {
+  if (opts.json && opts.out) {
+    throw new Error("--json and --out are mutually exclusive");
+  }
   const client = buildClient(opts);
   const payload = await readAgentFile(client, agentId, remotePath);
   if (opts.json)
@@ -210003,7 +210550,7 @@ function registerSessionCommands(agent) {
   addJsonFlag(withPagination(withBaseUrl(session.command("list <agent-id-or-slug>")), 50)).description("List builder sessions for an agent.").action(action(listSessions));
   addJsonFlag(withBaseUrl(session.command("get <session-id>"))).description("Get a builder session and messages.").action(action(getSession));
   addJsonFlag(withBaseUrl(session.command("start <agent-id-or-slug>"))).description("Start a builder session.").option("--title <title>", "Session title").action(action(startSession));
-  addJsonFlag(withBaseUrl(session.command("message <session-id>"))).description("Append a message to a builder session.").requiredOption("--text <message>", "Message text").option("--wait", "Reserved; server acknowledges after enqueueing the message").action(action(messageSession));
+  addJsonFlag(withBaseUrl(session.command("message <session-id>"))).description("Append a message to a builder session.").requiredOption("--text <message>", "Message text").action(action(messageSession));
   addJsonFlag(withBaseUrl(session.command("stop <session-id>"))).description("Stop a builder session.").option("--yes", "Skip confirmation (required in CI / agent terminals without a TTY)").action(action(stopSession));
 }
 async function listSessions(agentId, opts) {
@@ -237879,6 +238426,7 @@ var EXT_MIME = {
   ".doc": "application/msword",
   ".xls": "application/vnd.ms-excel",
   ".rtf": "application/rtf",
+  ".msg": "application/vnd.ms-outlook",
   ".json": "application/json",
   ".xml": "application/xml",
   ".html": "text/html"
@@ -237900,7 +238448,6 @@ function resolveEvalBaseDir(dir) {
 
 // src/commands/workflow/eval-example.ts
 var RUN_POLL_INTERVAL_MS = 2000;
-var RUN_MAX_WAIT_MS = 5 * 60 * 1000;
 function resolveEvalGraceMs() {
   const raw = env.EIGENPAL_EVAL_GRACE_MS;
   if (raw !== undefined) {
@@ -237949,7 +238496,7 @@ async function resolveExample(client, workflowId, name) {
     offset += rows.length;
   }
 }
-async function pollRunTerminal(client, runId) {
+async function pollRunTerminal(client, runId, intervalMs, maxWaitMs) {
   const start = Date.now();
   const base = `/v1/runs/${encodeURIComponent(runId)}`;
   for (;; ) {
@@ -237958,10 +238505,10 @@ async function pollRunTerminal(client, runId) {
     if (run.finished || status && TERMINAL.has(status)) {
       return await client.get(`${base}?expand=execution`);
     }
-    if (Date.now() - start > RUN_MAX_WAIT_MS) {
+    if (Date.now() - start > maxWaitMs) {
       return { ...run, status: "timeout", execution: { status: "timeout" } };
     }
-    await new Promise((r) => setTimeout(r, RUN_POLL_INTERVAL_MS));
+    await new Promise((r) => setTimeout(r, intervalMs));
   }
 }
 async function pollEvalRollup(client, runId) {
@@ -237991,15 +238538,18 @@ function toArtifactPayload(run, runId) {
     stepExecutions: []
   };
 }
-async function runWorkflowExamplesWithEval(client, dir, workflowIdOrSlug, workflowId, exampleNames) {
+async function runWorkflowExamplesWithEval(client, dir, workflowIdOrSlug, workflowId, exampleNames, options = {}) {
   const hasEvaluators = await fetchHasEvaluators(client, workflowId);
   const mode = hasEvaluators ? "evaluators" : "diff";
-  info(`Running ${ui.bold(`"${workflowIdOrSlug}"`)} ${ui.dim(`(${workflowId}, ${exampleNames.length} example(s))`)}`);
-  dim(hasEvaluators ? "Server example run; grading with configured evaluators." : "Server example run; no evaluators configured, grading by structural diff vs expected.");
+  if (!options.quiet) {
+    info(`Running ${ui.bold(`"${workflowIdOrSlug}"`)} ${ui.dim(`(${workflowId}, ${exampleNames.length} example(s))`)}`);
+    dim(hasEvaluators ? "Server example run; grading with configured evaluators." : "Server example run; no evaluators configured, grading by structural diff vs expected.");
+  }
   const evalBaseDir = resolveEvalBaseDir(dir);
   const results = [];
   for (const name of exampleNames) {
-    process.stderr.write(`${ui.dim("→")} ${name}
+    if (!options.quiet)
+      process.stderr.write(`${ui.dim("→")} ${name}
 `);
     try {
       const example = await resolveExample(client, workflowId, name);
@@ -238010,9 +238560,10 @@ async function runWorkflowExamplesWithEval(client, dir, workflowIdOrSlug, workfl
       const runId = started.id;
       if (typeof runId !== "string")
         throw new Error("Example run did not return a run id");
-      process.stderr.write(`  ${ui.dim(`run: ${runId}`)}
+      if (!options.quiet)
+        process.stderr.write(`  ${ui.dim(`run: ${runId}`)}
 `);
-      const run = await pollRunTerminal(client, runId);
+      const run = await pollRunTerminal(client, runId, options.intervalMs ?? RUN_POLL_INTERVAL_MS, options.maxWaitMs ?? 5 * 60 * 1000);
       const status = run.execution?.status ?? run.status;
       const runOk = status === "completed";
       const result = {
@@ -238038,14 +238589,17 @@ async function runWorkflowExamplesWithEval(client, dir, workflowIdOrSlug, workfl
             error: r.error ?? null
           }));
         } else {
-          warn(`  ${name}: no evaluator score after ${EVAL_GRACE_MS / 1000}s; grading by diff.`);
+          if (!options.quiet) {
+            warn(`  ${name}: no evaluator score after ${EVAL_GRACE_MS / 1000}s; grading by diff.`);
+          }
           gradeByDiff(result, example.expected, runOutput(run));
         }
       } else if (runOk) {
         gradeByDiff(result, example.expected, runOutput(run));
       }
       results.push(result);
-      reportLine(result);
+      if (!options.quiet)
+        reportLine(result);
       if (evalBaseDir) {
         try {
           await writeExecutionArtifacts(client, `${evalBaseDir}/${name}`, toArtifactPayload(run, runId));
@@ -238059,11 +238613,13 @@ async function runWorkflowExamplesWithEval(client, dir, workflowIdOrSlug, workfl
         mode: "none"
       };
       results.push(result);
-      reportLine(result);
+      if (!options.quiet)
+        reportLine(result);
     }
   }
   const summary = summarize(workflowIdOrSlug, mode, results);
-  process.stderr.write(`
+  if (!options.quiet)
+    process.stderr.write(`
 ${formatEvalSummary(summary)}
 `);
   return summary;
@@ -238157,8 +238713,8 @@ function registerRunsCommands(program) {
   });
   const listRunsCmd = addJsonFlag(withPagination(withBaseUrl(runs.command("list [source]")), 50)).alias("ls").description("List runs across workflows and agents, optionally scoped to one source.").option("--type <type>", "Filter by run type: workflow|agent").option("--status <status>", "Filter by run status").option("--source-ref <ref>", "Filter agent runs by source ref").option("--batch-id <id>", "Filter eval/experiment runs by batch id").option("--example-id <id>", "Filter eval runs by example id").option("--example-id-contains <text>", "Filter eval runs by example id substring").option("--from <date>", "Created at or after this ISO timestamp or relative date").option("--to <date>", "Created before this ISO timestamp or relative date").option("--created-after <date>", "Alias for --from").option("--created-before <date>", "Alias for --to").option("--completed-after <date>", "Completed at or after this ISO timestamp or relative date").option("--completed-before <date>", "Completed before this ISO timestamp or relative date").option("--compact", "Render compact run rows").option("--sort <field>", "Sort field; only createdAt is supported").option("--order <asc|desc>", "Sort order; only desc is supported");
   listRunsCmd.action(action(listRuns));
-  addJsonFlag(withBaseUrl(runs.command("get <run-id>"))).description("Get one run.").option("--step <name>", "For workflow runs, show only this step (or comma-separated list)").option("--expand <sections>", "Comma-separated server expand sections for GET /api/v1/runs/:id: input, usage, execution, debug. Use execution for status/schemaValid; completed runs include top-level output/files/error.").option("--include <parts>", "Comma-separated local workflow step projection fields (error, duration, inputRef, …). Legacy expand names are mapped when possible; use --expand for server sections.", "review").action(action(getRun));
-  addJsonFlag(withBaseUrl(runs.command("compare <reference-run-id> <run-id>"))).description("Compare one run against another run. PDF/DOCX use pdftotext/python3; XLSX compares structured workbook content (not ZIP bytes).").option("--baseline", "Compare actual outputs from both runs instead of expected artifacts").option("--step <name>", "For workflow runs, restrict comparison to one step").option("--out <dir>", "Write comparison artifacts to this directory").option("--normalize-dates", "Normalize YYYYMMDD and YYYY-MM-DD tokens in filenames/text").option("--fail-on-diff", "Exit 1 when comparison status is fail").action(action(compareRun));
+  addJsonFlag(withBaseUrl(runs.command("get <run-id>"))).description("Get one run.").option("--step <name>", "For workflow runs, show only this step (or comma-separated list)").option("--select <path>", "Print only a nested JSON value; implies JSON output (for example output.subjects or output.subjects[].name)").option("--expand <sections>", "Comma-separated server expand sections for GET /api/v1/runs/:id: input, usage, execution, debug. Use execution for status/schemaValid; completed runs include top-level output/files/error.").option("--include <parts>", "Comma-separated local workflow step projection fields (error, duration, inputRef, …). Legacy expand names are mapped when possible; use --expand for server sections.", "review").action(action(getRun));
+  addJsonFlag(withBaseUrl(runs.command("compare <reference-run-id> <run-id>"))).description("Compare one run against another. Repeated workflow steps are matched by stable branch/iteration path.").option("--baseline", "Compare actual outputs from both runs instead of expected artifacts").option("--step <name-or-path>", "For workflow runs, restrict by step name or stable path").option("--out <dir>", "Write comparison artifacts to this directory").option("--normalize-dates", "Normalize YYYYMMDD and YYYY-MM-DD tokens in filenames/text").option("--fail-on-diff", "Exit 1 when comparison status is fail").action(action(compareRun));
   addJsonFlag(withBaseUrl(runs.command("rerun <run-id>"))).description("Create a new run from a previous run's stored input snapshot.").option("--version <version>", "Version/source ref for the new run: latest (default), original, or an explicit ref (same grammar as eigenpal run)").option("--source-ref <ref>", "Alias for --version").option("--wait", "Poll until the rerun reaches a terminal status").option("--interval <seconds>", "Polling interval in seconds", intArg, 2).option("--max-wait <seconds>", "Maximum wait before exit code 2", intArg, 1800).action(action(rerunRun));
   addJsonFlag(withBaseUrl(runs.command("promote <run-id>"))).description("Promote a run into a dataset example on the run's automation.").option("--name <name>", "Name for the created example").addHelpText("after", `
 Examples
@@ -238174,7 +238730,7 @@ Use \`eigenpal runs reviews update\` first when you need to correct output.
   });
   addJsonFlag(withBaseUrl(artifacts.command("list <run-id>"))).description("List available run artifacts without downloading them.").action(action(listRunArtifacts));
   withBaseUrl(artifacts.command("fetch <run-id>")).description("Download run artifacts by canonical artifact path.").option("--out <dir>", "Output directory").option("--include <parts>", "Comma-separated parts: output,input,metadata,issues,trace,lockfile,expected,all", "all").option("--path <path>", "Fetch one exact artifact path from `artifacts list`; repeatable", collectRepeated, []).option("--json", "Output a JSON summary of written artifacts").action(action(fetchRunArtifacts));
-  addJsonFlag(withBaseUrl(artifacts.command("inspect [run-id] [artifact-path]"))).description("Inspect a run XLSX artifact as structured JSON (sheet names, headers, typed rows). Use --file for a local workbook.").option("--file <path>", "Inspect a local .xlsx/.xls file instead of downloading a run artifact").option("--path <path>", "Canonical artifact path from `artifacts list` (alias for positional artifact-path)").option("--sheet <names>", "Comma-separated sheet names or zero-based indices to include").option("--max-sheets <n>", "Maximum sheets to include (default 20)", intArg).option("--max-rows <n>", "Maximum data rows per sheet (default 500)", intArg).option("--max-cols <n>", "Maximum columns per sheet (default 50)", intArg).action(action(inspectRunArtifact));
+  withBaseUrl(artifacts.command("inspect [run-id] [artifact-path]")).description("Inspect a run XLSX artifact as structured JSON (sheet names, headers, typed rows). Use --file for a local workbook.").option("--file <path>", "Inspect a local .xlsx/.xls file instead of downloading a run artifact").option("--path <path>", "Canonical artifact path from `artifacts list` (alias for positional artifact-path)").option("--sheet <names>", "Comma-separated sheet names or zero-based indices to include").option("--max-sheets <n>", "Maximum sheets to include (default 20)", intArg).option("--max-rows <n>", "Maximum data rows per sheet (default 500)", intArg).option("--max-cols <n>", "Maximum columns per sheet (default 50)", intArg).action(action(inspectRunArtifact));
   withBaseUrl(runs.command("trace <run-id>")).description("Print raw trace.jsonl for a run, or write it with --out.").option("--out <file>", "Output file path").action(action(traceRun));
   registerRunReviewCommands(runs);
   registerRunExpectedCommands(runs);
@@ -238183,6 +238739,9 @@ Use \`eigenpal runs reviews update\` first when you need to correct output.
 Examples:
   $ eigenpal runs cancel exec_abc123
   $ eigenpal runs cancel exec_abc123 --yes    # required in scripts and agent terminals
+
+Cancellation is asynchronous. Human output confirms that the request was
+accepted; use \`--json\` to inspect the server response.
 `).action(action(cancelRun));
 }
 function registerRunReviewCommands(runs) {
@@ -238215,17 +238774,20 @@ Examples:
 `).action(action(deleteRunExpected));
 }
 async function runExample(agentId, opts) {
+  if (opts.failOnMismatch && !opts.wait) {
+    throw new Error("--fail-on-mismatch requires --wait because the evaluator verdict is asynchronous");
+  }
   const client = buildClient(opts);
   const started = await client.post(`/v1/automations/${encodeURIComponent(agentAutomationId(agentId))}/experiments`, {
     examples: [opts.example],
     ...opts.sourceRef ? { sourceRef: opts.sourceRef } : {}
   });
   const runId = started.runs?.[0]?.id;
-  if (opts.failOnMismatch && !opts.wait) {
-    warn("--fail-on-mismatch has no effect without --wait; the evaluator verdict is not awaited.");
+  if (opts.wait && !runId) {
+    throw new Error("Example start response did not include a run id; cannot honor --wait");
   }
   if (opts.wait && runId) {
-    let payload = await pollRun(client, runId, opts.interval, opts.maxWait);
+    let payload = await pollRun(client, runId, opts.interval, opts.maxWait, opts.json);
     const status = payload.execution?.status;
     let wait = { kind: "no-evaluators" };
     if (status === "completed") {
@@ -238355,43 +238917,46 @@ async function getRun(executionId, opts) {
   if (isWorkflowRun(run)) {
     const steps = filterWorkflowSteps(run.stepExecutions, opts.step);
     const projectionIncludes = workflowStepProjectionIncludes(projectionIncludeSource(opts));
-    if (opts.step) {
-      return printJson({ ...run, stepExecutions: projectWorkflowSteps(steps, projectionIncludes) });
+    const projectedRun = opts.step ? { ...run, stepExecutions: projectWorkflowSteps(steps, projectionIncludes) } : run;
+    if (opts.select) {
+      return printJson(selectJsonValue(projectedRun, opts.select));
     }
     if (opts.json) {
-      return printJson(run);
+      return printJson(projectedRun);
     }
-    console.log(renderFrame(toExecutionSnapshot(run, executionId)));
+    console.log(renderFrame(toExecutionSnapshot(projectedRun, executionId)));
     process.stderr.write(`${ui.dim(`use --json for the full payload, then pipe to jq for field projection`)}
 `);
     return;
   }
+  if (opts.select)
+    return printJson(selectJsonValue(run, opts.select));
   renderRunPayload(run, opts);
 }
 function isWorkflowRun(run) {
   return run.type === "workflow";
 }
-function objectOrNull(value) {
+function objectOrNull2(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function toLegacyRunView(run) {
-  const timing = objectOrNull(run.timing);
-  const source = objectOrNull(run.source);
-  const sourceGit = objectOrNull(source?.git);
-  const trigger = objectOrNull(run.trigger);
-  const lineage = objectOrNull(run.lineage);
-  const execution = objectOrNull(run.execution);
-  const legacyRetry = objectOrNull(lineage?.retry);
-  const retry = objectOrNull(execution?.retry) ?? legacyRetry;
-  const nextRun = objectOrNull(retry?.nextRun);
-  const evalInfo = objectOrNull(run.eval);
-  const result = objectOrNull(run.result);
-  const input = objectOrNull(run.input);
-  const usage = objectOrNull(run.usage);
-  const tokens = objectOrNull(usage?.tokens);
-  const executionFiles = objectOrNull(execution?.files);
-  const executionExpected = objectOrNull(execution?.expected);
-  const debug = objectOrNull(run.debug);
+  const timing = objectOrNull2(run.timing);
+  const source = objectOrNull2(run.source);
+  const sourceGit = objectOrNull2(source?.git);
+  const trigger = objectOrNull2(run.trigger);
+  const lineage = objectOrNull2(run.lineage);
+  const execution = objectOrNull2(run.execution);
+  const legacyRetry = objectOrNull2(lineage?.retry);
+  const retry = objectOrNull2(execution?.retry) ?? legacyRetry;
+  const nextRun = objectOrNull2(retry?.nextRun);
+  const evalInfo = objectOrNull2(run.eval);
+  const result = objectOrNull2(run.result);
+  const input = objectOrNull2(run.input);
+  const usage = objectOrNull2(run.usage);
+  const tokens = objectOrNull2(usage?.tokens);
+  const executionFiles = objectOrNull2(execution?.files);
+  const executionExpected = objectOrNull2(execution?.expected);
+  const debug = objectOrNull2(run.debug);
   const hasGroupedShape = timing != null || source != null || result != null || run.output !== undefined;
   if (!hasGroupedShape)
     return run;
@@ -238448,8 +239013,8 @@ function toLegacyRunView(run) {
       durationMs: usage.durationMs
     } : undefined,
     stepExecutions: execution?.steps,
-    nextRetryId: nextRun?.id ?? objectOrNull(execution?.nextRetry)?.id,
-    nextRetryStatus: nextRun?.status ?? objectOrNull(execution?.nextRetry)?.status,
+    nextRetryId: nextRun?.id ?? objectOrNull2(execution?.nextRetry)?.id,
+    nextRetryStatus: nextRun?.status ?? objectOrNull2(execution?.nextRetry)?.status,
     review: execution?.review,
     expected: executionExpected?.output,
     expectedFiles: executionExpected?.files,
@@ -238508,7 +239073,7 @@ function projectWorkflowStep(step, includes) {
   return out;
 }
 function toExecutionSnapshot(run, fallbackId) {
-  const execution = objectOrNull(run.execution);
+  const execution = objectOrNull2(run.execution);
   return {
     id: String(run.id ?? run.executionId ?? fallbackId),
     status: String(run.status ?? execution?.status ?? "unknown"),
@@ -238556,8 +239121,11 @@ async function rerunRun(executionId, opts) {
   const path = `/v1/runs/${encodeURIComponent(executionId)}/rerun${query ? `?${query}` : ""}`;
   let payload = await client.post(path);
   const rerunId = String(payload.id ?? "");
+  if (opts.wait && !rerunId) {
+    throw new Error("Rerun response did not include an id; cannot honor --wait");
+  }
   if (opts.wait && rerunId) {
-    payload = await pollRun(client, rerunId, opts.interval, opts.maxWait);
+    payload = await pollRun(client, rerunId, opts.interval, opts.maxWait, opts.json);
     renderRunPayload(payload, opts);
     setExitCodeForFailedTerminalRun(payload);
     return;
@@ -238654,8 +239222,6 @@ async function inspectRunArtifact(runId, artifactPathArg, opts) {
     ...source.kind === "local" ? { file: source.path } : { runId: source.runId, artifactPath: source.artifactPath },
     ...inspect
   };
-  if (opts.json)
-    return printJson(payload);
   printJson(payload);
 }
 async function listRunArtifacts(executionId, opts) {
@@ -238849,21 +239415,21 @@ async function compareRun(referenceId, executionId, opts) {
 function compareWorkflowRuns(referenceId, reference, targetId, target, stepFilter) {
   const referenceSteps = workflowSteps(reference.stepExecutions);
   const targetSteps = workflowSteps(target.stepExecutions);
-  const stepNames = new Set;
-  for (const step of referenceSteps)
-    if (step.stepName)
-      stepNames.add(step.stepName);
-  for (const step of targetSteps)
-    if (step.stepName)
-      stepNames.add(step.stepName);
+  const referenceByPath = new Map(referenceSteps.map((step) => [workflowStepComparisonPath(step), step]));
+  const targetByPath = new Map(targetSteps.map((step) => [workflowStepComparisonPath(step), step]));
+  const stepPaths = new Set([...referenceByPath.keys(), ...targetByPath.keys()]);
   const wanted = stepFilter ? new Set(stepFilter.split(",").map((step) => step.trim()).filter(Boolean)) : null;
-  const steps = [...stepNames].sort().filter((stepName) => !wanted || wanted.has(stepName)).map((stepName) => {
-    const referenceStep = referenceSteps.find((step) => step.stepName === stepName);
-    const targetStep = targetSteps.find((step) => step.stepName === stepName);
+  const steps = [...stepPaths].sort().map((stepPath) => {
+    const referenceStep = referenceByPath.get(stepPath);
+    const targetStep = targetByPath.get(stepPath);
+    const stepName = String(referenceStep?.stepName ?? targetStep?.stepName ?? stepPath);
+    return { stepPath, stepName, referenceStep, targetStep };
+  }).filter(({ stepName, stepPath }) => !wanted || wanted.has(stepName) || wanted.has(stepPath)).map(({ stepPath, stepName, referenceStep, targetStep }) => {
     const referenceDuration = typeof referenceStep?.durationMs === "number" ? referenceStep.durationMs : null;
     const targetDuration = typeof targetStep?.durationMs === "number" ? targetStep.durationMs : null;
     return {
       stepName,
+      stepPath,
       referenceStatus: String(referenceStep?.status ?? "-"),
       targetStatus: String(targetStep?.status ?? "-"),
       durationDeltaMs: referenceDuration != null && targetDuration != null ? targetDuration - referenceDuration : null,
@@ -238880,6 +239446,31 @@ function compareWorkflowRuns(referenceId, reference, targetId, target, stepFilte
     finalOutputState
   };
 }
+function workflowStepComparisonPath(step) {
+  const frames = Array.isArray(step.scopeStack) ? step.scopeStack : [];
+  const parts = [];
+  for (const frame of frames) {
+    const type = String(frame.type ?? "");
+    const stepName = String(frame.stepName ?? "");
+    if (!stepName || type === "root")
+      continue;
+    if (type === "parallel-map-iteration" || type === "foreach-iteration") {
+      const index = typeof frame.iterationIndex === "number" ? frame.iterationIndex : "?";
+      parts.push(`${stepName}[${index}]`);
+    } else if (type === "parallel-branch") {
+      parts.push(`${stepName}.${String(frame.branchName ?? "?")}`);
+    } else if (type === "if-then") {
+      parts.push(`${stepName}.then`);
+    } else if (type === "if-else") {
+      parts.push(`${stepName}.else`);
+    } else {
+      parts.push(stepName);
+    }
+  }
+  if (step.stepName)
+    parts.push(step.stepName);
+  return parts.join(".") || step.stepPath || step.stepName || step.scopeHash || "unknown-step";
+}
 function renderWorkflowComparisonReport(report) {
   console.log(`${ui.dim("A =")} ${ui.bold(report.comparedWithRunId)}   ${ui.dim("B =")} ${ui.bold(report.runId)}`);
   console.log("");
@@ -238887,7 +239478,7 @@ function renderWorkflowComparisonReport(report) {
   console.log(ui.dim(`------------------------     ---------   ---------   ----------   ------`));
   for (const step of report.steps) {
     const delta = step.durationDeltaMs == null ? "-" : `${step.durationDeltaMs >= 0 ? "+" : ""}${step.durationDeltaMs}ms`;
-    console.log(`${step.stepName.padEnd(28)} ${padColored(colorStatus(step.referenceStatus), step.referenceStatus, 11)} ${padColored(colorStatus(step.targetStatus), step.targetStatus, 11)} ${delta.padEnd(12)} ${colorOutputState(step.outputState)}`);
+    console.log(`${step.stepPath.padEnd(28)} ${padColored(colorStatus(step.referenceStatus), step.referenceStatus, 11)} ${padColored(colorStatus(step.targetStatus), step.targetStatus, 11)} ${delta.padEnd(12)} ${colorOutputState(step.outputState)}`);
   }
   console.log("");
   console.log(`${ui.dim("final output:")} ${colorOutputState(report.finalOutputState)}`);
@@ -238940,9 +239531,9 @@ async function listRuns(source, opts) {
   };
   const payload = await client.get("/v1/runs", params);
   const viewRuns = payload.runs.map(toLegacyRunView);
-  const rows = opts.compact ? viewRuns.map(compactRunRow) : viewRuns;
   if (opts.json)
-    return printJson({ ...payload, runs: rows });
+    return printJson({ ...payload, runs: viewRuns });
+  const rows = opts.compact ? viewRuns.map(compactRunRow) : viewRuns;
   if (payload.scanLimited)
     warn("Filtered run list scanned only the first matching window.");
   if (payload.noResolvedAnchor)
@@ -239124,7 +239715,7 @@ async function deleteRunExpected(executionId, name, opts) {
 async function watchRunCommand(executionId, opts) {
   const client = buildClient(opts);
   if (opts.json) {
-    const payload = await pollRun(client, executionId, opts.interval, opts.maxWait);
+    const payload = await pollRun(client, executionId, opts.interval, opts.maxWait, opts.json);
     renderRunPayload(payload, opts);
     setExitCodeForFailedTerminalRun(payload);
     return;
@@ -239146,7 +239737,7 @@ Detached after ${opts.maxWait}s without reaching terminal status. Re-run \`eigen
 `);
     process.exit(2);
   }
-  if (result.final.status === "failed" || result.final.status === "cancelled") {
+  if (result.final.status === "failed" || result.final.status === "cancelled" || result.final.status === "rejected") {
     process.exitCode = 1;
   }
 }
@@ -239154,7 +239745,11 @@ async function cancelRun(executionId, opts) {
   requireYesInNonInteractive(opts.yes, "Cancel run");
   const client = buildClient(opts);
   const payload = await client.post(`/v1/runs/${encodeURIComponent(executionId)}/cancel`, {});
-  renderRunPayload(payload, opts);
+  if (opts.json) {
+    printJson(payload);
+    return;
+  }
+  success(`Cancellation requested for run ${executionId}.`);
 }
 async function downloadTraceText(client, executionId) {
   const payload = await client.get(`/v1/runs/${encodeURIComponent(executionId)}/trace`);
@@ -239915,14 +240510,147 @@ async function completion(shell, program) {
 `);
 }
 
+// src/commands/docs.ts
+import { existsSync as existsSync13, readFileSync as readFileSync13 } from "node:fs";
+var docsCache = null;
+function bundledDocs() {
+  if (docsCache)
+    return docsCache;
+  const candidates = [
+    new URL("./docs-bundle.json", import.meta.url),
+    new URL("../docs-bundle.json", import.meta.url)
+  ];
+  const bundleUrl = candidates.find((candidate) => existsSync13(candidate));
+  if (!bundleUrl) {
+    throw new Error("Bundled documentation asset is missing. Reinstall the Eigenpal CLI.");
+  }
+  const parsed = JSON.parse(readFileSync13(bundleUrl, "utf8"));
+  if (!Array.isArray(parsed.entries)) {
+    throw new Error("Bundled documentation asset is invalid. Reinstall the Eigenpal CLI.");
+  }
+  docsCache = parsed.entries;
+  return docsCache;
+}
+function listDocs(prefix, source) {
+  const docs = bundledDocs();
+  const normalizedPrefix = normalizeTopic(prefix ?? "");
+  return docs.filter((doc) => (!normalizedPrefix || doc.topic.startsWith(normalizedPrefix)) && (!source || doc.source === source));
+}
+function resolveDoc(topic) {
+  const docs = bundledDocs();
+  const normalized = normalizeTopic(topic);
+  const exact = docs.find((doc) => doc.topic === normalized);
+  if (exact)
+    return exact;
+  const suffixMatches = docs.filter((doc) => doc.topic.endsWith(`/${normalized}`) || doc.topic === normalized);
+  if (suffixMatches.length === 1)
+    return suffixMatches[0];
+  if (suffixMatches.length > 1) {
+    throw new Error(`Documentation topic "${topic}" is ambiguous. Use one of: ${suffixMatches.map((doc) => doc.topic).join(", ")}`);
+  }
+  throw new Error(`Unknown documentation topic "${topic}". Run \`eigenpal docs search ${JSON.stringify(topic)}\` or \`eigenpal docs list\`.`);
+}
+function searchDocs(query, limit = 20) {
+  const docs = bundledDocs();
+  const terms = query.toLocaleLowerCase().split(/\s+/).filter(Boolean);
+  if (terms.length === 0)
+    throw new Error("Search query must not be empty.");
+  return docs.map((doc) => {
+    const title = `${doc.topic}
+${doc.title}
+${doc.description}`.toLocaleLowerCase();
+    const content = doc.content.toLocaleLowerCase();
+    if (!terms.every((term) => title.includes(term) || content.includes(term)))
+      return null;
+    const score = terms.reduce((sum, term) => sum + (title.includes(term) ? 10 : 0) + occurrences(content, term), 0);
+    return { ...doc, snippet: matchingSnippet(doc.content, terms), score };
+  }).filter((doc) => doc !== null).sort((a, b) => b.score - a.score || a.topic.localeCompare(b.topic)).slice(0, Math.max(1, limit)).map(({ score: _score, ...doc }) => doc);
+}
+function registerDocsCommands(program) {
+  const command = program.command("docs").description("List, search, and read the complete release-matched Eigenpal documentation offline.").action(() => {
+    process.stderr.write("`eigenpal docs` requires a subcommand: `list`, `search`, or `read`.\nRun `eigenpal docs --help` to see examples.\n");
+    process.exit(2);
+  });
+  addJsonFlag(command.command("list [prefix]")).description("List bundled documentation topics, optionally under a path prefix.").option("--source <source>", "Filter by public, agent-reference, or api").action(action(async (prefix, opts) => {
+    const results = listDocs(prefix, opts.source);
+    if (opts.json) {
+      printJson(results.map(({ content: _content, ...doc }) => doc));
+      return;
+    }
+    console.log(table(results, [
+      { key: "topic", header: "TOPIC" },
+      { key: "source", header: "SOURCE" },
+      { key: "title", header: "TITLE" }
+    ]));
+  }));
+  addJsonFlag(command.command("search <query>")).description("Search every public page and detailed agent reference.").option("--limit <n>", "Maximum matches", intArg, 20).action(action(async (query, opts) => {
+    const results = searchDocs(query, opts.limit);
+    if (opts.json) {
+      printJson(results.map(({ content: _content, ...doc }) => doc));
+      return;
+    }
+    console.log(table(results.map((doc) => ({ ...doc, match: doc.snippet || doc.description })), [
+      { key: "topic", header: "TOPIC" },
+      { key: "source", header: "SOURCE" },
+      { key: "match", header: "MATCH" }
+    ]));
+  }));
+  addJsonFlag(command.command("read <topic>")).description("Print one bundled documentation topic to stdout.").action(action(async (topic, opts) => {
+    const doc = resolveDoc(topic);
+    if (opts.json) {
+      printJson(doc);
+      return;
+    }
+    process.stdout.write(doc.content.endsWith(`
+`) ? doc.content : `${doc.content}
+`);
+  }));
+  command.addHelpText("after", `
+Examples:
+  $ eigenpal docs search "evaluator path syntax"
+  $ eigenpal docs read reference/evaluators
+  $ eigenpal docs read steps/transform/script
+  $ eigenpal docs list api-reference --json
+
+The bundle contains every public docs page, the OpenAPI specification, and the
+detailed agent references generated from Eigenpal's real schemas and CLI help.
+It ships with the CLI, needs no authentication, and matches that CLI release.
+`);
+}
+function normalizeTopic(value) {
+  let topic = value.trim();
+  try {
+    const url = new URL(topic);
+    topic = url.pathname;
+  } catch {}
+  return topic.replace(/^\/+/, "").replace(/^docs\//, "").replace(/\.(md|mdx|json)$/, "").replace(/\/+$/, "");
+}
+function occurrences(content, term) {
+  let count = 0;
+  let index = 0;
+  while ((index = content.indexOf(term, index)) >= 0) {
+    count += 1;
+    index += term.length;
+  }
+  return Math.min(count, 20);
+}
+function matchingSnippet(content, terms) {
+  const lines = content.split(/\r?\n/);
+  const line = lines.find((candidate) => {
+    const lower = candidate.toLocaleLowerCase();
+    return terms.some((term) => lower.includes(term));
+  }) ?? "";
+  return line.replace(/^[#>*\s-]+/, "").replace(/[`[\]{}]/g, "").trim().slice(0, 140);
+}
+
 // src/commands/init/index.ts
 init_dist4();
 import {
   copyFileSync,
-  existsSync as existsSync13,
+  existsSync as existsSync14,
   mkdirSync as mkdirSync5,
   readdirSync as readdirSync4,
-  readFileSync as readFileSync13,
+  readFileSync as readFileSync14,
   statSync as statSync4,
   writeFileSync as writeFileSync7
 } from "node:fs";
@@ -239940,10 +240668,10 @@ function isValidProjectName(name) {
 function resolveTemplatesRoot() {
   const here = dirname4(fileURLToPath6(import.meta.url));
   const srcCandidate = resolve4(here, "..", "..", "templates");
-  if (existsSync13(srcCandidate))
+  if (existsSync14(srcCandidate))
     return srcCandidate;
   const distCandidate = resolve4(here, "templates");
-  if (existsSync13(distCandidate))
+  if (existsSync14(distCandidate))
     return distCandidate;
   throw new Error(`Cannot locate bundled templates. Looked in:
   ${srcCandidate}
@@ -239955,7 +240683,7 @@ async function init(name, opts) {
   }
   const target = resolve4(process.cwd(), opts.dir ?? name);
   assertSafeTargetDir(target, opts.dir);
-  if (existsSync13(target) && readdirSync4(target).length > 0) {
+  if (existsSync14(target) && readdirSync4(target).length > 0) {
     throw new Error(`Target directory ${relative2(process.cwd(), target)} exists and is not empty.`);
   }
   let template;
@@ -239970,7 +240698,7 @@ async function init(name, opts) {
     template = await promptForTemplate();
   }
   const sourceRoot = join7(resolveTemplatesRoot(), template);
-  if (!existsSync13(sourceRoot)) {
+  if (!existsSync14(sourceRoot)) {
     throw new Error(`Template directory missing on disk: ${sourceRoot}`);
   }
   const written = copyTemplate(sourceRoot, target, name);
@@ -240023,7 +240751,7 @@ function copyTemplate(src, dst, projectName) {
       }
       mkdirSync5(dirname4(targetPath), { recursive: true });
       if (isTextFile(sourcePath)) {
-        const text = readFileSync13(sourcePath, "utf-8").replaceAll(PLACEHOLDER, projectName);
+        const text = readFileSync14(sourcePath, "utf-8").replaceAll(PLACEHOLDER, projectName);
         writeFileSync7(targetPath, text);
       } else {
         copyFileSync(sourcePath, targetPath);
@@ -240168,7 +240896,7 @@ function newIdempotencyKey() {
   return randomUUID();
 }
 async function uploadReusableFile(client, input) {
-  const contentType = input.mimeType ?? guessMimeType(input.filename) ?? "application/octet-stream";
+  const contentType = input.mimeType || guessMimeType(input.filename) || "application/octet-stream";
   const idempotencyKey = input.idempotencyKey ?? newIdempotencyKey();
   const negotiation = await client.post(apiPath("/files/uploads"), {
     filename: input.filename,
@@ -240223,7 +240951,7 @@ async function buildPreparedRunRequest(client, input) {
       fieldName: spec.fieldName,
       content: data,
       filename: path17.basename(spec.filePath),
-      mimeType: guessMimeType(path17.basename(spec.filePath)) ?? "application/octet-stream"
+      mimeType: guessMimeType(path17.basename(spec.filePath)) || "application/octet-stream"
     });
   }
   for (const file of input.files ?? []) {
@@ -240232,7 +240960,7 @@ async function buildPreparedRunRequest(client, input) {
       fieldName: file.fieldName,
       content,
       filename: file.filename,
-      mimeType: file.mimeType ?? guessMimeType(file.filename) ?? "application/octet-stream"
+      mimeType: file.mimeType || guessMimeType(file.filename) || "application/octet-stream"
     });
   }
   const preUploadIndices = indicesRequiringPreUpload(localFiles.map((file) => ({ size: file.content.byteLength })));
@@ -240291,7 +241019,7 @@ function upgradeMixedFieldPreUpload(localFiles, preUploadIndices) {
 }
 function appendFilePart(form, fieldName, content, filename, mimeType) {
   assertValidFileFieldName(fieldName);
-  const type = mimeType ?? guessMimeType(filename) ?? "application/octet-stream";
+  const type = mimeType || guessMimeType(filename) || "application/octet-stream";
   form.append(`files.${fieldName}`, new Blob([content], { type }), filename);
 }
 function assertValidFileFieldName(fieldName) {
@@ -240318,7 +241046,7 @@ function parseInputFileSpecs(inputFile) {
 
 // src/lib/format-eigenpal.ts
 import { spawnSync as spawnSync5 } from "child_process";
-import { existsSync as existsSync14, readFileSync as readFileSync14 } from "fs";
+import { existsSync as existsSync15, readFileSync as readFileSync15 } from "fs";
 import { join as join8, resolve as resolve5 } from "path";
 var PRETTRC_NAMES = [
   ".prettierrc",
@@ -240332,14 +241060,14 @@ var PRETTRC_NAMES = [
 ];
 function hasPrettierConfig(cwd) {
   for (const name of PRETTRC_NAMES) {
-    if (existsSync14(join8(cwd, name)))
+    if (existsSync15(join8(cwd, name)))
       return true;
   }
   try {
     const pkgPath = join8(cwd, "package.json");
-    if (!existsSync14(pkgPath))
+    if (!existsSync15(pkgPath))
       return false;
-    const raw = readFileSync14(pkgPath, "utf-8");
+    const raw = readFileSync15(pkgPath, "utf-8");
     const pkg = JSON.parse(raw);
     return pkg != null && typeof pkg === "object" && "prettier" in pkg;
   } catch {
@@ -240349,7 +241077,7 @@ function hasPrettierConfig(cwd) {
 function formatEigenpalDirIfAvailable(dir) {
   const cwd = process.cwd();
   const absDir = resolve5(cwd, dir);
-  if (!existsSync14(absDir))
+  if (!existsSync15(absDir))
     return;
   if (!hasPrettierConfig(cwd))
     return;
@@ -240369,9 +241097,13 @@ async function runSavedWorkflowExamples(workflow, examples, opts) {
     const client = new ApiClient(config);
     const workflowId = await resolveWorkflowId(client, workflow);
     if (opts.version && !["latest", "current", "undefined"].includes(opts.version)) {
-      warn(`--example runs the current published version; ignoring @${opts.version}.`);
+      throw new Error(`--example cannot run workflow version @${opts.version}; publish or activate that version first, then use @latest`);
     }
-    const summary = await runWorkflowExamplesWithEval(client, config.dir, workflow, workflowId, examples);
+    const summary = await runWorkflowExamplesWithEval(client, config.dir, workflow, workflowId, examples, {
+      quiet: opts.json,
+      intervalMs: Math.max(0, opts.interval ?? 2) * 1000,
+      maxWaitMs: Math.max(1, opts.maxWait ?? 1800) * 1000
+    });
     if (opts.json)
       console.log(JSON.stringify(summary, null, 2));
     if (summary.errored > 0)
@@ -240453,8 +241185,11 @@ async function runTarget(target, opts) {
   }
   const runId = String(payload.id ?? "");
   let waitedForTerminalRun = false;
+  if (opts.wait && !runId) {
+    throw new Error("Run start response did not include an id; cannot honor --wait");
+  }
   if (opts.wait && runId) {
-    payload = await pollRun(client, runId, opts.interval, opts.maxWait);
+    payload = await pollRun(client, runId, opts.interval, opts.maxWait, opts.json);
     waitedForTerminalRun = true;
   }
   renderRunPayload(payload, opts);
@@ -240469,10 +241204,10 @@ async function rerunTarget(runId, opts) {
 init_dist4();
 import { createHash as createHash5 } from "node:crypto";
 import {
-  existsSync as existsSync15,
+  existsSync as existsSync16,
   lstatSync,
   mkdirSync as mkdirSync6,
-  readFileSync as readFileSync15,
+  readFileSync as readFileSync16,
   readdirSync as readdirSync5,
   rmSync as rmSync2,
   rmdirSync,
@@ -240555,10 +241290,10 @@ var MANIFEST_NAME = ".eigenpal-manifest.json";
 function resolveSkillSource() {
   const here = dirname5(fileURLToPath7(import.meta.url));
   const srcCandidate = resolve6(here, "..", "..", "skill");
-  if (existsSync15(srcCandidate))
+  if (existsSync16(srcCandidate))
     return srcCandidate;
   const distCandidate = resolve6(here, "skill");
-  if (existsSync15(distCandidate))
+  if (existsSync16(distCandidate))
     return distCandidate;
   throw new Error(`Cannot locate bundled skill content. Looked in:
   ${srcCandidate}
@@ -240595,15 +241330,15 @@ async function installSkill(opts) {
   for (const relativePath of sourceFiles) {
     const sourcePath = join10(source, relativePath);
     const targetPath = join10(target, relativePath);
-    const sourceBytes = templateSourceFile(relativePath, readFileSync15(sourcePath), cliVersion);
+    const sourceBytes = templateSourceFile(relativePath, readFileSync16(sourcePath), cliVersion);
     const sourceHash = sha256(sourceBytes);
-    if (!existsSync15(targetPath)) {
+    if (!existsSync16(targetPath)) {
       mkdirSync6(dirname5(targetPath), { recursive: true });
       writeFileSync8(targetPath, sourceBytes);
       written += 1;
       continue;
     }
-    const targetBytes = readFileSync15(targetPath);
+    const targetBytes = readFileSync16(targetPath);
     const targetHash = sha256(targetBytes);
     if (targetHash === sourceHash) {
       skipped += 1;
@@ -240635,9 +241370,9 @@ async function installSkill(opts) {
   const manifestEntries = [];
   for (const relativePath of sourceFiles) {
     const targetPath = join10(target, relativePath);
-    if (!existsSync15(targetPath))
+    if (!existsSync16(targetPath))
       continue;
-    manifestEntries.push({ path: relativePath, sha256: sha256(readFileSync15(targetPath)) });
+    manifestEntries.push({ path: relativePath, sha256: sha256(readFileSync16(targetPath)) });
   }
   const manifest = {
     cliVersion,
@@ -240678,9 +241413,9 @@ async function uninstallSkill(opts) {
       console.error(`Refusing to touch ${path}: manifest path escapes ${targetReal}`);
       continue;
     }
-    if (!existsSync15(path))
+    if (!existsSync16(path))
       continue;
-    const currentHash = sha256(readFileSync15(path));
+    const currentHash = sha256(readFileSync16(path));
     if (currentHash !== entry.sha256 && !opts.yes) {
       kept += 1;
       continue;
@@ -240777,6 +241512,9 @@ async function uninstallSkillTools(opts) {
     await uninstallSkill({ target: opts.target, yes: opts.yes });
     return;
   }
+  if (!opts.all && !hasToolIds && (opts.yes || !isInteractiveStdout())) {
+    throw new Error("Non-interactive: pass tool ids (e.g. `skill uninstall claude`) or `--all`.");
+  }
   const cwd = process.cwd();
   const installedTools = TOOLS.filter((t) => isInstalled(cwd, t));
   if (installedTools.length === 0) {
@@ -240795,8 +241533,6 @@ async function uninstallSkillTools(opts) {
       info(`Not installed (skipping): ${notInstalled.join(", ")}`);
       targets = targets.filter((t) => installedIds.has(t.id));
     }
-  } else if (opts.yes || !isInteractiveStdout()) {
-    throw new Error("Non-interactive: pass tool ids (e.g. `skill uninstall claude`) or `--all`.");
   } else {
     const picked = await ve({
       message: "Select tools to uninstall (only installed tools shown)",
@@ -240880,10 +241616,10 @@ function hintFor(tool, installed, detected) {
   return tool.relativePath;
 }
 function isInstalled(cwd, tool) {
-  return existsSync15(join10(cwd, tool.relativePath, MANIFEST_NAME));
+  return existsSync16(join10(cwd, tool.relativePath, MANIFEST_NAME));
 }
 function isProjectUsing(cwd, tool) {
-  return tool.detectPaths.some((p) => existsSync15(join10(cwd, p)));
+  return tool.detectPaths.some((p) => existsSync16(join10(cwd, p)));
 }
 function listFiles(root) {
   const out = [];
@@ -240907,10 +241643,10 @@ function listFiles(root) {
 }
 function readManifest(target) {
   const path = join10(target, MANIFEST_NAME);
-  if (!existsSync15(path))
+  if (!existsSync16(path))
     return null;
   try {
-    return JSON.parse(readFileSync15(path, "utf-8"));
+    return JSON.parse(readFileSync16(path, "utf-8"));
   } catch {
     return null;
   }
@@ -240924,8 +241660,8 @@ function readCliVersion() {
       resolve6(here, "..", "package.json")
     ];
     for (const candidate of candidates) {
-      if (existsSync15(candidate)) {
-        const pkg = JSON.parse(readFileSync15(candidate, "utf-8"));
+      if (existsSync16(candidate)) {
+        const pkg = JSON.parse(readFileSync16(candidate, "utf-8"));
         if (pkg.name && pkg.name !== "@eigenpal/cli")
           continue;
         if (pkg.version)
@@ -240936,7 +241672,7 @@ function readCliVersion() {
   return "unknown";
 }
 function pruneEmptyDirs(root) {
-  if (!existsSync15(root))
+  if (!existsSync16(root))
     return;
   const stack = [];
   const collect = (dir) => {
@@ -241726,12 +242462,12 @@ function looksLikeFreeform(prop) {
   return prop.pattern !== undefined || prop.format !== undefined;
 }
 // src/commands/workflow/index.ts
-import { existsSync as existsSync21, promises as fs20 } from "node:fs";
+import { existsSync as existsSync22, promises as fs20 } from "node:fs";
 import path18 from "node:path";
 
 // src/lib/local-templates.ts
 init_src();
-import { existsSync as existsSync16, promises as fs17, realpathSync as realpathSync3, statSync as statSync5 } from "node:fs";
+import { existsSync as existsSync17, promises as fs17, realpathSync as realpathSync3, statSync as statSync5 } from "node:fs";
 import { basename, dirname as dirname6, isAbsolute, relative as relative4, resolve as resolve7, sep } from "node:path";
 
 // src/lib/office-template.ts
@@ -241974,7 +242710,7 @@ function walkTemplateSteps(steps, visit) {
 }
 function resolveWorkflowProjectRoot(workflowFile) {
   const abs = resolve7(workflowFile);
-  if (!existsSync16(abs)) {
+  if (!existsSync17(abs)) {
     throw new Error(`Workflow file not found: ${abs}`);
   }
   return dirname6(realpathSync3(abs));
@@ -241997,7 +242733,7 @@ function resolveWorkflowTemplatePath(workflowFile, templatePath, opts = {}) {
   if (!opts.allowExternal) {
     assertInsideProject(projectRoot, templatePath, candidate);
   }
-  if (!existsSync16(candidate)) {
+  if (!existsSync17(candidate)) {
     throw new Error(`Local template not found: ${candidate}`);
   }
   const real = realpathSync3(candidate);
@@ -242179,11 +242915,11 @@ function rewriteLocalTemplateYaml(yamlText, resolved) {
 }
 
 // src/commands/workflow/clear.ts
-import { existsSync as existsSync17, readdirSync as readdirSync6, rmSync as rmSync3, statSync as statSync6 } from "fs";
+import { existsSync as existsSync18, readdirSync as readdirSync6, rmSync as rmSync3, statSync as statSync6 } from "fs";
 import { basename as basename2, join as join11 } from "path";
 var EMPTY_REPORT = { removed: 0, kept: 0, touched: 0 };
 function getDirectoryEntries(path) {
-  if (!existsSync17(path))
+  if (!existsSync18(path))
     return [];
   return readdirSync6(path).filter((entry) => statSync6(join11(path, entry)).isDirectory()).sort();
 }
@@ -242204,7 +242940,7 @@ function removeDirEntriesWithRetention(path, removeAll) {
   return { removed, kept: keepSet.size, touched: entries.length };
 }
 function removeJudgeSummaryFilesWithRetention(exampleDir, removeAll) {
-  if (!existsSync17(exampleDir))
+  if (!existsSync18(exampleDir))
     return EMPTY_REPORT;
   const stampByFile = new Map;
   for (const fileName of readdirSync6(exampleDir).sort()) {
@@ -242276,7 +243012,7 @@ async function clearEvalOutputs(dir, exampleNames = [], options = {}) {
   runSection({
     exampleDirs,
     clean: (exampleDir) => removeDirEntriesWithRetention(join11(exampleDir, "executions"), removeAll),
-    shouldCount: (exampleDir) => existsSync17(join11(exampleDir, "executions")),
+    shouldCount: (exampleDir) => existsSync18(join11(exampleDir, "executions")),
     successLabel: "Execution cleanup complete",
     scannedLabel: "examples scanned:",
     seenLabel: "runs seen:       ",
@@ -242288,7 +243024,7 @@ async function clearEvalOutputs(dir, exampleNames = [], options = {}) {
   runSection({
     exampleDirs,
     clean: (exampleDir) => removeJudgeSummaryFilesWithRetention(exampleDir, removeAll),
-    shouldCount: (exampleDir) => existsSync17(exampleDir),
+    shouldCount: (exampleDir) => existsSync18(exampleDir),
     successLabel: "Judge summary cleanup complete",
     scannedLabel: "examples scanned:     ",
     seenLabel: "summary files seen:   ",
@@ -242401,7 +243137,7 @@ function registerStepExecCommands(workflow) {
 
 // src/commands/workflow/templates.ts
 init_src();
-import { existsSync as existsSync18, promises as fs19 } from "node:fs";
+import { existsSync as existsSync19, promises as fs19 } from "node:fs";
 import { basename as basename3, resolve as resolve8 } from "node:path";
 function buildClient2(opts) {
   const config = resolveConfig(opts);
@@ -242582,7 +243318,7 @@ function registerTemplateCommands(parent) {
       filename = downloaded.filename;
     } else {
       const filePath = resolve8(templateArg);
-      if (!existsSync18(filePath)) {
+      if (!existsSync19(filePath)) {
         throw new Error(`Template file not found: ${filePath}. Pass a local .docx/.xlsx path or a tmpl_… id.`);
       }
       bytes = await fs19.readFile(filePath);
@@ -242624,12 +243360,12 @@ function registerTemplateCommands(parent) {
 
 // src/commands/workflow/validation.ts
 init_src();
-import { existsSync as existsSync20, readdirSync as readdirSync7, readFileSync as readFileSync17, statSync as statSync7 } from "fs";
+import { existsSync as existsSync21, readdirSync as readdirSync7, readFileSync as readFileSync18, statSync as statSync7 } from "fs";
 import { join as join12, resolve as resolve9 } from "path";
 
 // src/lib/template-diagnostics.ts
 init_src();
-import { existsSync as existsSync19, readFileSync as readFileSync16 } from "node:fs";
+import { existsSync as existsSync20, readFileSync as readFileSync17 } from "node:fs";
 function walkSteps(steps, pathPrefix, visit) {
   if (!Array.isArray(steps))
     return;
@@ -242754,7 +243490,7 @@ async function diagnoseTemplateSteps(args) {
         });
         continue;
       }
-      if (!existsSync19(absolute)) {
+      if (!existsSync20(absolute)) {
         diagnostics.push({
           field: `${info.fieldPath}.template`,
           message: `File not found: ${absolute}`,
@@ -242763,7 +243499,7 @@ async function diagnoseTemplateSteps(args) {
         continue;
       }
       try {
-        const bytes = readFileSync16(absolute);
+        const bytes = readFileSync17(absolute);
         const inspection = inspectOfficeTemplateBytes(bytes, absolute);
         diagnostics.push(...formatDiagnostics(info, inspection));
       } catch (err) {
@@ -242877,8 +243613,17 @@ function countInvokeWorkflowSteps(steps) {
     if (step.type === "action.invoke-workflow")
       count++;
     count += countInvokeWorkflowSteps(step.steps);
+    count += countInvokeWorkflowSteps(step.body);
     count += countInvokeWorkflowSteps(step.then);
     count += countInvokeWorkflowSteps(step.else);
+    count += countInvokeWorkflowSteps(step.default);
+    if (Array.isArray(step.cases)) {
+      for (const switchCase of step.cases) {
+        if (switchCase && typeof switchCase === "object") {
+          count += countInvokeWorkflowSteps(switchCase.steps);
+        }
+      }
+    }
     if (Array.isArray(step.branches)) {
       for (const branch of step.branches) {
         if (branch && typeof branch === "object") {
@@ -242890,7 +243635,7 @@ function countInvokeWorkflowSteps(steps) {
   return count;
 }
 function validateWorkflowYaml(path) {
-  if (!existsSync20(path)) {
+  if (!existsSync21(path)) {
     return {
       issues: [{ field: path, message: "File not found." }],
       warnings: [],
@@ -242899,7 +243644,7 @@ function validateWorkflowYaml(path) {
       steps: []
     };
   }
-  const text = readFileSync17(path, "utf-8");
+  const text = readFileSync18(path, "utf-8");
   try {
     const definition = parseWorkflow(text);
     let warnings = [];
@@ -243000,10 +243745,10 @@ function printSchemaQualityWarnings(path, warnings) {
   }
 }
 function validateEvaluatorsYaml(path) {
-  if (!existsSync20(path)) {
+  if (!existsSync21(path)) {
     return [{ field: path, message: "File not found." }];
   }
-  const text = readFileSync17(path, "utf-8");
+  const text = readFileSync18(path, "utf-8");
   let parsed;
   try {
     parsed = $parse(text);
@@ -243020,17 +243765,17 @@ function validateEvaluatorsYaml(path) {
 }
 function validateDatasetFolder(root) {
   const issues = [];
-  if (!existsSync20(root)) {
+  if (!existsSync21(root)) {
     return [{ field: root, message: "Folder not found." }];
   }
-  if (existsSync20(join12(root, "manifest.json"))) {
+  if (existsSync21(join12(root, "manifest.json"))) {
     issues.push({
       field: "manifest.json",
       message: "Top-level manifest.json is the legacy format. Re-export the dataset using the folder convention."
     });
   }
   const examplesDir = join12(root, "examples");
-  if (!existsSync20(examplesDir)) {
+  if (!existsSync21(examplesDir)) {
     issues.push({ field: "examples/", message: "No examples/ directory found at dataset root." });
     return issues;
   }
@@ -243046,7 +243791,7 @@ function validateDatasetFolder(root) {
       continue;
     }
     const inputJsonPath = join12(exampleFolder, "input.json");
-    const hasInputJson = existsSync20(inputJsonPath);
+    const hasInputJson = existsSync21(inputJsonPath);
     if (!hasInputJson) {
       issues.push({
         field: `examples/${exampleName}/input.json`,
@@ -243056,7 +243801,7 @@ function validateDatasetFolder(root) {
     }
     let args;
     try {
-      const parsed = JSON.parse(readFileSync17(inputJsonPath, "utf-8"));
+      const parsed = JSON.parse(readFileSync18(inputJsonPath, "utf-8"));
       if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         issues.push({
           field: `examples/${exampleName}/input.json`,
@@ -243073,7 +243818,7 @@ function validateDatasetFolder(root) {
       continue;
     }
     const inputDir = join12(exampleFolder, "input");
-    if (existsSync20(join12(inputDir, "arguments.json"))) {
+    if (existsSync21(join12(inputDir, "arguments.json"))) {
       issues.push({
         field: `examples/${exampleName}/input/arguments.json`,
         message: "Legacy input/arguments.json is no longer accepted. Use input.json instead."
@@ -243090,7 +243835,7 @@ function validateDatasetFolder(root) {
     }
     const expectedDir = join12(exampleFolder, "expected");
     const expectedJsonPath = join12(exampleFolder, "expected.json");
-    if (existsSync20(expectedDir)) {
+    if (existsSync21(expectedDir)) {
       for (const entry of readdirSync7(expectedDir)) {
         if (entry === "output.json" || entry === "error.json") {
           issues.push({
@@ -243126,10 +243871,10 @@ function validateDatasetFolder(root) {
         }
       }
     }
-    if (existsSync20(expectedJsonPath)) {
+    if (existsSync21(expectedJsonPath)) {
       let parsed;
       try {
-        parsed = JSON.parse(readFileSync17(expectedJsonPath, "utf-8"));
+        parsed = JSON.parse(readFileSync18(expectedJsonPath, "utf-8"));
       } catch {
         issues.push({
           field: `examples/${exampleName}/expected.json`,
@@ -243208,7 +243953,7 @@ function validateFileRefs2(args) {
       });
       continue;
     }
-    if (!existsSync20(join12(args.filesRoot, relative))) {
+    if (!existsSync21(join12(args.filesRoot, relative))) {
       issues.push({
         field: `${args.fieldPrefix}:${ref.jsonPath}`,
         message: `Referenced file does not exist: ${ref.path}.`
@@ -243238,16 +243983,55 @@ async function onlineInvokeIssues(yamlText, opts) {
   const res = await client.post("/api/workflows/validate", { yaml: yamlText });
   return res.issues ?? [];
 }
+function discoverWorkflowProjectRoots(rootPath) {
+  const root = resolve9(rootPath);
+  if (existsSync21(join12(root, "workflow.yaml")))
+    return [root];
+  const candidates = [
+    join12(root, "eigenpal", "workflows"),
+    join12(root, "workflows"),
+    root.endsWith(join12("eigenpal", "workflows")) ? root : ""
+  ].filter(Boolean);
+  for (const parent of candidates) {
+    if (!existsSync21(parent) || !statSync7(parent).isDirectory())
+      continue;
+    const projects = readdirSync7(parent, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.isSymbolicLink() && existsSync21(join12(parent, entry.name, "workflow.yaml"))).map((entry) => join12(parent, entry.name)).sort();
+    if (projects.length > 0)
+      return projects;
+  }
+  return [];
+}
+async function validateProjectRoot(root, opts) {
+  const wfFile = join12(root, "workflow.yaml");
+  const wfResult = validateWorkflowYaml(wfFile);
+  const wfPath = relPath(root, wfFile);
+  const wfOk = printIssues("workflow.yaml", wfPath, wfResult.issues);
+  if (wfOk) {
+    printSchemaQualityWarnings(wfPath, wfResult.warnings);
+    printInvokeOnlineHint(wfResult.invokeStepCount, wfResult.templateStepCount, opts.online);
+  }
+  const evOk = printIssues("evaluators.yaml", relPath(root, join12(root, "evaluators.yaml")), validateEvaluatorsYaml(join12(root, "evaluators.yaml")));
+  const dsOk = printIssues("dataset/", relPath(root, join12(root, "dataset")), validateDatasetFolder(join12(root, "dataset")));
+  const templateOk = wfOk && existsSync21(wfFile) ? await runTemplateDiagnostics(wfFile, wfResult.steps, opts) : true;
+  let onlineOk = true;
+  if (wfOk && opts.online && existsSync21(wfFile)) {
+    onlineOk = printIssues("invoke refs (server)", wfPath, await onlineInvokeIssues(readFileSync18(wfFile, "utf-8"), opts));
+  }
+  return wfOk && evOk && dsOk && templateOk && onlineOk;
+}
 function registerAllValidateCommand(parent) {
-  const cmd = parent.command("validate [path]").description("Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/). With [path] pointing at a YAML file: validates that workflow.yaml. For per-noun targeting use `evaluators validate` or `dataset validate`.").option("--dir <path>", "Project root (defaults to cwd; resolves the three default paths from here)").option("--online", "Authenticate and also validate action.invoke-workflow targets, transform.template tmpl_… references, and explicitly selected OCR/vision/text models against this tenant environment (existence, format, revision pairing, tokens vs data, XLSX {{ }} mistakes, configured catalog). Local template: paths are inspected on disk with or without this flag. Model checks use the configured catalog only — they do not probe live provider health.").option("--allow-external-templates", "Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected.").addHelpText("after", `
+  const cmd = parent.command("validate [path]").description("Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/) in the project root. When the root has no workflow.yaml, discovers nested projects under eigenpal/workflows/<slug>/ or workflows/<slug>/ and validates each. With [path] pointing at a YAML file: validates that workflow.yaml only. For per-noun targeting use `evaluators validate` or `dataset validate`.").option("--dir <path>", "Project root (defaults to cwd; resolves the three default paths from here)").option("--online", "Authenticate and also validate action.invoke-workflow targets, transform.template tmpl_… references, and explicitly selected OCR/vision/text models against this tenant environment (existence, format, revision pairing, tokens vs data, XLSX {{ }} mistakes, configured catalog). Local template: paths are inspected on disk with or without this flag. Model checks use the configured catalog only — they do not probe live provider health.").option("--allow-external-templates", "Allow local template: paths whose real path is outside the workflow project directory (the folder that contains the YAML file). Off by default; ../ and symlink escapes are rejected.").addHelpText("after", `
 Note
+` + `  When [path] or --dir points at a repository root (or eigenpal/workflows),
+` + `  every discovered workflow project is validated and failures are grouped
+` + `  by project path.
 ` + `  Local validation cannot resolve action.invoke-workflow targets, tmpl_…
 ` + `  template ids, or whether selected OCR/vision/text models exist in this
 ` + "  environment (they live on the server). Run `validate --online` to check\n" + "  them before pushing. Source-controlled `template: ./file.xlsx` paths are\n" + `  inspected on disk without --online and must stay inside the workflow
 ` + `  project unless you pass --allow-external-templates.
 `);
   withBaseUrl(cmd).action(action(async (path, opts) => {
-    if (path) {
+    if (path && (!existsSync21(resolve9(path)) || !statSync7(resolve9(path)).isDirectory())) {
       const target = resolve9(path);
       const wfResult = validateWorkflowYaml(target);
       const wfOk = printIssues("workflow.yaml", target, wfResult.issues);
@@ -243258,29 +244042,29 @@ Note
       const templateOk = wfOk ? await runTemplateDiagnostics(target, wfResult.steps, opts) : true;
       let onlineOk = true;
       if (wfOk && opts.online) {
-        onlineOk = printIssues("invoke refs (server)", target, await onlineInvokeIssues(readFileSync17(target, "utf-8"), opts));
+        onlineOk = printIssues("invoke refs (server)", target, await onlineInvokeIssues(readFileSync18(target, "utf-8"), opts));
       }
       if (!wfOk || !templateOk || !onlineOk)
         process.exit(1);
       return;
     }
-    const root = rootDir(opts);
-    const wfFile = join12(root, "workflow.yaml");
-    const wfResult = validateWorkflowYaml(wfFile);
-    const wfPath = relPath(root, wfFile);
-    const wfOk = printIssues("workflow.yaml", wfPath, wfResult.issues);
-    if (wfOk) {
-      printSchemaQualityWarnings(wfPath, wfResult.warnings);
-      printInvokeOnlineHint(wfResult.invokeStepCount, wfResult.templateStepCount, opts.online);
-    }
-    const evOk = printIssues("evaluators.yaml", relPath(root, join12(root, "evaluators.yaml")), validateEvaluatorsYaml(join12(root, "evaluators.yaml")));
-    const dsOk = printIssues("dataset/", relPath(root, join12(root, "dataset")), validateDatasetFolder(join12(root, "dataset")));
-    let onlineOk = true;
-    const templateOk = wfOk && existsSync20(wfFile) ? await runTemplateDiagnostics(wfFile, wfResult.steps, opts) : true;
-    if (wfOk && opts.online && existsSync20(wfFile)) {
-      onlineOk = printIssues("invoke refs (server)", wfPath, await onlineInvokeIssues(readFileSync17(wfFile, "utf-8"), opts));
-    }
-    if (!wfOk || !evOk || !dsOk || !templateOk || !onlineOk)
+    const requestedRoot = path ? resolve9(path) : rootDir(opts);
+    const projects = discoverWorkflowProjectRoots(requestedRoot);
+    if (projects.length === 0) {
+      if (!await validateProjectRoot(requestedRoot, opts))
+        process.exit(1);
+      return;
+    }
+    let valid = true;
+    for (const project of projects) {
+      if (projects.length > 1) {
+        process.stderr.write(`${ui.bold(relPath(requestedRoot, project))}
+`);
+      }
+      if (!await validateProjectRoot(project, opts))
+        valid = false;
+    }
+    if (!valid)
       process.exit(1);
   }));
 }
@@ -243509,7 +244293,7 @@ new uploads are deleted. The file on disk is not rewritten.
           defaultValue: "workflow.yaml",
           validate: (value) => {
             const p = value || "workflow.yaml";
-            if (!existsSync21(p))
+            if (!existsSync22(p))
               return `Not found: ${p}`;
             return;
           }
@@ -244148,7 +244932,7 @@ function registerExperimentCommands2(parent) {
       }
     ], { ...opts, entityLabel: "experiment" });
   }));
-  const runCmd = experiment.command("run <workflow-id>").description(descriptionFor("workflow_run_experiment")).option("--example-id <id>", "Run only this example (repeatable)", (val2, prev) => [...prev, val2], []).option("--wait", "Poll until terminal; non-zero exit on passRate < 1.0", false).option("--interval <n>", "Polling interval in seconds (default 10)", intArg, 10).addHelpText("after", `
+  const runCmd = experiment.command("run <workflow-id>").description(descriptionFor("workflow_run_experiment")).option("--example-id <id>", "Run only this example (repeatable)", (val2, prev) => [...prev, val2], []).option("--wait", "Poll until terminal; non-zero exit on passRate < 1.0", false).option("--interval <n>", "Polling interval in seconds (default 10)", intArg, 10).option("--max-wait <seconds>", "Maximum wait before exit code 2 (default 1800)", intArg, 1800).addHelpText("after", `
 Examples:
   $ eigenpal workflow experiment run wf_abc123
   $ eigenpal workflow experiment run my-extraction --example-id evx_111
@@ -244181,15 +244965,40 @@ returns immediately with \`{ batchId, total }\`; poll
       return;
     }
     const intervalMs = Math.max(1, opts.interval) * 1000;
+    const deadline = Date.now() + Math.max(1, opts.maxWait) * 1000;
     while (true) {
       const status = await client.get(`/v1/automations/${workflowId}/experiments/${experimentId}`);
       if (status.status === "completed") {
-        printJson3(status);
+        if (opts.json) {
+          printJson3({
+            ...status,
+            batchId: experimentId,
+            total: status.runCount ?? status.total
+          });
+        } else {
+          const completed = status.completedCount ?? status.completed;
+          const runTotal = status.runCount ?? status.total;
+          const score = typeof status.evalScore === "number" ? ` average=${status.evalScore.toFixed(3)}` : "";
+          success(`Experiment ${ui.bold(experimentId)} completed (${completed}/${runTotal}${score})`);
+        }
         if (typeof status.passRate === "number" && status.passRate < 1 || typeof status.failedCount === "number" && status.failedCount > 0)
           process.exit(1);
         return;
       }
-      console.error(`${ui.dim(`[${experimentId}]`)} ${status.completedCount ?? status.completed}/${status.runCount ?? status.total} ${ui.dim(`(status=${status.status})`)}`);
+      if (!opts.json) {
+        console.error(`${ui.dim(`[${experimentId}]`)} ${status.completedCount ?? status.completed}/${status.runCount ?? status.total} ${ui.dim(`(status=${status.status})`)}`);
+      }
+      if (Date.now() >= deadline) {
+        if (opts.json) {
+          printJson3({
+            ...status,
+            batchId: experimentId,
+            total: status.runCount ?? status.total
+          });
+        }
+        error2(`Timed out waiting for experiment ${experimentId} after ${opts.maxWait}s`);
+        process.exit(2);
+      }
       await new Promise((r) => setTimeout(r, intervalMs));
     }
   }));
@@ -244199,6 +245008,10 @@ returns immediately with \`{ batchId, total }\`; poll
       error2("--short and --watch are mutually exclusive (short is for spot-check polling).");
       process.exit(2);
     }
+    if (opts.short && opts.json) {
+      error2("--short and --json are mutually exclusive (short is human spot-check output).");
+      process.exit(2);
+    }
     const includes = new Set((opts.include ?? "").split(",").map((s) => s.trim()).filter(Boolean));
     const includePayload = includes.has("payload");
     const { client, workflowId } = await buildClientForWorkflow(workflow, opts);
@@ -244307,14 +245120,41 @@ Behavior:
     }
     return value;
   };
-  const resultsCmd = experiment.command("results <workflow-id> [batchId]").description(descriptionFor("workflow_get_experiment_results")).requiredOption("--format <csv|json>", "Output format", parseExportFormat).option("--out <path>", "Output file. When omitted, the binary streams to stdout.");
-  withBaseUrl(resultsCmd).action(action(async (workflow, batchId, opts) => {
+  const resultsCmd = experiment.command("results <workflow-id> [batchId]").description(descriptionFor("workflow_get_experiment_results")).option("--format <csv|json>", "Output format (default json)", parseExportFormat, "json").option("--out <path>", "Output file. When omitted, the binary streams to stdout.").option("--summary", "Show total/pass/fail/error counts, average score, and evaluator rollups").option("--failed-only", "Keep only failed or errored evaluator results").option("--evaluator <name>", "Keep only results from this evaluator").option("--select <path>", "Print only a nested JSON value (for example summary.byEvaluator or discrepancies[].path)");
+  addJsonFlag(withBaseUrl(resultsCmd)).action(action(async (workflow, batchId, opts) => {
     const { client, workflowId } = await buildClientForWorkflow(workflow, opts);
+    if (opts.json && opts.format !== "json") {
+      throw new Error("--json cannot be combined with --format csv");
+    }
+    const analyze = opts.summary || opts.failedOnly || opts.evaluator !== undefined || opts.select !== undefined;
+    if (analyze) {
+      if (!batchId) {
+        throw new Error("--summary, --failed-only, --evaluator, and --select require a single experiment batch id");
+      }
+      if (opts.format !== "json") {
+        throw new Error("Experiment analysis options require --format json");
+      }
+      const detailPayload = await client.get(`/v1/automations/${workflowId}/experiments/${encodeURIComponent(batchId)}`);
+      const analysis = analyzeExperimentResults({
+        rows: experimentRowsFromDetail(detailPayload),
+        runs: detailPayload.runs ?? [],
+        evaluator: opts.evaluator,
+        failedOnly: opts.failedOnly
+      });
+      const selected = opts.select ? selectJsonValue(analysis, opts.select) : analysis;
+      if (opts.summary && !opts.json && !opts.out && !opts.select) {
+        renderExperimentResultsSummary(analysis);
+        return;
+      }
+      await writeOrPrint(opts.out, `${JSON.stringify(selected, null, 2)}
+`);
+      return;
+    }
     const params = new URLSearchParams({ format: opts.format });
     const exportPath = batchId ? `/v1/automations/${workflowId}/experiments/${batchId}/export?${params.toString()}` : `/v1/automations/${workflowId}/experiments/export?${params.toString()}`;
     await downloadStreamToFile2(client, exportPath, opts.out);
   }));
-  const compareCmd = experiment.command("compare <batchIdA> <batchIdB>").description("Diff eval scores between two experiment batches.").option("--sort <abs-delta-desc|delta-asc|delta-desc|name>", "Row sort order (default: biggest movers first)", "abs-delta-desc").option("--regression-threshold <n>", "Δ below this is flagged as a regression (default 0.05)", Number.parseFloat, 0.05).addHelpText("after", `
+  const compareCmd = experiment.command("compare <batchIdA> <batchIdB>").description("Compare evaluator scores or actual outputs between two experiment batches.").option("--outputs", "Compare actual run outputs instead of evaluator scores").option("--sort <abs-delta-desc|delta-asc|delta-desc|name>", "Row sort order (default: biggest movers first)", "abs-delta-desc").option("--regression-threshold <n>", "Δ below this is flagged as a regression (default 0.05)", Number.parseFloat, 0.05).addHelpText("after", `
 Examples:
   $ eigenpal workflow experiment compare evb_old evb_new
   $ eigenpal workflow experiment compare evb_old evb_new --regression-threshold 0.10
@@ -244334,6 +245174,26 @@ batches must belong to the same workflow within the caller's tenant.
       throw new Error("--regression-threshold must be a non-negative number");
     }
     const client = buildClient3(opts);
+    if (opts.outputs) {
+      const [outputsA, outputsB] = await Promise.all([
+        fetchExperimentOutputs(client, batchIdA),
+        fetchExperimentOutputs(client, batchIdB)
+      ]);
+      if (outputsA.automationId !== outputsB.automationId) {
+        throw new Error("Experiment batches must belong to the same automation");
+      }
+      const outputDiff = buildExperimentOutputDiff({
+        batchIdA,
+        batchIdB,
+        rowsA: outputsA.rows,
+        rowsB: outputsB.rows
+      });
+      if (opts.json)
+        printJson3(outputDiff);
+      else
+        renderExperimentOutputDiffHuman(outputDiff);
+      return;
+    }
     const [bodyA, bodyB] = await Promise.all([
       fetchEvalResults(client, batchIdA),
       fetchEvalResults(client, batchIdB)
@@ -244385,7 +245245,7 @@ Behavior:
     const dest = opts.pull ? opts.pullOnComplete ?? `./results-${batchId}.${opts.format}` : null;
     if (dest) {
       const dir = path18.dirname(dest);
-      if (!existsSync21(dir)) {
+      if (!existsSync22(dir)) {
         error2(`Destination directory does not exist: ${dir}. Create it first or pass a path under an existing directory.`);
         process.exit(2);
       }
@@ -245158,6 +246018,7 @@ registerModelsCommands(program2);
 registerRunCommands(program2);
 registerRunsCommands(program2);
 registerGitCommands(program2);
+registerDocsCommands(program2);
 program2.command("completion <shell>").description("Print a shell completion script to stdout (supported shells: bash, zsh, fish). Pipe into the appropriate completion file for your shell — see the script header for install instructions.").action(async (shell) => {
   try {
     await completion(shell, program2);