@eigenpal/cli 0.12.2 → 0.13.1

package/dist/skill/SKILL.md

@@ -17,7 +17,10 @@ appear in user examples, but do not prefer them.
 ## Choose A Command
 
 - `eigenpal workflow` manages YAML workflow definitions, datasets, evaluators,
-  experiments, versions, and step schemas.
+  experiments, versions, workspace templates, and step schemas.
+- `eigenpal models list` inventories text, vision, and OCR models configured
+  for the current tenant environment (`--json` for scripting). Health is
+  `configured` or `unconfigured` from local credentials — not a live provider probe.
 - `eigenpal agents` manages Git-backed agent source packages, shared resources,
   releases, sync, secrets, datasets, and live file inspection.
 - `eigenpal run` starts a single workflow or agent run from a target. This is the
@@ -30,6 +33,8 @@ appear in user examples, but do not prefer them.
 Use stable ids in scripts:
 
 - Workflow id: `wf_...`
+- Template id: `tmpl_...`
+- Template revision id: `tmpr_...`
 - Workflow execution id: `evx_...`
 - Agent execution id: `aex_...`
 - Experiment batch id: `evb_...`
@@ -49,10 +54,13 @@ eigenpal workflow step-type get ai.extract --json | jq '.configSchema.properties
 
 # Validate and push.
 eigenpal workflow validate ./workflow.yaml
-# If the workflow has action.invoke-workflow steps, local validation cannot
-# resolve their targets (sibling workflows live in the server DB). Add --online
-# to check invoke targets, input types, and cycles before pushing.
+# --online also checks action.invoke-workflow targets, transform.template
+# tmpl_… ids, and explicitly selected OCR/vision/text models against live tenant
+# catalog metadata. Local `template: ./file.xlsx` paths
+# are inspected on disk with or without --online and must stay inside the
+# workflow project unless you pass --allow-external-templates.
 eigenpal workflow validate ./workflow.yaml --online
+eigenpal models list --json
 eigenpal workflow push --file workflow.yaml
 
 # Run with ad-hoc input and read the output (use this for API-triggered workflows).
@@ -80,6 +88,13 @@ eigenpal workflow evaluators push <workflow-id> --file ./evaluators.yaml
 eigenpal workflow experiment run <workflow-id>
 eigenpal workflow experiment watch <workflow-id> <batch-id>
 eigenpal workflow experiment results <workflow-id> <batch-id> --format csv --out results.csv
