@eigenpal/cli 0.13.2 → 0.14.0

package/dist/skill/SKILL.md

@@ -14,6 +14,48 @@ metadata:
 Use long command names in generated commands and documentation. Short aliases may
 appear in user examples, but do not prefer them.
 
+## Non-interactive / agent terminals (read first)
+
+**Never run a CLI command that opens a confirmation or picker without checking
+`--help` first.** Agent terminals, CI, and piped shells are usually non-TTY — an
+interactive prompt will hang indefinitely.
+
+Rules:
+
+- **`--yes`** — skip confirmations and pickers when a deterministic default exists,
+  or acknowledge a destructive action in scripts. Required for most cancel/delete/replace
+  flows in non-TTY.
+- **`--force`** — only where documented: overwrite user-edited skill files on reinstall
+  (`skill install --force`). Do not use as a generic “yes to everything”.
+- **Provide explicit inputs** instead of prompts: `--file`, `--template`, `--tools`,
+  `--stdin` / `--value-file`, `--base-url`, profile name for `auth use <name>`,
+  `EIGENPAL_API_KEY` instead of `auth login` in CI.
+
+Commands that can prompt or block (always inspect `--help` for the exact flag):
+
+| Area | Command | Non-interactive bypass |
+| --- | --- | --- |
+| Init | `init [name]` | `--template <name>` and/or `--yes` (default template: blank) |
+| Auth | `auth login` | Do not run non-interactively; set `EIGENPAL_API_KEY` and optionally `EIGENPAL_BASE_URL` |
+| Auth | `auth use` | positional profile name |
+| Skill | `skill install` | `--tools claude,cursor` and/or `--yes`; `--force` to overwrite edits |
+| Skill | `skill uninstall` | tool ids, `--all`, or `--target` + `--yes` |
+| Workflow | `workflow push` | `--file workflow.yaml` (TTY-only path picker otherwise) |
+| Workflow | `workflow dataset push --mode replace` | `--yes` |
+| Workflow | `workflow dataset example delete` | `--yes` |
+| Workflow | `workflow experiment cancel` | `--yes` |
+| Workflow | `workflow templates delete` | `--yes` |
+| Agents | `agents dataset push --mode replace` | `--yes` |
+| Agents | `agents experiment cancel` | `--yes` |
+| Agents | `agents session stop` | `--yes` |
+| Agents | `agents secrets set` | `--stdin` or `--value-file` |
+| Runs | `runs cancel` | `--yes` |
+| Runs | `runs reviews clear` | `--yes` |
+| Runs | `runs expected delete` | `--yes` |
+
+If a command fails with “requires --yes when run non-interactively”, re-run with
+`--yes` only when the action is intentional — never to blindly retry.
+
 ## Choose A Command
 
 - `eigenpal workflow` manages YAML workflow definitions, datasets, evaluators,
@@ -30,15 +72,28 @@ appear in user examples, but do not prefer them.
 - `eigenpal runs` inspects, watches, compares, reruns, cancels, and downloads
   artifacts for workflow or agent runs.
 
+## Authenticate And Select A Workspace
+
+```bash
+eigenpal auth login
+eigenpal status --json
+eigenpal auth list
+eigenpal auth use <profile>
+```
+
+For CI, set `EIGENPAL_API_KEY` and optionally `EIGENPAL_BASE_URL` instead of
+running the interactive login.
+
 Use stable ids in scripts:
 
 - Workflow id: `wf_...`
 - Template id: `tmpl_...`
 - Template revision id: `tmpr_...`
-- Workflow execution id: `evx_...`
+- Workflow execution id: `exec_...`
 - Agent execution id: `aex_...`
 - Experiment batch id: `evb_...`
-- Dataset example id: `ex_...`
+- Workflow dataset example id: `evx_...`
+- Agent dataset example id: `aeg_...`
 
 ## Workflow Loop
 
@@ -48,9 +103,11 @@ eigenpal init workflow invoices --template pdf-extraction
 cd invoices
 $EDITOR workflow.yaml
 
-# Inspect step schemas before editing config.
+# Inspect step and evaluator schemas before editing config.
 eigenpal workflow step-type list --search extract
-eigenpal workflow step-type get ai.extract --json | jq '.configSchema.properties'
+eigenpal workflow step-type get ai.extract | jq '.configSchema.properties'
+eigenpal workflow evaluator-type list
+eigenpal workflow evaluator-type get exact-diff | jq '.configSchema'
 
 # Validate and push.
 eigenpal workflow validate ./workflow.yaml
