@eigenpal/cli 0.5.8 → 0.5.9

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @eigenpal/cli
 
-## 1.0.0
+## 0.5.9
 
 ### Major Changes
 
@@ -333,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:

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.8",
+  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",
@@ -188043,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";
@@ -188061,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) {
@@ -188261,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)
@@ -188916,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.");
@@ -188933,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)");
@@ -188950,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.8",
+  "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",