@eigenpal/cli 0.5.7 → 0.5.9

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @eigenpal/cli
 
-## 1.0.0
+## 0.5.9
 
 ### Major Changes
 
@@ -317,6 +317,12 @@ actual) { ... }` declaration around your statements. Parameter order is
   - **`init agent` and bare `agent` now exit 2** instead of 0 when invoked. Both subcommands are reserved-but-unimplemented placeholders, and exiting 0 made it possible for a CI script that misrouted into one of them to silently no-op. POSIX exit 2 ("command exists but isn't usable as invoked") makes the misroute fail loudly. The human-readable "coming soon" stderr message is unchanged.
   - **New `--no-color` global flag.** Disables ANSI colors in all output, matching the convention shared by `gh`, `kubectl`, `npm`, and `terraform`. Equivalent to setting `NO_COLOR=1` in the environment, but takes effect for the current invocation only. Implemented as a lazy picocolors wrapper so the flip propagates to every helper in `lib/ui.ts` (and every downstream caller of `pc`) regardless of when in the command lifecycle the flag is parsed.
 
+- 809f3d4: `auth list`: the org name is now the primary label (bold, immediately after
+  the marker), the profile slug is dimmed beside it (still the value you feed
+  to `auth use <name>` or `EIGENPAL_PROFILE=<name>`), and the base URL trails
+  on the right. The redundant `(tenantId)` column was dropped — the profile
+  slug already disambiguates. `auth use` (interactive picker) now prints the
+  non-interactive form on success so you learn the slug you just picked.
 - 49a8f94: Fixed a stray `undefined` in the `eigenpal auth login` outro. The success message used `dim(...)` (a stderr printer that returns `void`) inside a template literal where `ui.dim(...)` (the inline string formatter) was meant. The dim "Saved profile X — switch with" hint now renders correctly instead of literal `undefined`.
 - 16c6e83: Updated `@eigenpal/cli` author from `Eigenpal <hello@eigenpal.com>` to `Jedr Blaszyk <jedr@eigenpal.com>`. Surfaces on the npm package page and in `npm view @eigenpal/cli`.
 - b1d2d77: CLI: default `baseUrl` is now `https://studio.eigenpal.com` instead of `http://localhost:3000`.
@@ -327,6 +333,10 @@ actual) { ... }` declaration around your statements. Parameter order is
 
   Also scrubs internal references from CLI source ahead of open-sourcing — generic placeholder names in docstrings and test fixtures, internal-tracker IDs stripped from comments, and one user-facing error message updated to point at the public issue tracker.
 
+- 75caaec: `eigenpal workflow push` and `eigenpal workflow validate` now surface non-fatal **schema-quality warnings** when an output schema is loose enough to hurt downstream typing: categorical fields like `category`/`status`/`kind` declared as plain strings (no `enum`), `transform.script` functions returning `any`/`unknown`, untyped objects (`type: object` with no `properties`), and untyped arrays (`type: array` with no `items`). Warnings print to stderr and never block the push.
+
+  Updated the bundled CLI skill (`workflow-yaml.md`) with a "Be specific with types" section teaching `enum` fields, per-value meanings inline in `description`, and how `transform.script` TS literal unions auto-produce JSON Schema enums.
+
 - be693a3: `EIGENPAL_API_KEY` is now a complete profile bypass — when set, the active profile's `baseUrl` is also ignored (previously the env key was paired with the profile's URL, which is always wrong because an API key is provisioned for one server).
 
   In CI:
@@ -467,6 +477,7 @@ actual) { ... }` declaration around your statements. Parameter order is
 
 - 71361fd: `workflow get-experiment-status --watch` now prints a per-example failure summary on stderr when the batch finishes with any failed/cancelled execution: example name, top-level error (truncated), and the exact `eigenpal execution get <exec-id>` command to drill into step-by-step detail. Removes the need for the agent to grep through a 1000-line JSON dump to find which example broke and why. `reference/debugging.md` documents the discovery path.
 - 71361fd: `eigenpal workflow get-experiment-status --watch` now polls until every execution in the batch reaches a terminal state (`completed` / `failed` / `cancelled`), then exits non-zero if any execution failed or was cancelled. Removes the need for agent-side polling loops that didn't notice all-terminal-already and kept ticking. Renders a one-line `N/M terminal (counts)` progress summary on stderr (in-place rewrite when stderr is a TTY), dumps the full JSON on stdout when done. `--interval <s>` and `--max-wait <s>` are configurable; defaults are 5s/30min.