@@ -61,7 +118,10 @@ eigenpal workflow validate ./workflow.yaml
 # workflow project unless you pass --allow-external-templates.
 eigenpal workflow validate ./workflow.yaml --online
 eigenpal models list --json
-eigenpal workflow push --file workflow.yaml
+# First push creates a new wf_…; capture the id from --json output.
+eigenpal workflow push --file workflow.yaml --json | jq '.id'
+# Later pushes must pass --workflow-id to update in place (omit it only on first create).
+eigenpal workflow push --file workflow.yaml --workflow-id wf_…
 
 # Run with ad-hoc input and read the output (use this for API-triggered workflows).
 # `--wait --json` polls to completion and prints the run with top-level `output`.
@@ -125,6 +185,8 @@ Key rules:
 # Clone source and create a branch.
 eigenpal agents clone --out ./source
 cd ./source
+# Use `agents save` to validate, commit, and push source. For other Git ops, use
+# `eigenpal git -- <git-args>` (not bare `git` — the passthrough wires credentials).
 eigenpal git -- switch -c <short-task-branch>
 
 # Inspect source state.
@@ -175,15 +237,34 @@ DOCX/XLSX templates for **runtime agents** live in Git source, not in the
 workspace Templates table. YAML workflows use workspace templates via
 `transform.template` and `tmpl_...` instead — see `reference/step-types.md`.
 
-Workspace DOCX/XLSX templates for YAML workflows:
+Workspace DOCX/XLSX templates for YAML workflows (`tmpl_…` / `tmpr_…`):
 
 ```bash
+# Upload a new template (returns tmpl_… + tmpr_… with --json).
 eigenpal workflow templates upload ./templates/roster.xlsx --json
+
+# List and inspect server templates.
+eigenpal workflow templates list --json
+eigenpal workflow templates get tmpl_…
+eigenpal workflow templates get tmpl_… --json | jq '.currentRevision.id'
+
+# Download current bytes (--out required).
+eigenpal workflow templates download tmpl_… --out ./templates/roster.xlsx
+
+# Replace with a new local file (creates a new tmpr_… revision).
+eigenpal workflow templates replace tmpl_… ./templates/roster-v2.xlsx --json
+
+# Delete the tmpl_… pointer (--yes required outside a TTY).
+eigenpal workflow templates delete tmpl_… --yes
+
+# Smoke-fill locally (no server) or from a tmpl_… id (downloads bytes, fills locally).
 eigenpal workflow templates smoke ./templates/roster.xlsx --data ./fixture.json --out ./filled.xlsx
+eigenpal workflow templates smoke tmpl_… --data ./fixture.json --out ./filled.xlsx
+
 # YAML may keep a source path; push uploads and sends tmpl_ + tmpr_ ids.
 # template: ./templates/roster.xlsx
 eigenpal workflow validate ./workflow.yaml --online
-eigenpal workflow push --file workflow.yaml
+eigenpal workflow push --file workflow.yaml --workflow-id wf_…
 ```
 
 **Local template** (one agent):
@@ -269,10 +350,10 @@ Agent examples are runtime data, not Git source. `agents save` does not persist
 them.
 
 ```bash
-eigenpal agents dataset validate /workspace/evals --agent-dir agents/<slug>
-eigenpal agents dataset push agents.<slug> --file /workspace/evals
+eigenpal agents dataset validate ./dataset --agent-dir agents/<slug>
+eigenpal agents dataset push agents.<slug> --file ./dataset
 eigenpal agents dataset list agents.<slug>
-eigenpal agents dataset pull agents.<slug> --out ./dataset
+eigenpal agents dataset pull agents.<slug> --out ./dataset.zip
 ```
 
 Expected outputs should include stable fields only. Omit timestamps, random IDs,