+
+# Create a tagged candidate without moving live traffic, then promote it.
+eigenpal workflow versions create <workflow-id> --file workflow.yaml --set-version 1.4.0 --no-activate
+eigenpal workflow versions list <workflow-id>
+eigenpal workflow versions promote <workflow-id> <version-id>
+# Restore copies a snapshot into a new untagged current HEAD.
+eigenpal workflow versions restore <workflow-id> <version-id>
 ```
 
 Folders are server metadata, not `workflow.yaml` content:
@@ -154,6 +169,75 @@ eigenpal run agents.<slug> \
 `agents file list/get/diff` are read/compare commands only. Change agent files
 through Git source, then use `agents save`, `agents release`, and `agents sync`.
 
+## Agent templates (Git source)
+
+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:
+
+```bash
+eigenpal workflow templates upload ./templates/roster.xlsx --json
+eigenpal workflow templates smoke ./templates/roster.xlsx --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
+```
+
+**Local template** (one agent):
+
+```text
+agents/<slug>/templates/<template-slug>/
+  template.docx   # or template.xlsx
+  TEMPLATE.md     # frontmatter: name, description, type: docx|xlsx
+```
+
+**Shared template package** (reused across agents):
+
+```text
+resources/templates/<template-slug>/
+  eigenpal.yaml   # required package manifest
+  template.docx   # or template.xlsx
+  TEMPLATE.md     # optional metadata
+```
+
+At runtime the agent fills templates with the baked-in **fill-template**
+platform skill (`vars`, then `fill`) — not `transform.template`. Local
+templates resolve by slug under `agent/templates/<slug>/`. Shared dependencies
+install under `agent/eigenpal_modules/resources/templates/<slug>/`; pass that
+file path to fill-template when the template is not copied locally.
+
+```bash
+# Add or update a local template, then validate and save.
+cp ./invoice.docx agents/<slug>/templates/invoice/template.docx
+$EDITOR agents/<slug>/templates/invoice/TEMPLATE.md
+eigenpal agents validate agents/<slug>
+eigenpal agents save -m "Add invoice template"
+eigenpal agents release patch agents/<slug>
+eigenpal agents sync agents.<slug>
+
+# Shared template: validate, save, and release the package.
+cp ./report.xlsx resources/templates/monthly-report/template.xlsx
+$EDITOR resources/templates/monthly-report/eigenpal.yaml
+eigenpal agents validate resources/templates/monthly-report
+eigenpal agents save -m "Add monthly report template"
+eigenpal agents release patch resources/templates/monthly-report
+
+# Consuming agent: pin an exact dependency version, then release and sync.
+$EDITOR agents/<slug>/eigenpal.yaml   # workspace:resources.templates.monthly-report: "1.0.0"
+eigenpal agents validate agents/<slug>
+eigenpal agents save -m "Use monthly report template"
+eigenpal agents release patch agents/<slug>
+eigenpal agents sync agents.<slug>
+```
+
+Updating a shared template does not auto-sync dependent agents. Release the
+template package, bump each consumer's exact-version dependency, then release
+and sync those agents. Workspace `tmpl_...` templates are a different system —
+use `eigenpal workflow templates`, not `agents save`.
+
 ## Shared Resource Updates
 
 Do not move every dependent agent automatically. Find dependents, ask which ones

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

@@ -0,0 +1,40 @@
+# eigenpal models
+
+Inspect models and providers configured for the current tenant environment (text, vision, OCR).
+
+## Contents
+
+- [Surface](#surface)
+- [Commands](#commands)
+  - [Core](#core)
+- [Details](#details)
+  - [`eigenpal models list|ls [options]`](#eigenpal-models-listls-options)
+
+## Surface
+
+```
+models
+└── list|ls
+```
+
+## Commands
+
+### Core
+
+| Command                              | Description                                                                                                                                                                                                                       |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eigenpal models list\|ls [options]` | List configured text, vision, and OCR models. This is a catalog inventory from the server, not a live provider health probe. `health` is `configured` or `unconfigured` from local credentials. Pair with `--json` for scripting. |
+
+## Details
+
+### `eigenpal models list|ls [options]`
+
+List configured text, vision, and OCR models. This is a catalog inventory from the server, not a live provider health probe. `health` is `configured` or `unconfigured` from local credentials. Pair with `--json` for scripting.
+
+### Options
+
+| Flag                  | Required | Default | Description                                                                |
+| --------------------- | -------- | ------- | -------------------------------------------------------------------------- |
+| `--capability <kind>` | no       |         | Filter to `text`, `vision`, or `ocr` (matches the API `capability` query). |
+| `--base-url <url>`    | no       |         | Server base URL                                                            |
+| `--json`              | no       |         | Output the raw server response as JSON                                     |

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