+- c3bc4e9: Fix Git-backed source release and status edge cases.
 - 04e4018: Harden hidden Git materialization commands for package-ref installs, frozen lockfile replay, dependency materialization, and source authoring smoke flows.
 - 71361fd: `install-skill`: multi-tool support via interactive multiselect.
   - Opens a `@clack/prompts` multiselect picker over supported agent tools

package/dist/cli.js

@@ -28107,7 +28107,8 @@ var init_parser = __esm(() => {
     maxConcurrency: exports_external.number().min(1).max(30).default(3),
     pagesPerBatch: exports_external.number().min(1).max(20).default(5),
     prompt: exports_external.string().optional().describe("Custom prompt for LLM-based parsing"),
-    languages: exports_external.array(exports_external.string()).optional().describe("OCR language hints")
+    languages: exports_external.array(exports_external.string()).optional().describe("OCR language hints"),
+    tenantId: exports_external.string().optional()
   });
   ParserInputSchema = exports_external.object({
     data: exports_external.instanceof(Buffer).or(exports_external.instanceof(Uint8Array)),
@@ -65788,8 +65789,16 @@ function convertTsTypeToJsonSchema(node, ctx) {
     case "TSVoidKeyword":
       return {};
     case "TSAnyKeyword":
-    case "TSUnknownKeyword":
+    case "TSUnknownKeyword": {
+      const keyword = node.type === "TSAnyKeyword" ? "any" : "unknown";
+      ctx.warnings.push({
+        code: "weak-return-type",
+        message: `\`${keyword}\` produces an empty schema, so downstream steps can't autocomplete this field or its descendants. Describe the actual shape (\`{ name: string; total: number }\`) or a literal union (\`"low" | "medium" | "high"\`) for the strongest downstream typing.`,
+        start: node.start ?? undefined,
+        end: node.end ?? undefined
+      });
       return {};
+    }
     case "TSNeverKeyword":
       return { not: {} };
     case "TSArrayType":
@@ -66138,13 +66147,15 @@ function compileTypedScript(opts) {
     });
   }
   const convertIssues = [];
+  const convertWarnings = [];
   const inScopeSchemas = new Map(Object.entries(opts.inScopeSchemas ?? {}));
   const localAliases = collectLocalAliases(aliasDecls);
   const returnSchema = opts.kind === "evaluator" ? { type: "number" } : convertTsTypeToJsonSchema(returnTsType, {
     localAliases,
     inScopeSchemas,
     resolving: new Set,
-    issues: convertIssues
+    issues: convertIssues,
+    warnings: convertWarnings
   });
   if (convertIssues.length > 0) {
     return {
@@ -66157,10 +66168,7 @@ function compileTypedScript(opts) {
   }
   let stripped;
   try {
-    const out = import_sucrase.transform(opts.source, {
-      transforms: ["typescript"]
-    });
-    stripped = out.code;
+    stripped = import_sucrase.transform(opts.source, { transforms: ["typescript"] }).code;
   } catch (err) {
     const e2 = err;
     return failWith({
@@ -66174,7 +66182,8 @@ function compileTypedScript(opts) {
       js: stripped,
       returnSchema,
       paramNames: actualParamNames
-    }
+    },
+    warnings: convertWarnings
   };
 }
 function failWith(issue2) {
@@ -181601,7 +181610,7 @@ import { fileURLToPath as fileURLToPath6 } from "url";
 // package.json
 var package_default = {
   name: "@eigenpal/cli",
-  version: "0.5.7",
+  version: "0.5.9",
   description: "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   keywords: [
     "eigenpal",
@@ -181641,6 +181650,8 @@ 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",
     "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",
@@ -183847,16 +183858,19 @@ async function authList() {
     dim("No profiles configured. Run `eigenpal auth login` to add one.");
     return;
   }
-  const nameWidth = Math.max(16, ...names.map((n) => n.length));
-  for (const name of names.sort()) {
+  const rows = names.sort().map((name) => {
     const p2 = profiles[name];
-    const marker = name === current ? ui.ok("●") : ui.dim("○");
     const tenant = p2.tenantName ?? p2.tenantId ?? "?";
-    const tenantLabel = p2.tenantName && p2.tenantId ? `${tenant} ${ui.dim(`(${p2.tenantId})`)}` : tenant;
-    console.log(`${marker} ${ui.bold(name.padEnd(nameWidth))} ${ui.dim(tenantLabel)}  ${ui.dim(p2.baseUrl)}`);
+    return { name, baseUrl: p2.baseUrl, tenant };
+  });
+  const tenantWidth = Math.max(16, ...rows.map((r) => r.tenant.length));
+  const nameWidth = Math.max(16, ...rows.map((r) => r.name.length));
+  for (const r of rows) {
+    const marker = r.name === current ? ui.ok("●") : ui.dim("○");
+    console.log(`${marker} ${ui.bold(r.tenant.padEnd(tenantWidth))}  ${ui.dim(r.name.padEnd(nameWidth))}  ${ui.dim(r.baseUrl)}`);
   }
   console.log("");
-  dim(`(● = active. Switch with \`eigenpal auth use <name>\` or \`EIGENPAL_PROFILE=<name>\`.)`);
+  dim(`(● = active. Switch with \`eigenpal auth use <name>\` or \`EIGENPAL_PROFILE=<name>\` for one shell.)`);
 }
 async function authUse(profileName) {
   const { current, profiles } = listProfiles();
@@ -183901,7 +183915,8 @@ async function authUse(profileName) {
   if (profileName) {
     success2(`Switched to ${ui.bold(target)}${tenantSuffix}`);
   } else {
-    ye(`${ui.ok("✓")} Switched to ${ui.bold(target)}${tenantSuffix}`);
+    ye(`${ui.ok("✓")} Switched to ${ui.bold(target)}${tenantSuffix}
+  ${ui.dim(`In scripts: \`eigenpal auth use ${target}\` or \`EIGENPAL_PROFILE=${target}\``)}`);
   }
 }
 
@@ -184616,6 +184631,9 @@ function checkRepoVersion(gitRoot, mutation) {
 function resolvePackagePath(target) {
   return target.includes("/") ? SourcePackagePathSchema.parse(target) : dottedPackageNameToPath(DottedPackageNameSchema.parse(target));
 }
+function isAutomationPackagePath(packagePath) {
+  return packagePath.startsWith("agents/") || packagePath.startsWith("workflows/");
+}
 function semverParts(version2) {
   const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version2);
   if (!match)
@@ -184876,14 +184894,15 @@ function packageStatus(opts) {
   const context = resolveGitSourceContext(opts);
   if (context.gitRoot)
     checkRepoVersion(context.gitRoot, false);
-  const validation = context.packageRoot ? validatePackage(context.packageRoot) : null;
+  const isRepoRootStatus = context.gitRoot && context.packageRoot && context.gitRoot === context.packageRoot;
+  const validation = context.packageRoot && !isRepoRootStatus ? validatePackage(context.packageRoot) : null;
   const gitStatus = context.gitRoot ? gitOutput(["status", "--short"], context.gitRoot) ?? "" : "";
   const payload = {
     gitRoot: context.gitRoot,
     packageRoot: context.packageRoot,
     packagePath: context.packagePath,
     clean: gitStatus.length === 0,
-    valid: validation?.valid ?? false,
+    valid: validation?.valid ?? null,
     errors: validation?.errors ?? []
   };
   if (opts.json)
@@ -185061,7 +185080,9 @@ async function release(versionOrBump, dir, opts) {
     throw err;
   }
   success2(`Released ${tag}.`);
-  await syncLatestAutomation(client, context.packagePath);
+  if (isAutomationPackagePath(context.packagePath)) {
+    await syncLatestAutomation(client, context.packagePath);
+  }
 }
 async function sync(target, opts) {
   const context = resolveGitSourceContext({ dir: opts.dir });
@@ -185072,6 +185093,9 @@ async function sync(target, opts) {
   if (!packagePath) {
     throw new Error("Pass an automation target or run sync inside a source package.");
   }
+  if (!isAutomationPackagePath(packagePath)) {
+    throw new Error("Sync only supports agent and workflow packages.");
+  }
   await syncLatestAutomation(new ApiClient(resolveConfig(opts)), packagePath);
 }
 async function install(packageRef, opts) {
@@ -188030,6 +188054,155 @@ function parseWorkflow(yaml) {
   }
   return result.data;
 }
+// ../workflow-yaml/src/validate-quality.ts
+init_src();
+var CATEGORICAL_NAMES = new Set([
+  "category",
+  "subcategory",
+  "kind",
+  "status",
+  "type",
+  "subtype",
+  "level",
+  "severity",
+  "priority",
+  "state",
+  "stage",
+  "tier",
+  "classification",
+  "monitoring",
+  "frequency",
+  "reference",
+  "sectionname",
+  "code",
+  "flag",
+  "signal",
+  "mode",
+  "phase"
+]);
+var SEPARATOR_LIST_RE = /(?:^|[\s(])((?:[A-Za-z0-9_-]{1,20})(?:\s*[|,/]\s*[A-Za-z0-9_-]{1,20}){1,7})(?:$|[\s).])/;
+function validateSchemaQuality(workflow2) {
+  const warnings = [];
+  for (let i5 = 0;i5 < workflow2.steps.length; i5++) {
+    const step = workflow2.steps[i5];
+    if (!step)
+      continue;
+    const basePath = `steps.${i5}`;
+    walkStep(step, basePath, warnings);
+  }
+  return warnings;
+}
+function walkStep(step, basePath, out) {
+  if (step.type === "ai.extract") {
+    const schema = step.with?.schema;
+    if (schema && typeof schema === "object") {
+      walkSchema(schema, `${basePath}.with.schema`, out);
+    }
+    return;
+  }
+  if (step.type === "transform.script") {
+    const cfg = step.with;
+    const source2 = typeof cfg?.function === "string" ? cfg.function : null;
+    if (!source2)
+      return;
+    const paramNames = cfg?.inputs && typeof cfg.inputs === "object" && !Array.isArray(cfg.inputs) ? Object.keys(cfg.inputs) : [];
+    const compiled = compileTypedScript({ kind: "transform", source: source2, paramNames });
+    if (!compiled.ok)
+      return;
+    for (const w10 of compiled.warnings) {
+      if (w10.code === "weak-return-type") {
+        out.push({
+          code: "weak-script-return",
+          field: `${basePath}.with.function`,
+          message: `transform.script return type is too loose: ${w10.message}`,
+          hint: 'Replace `unknown`/`any` with a concrete shape, or use a TS literal union (e.g. `"low" | "medium" | "high"`) when the value belongs to a closed set.'
+        });
+      }
+    }
+    const schema = compiled.result.returnSchema;
+    if (schema.type === "object" && (!schema.properties || Object.keys(schema.properties).length === 0) && schema.additionalProperties !== false) {
+      out.push({
+        code: "untyped-object",
+        field: `${basePath}.with.function`,
+        message: "transform.script returns an untyped object. Downstream steps cannot autocomplete its fields.",
+        hint: "Describe the actual shape in the return annotation: `function script(...): { name: string; total: number }`."
+      });
+    }
+    return;
+  }
+  const withAny = step.with;
+  const nestedSteps = withAny?.steps;
+  if (Array.isArray(nestedSteps)) {
+    for (let i5 = 0;i5 < nestedSteps.length; i5++) {
+      const s5 = nestedSteps[i5];
+      if (s5)
+        walkStep(s5, `${basePath}.with.steps.${i5}`, out);
+    }
+  }
+  const nestedBranches = withAny?.branches;
+  if (Array.isArray(nestedBranches)) {
+    for (let b8 = 0;b8 < nestedBranches.length; b8++) {
+      const branch = nestedBranches[b8];
+      if (branch && Array.isArray(branch.steps)) {
+        for (let i5 = 0;i5 < branch.steps.length; i5++) {
+          const s5 = branch.steps[i5];
+          if (s5)
+            walkStep(s5, `${basePath}.with.branches.${b8}.steps.${i5}`, out);
+        }
+      }
+    }
+  }
+}
+function walkSchema(schema, basePath, out) {
+  const type = schema.type;
+  if (type === "object" && (!schema.properties || Object.keys(schema.properties).length === 0) && schema.additionalProperties !== false) {
+    out.push({
+      code: "untyped-object",
+      field: basePath,
+      message: "Object schema has no properties. The LLM has no guidance on what fields to emit and downstream autocomplete is empty.",
+      hint: "Add concrete fields under `properties`, or set `additionalProperties: false` if the object is intentionally open."
+    });
+  }
+  if (type === "array" && (schema.items === undefined || isEmptyObject(schema.items))) {
+    out.push({
+      code: "untyped-array-items",
+      field: basePath,
+      message: "Array items are untyped. The LLM does not know what shape each element should take.",
+      hint: "Add an `items:` block describing the element type, e.g. `items: { type: object, properties: { ... } }`."
+    });
+  }
+  if (schema.properties && typeof schema.properties === "object") {
+    for (const [name, raw] of Object.entries(schema.properties)) {
+      if (!raw || typeof raw !== "object")
+        continue;
+      const prop = raw;
+      const propType = prop.type;
+      const propEnum = Array.isArray(prop.enum) && prop.enum.length > 0;
+      const lower = name.toLowerCase();
+      const description = typeof prop.description === "string" ? prop.description : "";
+      const looksCategoricalByName = CATEGORICAL_NAMES.has(lower);
+      const looksCategoricalByDescription = description.length > 0 && SEPARATOR_LIST_RE.test(description);
+      if (propType === "string" && !propEnum && (looksCategoricalByName || looksCategoricalByDescription) && !looksLikeFreeform(prop)) {
+        out.push({
+          code: "categorical-missing-enum",
+          field: `${basePath}.properties.${name}`,
+          message: `Field \`${name}\` looks categorical but has no \`enum\`. Coded values extract more reliably when the LLM is constrained to a closed set.`,
+          hint: "In the workflow builder, switch the field type to `Enum` and list the allowed values. In raw YAML, add `enum: ['value1', 'value2', ...]` to the field, and write the per-value meanings into the field's `description`."
+        });
+      }
+      walkSchema(prop, `${basePath}.properties.${name}`, out);
+    }
+  }
+  if (schema.items && typeof schema.items === "object" && !Array.isArray(schema.items)) {
+    walkSchema(schema.items, `${basePath}.items`, out);
+  }
+}
+function isEmptyObject(v11) {
+  return typeof v11 === "object" && v11 !== null && !Array.isArray(v11) && Object.keys(v11).length === 0;
+}
+function looksLikeFreeform(prop) {
+  return prop.pattern !== undefined || prop.format !== undefined;
+}
 // src/commands/validate.ts
 var import_yaml6 = __toESM(require_dist(), 1);
 import { existsSync as existsSync10, readdirSync as readdirSync7, readFileSync as readFileSync10, statSync as statSync6 } from "fs";
@@ -188048,24 +188221,46 @@ function isDirSafe(path15, issues, field) {
 }
 function validateWorkflowYaml(path15) {
   if (!existsSync10(path15)) {
-    return [{ field: path15, message: "File not found." }];
+    return { issues: [{ field: path15, message: "File not found." }], warnings: [] };
   }
   const text = readFileSync10(path15, "utf-8");
   try {
-    parseWorkflow(text);
-    return [];
+    const definition = parseWorkflow(text);
+    let warnings = [];
+    try {
+      warnings = validateSchemaQuality(definition);
+    } catch {
+      warnings = [];
+    }
+    return { issues: [], warnings };
   } catch (err2) {
     if (err2 instanceof YamlParseError) {
       const where = err2.line !== undefined ? ` (line ${err2.line})` : "";
-      return [{ field: "yaml", message: `${err2.message}${where}` }];
+      return { issues: [{ field: "yaml", message: `${err2.message}${where}` }], warnings: [] };
     }
     if (err2 instanceof WorkflowValidationError) {
-      return err2.errors.map((e8) => ({
-        field: e8.path.length > 0 ? e8.path.map(String).join(".") : "(root)",
-        message: e8.message
-      }));
+      return {
+        issues: err2.errors.map((e8) => ({
+          field: e8.path.length > 0 ? e8.path.map(String).join(".") : "(root)",
+          message: e8.message
+        })),
+        warnings: []
+      };
     }
-    return [{ field: "(root)", message: err2 instanceof Error ? err2.message : String(err2) }];
+    return {
+      issues: [{ field: "(root)", message: err2 instanceof Error ? err2.message : String(err2) }],
+      warnings: []
+    };
+  }
+}
+function printSchemaQualityWarnings(path15, warnings) {
+  if (warnings.length === 0)
+    return;
+  warn(`workflow.yaml ${ui.dim(`(${path15})`)}: ${warnings.length} schema-quality warning${warnings.length === 1 ? "" : "s"}`);
+  for (const w10 of warnings) {
+    warn(`  ${ui.dim(w10.field)} ${w10.message}`);
+    if (w10.hint)
+      warn(`    ${ui.dim("hint:")} ${w10.hint}`);
   }
 }
 function validateEvaluatorsYaml(path15) {
@@ -188248,9 +188443,23 @@ function rootDir(opts) {
   return resolve6(opts.dir ?? process.cwd());
 }
 function registerAllValidateCommand(parent) {
-  parent.command("validate").description("Local-only validation against the templated project layout: ./workflow.yaml + ./evaluators.yaml + ./dataset/. For targeted validation use `evaluators validate` or `dataset validate`.").option("--dir <path>", "Project root (defaults to cwd; resolves the three default paths from here)").action((opts) => {
+  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 just 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)").action((path15, opts) => {
+    if (path15) {
+      const target = resolve6(path15);
+      const wfResult2 = validateWorkflowYaml(target);
+      const wfOk2 = printIssues("workflow.yaml", target, wfResult2.issues);
+      if (wfOk2)
+        printSchemaQualityWarnings(target, wfResult2.warnings);
+      if (!wfOk2)
+        process.exit(1);
+      return;
+    }
     const root2 = rootDir(opts);
-    const wfOk = printIssues("workflow.yaml", relPath(root2, join12(root2, "workflow.yaml")), validateWorkflowYaml(join12(root2, "workflow.yaml")));
+    const wfResult = validateWorkflowYaml(join12(root2, "workflow.yaml"));
+    const wfPath = relPath(root2, join12(root2, "workflow.yaml"));
+    const wfOk = printIssues("workflow.yaml", wfPath, wfResult.issues);
+    if (wfOk)
+      printSchemaQualityWarnings(wfPath, wfResult.warnings);
     const evOk = printIssues("evaluators.yaml", relPath(root2, join12(root2, "evaluators.yaml")), validateEvaluatorsYaml(join12(root2, "evaluators.yaml")));
     const dsOk = printIssues("dataset/", relPath(root2, join12(root2, "dataset")), validateDatasetFolder(join12(root2, "dataset")));
     if (!wfOk || !evOk || !dsOk)
@@ -188903,6 +189112,7 @@ flag would otherwise shadow it. Validation failures come back as
         return;
       }
       success2(`Pushed ${ui.bold(workflowId)} (v${result.version ?? nextVersion})`);
+      printSchemaQualityWarnings2(result.warnings);
     } else {
       if (opts.bump) {
         throw new Error("--bump requires --workflow-id (need a current version to bump from). For a new workflow, use --set-version <X.Y.Z> or omit both.");
@@ -188920,6 +189130,7 @@ flag would otherwise shadow it. Validation failures come back as
       const id2 = result.workflow?.id ?? result.id ?? "?";
       const ver = result.version?.version ?? result.workflow?.currentVersion?.version ?? result.currentVersion?.version ?? "?";
       success2(`Created ${ui.bold(id2)} (v${ver})`);
+      printSchemaQualityWarnings2(result.warnings);
     }
   }));
   const moveCmd = parent.command("move <workflow-id>").description("Move a workflow to a folder path, creating folders as needed").requiredOption("--folder <path>", "Target folder path (`/` for root)");