@@ -301,16 +382,18 @@ Use `--version original` only to reproduce the previous resolved version.
 ```bash
 eigenpal runs reviews update <agent-execution-id> \
   --status open \
-  --verdict needs_changes \
+  --verdict incorrect \
   --note "Expected the filing date to be extracted."
 eigenpal runs reviews close <agent-execution-id> \
   --note "Fixed and verified."
 eigenpal runs reviews clear <agent-execution-id> --yes
 
-eigenpal runs reviews expected list <agent-execution-id>
-eigenpal runs reviews expected upload <agent-execution-id> expected.json --name expected.json
-eigenpal runs reviews expected copy-output <agent-execution-id> result.json --name expected.json
-eigenpal runs reviews expected pull <agent-execution-id> --out expected/
+eigenpal runs expected list <agent-execution-id>
+eigenpal runs expected upload <agent-execution-id> expected.json --name expected.json
+eigenpal runs expected copy-output <agent-execution-id> result.json --name expected.json
+eigenpal runs expected pull <agent-execution-id> --out expected/
+eigenpal runs expected rename <agent-execution-id> old.json new.json
+eigenpal runs expected delete <agent-execution-id> old.json --yes
 ```
 
 ## Output
@@ -336,12 +419,25 @@ Status messages go to stderr. Pipeable data goes to stdout.
 
 Use generated references for exact flags and defaults:
 
+CLI command references:
+
 - [`reference/cli/workflow.md`](reference/cli/workflow.md)
 - [`reference/cli/agents.md`](reference/cli/agents.md)
 - [`reference/cli/runs.md`](reference/cli/runs.md)
+- [`reference/cli/run.md`](reference/cli/run.md)
+- [`reference/cli/rerun.md`](reference/cli/rerun.md)
 - [`reference/cli/auth.md`](reference/cli/auth.md)
+- [`reference/cli/init.md`](reference/cli/init.md)
+- [`reference/cli/models.md`](reference/cli/models.md)
+- [`reference/cli/skill.md`](reference/cli/skill.md)
+- [`reference/cli/status.md`](reference/cli/status.md)
+- [`reference/cli/surface.md`](reference/cli/surface.md)
+
+Workflow and eval references:
+
 - [`reference/workflow-yaml.md`](reference/workflow-yaml.md)
 - [`reference/step-types.md`](reference/step-types.md)
+- [`reference/step-exec.md`](reference/step-exec.md)
 - [`reference/dataset-format.md`](reference/dataset-format.md)
 - [`reference/evaluators.md`](reference/evaluators.md)
 - [`reference/debugging.md`](reference/debugging.md)

package/dist/skill/examples/hello-world/evaluators.yaml

@@ -1,5 +1,7 @@
+passThreshold: 1.0
 evaluators:
   - name: exact-match
     type: exact-diff
     config:
-      passThreshold: 1.0
+      rules:
+        $: {}

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

@@ -519,12 +519,12 @@ Encrypt and set a secret value in secrets.enc.yaml.
 
 ### Options
 
-| Flag                   | Required | Default | Description                       |
-| ---------------------- | -------- | ------- | --------------------------------- |
-| `--dir <dir>`          | no       |         | Directory to inspect              |
-| `--stdin`              | no       |         | Read the secret value from stdin  |
-| `--value-file <path>`  | no       |         | Read the secret value from a file |
-| `--description <text>` | no       |         | Secret description                |
+| Flag                   | Required | Default | Description                                                         |
+| ---------------------- | -------- | ------- | ------------------------------------------------------------------- |
+| `--dir <dir>`          | no       |         | Directory to inspect                                                |
+| `--stdin`              | no       |         | Read the secret value from stdin (required in CI / agent terminals) |
+| `--value-file <path>`  | no       |         | Read the secret value from a file                                   |
+| `--description <text>` | no       |         | Secret description                                                  |
 
 ### `eigenpal agents secrets|secret unset [options] <name>`
 
@@ -607,13 +607,13 @@ Upload dataset examples from a local dataset directory or zip archive.
 
 ### Options
 
-| Flag                       | Required | Default    | Description                                          |
-| -------------------------- | -------- | ---------- | ---------------------------------------------------- |
-| `--base-url <url>`         | no       |            | Server base URL                                      |
-| `--json`                   | no       |            | Output the raw server response as JSON               |
-| `--file <path>`            | yes      |            | Dataset directory or .zip archive                    |
-| `--mode <append\|replace>` | no       | `"append"` | Upload mode                                          |
-| `--yes`                    | no       |            | Confirm replace mode in non-interactive environments |
+| Flag                       | Required | Default    | Description                                                                        |
+| -------------------------- | -------- | ---------- | ---------------------------------------------------------------------------------- |
+| `--base-url <url>`         | no       |            | Server base URL                                                                    |
+| `--json`                   | no       |            | Output the raw server response as JSON                                             |
+| `--file <path>`            | yes      |            | Dataset directory or .zip archive                                                  |
+| `--mode <append\|replace>` | no       | `"append"` | Upload mode                                                                        |
+| `--yes`                    | no       |            | Skip typed-slug confirmation for --mode replace (required in CI / agent terminals) |
 
 ### `eigenpal agents dataset pull [options] <agent-id-or-slug>`
 