@@ -21,6 +21,7 @@ Inspect, watch, and manage workflow, agent, and eval runs.
   - [`eigenpal runs cancel [options] <run-id>`](#eigenpal-runs-cancel-options-run-id)
   - [`eigenpal runs artifacts|artifact list|ls [options] <run-id>`](#eigenpal-runs-artifactsartifact-listls-options-run-id)
   - [`eigenpal runs artifacts|artifact fetch [options] <run-id>`](#eigenpal-runs-artifactsartifact-fetch-options-run-id)
+  - [`eigenpal runs artifacts|artifact inspect [options] [run-id] [artifact-path]`](#eigenpal-runs-artifactsartifact-inspect-options-run-id-artifact-path)
   - [`eigenpal runs reviews|rv update [options] <run-id>`](#eigenpal-runs-reviewsrv-update-options-run-id)
   - [`eigenpal runs reviews|rv close [options] <run-id>`](#eigenpal-runs-reviewsrv-close-options-run-id)
   - [`eigenpal runs reviews|rv clear [options] <run-id>`](#eigenpal-runs-reviewsrv-clear-options-run-id)
@@ -42,7 +43,8 @@ runs
 ├── promote <run-id>
 ├── artifacts|artifact
 │   ├── list|ls <run-id>
-│   └── fetch <run-id>
+│   ├── fetch <run-id>
+│   └── inspect [run-id] [artifact-path]
 ├── trace <run-id>
 ├── reviews|rv
 │   ├── update <run-id>
@@ -63,23 +65,24 @@ runs
 
 ### Core
 
-| Command                                                             | Description                                                                                                      |
-| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `eigenpal runs list\|ls [options] [source]`                         | List runs across workflows and agents, optionally scoped to one source.                                          |
-| `eigenpal runs get [options] <run-id>`                              | Get one run.                                                                                                     |
-| `eigenpal runs compare\|diff [options] <reference-run-id> <run-id>` | Compare one run against another run. PDF/DOCX text comparison uses pdftotext/python3 and reports byte fallbacks. |
-| `eigenpal runs rerun [options] <run-id>`                            | Create a new run from a previous run's stored input snapshot.                                                    |
-| `eigenpal runs promote [options] <run-id>`                          | Promote a run into a dataset example on the run's automation.                                                    |
-| `eigenpal runs trace [options] <run-id>`                            | Print raw trace.jsonl for a run, or write it with --out.                                                         |
-| `eigenpal runs watch [options] <run-id>`                            | Watch a run until it reaches a terminal status.                                                                  |
-| `eigenpal runs cancel [options] <run-id>`                           | Cancel a run.                                                                                                    |
+| Command                                                             | Description                                                                                                                     |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `eigenpal runs list\|ls [options] [source]`                         | List runs across workflows and agents, optionally scoped to one source.                                                         |
+| `eigenpal runs get [options] <run-id>`                              | Get one run.                                                                                                                    |
+| `eigenpal runs compare\|diff [options] <reference-run-id> <run-id>` | Compare one run against another run. PDF/DOCX use pdftotext/python3; XLSX compares structured workbook content (not ZIP bytes). |
+| `eigenpal runs rerun [options] <run-id>`                            | Create a new run from a previous run's stored input snapshot.                                                                   |
+| `eigenpal runs promote [options] <run-id>`                          | Promote a run into a dataset example on the run's automation.                                                                   |
+| `eigenpal runs trace [options] <run-id>`                            | Print raw trace.jsonl for a run, or write it with --out.                                                                        |
+| `eigenpal runs watch [options] <run-id>`                            | Watch a run until it reaches a terminal status.                                                                                 |
+| `eigenpal runs cancel [options] <run-id>`                           | Cancel a run.                                                                                                                   |
 
 ### Artifacts
 
-| Command                                                         | Description                                            |
-| --------------------------------------------------------------- | ------------------------------------------------------ |
-| `eigenpal runs artifacts\|artifact list\|ls [options] <run-id>` | List available run artifacts without downloading them. |
-| `eigenpal runs artifacts\|artifact fetch [options] <run-id>`    | Download run artifacts by canonical artifact path.     |
+| Command                                                                        | Description                                                                                                         |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `eigenpal runs artifacts\|artifact list\|ls [options] <run-id>`                | List available run artifacts without downloading them.                                                              |
+| `eigenpal runs artifacts\|artifact fetch [options] <run-id>`                   | Download run artifacts by canonical artifact path.                                                                  |
+| `eigenpal runs artifacts\|artifact inspect [options] [run-id] [artifact-path]` | Inspect a run XLSX artifact as structured JSON (sheet names, headers, typed rows). Use --file for a local workbook. |
 
 ### Reviews
 
@@ -158,7 +161,7 @@ Get one run.
 
 ### `eigenpal runs compare|diff [options] <reference-run-id> <run-id>`
 
-Compare one run against another run. PDF/DOCX text comparison uses pdftotext/python3 and reports byte fallbacks.
+Compare one run against another run. PDF/DOCX use pdftotext/python3; XLSX compares structured workbook content (not ZIP bytes).
 
 ### Arguments
 
@@ -310,6 +313,30 @@ Download run artifacts by canonical artifact path.
 | `--path <path>`     | no       | `[]`    | Fetch one exact artifact path from `artifacts list`; repeatable                 |
 | `--json`            | no       |         | Output a JSON summary of written artifacts                                      |
 
+### `eigenpal runs artifacts|artifact inspect [options] [run-id] [artifact-path]`
+
+Inspect a run XLSX artifact as structured JSON (sheet names, headers, typed rows). Use --file for a local workbook.
+
+### Arguments
+
+| Name            | Required | Variadic | Description |
+| --------------- | -------- | -------- | ----------- |
+| `run-id`        | no       | no       |             |
+| `artifact-path` | no       | no       |             |
+
+### Options
+
+| Flag               | Required | Default | Description                                                                        |
+| ------------------ | -------- | ------- | ---------------------------------------------------------------------------------- |
+| `--base-url <url>` | no       |         | Server base URL                                                                    |
+| `--json`           | no       |         | Output the raw server response as JSON                                             |
+| `--file <path>`    | no       |         | Inspect a local .xlsx/.xls file instead of downloading a run artifact              |
+| `--path <path>`    | no       |         | Canonical artifact path from `artifacts list` (alias for positional artifact-path) |
+| `--sheet <names>`  | no       |         | Comma-separated sheet names or zero-based indices to include                       |
+| `--max-sheets <n>` | no       |         | Maximum sheets to include (default 20)                                             |
+| `--max-rows <n>`   | no       |         | Maximum data rows per sheet (default 500)                                          |
+| `--max-cols <n>`   | no       |         | Maximum columns per sheet (default 50)                                             |
+
 ### `eigenpal runs reviews|rv update [options] <run-id>`
 
 Edit review verdict, status, note, or corrected JSON for a run.

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

@@ -32,6 +32,14 @@ eigenpal
 │   │   │   ├── delete <workflow-id> <exampleId>
 │   │   │   └── get <workflow-id> <exampleId>
 │   │   └── validate [path]
+│   ├── templates
+│   │   ├── upload <file>
+│   │   ├── list|ls
+│   │   ├── get|inspect <template-id>
+│   │   ├── download <template-id>
+│   │   ├── replace <template-id> <file>
+│   │   ├── delete <template-id>
+│   │   └── smoke <template>
 │   ├── experiment|exp
 │   │   ├── list|ls <workflow-id>
 │   │   ├── run <workflow-id>
@@ -42,6 +50,8 @@ eigenpal
 │   │   └── watch <workflow-id> <batchId>
 │   ├── versions
 │   │   ├── list|ls <workflow-id>
+│   │   ├── create <workflow-id>
+│   │   ├── promote <workflow-id> <versionId>
 │   │   └── restore <workflow-id> <versionId>
 │   ├── step-type
 │   │   ├── list|ls
@@ -102,6 +112,8 @@ eigenpal
 │   │   └── stop <session-id>
 │   └── env
 │       └── pull [target]
+├── models
+│   └── list|ls
 ├── run <target>
 ├── rerun <run-id>
 ├── runs
@@ -112,7 +124,8 @@ eigenpal
 │   ├── promote <run-id>
 │   ├── artifacts|artifact
 │   │   ├── list|ls <run-id>
-│   │   └── fetch <run-id>
+│   │   ├── fetch <run-id>
+│   │   └── inspect [run-id] [artifact-path]
 │   ├── trace <run-id>
 │   ├── reviews|rv
 │   │   ├── update <run-id>