@@ -188937,6 +189148,16 @@ flag would otherwise shadow it. Validation failures come back as
   }));
 }
 var SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
+function printSchemaQualityWarnings2(warnings) {
+  if (!warnings || warnings.length === 0)
+    return;
+  warn(`${warnings.length} schema-quality warning${warnings.length === 1 ? "" : "s"} (push succeeded; sharper types make downstream steps easier to wire):`);
+  for (const w10 of warnings) {
+    warn(`  ${ui.dim(w10.field)} ${w10.message}`);
+    if (w10.hint)
+      warn(`    ${ui.dim("hint:")} ${w10.hint}`);
+  }
+}
 function isBumpLevel(value) {
   return value === "patch" || value === "minor" || value === "major";
 }

package/dist/skill/reference/cli/workflow.md

@@ -20,7 +20,7 @@ Manage workflows: push, pull, run, evaluate.
   - [`eigenpal workflow pull [options] <workflow-id>`](#eigenpal-workflow-pull-options-workflow-id)
   - [`eigenpal workflow push [options]`](#eigenpal-workflow-push-options)
   - [`eigenpal workflow move [options] <workflow-id>`](#eigenpal-workflow-move-options-workflow-id)
-  - [`eigenpal workflow validate [options]`](#eigenpal-workflow-validate-options)
+  - [`eigenpal workflow validate [options] [path]`](#eigenpal-workflow-validate-options-path)
   - [`eigenpal workflow clear-local [options] [examples...]`](#eigenpal-workflow-clear-local-options-examples)
   - [`eigenpal workflow evaluators pull [options] <workflow-id>`](#eigenpal-workflow-evaluators-pull-options-workflow-id)
   - [`eigenpal workflow evaluators push [options] <workflow-id>`](#eigenpal-workflow-evaluators-push-options-workflow-id)
@@ -100,7 +100,7 @@ workflow
 ├── evaluator-type
 │   ├── list|ls
 │   └── get <type>
-├── validate
+├── validate [path]
 ├── clear-local [examples...]
 └── step
     └── exec <type>
@@ -110,14 +110,14 @@ workflow
 
 ### Core
 
-| Command                                                 | Description                                                                                                                                                                            |
-| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
-| `eigenpal workflow list                                 | ls [options]`                                                                                                                                                                          | List workflows the caller can read. |
-| `eigenpal workflow pull [options] <workflow-id>`        | Download the YAML definition of the workflow at its current version.                                                                                                                   |
-| `eigenpal workflow push [options]`                      | Create or update a workflow from a YAML file.                                                                                                                                          |
-| `eigenpal workflow move [options] <workflow-id>`        | Move a workflow to a folder path, creating folders as needed                                                                                                                           |
-| `eigenpal workflow validate [options]`                  | Local-only validation against the templated project layout: ./workflow.yaml + ./evaluators.yaml + ./dataset/. For targeted validation use `evaluators validate` or `dataset validate`. |
-| `eigenpal workflow clear-local [options] [examples...]` | Delete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default.                                                                               |
+| Command                                                 | Description                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `eigenpal workflow list                                 | ls [options]`                                                                                                                                                                                                                                                                 | List workflows the caller can read. |
+| `eigenpal workflow pull [options] <workflow-id>`        | Download the YAML definition of the workflow at its current version.                                                                                                                                                                                                          |
+| `eigenpal workflow push [options]`                      | Create or update a workflow from a YAML file.                                                                                                                                                                                                                                 |
+| `eigenpal workflow move [options] <workflow-id>`        | Move a workflow to a folder path, creating folders as needed                                                                                                                                                                                                                  |
+| `eigenpal workflow validate [options] [path]`           | Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/). With [path] pointing at a YAML file: validates just that workflow.yaml. For per-noun targeting use `evaluators validate` or `dataset validate`. |
+| `eigenpal workflow clear-local [options] [examples...]` | Delete local execution artifacts under ./dataset/examples/. Keeps the latest run per example by default.                                                                                                                                                                      |
 
 ### Evaluators
 
@@ -256,9 +256,15 @@ Move a workflow to a folder path, creating folders as needed
 | `--base-url <url>` | no       |         | Server base URL                        |
 | `--json`           | no       |         | Output the raw server response as JSON |
 
-### `eigenpal workflow validate [options]`
+### `eigenpal workflow validate [options] [path]`
 
-Local-only validation against the templated project layout: ./workflow.yaml + ./evaluators.yaml + ./dataset/. For targeted validation use `evaluators validate` or `dataset validate`.
+Local-only validation. Without [path]: runs the templated three-way check (./workflow.yaml + ./evaluators.yaml + ./dataset/). With [path] pointing at a YAML file: validates just that workflow.yaml. For per-noun targeting use `evaluators validate` or `dataset validate`.
+
+### Arguments
+
+| Name   | Required | Variadic | Description |
+| ------ | -------- | -------- | ----------- |
+| `path` | no       | no       |             |
 
 ### Options
 

package/dist/skill/reference/workflow-yaml.md

@@ -191,6 +191,76 @@ The script runs in a WASM sandbox: 5s wall clock, 10 MB heap, no network,
 no filesystem. Trips show up as `script_timeout` / `script_memory_limit`
 on the step execution.
 
+## Be specific with types
+
+Every output schema you write is read three times: by the LLM (for
+`ai.extract`), by downstream steps (autocomplete + template resolution),
+and by the runtime validator. **The more specific the type, the better
+the workflow runs.**
+
+### Use `enum` for coded values
+
+Categorical fields like `category`, `status`, `kind`, `severity`,
+`monitoring`, `frequency` should be enums whenever the value set is
+closed. The LLM is constrained to emit only allowed values, and
+downstream `transform.script` steps know exactly what they'll see.
+
+```yaml
+- name: classify
+  type: ai.extract
+  with:
+    input: '{{ input.text }}'
+    schema:
+      type: object
+      properties:
+        category:
+          type: string
+          enum: ['901', '902']
+          description: |
+            Covenant category.
+            901 = Odkladacie podmienky (conditions precedent).
+            902 = Následné podmienky (subsequent / ongoing covenants).
+      required: [category]
+```
+
+Per-value meanings go inline in the field's `description`. The LLM picks
+them up reliably from there, and the scope browser renders the allowed
+values when downstream steps reference the field.
+
+### `transform.script` — TS literal unions become JSON Schema enums
+
+A TS literal-union return type compiles to a JSON-Schema enum
+automatically. Use it when the function returns a value from a closed set:
+
+```yaml
+- name: severity
+  type: transform.script
+  with:
+    inputs:
+      score: '{{ steps.score.output.value }}'
+    function: |
+      function script(score: number): { level: 'low' | 'medium' | 'high' } {
+        return { level: score > 0.8 ? 'high' : score > 0.4 ? 'medium' : 'low' };
+      }
+```
+
+Downstream steps autocomplete `low | medium | high` for `level`.
+
+### `eigenpal workflow push` warns on weak types
+
+Push surfaces non-fatal **schema-quality warnings** when it sees patterns
+that hurt downstream typing. Common ones:
+
+| Warning code                 | What it means                                                                                |
+| ---------------------------- | -------------------------------------------------------------------------------------------- |
+| `categorical-missing-enum`   | A field named like `category` / `status` / `kind` is a plain `string`. Consider declaring an `enum`. |
+| `weak-script-return`         | A `transform.script` returns `any` or `unknown`. Replace with a concrete shape or a literal union. |
+| `untyped-object`             | A `type: object` field has no `properties`. The LLM has no guidance on what to emit.         |
+| `untyped-array-items`        | A `type: array` field has no `items:` declared.                                              |
+
+Warnings do not block the push. They print to stderr as `! …` lines. Run
+`eigenpal workflow validate` locally to surface them before pushing.
+
 ## Common patterns
 
 ### Conditional branches

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigenpal/cli",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   "keywords": [
     "eigenpal",
@@ -40,6 +40,8 @@
   "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",
     "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",