@@ -763,11 +763,11 @@ Cancel every active execution in an experiment.
 
 ### Options
 
-| Flag               | Required | Default | Description                              |
-| ------------------ | -------- | ------- | ---------------------------------------- |
-| `--base-url <url>` | no       |         | Server base URL                          |
-| `--json`           | no       |         | Output the raw server response as JSON   |
-| `--yes`            | no       |         | Required in non-interactive environments |
+| Flag               | Required | Default | Description                                                        |
+| ------------------ | -------- | ------- | ------------------------------------------------------------------ |
+| `--base-url <url>` | no       |         | Server base URL                                                    |
+| `--json`           | no       |         | Output the raw server response as JSON                             |
+| `--yes`            | no       |         | Skip confirmation (required in CI / agent terminals without a TTY) |
 
 ### `eigenpal agents session list|ls [options] <agent-id-or-slug>`
 
@@ -854,11 +854,11 @@ Stop a builder session.
 
 ### Options
 
-| Flag               | Required | Default | Description                              |
-| ------------------ | -------- | ------- | ---------------------------------------- |
-| `--base-url <url>` | no       |         | Server base URL                          |
-| `--json`           | no       |         | Output the raw server response as JSON   |
-| `--yes`            | no       |         | Required in non-interactive environments |
+| Flag               | Required | Default | Description                                                        |
+| ------------------ | -------- | ------- | ------------------------------------------------------------------ |
+| `--base-url <url>` | no       |         | Server base URL                                                    |
+| `--json`           | no       |         | Output the raw server response as JSON                             |
+| `--yes`            | no       |         | Skip confirmation (required in CI / agent terminals without a TTY) |
 
 ### `eigenpal agents env pull [options] [target]`
 

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

@@ -270,11 +270,11 @@ Cancel a run.
 
 ### Options
 
-| Flag               | Required | Default | Description                              |
-| ------------------ | -------- | ------- | ---------------------------------------- |
-| `--base-url <url>` | no       |         | Server base URL                          |
-| `--json`           | no       |         | Output the raw server response as JSON   |
-| `--yes`            | no       |         | Required in non-interactive environments |
+| Flag               | Required | Default | Description                                                        |
+| ------------------ | -------- | ------- | ------------------------------------------------------------------ |
+| `--base-url <url>` | no       |         | Server base URL                                                    |
+| `--json`           | no       |         | Output the raw server response as JSON                             |
+| `--yes`            | no       |         | Skip confirmation (required in CI / agent terminals without a TTY) |
 
 ### `eigenpal runs artifacts|artifact list|ls [options] <run-id>`
 
@@ -393,11 +393,11 @@ Delete review metadata, corrected JSON, and corrected files for a run.
 
 ### Options
 
-| Flag               | Required | Default | Description                              |
-| ------------------ | -------- | ------- | ---------------------------------------- |
-| `--base-url <url>` | no       |         | Server base URL                          |
-| `--json`           | no       |         | Output the raw server response as JSON   |
-| `--yes`            | no       |         | Required in non-interactive environments |
+| Flag               | Required | Default | Description                                                                   |
+| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |
+| `--base-url <url>` | no       |         | Server base URL                                                               |
+| `--json`           | no       |         | Output the raw server response as JSON                                        |
+| `--yes`            | no       |         | Skip typed-slug confirmation (required in CI / agent terminals without a TTY) |
 
 ### `eigenpal runs expected list|ls [options] <run-id>`
 
@@ -503,8 +503,8 @@ Delete an expected artifact.
 
 ### Options
 
-| Flag               | Required | Default | Description                              |
-| ------------------ | -------- | ------- | ---------------------------------------- |
-| `--base-url <url>` | no       |         | Server base URL                          |
-| `--json`           | no       |         | Output the raw server response as JSON   |
-| `--yes`            | no       |         | Required in non-interactive environments |
+| Flag               | Required | Default | Description                                                                   |
+| ------------------ | -------- | ------- | ----------------------------------------------------------------------------- |
+| `--base-url <url>` | no       |         | Server base URL                                                               |
+| `--json`           | no       |         | Output the raw server response as JSON                                        |
+| `--yes`            | no       |         | Skip typed-slug confirmation (required in CI / agent terminals without a TTY) |

