@eigenpal/cli 0.0.1 → 0.4.1

package/dist/skill/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: eigenpal
+description: Build, run, and iterate on Eigenpal workflows from the command line. The workflow engine, evaluators, dataset folders, and execution introspection are all controlled via `eigenpal` subcommands. The server is the source of truth — local files are inputs you push.
+license: Apache-2.0
+compatibility: Requires eigenpal CLI.
+metadata:
+  author: eigenpal
+  version: '1.0'
+  generatedBy: 'eigenpal@__CLI_VERSION__'
+---
+
+# Eigenpal
+
+Eigenpal is a workflow engine. A workflow is a DAG of steps
+(parsing, extraction, scripting, etc.). Iteration happens locally with the
+`eigenpal` CLI; **execution + datasets + experiments live on the server**.
+
+This skill is the schema reference. The CLI does the actual work.
+
+## Iteration loop (end-to-end)
+
+```
+1.  eigenpal init workflow my-extraction --template pdf-extraction
+2.  edit workflow.yaml + evaluators.yaml + dataset/examples/*/expected/output.json
+3.  eigenpal workflow validate                                       # local: all three checks, no server contact
+4.  eigenpal workflow execution run my-extraction sample-name        # one-off run for debugging
+5.  eigenpal workflow push --file workflow.yaml                      # creates wf_… on first push
+6.  eigenpal workflow evaluators push <wf-id> --file evaluators.yaml
+7.  eigenpal workflow dataset push <wf-id> --file dataset/ --mode replace
+8.  eigenpal workflow experiment run <wf-id>                         # → { batchId, executionIds }
+9.  eigenpal workflow experiment status <wf-id> <batch-id>
+10. eigenpal workflow experiment results <wf-id> <batch-id> --format csv --out r.csv
+```
+
+## Common recipes
+
+### From zero — new workflow from a template
+
+```bash
+eigenpal init workflow invoices --template pdf-extraction   # scaffolds workflow.yaml + dataset/ + evaluators.yaml
+cd invoices
+eigenpal workflow validate                                   # confirm scaffold is valid before pushing
+eigenpal workflow push --file workflow.yaml
+# → ✓ Created wf_abc123  (`eigenpal workflow list` to see it again)
+```
+
+### Author + validate a workflow
+
+```bash
+# Pick the right step types BEFORE writing the workflow
+eigenpal workflow step-type list --search extract
+eigenpal workflow step-type get ai.extract | jq '.configSchema.properties'
+
+# Validate locally (zod parse + step-type lookup, no server)
+eigenpal workflow validate ./workflow.yaml
+
+# Push (creates on first call; same name + new version appends to history)
+eigenpal workflow push --file workflow.yaml --workflow-id wf_abc123
+
+# Update an existing workflow with explicit / auto-bumped semver:
+eigenpal workflow push --file workflow.yaml --workflow-id wf_abc123 --set-version 2.0.0
+eigenpal workflow push --file workflow.yaml --workflow-id wf_abc123 --bump patch    # patch | minor | major
+```
+
+The validator emits structured field-path errors with a hint pointing at
+`step-type get <type>` for the offending step. Follow the hint.
+
+Version bumping rules (`--bump` vs `--set-version` vs YAML `version:`)
+live in [`reference/workflow-yaml.md`](reference/workflow-yaml.md#validate-before-pushing).
+
+### Iterate fast on one step (no server, no DAG)
+
+Tightest possible loop — local sandbox, milliseconds per run. Today
+covers `transform.script` and `ai.extract`. For any other step type,
+fall back to `workflow execution run` against the server.
+
+```bash
+eigenpal workflow step exec transform.script \
+  --config-json '{"code":"return items.reduce((s,i)=>s+i.v,0)"}' \
+  --inputs items=@items.json
+# 3
+```
+
+See [`reference/step-exec.md`](reference/step-exec.md) for the full
+grammar — inputs, config, output schema, exit codes.
+
+### Cancel a long-running execution
+
+```bash
+eigenpal workflow execution cancel exec_abc        # TTY: silent; CI: needs --yes
+eigenpal workflow execution cancel exec_abc --yes  # CI / pipes
+```
+
+The worker finishes the current step, then stops — the check happens
+between every step transition, including inside `control.foreach` /
+`control.parallel` / `control.block` bodies. Already-terminal
+executions (completed/failed/cancelled) exit 0 with an info line. Safe
+to retry.
+
+### Compare two experiment batches (no workflow id needed)
+
+```bash
+eigenpal workflow experiment compare evb_old evb_new --regression-threshold 0.05
+```
+
+Unlike its siblings, `compare` takes no `<wf-id>` — the server resolves
+the owning workflow from each batch id. Both batches must live in the
+same workflow within your tenant. See [`reference/debugging.md`](reference/debugging.md#6-compare-two-experiment-batches)
+for sort flags + `--json` shape.
+
+### Author + validate evaluators
+
+```bash
+# Inspect what evaluator types exist + their config shape
+cat packages/cli/src/skill/reference/evaluators.md   # or read this skill's `reference/`
+
+# Validate locally (every evaluator entry parsed against its discriminated-union schema)
+eigenpal workflow evaluators validate ./evaluators.yaml
+
+# Push (overwrites the workflow's evaluator config)
+eigenpal workflow evaluators push <wf-id> --file evaluators.yaml
+```
+
+### Build + validate + upload a dataset
+
+```bash
+# Folder layout: dataset/examples/<name>/{input/arguments.json, input/<file-arg>/<file>, expected/output.json, meta.json}
+eigenpal workflow dataset validate ./dataset            # rejects bad folder names, arg-name collisions, etc.
+
+# Push. `replace` wipes server-side examples for this workflow first; `append` adds.
+eigenpal workflow dataset push <wf-id> --file ./dataset --mode replace
+# Watch the `expectedSet` count in the final NDJSON `done` event — if 0, evals run un-graded.
+```
+
+To inspect or round-trip the server's current dataset:
+
+```bash
+eigenpal workflow dataset list <wf-id>
+eigenpal workflow dataset pull <wf-id> --out current.zip   # round-trip back to local
+```
+
+### Edit one example without re-uploading the whole dataset
+
+```bash
+# Inspect one example end-to-end (triggerInput + expectedOutput + metadata):
+eigenpal workflow dataset example get <wf-id> <example-id>
+eigenpal workflow dataset example get <wf-id> <example-id> --json | jq '.expectedOutput'
+
+# Capture a corrected output as the new ground truth (the most common one):
+#   1. Look at what the workflow returned
+eigenpal workflow execution get exec_… --json | jq '.output.data' > /tmp/correct.json
+#   2. Patch that example's expected output in place
+eigenpal workflow dataset example update <wf-id> <example-id> \
+  --expected-file /tmp/correct.json
+
+# Add one new example to a known dataset:
+eigenpal workflow dataset example create <wf-id> \
+  --name missing-required-field \
+  --input-json '{"language":"en"}' \
+  --expected-file /tmp/expected.json \
+  --annotation "edge case: required field absent from input"
+
+# Drop a bad example by id (CI requires --yes):
+eigenpal workflow dataset example delete <wf-id> <example-id> --yes
+```
+
+`example update` is a partial PATCH — any flag you omit is left alone. Pass
+`--annotation ""` to clear an annotation. For bulk changes, edit the local
+dataset folder and re-push with `dataset push --mode replace`.
+
+### Run an experiment + collect results
+
+```bash
+# Kick off — runs every example in the dataset against every evaluator.
+eigenpal workflow experiment run <wf-id>                       # → { batchId, executionIds }
+
+# Or restrict to one example:
+eigenpal workflow experiment run <wf-id> --example-id evx_…
+
+# Poll until done. `experiment status` auto-detaches after 30 min; just re-run.
+eigenpal workflow experiment status <wf-id> <batch-id>
+
+# Pull results — `--out` writes the file directly from the server's signed-URL
+# storage, so large CSVs don't go through the CLI process.
+eigenpal workflow experiment results <wf-id> <batch-id> --format csv --out r.csv
+```
+
+### Debug a failing workflow
+
+```bash
+# 1. Reproduce locally with the live step list
+eigenpal workflow execution run <workflow-name> <example-name>
+
+# 2. Or pull a recorded failure from the server
+eigenpal workflow execution list <wf-id> --status failed --limit 5
+eigenpal workflow execution get  exec_…                           # full payload, all steps
+eigenpal workflow execution get  exec_… --step extract --include input,output,error
+
+# 3. Compare two runs (e.g. before/after a workflow change)
+eigenpal workflow execution compare <exec-a> <exec-b>
+
+# 4. Wait for a kicked-off run to finish (use this whenever you need
+#    to block until terminal — adaptive polling, 30-min auto-detach)
+eigenpal workflow execution watch exec_…
+```
+
+See [`reference/debugging.md`](reference/debugging.md) for common failure
+modes (`validation_failed`, `template_resolution_failed`, `script_timeout`,
+`step_type_unknown`) and how to skip flaky external steps via
+`meta.json` overrides.
+
+## Output convention
+
+Every command splits its output:
+
+- **stdout** = data — JSON payloads, table rows, file contents from
+  `pull` / `experiment results`. Pipe-safe.
+- **stderr** = status — `✓` / `✗` / `ℹ` / `!` lines. Silenced by
+  `-q` / `--quiet` (errors and warnings always fire; stdout never
+  silenced).
+
+The `--json` flag (on every `list` / `get` / mutating command) flips
+the human-readable table on stdout to the raw server payload — pipe
+through real `jq` to project:
+
+```bash
+eigenpal workflow execution list wf_abc --json | jq '.data[0].id'
+eigenpal workflow execution get exec_abc --json | jq '.stepExecutions[].status'
+```
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success. |
+| 1 | Runtime error — network, server 5xx, command-specific failure (e.g. `experiment status` (with or without `--watch`) reports a terminal batch where at least one execution failed or was cancelled). |
+| 2 | Misuse or recoverable failure — bad flag, `step exec --output-schema` violation, `execution watch --max-wait` deadline, `step exec` against an unsupported step type. |
+
+Exit 2 means "fix your invocation and re-run." Exit 1 means something
+broke upstream — check the error.
+
+## Where the schemas live
+
+The CLI ships JSON Schema for every step type and every evaluator type.
+Don't guess fields — introspect:
+
+```bash
+eigenpal workflow step-type      list                # full step catalog
+eigenpal workflow step-type      get ai.extract      # config + output schema
+eigenpal workflow evaluator-type list                # full evaluator catalog
+eigenpal workflow evaluator-type get llm-judge       # config schema
+```
+
+For workflow / evaluators / dataset shape, see this skill's `reference/`:
+
+- [`reference/workflow-yaml.md`](reference/workflow-yaml.md) — top-level shape, triggers, inputs, steps, output, template expressions
+- [`reference/step-types.md`](reference/step-types.md) — step-type catalog + when to reach for each
+- [`reference/step-exec.md`](reference/step-exec.md) — local single-step iteration (`workflow step exec`) — inputs, config, output schema, exit codes
+- [`reference/dataset-format.md`](reference/dataset-format.md) — `dataset/examples/<name>/{input,expected,meta}` folder convention
+- [`reference/evaluators.md`](reference/evaluators.md) — evaluators.yaml schema + judge patterns
+- [`reference/debugging.md`](reference/debugging.md) — execution introspection + common failures
+- [`reference/cli/`](reference/cli/) — full flag reference per command (autogenerated from the live Commander tree, never lies)
+
+## Validation errors carry hints
+
+Every server-side validation failure returns a structured envelope:
+
+```json
+{
+  "issues": [
+    { "field": "steps.2.config.passThreshold",
+      "message": "Required, got undefined", "code": "invalid_value" }
+  ],
+  "hint": "Failing step is type `eval.llm-judge`. Run `eigenpal workflow step-type get eval.llm-judge` to inspect its config schema."
+}
+```
+
+The CLI renders this with the field column aligned and the hint inline —
+follow the hint, the schema lookup is one command away.
+
+## Don't reach for
+
+- `eval-local` / similar local-mirror commands — they don't exist. Drive
+  the dataset by editing the local folder and pushing with
+  `workflow dataset push --mode replace`, OR use the per-example CRUD
+  (`dataset example {create,update,delete,get}`) when you only need to
+  flip one row.
+- The `manifest.json` dataset format — legacy, the import endpoint rejects
+  it. Always use the folder convention.
+
+## CLI surface
+
+```bash
+# Auth + tenant switching
+eigenpal auth login              # add a profile (or update existing tenant's)
+eigenpal auth list               # see all profiles, current marked ●
+eigenpal auth use [profile]      # switch active (interactive picker if no arg)
+eigenpal status                  # active tenant, user, key id, workflow count
+
+# Definition
+eigenpal workflow list
+eigenpal workflow push --file workflow.yaml [--workflow-id <wf-id>]
+eigenpal workflow pull <wf-id>
+eigenpal workflow validate [path]
+
+# Evaluators
+eigenpal workflow evaluators push <wf-id> --file evaluators.yaml
+eigenpal workflow evaluators pull <wf-id>
+eigenpal workflow evaluators validate [path]
+
+# Dataset
+eigenpal workflow dataset push <wf-id> --file dataset/ [--mode {append|replace}]      # default: append
+eigenpal workflow dataset pull <wf-id> --out dataset.zip
+eigenpal workflow dataset list <wf-id>
+eigenpal workflow dataset validate [path]
+eigenpal workflow dataset example create <wf-id> --name <n> [--input-file] [--expected-file] [--annotation]
+eigenpal workflow dataset example update <wf-id> <example-id> [--name] [--input-file] [--expected-file] [--annotation] [--row-order]
+eigenpal workflow dataset example delete <wf-id> <example-id> --yes
+eigenpal workflow dataset example get    <wf-id> <example-id>                          # full row + metadata
+
+# All-in-one validation against the templated project layout
+eigenpal workflow validate                    # ./workflow.yaml + ./evaluators.yaml + ./dataset/
+
+# Local artifacts
+eigenpal workflow clear-local                 # delete local execution artifacts (no server impact)
+
+# Experiments (batch eval runs)
+eigenpal workflow experiment run     <wf-id> [--example-id <id> ...]
+eigenpal workflow experiment status  <wf-id> <batch-id> [--watch]    # exit 1 on terminal w/ failures, 2 on --max-wait
+eigenpal workflow experiment results <wf-id> [batch-id] --format {csv|json} --out r.csv
+eigenpal workflow experiment list    <wf-id>
+eigenpal workflow experiment compare <batch-a> <batch-b> [--regression-threshold] [--sort]   # no --workflow-id
+
+# Step-type / evaluator-type introspection
+eigenpal workflow step-type      list
+eigenpal workflow step-type      get <type>
+eigenpal workflow evaluator-type list
+eigenpal workflow evaluator-type get <type>
+
+# Local single-step iteration (no server)
+eigenpal workflow step exec <type> [--config-json | --config-file] [--inputs k=v...] [--output-schema]
+
+# Execution (one-off run + read-side debugging + cancellation)
+eigenpal workflow execution run     <workflow-slug> [examples...]
+eigenpal workflow execution get     <exec-id>
+eigenpal workflow execution list    <wf-id> [--status running|failed|completed]
+eigenpal workflow execution watch   <exec-id>          # 2s/5s adaptive polling
+eigenpal workflow execution compare <exec-a> <exec-b>
+eigenpal workflow execution cancel  <exec-id>          # tells the worker to stop between steps; safe to retry
+
+# Versions
+eigenpal workflow versions list    <wf-id>                          # pushed semver history (newest first)
+eigenpal workflow versions restore <wf-id> <version-id>             # re-activate a prior version as the live one
+
+# Tooling
+eigenpal skill install           # interactive multiselect for Claude Code, Cursor, …
+eigenpal skill uninstall [toolIds...]  # name one or more tools, or pass --all
+eigenpal skill list              # show what's installed where
+```
+
+`eigenpal --help` for the grouped overview, `eigenpal <command> --help`
+for any specific command. The full per-command flag reference is also
+bundled at [`reference/cli/`](reference/cli/) (autogenerated from the
+live Commander tree, so it never lies). Read those when you need the
+exact spelling / default / data type for a flag without round-tripping
+to `--help`.

package/dist/skill/examples/hello-world/dataset/examples/sample/expected/output.json

@@ -0,0 +1,4 @@
+{
+  "length": 13,
+  "original": "Hello, world."
+}

package/dist/skill/examples/hello-world/dataset/examples/sample/input/arguments.json

@@ -0,0 +1,3 @@
+{
+  "text": "Hello, world."
+}

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

@@ -0,0 +1,5 @@
+evaluators:
+  - name: exact-match
+    type: exact-diff
+    config:
+      passThreshold: 1.0

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

@@ -0,0 +1,28 @@
+name: hello-world
+version: 1.0.0
+description: Smallest possible workflow — echoes the input back through transform.script.
+
+triggerMethods:
+  - api
+
+inputs:
+  - name: text
+    type: string
+
+steps:
+  - name: echo
+    type: transform.script
+    with:
+      inputs:
+        text: '{{ input.text }}'
+      code: |
+        return { length: text.length, original: text };
+      outputSchema:
+        type: object
+        properties:
+          length: { type: number }
+          original: { type: string }
+
+output:
+  length: '{{ steps.echo.output.length }}'
+  original: '{{ steps.echo.output.original }}'

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

@@ -0,0 +1,7 @@
+# eigenpal agent
+
+> **Auto-generated.** This file is regenerated from the live Commander tree in
+> `packages/cli/src/cli.ts` by `bun run --cwd packages/cli generate:cli-docs`.
+> Do not hand-edit — your changes will be overwritten on the next run.
+
+Agent (agentic process) operations — coming soon. Agent workflows live on the server today; CLI surface is reserved for future commands.

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

@@ -0,0 +1,75 @@
+# eigenpal auth
+
+> **Auto-generated.** This file is regenerated from the live Commander tree in
+> `packages/cli/src/cli.ts` by `bun run --cwd packages/cli generate:cli-docs`.
+> Do not hand-edit — your changes will be overwritten on the next run.
+
+Manage authentication. Credentials live in ~/.config/eigenpal/credentials.json as named profiles. Switch tenants with `auth use <name>` or set `EIGENPAL_PROFILE=<name>` for one shell.
+
+## Contents
+
+- [Surface](#surface)
+- [Commands](#commands)
+  - [Core](#core)
+- [Details](#details)
+  - [`eigenpal auth login [options]`](#eigenpal-auth-login-options)
+  - [`eigenpal auth logout [options] [profile]`](#eigenpal-auth-logout-options-profile)
+  - [`eigenpal auth list [options]`](#eigenpal-auth-list-options)
+  - [`eigenpal auth use [options] [profile]`](#eigenpal-auth-use-options-profile)
+
+## Surface
+
+```
+auth
+├── login
+├── logout [profile]
+├── list
+└── use [profile]
+```
+
+## Commands
+
+### Core
+
+| Command                                    | Description                                                                                                                                                                                                                          |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `eigenpal auth login [options]`            | Authenticate with Eigenpal. Opens a browser to create an API key, stores it under a profile named after the tenant, and makes that profile active. Re-running `login` against the same tenant updates the existing profile in place. |
+| `eigenpal auth logout [options] [profile]` | Remove a profile from the credentials file. Defaults to the active profile if no name is given. After removal the next available profile becomes active.                                                                             |
+| `eigenpal auth list [options]`             | List configured profiles. The active one is marked ● — switch with `auth use`.                                                                                                                                                       |
+| `eigenpal auth use [options] [profile]`    | Switch the active profile (persistent across shells). Omit `[profile]` to pick from a list. For one-shot per-shell switching, set `EIGENPAL_PROFILE=<name>` instead.                                                                 |
+
+## Details
+
+### `eigenpal auth login [options]`
+
+Authenticate with Eigenpal. Opens a browser to create an API key, stores it under a profile named after the tenant, and makes that profile active. Re-running `login` against the same tenant updates the existing profile in place.
+
+### Options
+
+| Flag               | Required | Default | Description     |
+| ------------------ | -------- | ------- | --------------- |
+| `--base-url <url>` | no       |         | Server base URL |
+
+### `eigenpal auth logout [options] [profile]`
+
+Remove a profile from the credentials file. Defaults to the active profile if no name is given. After removal the next available profile becomes active.
+
+### Arguments
+
+| Name      | Required | Variadic | Description |
+| --------- | -------- | -------- | ----------- |
+| `profile` | no       | no       |             |
+
+### `eigenpal auth list [options]`
+
+List configured profiles. The active one is marked ● — switch with `auth use`.
+
+### `eigenpal auth use [options] [profile]`
+
+Switch the active profile (persistent across shells). Omit `[profile]` to pick from a list. For one-shot per-shell switching, set `EIGENPAL_PROFILE=<name>` instead.
+
+### Arguments
+
+| Name      | Required | Variadic | Description |
+| --------- | -------- | -------- | ----------- |
+| `profile` | no       | no       |             |

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

@@ -0,0 +1,13 @@
+# eigenpal completion
+
+> **Auto-generated.** This file is regenerated from the live Commander tree in
+> `packages/cli/src/cli.ts` by `bun run --cwd packages/cli generate:cli-docs`.
+> Do not hand-edit — your changes will be overwritten on the next run.
+
+Print a shell completion script to stdout (supported shells: bash, zsh, fish). Pipe into the appropriate completion file for your shell — see the script header for install instructions.
+
+### Arguments
+
+| Name    | Required | Variadic | Description |
+| ------- | -------- | -------- | ----------- |
+| `shell` | yes      | no       |             |

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

@@ -0,0 +1,63 @@
+# eigenpal init
+
+> **Auto-generated.** This file is regenerated from the live Commander tree in
+> `packages/cli/src/cli.ts` by `bun run --cwd packages/cli generate:cli-docs`.
+> Do not hand-edit — your changes will be overwritten on the next run.
+
+Scaffold a new workflow project. Without `[name]`, scaffolds into the current directory using the cwd basename as the workflow name. With `[name]`, creates `./<name>/` and uses that as the slug. The flat layout matches what `workflow execution run <slug>` already discovers — no manual file moves.
+
+## Contents
+
+- [Surface](#surface)
+- [Commands](#commands)
+  - [Core](#core)
+- [Details](#details)
+  - [`eigenpal init workflow [options] <name>`](#eigenpal-init-workflow-options-name)
+  - [`eigenpal init agent [options] <name>`](#eigenpal-init-agent-options-name)
+
+## Surface
+
+```
+init
+├── workflow <name>
+└── agent <name>
+```
+
+## Commands
+
+### Core
+
+| Command                                   | Description                                                                                                                                                             |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eigenpal init workflow [options] <name>` | Alias of `eigenpal init <name>`. Kept so the `init {workflow,agent}` namespace stays visible — once the agent surface lights up, both kinds will live as siblings here. |
+| `eigenpal init agent [options] <name>`    | Scaffold a new agent (agentic process) project — coming soon. The namespace is reserved so the workflow / agent split is visible from day one.                          |
+
+## Details
+
+### `eigenpal init workflow [options] <name>`
+
+Alias of `eigenpal init <name>`. Kept so the `init {workflow,agent}` namespace stays visible — once the agent surface lights up, both kinds will live as siblings here.
+
+### Arguments
+
+| Name   | Required | Variadic | Description |
+| ------ | -------- | -------- | ----------- |
+| `name` | yes      | no       |             |
+
+### Options
+
+| Flag                | Required | Default | Description                                        |
+| ------------------- | -------- | ------- | -------------------------------------------------- |
+| `--template <name>` | no       |         | Skip the picker; use this template                 |
+| `--dir <dir>`       | no       |         | Target directory (default: ./<name>)               |
+| `--yes`             | no       |         | Non-interactive: pick the default template (blank) |
+
+### `eigenpal init agent [options] <name>`
+
+Scaffold a new agent (agentic process) project — coming soon. The namespace is reserved so the workflow / agent split is visible from day one.
+
+### Arguments
+
+| Name   | Required | Variadic | Description |
+| ------ | -------- | -------- | ----------- |
+| `name` | yes      | no       |             |

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

@@ -0,0 +1,79 @@
+# eigenpal skill
+
+> **Auto-generated.** This file is regenerated from the live Commander tree in
+> `packages/cli/src/cli.ts` by `bun run --cwd packages/cli generate:cli-docs`.
+> Do not hand-edit — your changes will be overwritten on the next run.
+
+Install / uninstall / list the Eigenpal agent skill in your project (Claude Code, Cursor, Codex, Gemini CLI, Antigravity, OpenCode, Pi, Windsurf, GitHub Copilot).
+
+## Contents
+
+- [Surface](#surface)
+- [Commands](#commands)
+  - [Core](#core)
+- [Details](#details)
+  - [`eigenpal skill install [options]`](#eigenpal-skill-install-options)
+  - [`eigenpal skill uninstall [options] [toolIds...]`](#eigenpal-skill-uninstall-options-toolids)
+  - [`eigenpal skill list [options]`](#eigenpal-skill-list-options)
+
+## Surface
+
+```
+skill
+├── install
+├── uninstall [toolIds...]
+└── list
+```
+
+## Commands
+
+### Core
+
+| Command                                           | Description                                                                                                                                                                                        |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `eigenpal skill install [options]`                | Install the skill into one or more tools. Opens an interactive multiselect picker (toggle on to install, toggle off to uninstall) — pass `--tools` for non-interactive use.                        |
+| `eigenpal skill uninstall [options] [toolIds...]` | Remove the skill from named tools (e.g. `skill uninstall claude cursor`), pass `--all` to wipe every install, or run with no args in a TTY for an interactive picker showing only installed tools. |
+| `eigenpal skill list [options]`                   | Show every tool that has an Eigenpal skill installed in the current directory, with the CLI version that wrote it.                                                                                 |
+
+## Details
+
+### `eigenpal skill install [options]`
+
+Install the skill into one or more tools. Opens an interactive multiselect picker (toggle on to install, toggle off to uninstall) — pass `--tools` for non-interactive use.
+
+### Options
+
+| Flag              | Required | Default | Description                                                                      |
+| ----------------- | -------- | ------- | -------------------------------------------------------------------------------- |
+| `--tools <ids>`   | no       |         | Comma-separated tool ids. Skips the picker; tools not listed are uninstalled.    |
+| `--target <path>` | no       |         | Power-user override: install into a single custom directory and skip the picker. |
+| `--force`         | no       |         | Overwrite user-edited files without prompting                                    |
+| `--yes`           | no       |         | Non-interactive mode (keep currently installed tools, keep user edits)           |
+
+### `eigenpal skill uninstall [options] [toolIds...]`
+
+Remove the skill from named tools (e.g. `skill uninstall claude cursor`), pass `--all` to wipe every install, or run with no args in a TTY for an interactive picker showing only installed tools.
+
+### Arguments
+
+| Name      | Required | Variadic | Description |
+| --------- | -------- | -------- | ----------- |
+| `toolIds` | no       | yes      |             |
+
+### Options
+
+| Flag              | Required | Default | Description                                                                     |
+| ----------------- | -------- | ------- | ------------------------------------------------------------------------------- |
+| `--all`           | no       |         | Uninstall every tool that has an Eigenpal skill installed                       |
+| `--target <path>` | no       |         | Power-user override: uninstall a single custom directory (skips tool detection) |
+| `--yes`           | no       |         | Required for non-TTY shells; skips confirmation in TTY                          |
+
+### `eigenpal skill list [options]`
+
+Show every tool that has an Eigenpal skill installed in the current directory, with the CLI version that wrote it.
+
+### Options
+
+| Flag     | Required | Default | Description                                   |
+| -------- | -------- | ------- | --------------------------------------------- |
+| `--json` | no       |         | Emit machine-readable JSON instead of a table |

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

@@ -0,0 +1,14 @@
+# eigenpal status
+
+> **Auto-generated.** This file is regenerated from the live Commander tree in
+> `packages/cli/src/cli.ts` by `bun run --cwd packages/cli generate:cli-docs`.
+> Do not hand-edit — your changes will be overwritten on the next run.
+
+One-shot dashboard: server, active tenant, user, key id, workflow count. Pair with `--json` for scripting.
+
+### Options
+
+| Flag               | Required | Default | Description                                               |
+| ------------------ | -------- | ------- | --------------------------------------------------------- |
+| `--base-url <url>` | no       |         | Server base URL                                           |
+| `--json`           | no       |         | Emit machine-readable JSON instead of human-readable text |