package/dist/skill/reference/debugging.md

@@ -16,9 +16,10 @@ eigenpal run workflows.<workflow-id> --example <example-name>
 
 `<workflow-id>` is either a `wf_…` id or a slug (the YAML's `name:`
 field). The workflow must be pushed (`eigenpal workflow push`) before
-`eigenpal run` works — only saved workflows execute. Streams a live
-step list as the run progresses. Bails to the prompt the moment a step
-transitions to `failed`.
+`eigenpal run` works — only saved workflows execute. Without `--wait`,
+the command enqueues the run and exits after printing the run id — it
+does not stream step progress. Add `--wait` to poll until a terminal
+status, or use `runs watch <exec-id>` for a live step-by-step view.
 
 If the workflow is server-stable and the failure is on a real
 historical execution, skip the rerun and pull the recorded execution

package/dist/skill/reference/evaluators.md

@@ -56,19 +56,75 @@ finance) who never see the YAML or the judge prompt. Write it for them:
 
 ### `exact-diff` — JSON deep-diff against `expected.json`
 
+Author comparison with a per-field `rules` map. Each key is a path into the
+workflow output (the `.data` object). Use `$` to target the full output.
+An ancestor rule covers its whole subtree; more specific descendants override
+inherited settings. `{}` selects a path with inherited platform defaults.
+
 ```yaml
 - name: invoice-fields
   type: exact-diff
   config:
-    passThreshold: 1.0 # 1.0 = byte-equal; lower = allow some slack
-    paths: [invoiceNumber, totalAmount] # OPTIONAL — restrict to specific dotted paths
+    rules:
+      invoiceNumber: {}
+      total:
+        numericTolerance: 0.01
+      lineItems:
+        order: unordered
+        items: exactly
+        matchBy: sku
+      lineItems[]:
+        allowExtraFields: false
+      lineItems[].unitPrice:
+        numericTolerance: 0.01
 ```
 
-- `passThreshold` — number in `[0, 1]`. The diff produces a similarity
-  score; `score >= passThreshold` ⇒ `passed: true`.
-- `paths` — array of dotted paths into the actual / expected outputs.
-  When set, only those paths are diffed. When absent, the whole object
-  is compared.
+- `rules` — map of path → comparison settings. Only listed paths (and their
+  descendants, unless a descendant adds its own rule) are scored. Omit a path
+  to ignore it, or set `$: {}` to compare the entire output with defaults.
+- `numericTolerance` — maximum absolute difference between expected and actual
+  numeric values at this path. Use `0` for exact integers; `0.01` is typical
+  for currency. When omitted, numeric comparison keeps the historical relative
+  epsilon.
+- `order: unordered` — on an array path, match items by value instead of
+  position. Matches always use distinct item slots; whether missing expected
+  items fail is controlled independently by `items`.
+- `matchBy` — optional identity 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 field (`sku`) or unique
+  fields (`[country, sku]`) inside each item. Expected and actual objects are
+  paired by exact identity first, then the paired objects are compared with
+  inherited nested rules, so a matching SKU with the wrong amount reports
+  `lineItems[i].amount` instead of "no matching item". Applies only at the
+  array path where it is set and is not inherited. Identity type and value
+  must both match: numeric `10` differs from string `'10'`; no coercion or
+  numeric tolerance. With `items: at-least`, extra actual items may omit or
+  duplicate identities; with `at-most`, missing expected identities are
+  allowed but every actual item being checked needs a unique valid identity;
+  `exactly` validates both sides. Omit `matchBy` to keep structural matching,
+  which still allows legitimate duplicate objects.
+- `items: at-least` — require every expected item while allowing additional
+  actual items (the default). Use `at-most` to permit a subset of expected
+  items but reject unexpected actual items, or `exactly` to permit neither.
+- `order` is independent. Ordered arrays use positional prefix matching:
+  `at-least` requires expected to match actual from index 0 (trailing actual
+  extras only); `at-most` requires actual to match expected from index 0
+  (trailing expected extras only); `exactly` is equal-length positional.
+  `unordered` ignores positions. Set `order`, `items`, and `matchBy` on
+  `lineItems`, not `lineItems[]`.
+- `allowExtraFields: false` — on an object path (often `someArray[]`), reject
+  object keys present in actual but absent from expected.
+
+Path syntax: `lineItems` targets the array; `lineItems[]` targets each element;
+`lineItems[].unitPrice` targets a field inside every element. Nested unordered
+lists use paths such as `groups[].members` with `order: unordered` on that path.
+
+Extract steps may attach `_grounding` metadata under output fields. Exact-diff
+strips that metadata before comparison, so you do not need a rule to exclude it.
+
+Configs authored before per-field rules used other top-level `exact-diff`
+options. Those configs keep working unchanged. Do not mix legacy options with
+`rules` in the same evaluator; validation rejects mixed configs.
 
 `exact-diff` branches on the example's expected shape: success-expected
 examples (`expected.json`) are diffed against the workflow's actual output, and
@@ -120,15 +176,16 @@ one of the keys in `labels`; the harness then looks up the score.
   config:
     passThreshold: 1.0
     function: |
-      type WorkflowOutput = {
+      type WorkflowData = {
         totalAmount: number;
       };
+      type WorkflowOutput = { data: WorkflowData };
       type Expected = WorkflowOutput;
       type Actual = WorkflowOutput;
 
       function scoreScript(expected: WorkflowOutput, actual: WorkflowOutput): number {
-        const a = actual.totalAmount ?? 0;
-        const e = expected.totalAmount ?? 0;
+        const a = actual.data.totalAmount ?? 0;
+        const e = expected.data.totalAmount ?? 0;
         return Math.abs(a - e) <= 0.01 ? 1 : 0;
       }
 ```
@@ -142,6 +199,9 @@ enforced at parse time. The dashboard seeds new evaluators with a
 declaration, plus `Expected` / `Actual` aliases for compatibility. Plain
 `unknown` works too if you do not want a typed signature.
 
+Both arguments are envelopes. Read workflow fields from `expected.data` and
+`actual.data`; the actual envelope may also include `files`.
+
 The signature shape is **locked**:
 
 - Function name MUST be `scoreScript`.
@@ -263,10 +323,22 @@ _Generated from `EvalConfigYamlSchema` in `@eigenpal/types/src/eval/evaluator-co
 
 | Field | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
-| `numericTolerance` | number | no | `0.000001` | Maximum absolute difference between numeric values that still counts as equal. Use 1e-6 for floats, 0 for exact integer match. |
-| `allowExtraFields` | boolean | no | `true` | When on, extra fields in the actual output do not fail the diff. Off = actual must match expected exactly. |
+| `rules` | record<string, object> | no |  | 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`. |
+| `numericTolerance` | number | no |  | Legacy global numeric tolerance (absolute). When omitted, comparison uses historical relative epsilon. Prefer `rules.<path>.numericTolerance`. Accepted only when `rules` is omitted. |
+| `allowExtraFields` | boolean | no |  | 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` | number | no |  | Legacy per-evaluator pass threshold. Pass/fail now uses the single workflow-level pass threshold; this is read only to preserve the run gate of configs authored before the single-threshold model. |
-| `paths` | array<string> | no |  | Dot-paths to scope the diff to a subset of the expected tree. Empty = diff entire expected. Syntax: `header.id`, `lineItems[].total`, `lineItems[0].sku`. Use this when expected has noisy sections you do not want to score. |
+| `paths` | array<string> | no |  | Legacy scoped paths. Prefer selecting those paths as `rules` keys. Syntax: `header.id`, `lineItems[].total`, `lineItems[0].sku`. |
+| `unorderedPaths` | array<string> | no |  | Legacy unordered array paths. Prefer `rules.<path>.order: unordered`. Name the array field itself (`subjects`, not `subjects[]`). |
+
+#### Per-path `rules` fields
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `order` | `"ordered"` \| `"unordered"` | no |  | 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 1000 items, 1000000 candidate pairs, and 2000000 recursive operations per comparison. |
+| `items` | `"at-least"` \| `"at-most"` \| `"exactly"` | no |  | 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` | string \| array<string> | no |  | 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` | boolean | no |  | When false, extra actual keys at this object fail the diff. When omitted, extra keys are allowed. Applies only to objects. |
+| `numericTolerance` | number | no |  | Maximum absolute difference for numeric leaves at or under this path. Omitted = inherit, then historical relative epsilon. Explicit `0` is exact. |
 
 
 ### `llm-judge` — LLM-as-judge scoring
@@ -285,7 +357,7 @@ _Generated from `EvalConfigYamlSchema` in `@eigenpal/types/src/eval/evaluator-co
 
 | Field | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
-| `function` | string | yes |  | Full TypeScript source for optional `type` aliases plus `function scoreScript(expected, actual): number { ... }`. Receives `expected` (the example's expected output) and `actual` (the workflow's actual output), returns a number in [0, 1] (the `: number` annotation is required). The `: number` return-type annotation is required and enforced at parse time. Throws are caught and scored as 0. |
+| `function` | string | yes |  | Full TypeScript source for optional `type` aliases plus `function scoreScript(expected, actual): number { ... }`. Receives `expected` (the example's expected-output envelope (`{ data: ... }`)) and `actual` (the workflow result envelope (`{ data: ..., files?: ... }`)), returns a number in [0, 1] (the `: number` annotation is required). The `: number` return-type annotation is required and enforced at parse time. Throws are caught and scored as 0. |
 | `timeoutMs` | integer | no | `5000` | Maximum wall-clock time the script can run before it is killed and the run is marked failed. |
 | `memoryLimitMb` | integer | no | `10` | Maximum memory the sandbox may allocate. Increase if the script processes large arrays or strings. |
 | `passThreshold` | number | no |  | Legacy per-evaluator pass threshold. Pass/fail now uses the single workflow-level pass threshold; this is read only to preserve the run gate of configs authored before the single-threshold model. |

package/dist/skill/reference/step-types.md

@@ -431,7 +431,7 @@ Extract text from documents (PDF, DOCX, images) using native extraction, OCR, or
 | `imageQuality` | integer | no | `85` | JPEG quality for rendered PDF page images sent to VLM parsing. Higher values reduce compression artifacts at larger payload sizes. |
 | `prompt` | string | no |  | Custom extraction prompt |
 | `languages` | array<string> | no |  | OCR language hints |
-| `outputFormat` | `"plain"` \| `"markdown"` \| `"djot"` \| `"html"` | no | `"markdown"` | Format for extracted text. `markdown` (default) keeps structure and is best for LLM extraction; `plain` is unstyled text; `djot`/`html` preserve more layout. Only the native (Kreuzberg) parser respects this — OCR/VLM always emit markdown. |
+| `outputFormat` | `"plain"` \| `"markdown"` \| `"djot"` \| `"html"` \| `"layout"` | no | `"markdown"` | Format for extracted text. `markdown` (default) keeps structure; `plain` is unstyled text; `djot`/`html` preserve more markup. `layout` is native-PDF spatial text with column gaps preserved as spaces. It requires `parseMode: native` or `parseMode: native-or-ocr` and a PDF — omitted parseMode and `nativeText: true` are not enough. Native mode is layout-only and fail-closed. `native-or-ocr` keeps layout text on accepted native pages and uses OCR markdown on suspect or empty pages, so the document can mix fixed-width layout and markdown. Extractor failure never falls back to another parser. Office, plaintext, and images fail. OCR/vision cannot request `layout`. |
 | `nativeText` | boolean | no | `false` | Extract native/embedded text from PDFs without OCR/VLM. Faster and uses no credits. Falls back to OCR/VLM if the PDF has no embedded text. |
 | `describeFigures` | boolean | no |  | Opt-in (default off). After text extraction, detect which pages contain figures with an in-worker layout model, then caption those pages with a vision model and append `<figure>description</figure>` to their text — so image-only pages (property photos, signatures, charts) become findable by text-based steps like ai.split. Note: the layout scan runs over all pages, and the caption step and its vision calls are billed. Skipped for plaintext. |
 | `figureInstructions` | string | no |  | Custom instruction for the figure-description pass, e.g. "Describe each figure; label a handwritten signature as `<figure>signature</figure>` and a stamp as `<figure>stamp</figure>`; for property photos note the room or exterior shown." Applied only when describeFigures runs. |
@@ -740,9 +740,9 @@ Embed OCR text layer into scanned PDFs/images to make them searchable
 | `wordCount` | number | yes |  | Number of words embedded |
 | `text` | string | yes |  | Extracted text from the document |
 
-#### `transform.xlsx-to-json` — XLSX to JSON
+#### `transform.xlsx-to-json` — Spreadsheet to JSON
 
-Convert XLSX spreadsheet to JSON array of row objects for use in scripts or downstream steps
+Convert an XLS or XLSX spreadsheet to a JSON array of row objects. Supports headerless files, named or positional columns, displayed text, and a single rectangular range.
 
 **Durable retry:** Transforms, including those that write files, are not durably retried.
 
@@ -751,16 +751,26 @@ Convert XLSX spreadsheet to JSON array of row objects for use in scripts or down
 | Field | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
 | `input` | string | yes |  | File input - template expression e.g. {{input.document}} resolving to a scoped $file artifact at runtime |
-| `sheet` | integer \| string | no |  | Sheet to read: 0-based index or sheet name. Omit for first sheet. |
-| `outputCsv` | boolean | no | `false` | If true, also write CSV to storage and include fileId in output |
+| `sheet` | integer \| string | no |  | Sheet to read: 0-based index or exact sheet name. Omit for the first sheet. |
+| `outputCsv` | boolean | no | `false` | If true, also write CSV to storage and include fileId. Zero-config uses the historical full-sheet SheetJS CSV. When columns, range, headerRow, valueMode, blankCells, or blankRows are set, CSV matches that projection. |
+| `includeMetadata` | boolean | no | `false` | If true, include sheet metadata and diagnostics in the step output. Omit to keep output as rows (and fileId when outputCsv is true). Warnings are still logged when this is false. |
 | `outputFilename` | string | no |  | Output CSV filename when outputCsv is true - supports LiquidJS e.g. {{filename}}.csv |
+| `headerRow` | `false` \| integer | no |  | Header row: a positive 1-based Excel row, or false to keep the first effective row as data. Omit to use the first effective row as the header. When range is set and this is omitted, the first range row is the header. |
+| `columns` | array<object> | no |  | Ordered output columns. Each item needs a key and exactly one source: index (0-based absolute column) or header (exact displayed header text). Named header sources require a header row. Omit to keep every column in the effective range. |
+| `valueMode` | `"raw"` \| `"displayed"` | no | `"raw"` | raw (default) returns typed cached cell values. displayed returns formatted cell text (dates, leading zeros, punctuation, diacritics, embedded newlines). Formulas are never calculated. |
+| `range` | string | no |  | Optional rectangular A1 range without a sheet qualifier, e.g. A1:D20. Disjoint ranges are rejected. |
+| `blankCells` | `"empty-string"` \| `"null"` \| `"omit"` | no | `"empty-string"` | How truly empty cells appear in each row object. Default empty-string. 0, false, and a formula that cached an empty string are not empty cells. |
+| `blankRows` | `"skip"` \| `"keep"` | no | `"skip"` | skip (default) drops rows whose projected columns are all truly empty. keep retains them. Detection uses projected columns only. |
+| `limits` | object | no |  | Optional workload caps that can only lower the server defaults. Omitted fields use the server defaults. |
 
 **Output:** `object`
 
 | Field | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
-| `rows` | array<record<string, unknown>> | yes |  | Array of row objects (first row = headers as keys) |
+| `rows` | array<record<string, unknown>> | yes |  | Array of row objects (first row = headers as keys unless headerRow is false) |
 | `fileId` | string | no |  | File ID of stored CSV when outputCsv is true |
+| `sheet` | object | no |  | Selected sheet metadata after projection. Present only when includeMetadata is true. |
+| `diagnostics` | array<object> | no |  | Non-fatal warnings collected while reading the sheet. Present only when includeMetadata is true. Warnings are still logged when metadata is omitted. |
 
 #### `transform.json-to-xlsx` — JSON to XLSX
 
@@ -899,7 +909,7 @@ Execute another workflow and return its output
 
 **Output:** `record<string, unknown>`
 
-> When wait is true, the invoked workflow's declared output fields are flattened to the top level alongside a `files` array — reference them as {{ steps.<invoke>.output.<field> }} (there is no `.data` or `.result` wrapper). When wait is false, execution metadata. Call get_workflow_output_schema to see the exact resolved fields.
+> When wait is true, the invoked workflow's declared output fields are flattened to the top level alongside a `files` array — reference them as {{ steps.<invoke>.output.<field> }} (there is no `.data` or `.result` wrapper). When wait is false, execution metadata. CLI authors can run `eigenpal workflow schema <workflow-id>` to inspect resolved fields; Studio builder agents can call `get_workflow_output_schema`.
 
 #### `action.website-reader` — Website Reader
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eigenpal/cli",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Eigenpal CLI — author and run document workflows from your terminal. Agent-ready.",
   "keywords": [
     "eigenpal",